# metastackr

> An event-driven meta-repo orchestration platform with custom git meta CLI and PostgreSQL DAG cascade merge engine.

- Website: https://metastac.kr
- GitHub: https://github.com/eliotstocker/MetaStackr

# Multi-Repo Simplicity. Zero Submodule Friction.

**Coordinate multi-repository features across Git submodules effortlessly.** MetaStackr automates cross-repo synchronization from local branches to production merges—enforcing bottom-up atomic pushes, preventing broken pointer drift, and cascading PR merges topologically.

*Mono-repo coordination with multi-repo independence—built for developer teams and AI coding agents.*

- `curl -fsSL https://metastac.kr/install.sh | bash`
- [View on GitHub](https://github.com/eliotstocker/MetaStackr)

## How MetaStackr Works 

An end-to-end automated workflow from local branches to production merge.

### Push & Open Stacked PRs
- **Atomic Commits**: Modify child submodules and parent meta-repo simultaneously. Commit pointers align automatically.
- **Unified Push & PRs**: Push branches and open Pull Requests across all modified repositories with a single `git meta create-pr` command.

### Automatic Dependency Locking
- **Webhook Ingestion**: MetaStackr detects PR creation and links root meta PRs with their child submodule PRs.
- **Prevent Premature Merges**: Attaches a status check (`meta-repo/sync`) to block parent merges while child PRs remain open.

### Real-Time Pointer Synchronization
- **Track Submodule Merges**: When child PRs are merged, MetaStackr captures the new target commit SHAs.
- **Auto-Update Parent**: MetaStackr automatically bumps root submodule pointers to the new SHAs, eliminating detached HEADs.

### Safe, Autonomous Root Merge
- **Topological Merge**: As dependencies clear, MetaStackr cascades merges across the tree in topological order.
- **Zero-Touch Completion**: Auto-merges the parent meta PR once all children are merged, or removes the blocker check for final review.

## Why tho? 

The difference between traditional manual Git submodule pain and MetaStackr automation.

| Problem | Without MetaStackr | With MetaStackr |
| :--- | :--- | :--- |
| **Submodule Drift** | Detached HEAD states and forgotten pointer updates | Coordinated multi-repo checkouts and automated pointer bumping |
| **Merge Order & Safety** | Root PR merged before dependencies -> broken CI | Topologically locked status checks & automated cascade merging |
| **Context Switching** | Manually opening, tracking & merging 4+ separate PRs | Single-command PR creation and unified multi-repo tracking |
| **AI Agent Friction** | Coding agents break submodule pointers with raw Git commands | Machine-readable agent rules (`git meta agents`) and deterministic `--json` CLI |

## Features 

Built for high-concurrency multi-repository engineering teams.

### Optimistic Concurrency Control
Reconciliation loops enforce strict `lock_version` validation to eliminate race conditions during high-volume webhook deliveries.

### Topological DAG Resolution
Evaluates multi-repo dependency graphs in real time, determining optimal merge order and aborting immediately if a circular dependency is detected.

### Fault-Tolerant Saga Protocol
Executes merges topologically in parallel depth batches, halting safely on conflicts without force-reverting base branches.

### Unified Checks Matrix
Consolidates submodule approvals, branch pointer alignments, and CI statuses into a single GitHub Check Run named `meta-repo/sync`.

### Proactive Git Hooks
Installs `post-checkout` and `pre-commit` hooks in `.git/hooks` to verify submodule branch alignment and alert on detached HEAD states locally.

### Zero-Trust Privacy
Operates strictly on Git metadata (branch names and commit SHAs) by default without pulling or storing your source code on remote servers.

## IDE & Browser Extensions 

Integrate MetaStackr directly into your browser, VS Code, and JetBrains IDEs.

### Chrome Extension
Native PR matrix tab, real-time submodule synchronization status, and check run overlays directly on GitHub and GitLab.

**Status: Available** | [Install Extension](https://github.com/eliotstocker/MetaStackr/tree/main/extensions/chrome)

### VS Code Extension
Unified Source Control panel showing multi-repo worktree changes, staging with atomic coordinated commits, and automatic pointer alignment.

**Status: Available** | [View Extension](https://github.com/eliotstocker/MetaStackr/tree/main/extensions/vscode)

### JetBrains Plugin
Dedicated MetaStackr Tool Window for IntelliJ IDEA, PyCharm, WebStorm, and GoLand with multi-repo drift tracking, atomic commits, and VCS checkin interception.

**Status: Available** | [View Plugin](https://github.com/eliotstocker/MetaStackr/tree/main/extensions/jetbrains)

## `git meta` Interactive Terminal 

Operate natively using standard Git commands. `git meta` coordinates your multi-repo workspace, keeping branches aligned, enforcing bottom-up pushes, and preventing dangling pointers.

- `git meta status`: Inspect local submodule drift alongside remote PR and cascade merge status.
- `git meta checkout [-b] <branch>`: Safely switch or create feature branches across the parent meta-repo and all submodules.
- `git meta commit -m "<msg>"`: Create coordinated atomic commits across modified submodules and update parent commit pointers.
- `git meta push`: Enforce bottom-up pushes to remote origins before updating parent pointer references.
- `git meta create-pr`: Open Pull Requests across all modified repositories and the parent meta-repo in one step.
- `git meta sync`: Fetch upstream changes, fast-forward submodules, and align root pointers to main.
- `git meta rebase <upstream>`: Perform two-phase rebasing across child submodules and parent references safely.
- `git meta retry-merge --pr <id>`: Manually re-trigger cascade merge execution from unmerged dependency nodes.
- `git meta agents`: Output standardized machine-readable guidelines and operation rules for AI coding agents.
- `git meta init`: Onboard your workspace with backend tracking, automated Git hooks, and webhook integration.

## Built for you *and* your AI coding agents 

Submodule orchestration rules and machine-readable protocols built directly into the CLI:

- **Standardized Agent Rules**: Run `git meta agents` to export workspace guidelines (`AGENTS.md`) preventing AI agents from executing raw Git commands that corrupt submodule pointers.
- **Deterministic JSON Output**: Every `git meta` command accepts `--json` for predictable state parsing and structured agent tool integration.
- **Autonomous Coordination**: Agents can safely inspect drift, create branches, execute bottom-up pushes, and trigger cascade merges without breaking pointer alignment.
- **Dynamic Feedback**: Status checks and webhooks report topological dependency resolution dynamically back to AI agent workflows.

---

# Page: config-details

# MetaStackr Configuration Details

MetaStackr coordinates multi-repo submodules using a config file. Below is the configuration structure and edge definitions.

## Schema Specifications

- **name**: Name of the parent meta-repository.
- **allowCodePull**: Boolean flag (default `false`) indicating if the orchestration server is authorized to pull/clone repository source code.
- **submodules**: List of tracked submodules.
  - **path**: The filesystem path relative to the root meta-repository.
  - **repo**: The remote GitHub repository identifier (e.g. `org/sub-repo`).
  - **dependsOn**: Array of submodule paths that must be merged/processed BEFORE this submodule.

## Opt-In Code Access Benefits

When `allowCodePull` is enabled (`true`), the backend gains permission to cache and inspect files, unlocking the following features:
1. **Static Import Dependency Analysis**: Auto-builds topological DAGs by scanning file imports directly.
2. **Local Dry-Run Reconciliations**: Simulates merges locally to detect conflicts and raise warnings before writing pointer updates back to remote origins.
3. **Check Run Diff Integration**: Formats detailed warnings in the check run status showing exact line differences in mismatching submodule files.