mergetrain 0.1.0__tar.gz

mergetrain-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# mergetrain runtime state (queue DB, logs, temporary worktrees)
+.mergetrain/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Dashboard authoring dependencies and cache
+dashboard/node_modules/
+dashboard/.npm-cache/
+
+# IDE / editor
+.idea/
+.vscode/
+
+# OS
+.DS_Store

mergetrain-0.1.0/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md
+
+This repository contains `mergetrain`, a local deploy train for coding-agent
+worktrees.
+
+## Agent operating rules
+
+1. Work on a task-specific branch and worktree.
+2. Commit all changes before enqueueing.
+3. Do not push deploy refs directly.
+4. Read `mergetrain doctor --json` or `mergetrain status --json` before deciding
+   the next action.
+5. Use `--auto` only after explicit unattended-deploy approval.
+6. Let one runner or daemon own merge, test, push, and verify.
+7. Fix blocked or failed work in the owning branch, commit a clean result, then
+   enqueue a new job.
+
+## Useful commands
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+PYTHONPATH=src python -m mergetrain agent-contract --json
+PYTHONPATH=src python -m mergetrain init --project demo
+```
+
+## Boundaries
+
+- Never add provider-specific credentials to examples or tests.
+- Keep core provider-neutral; adapters belong under `integrations/` or in a
+  separate service repository.
+- Gate and verify commands run through `/bin/sh`; document new shell execution
+  behavior clearly.

mergetrain-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-07-17
+
+First public alpha release.
+
+- Preserve exact validated train identity for a later approval-gated deploy.
+- Rebuild validated trains on the current integration ref and reject changed task HEADs.
+- Exclude validated-but-not-deployed branches from destructive GC.
+- Fence batch claims and state transitions with unique lease tokens.
+- Heartbeat, cancel, and time out long-running Git and shell subprocesses.
+- Reject explicitly empty deploy refs and invalid queue timing at config load.
+- Return truthful JSON outcomes and non-zero exit codes for blocked/failed jobs.
+- Version SQLite migrations with `PRAGMA user_version`.
+- Add a loopback-first, read-only live dashboard with SSE and polling fallback.
+- Distinguish browser connectivity from runner activity and explain the current gate, command, scope, and Activity milestones.
+- Record structured runner phases and explicit lock heartbeat timestamps.
+- Redact lease tokens and local filesystem paths from dashboard payloads.
+- SQLite-backed local deploy queue.
+- Runner lock with PID liveness checks.
+- Git worktree merge train execution.
+- Configurable pre-push gates and post-push verify hooks.
+- Atomic push refs.
+- Auto-only daemon boundary.
+- JSON-first agent contract, status, doctor, and GC output.

mergetrain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mergetrain contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mergetrain-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: mergetrain
+Version: 0.1.0
+Summary: A local-first merge-and-deploy queue for coding-agent worktrees
+Project-URL: Homepage, https://github.com/yongjip/mergetrain
+Project-URL: Documentation, https://github.com/yongjip/mergetrain/tree/main/docs
+Project-URL: Issues, https://github.com/yongjip/mergetrain/issues
+Project-URL: Changelog, https://github.com/yongjip/mergetrain/blob/main/CHANGELOG.md
+Author: mergetrain contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,deploy,git,llm,merge-train,sqlite,worktree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatchling>=1.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# mergetrain
+
+**A local-first merge-and-deploy queue for coding-agent worktrees.**
+
+mergetrain keeps its queue, coordination, merge assembly, and gate execution on
+your machine. Coding agents commit in separate worktrees; one local runner
+serializes their branches, validates the exact train, and pushes only after
+explicit approval. No hosted merge-queue service or CI provider is required.
+
+> **Local-first, not local-only.** Queue state, locking, train assembly, and
+> gates stay local. Configured Git remotes and post-deploy verification may
+> still use external services.
+
+> Status: alpha (`v0.1.0`). The core is implemented and tested; interfaces may still change. Built to scratch my own itch first — published in case it scratches yours too.
+
+---
+
+## The problem
+
+When several Codex/Claude/LLM sessions work on the same repo at the same time, each in its own worktree and branch, a few things break down:
+
+- It's unclear what order branches should land on the deploy branch.
+- If an agent runs `git push` itself, sessions overwrite each other or ship unverified combinations.
+- Each branch passes its own tests, but the *merge of several branches in sequence* can still be broken.
+- Conflicts, stale locks, duplicate enqueues, and "is the daemon allowed to deploy this?" all become judgment calls — and you do not want an LLM guessing at those.
+
+Hosted merge queues (GitHub Merge Queue, GitLab Merge Trains, Mergify, Aviator, bors) solve a related problem, but they are PR-first, remote-CI-first, and platform-first. mergetrain is for the other workflow: **local-agent, worktree-first, deploy-branch-first.**
+
+## How it works
+
+```
+  agent A ─┐
+  agent B ─┼─▶  mergetrain queue (SQLite)  ─▶  one runner (lock)
+  agent C ─┘                                      │
+                                                  ▼
+                          fresh integration worktree @ origin/main
+                                merge A → B → C  (the train)
+                                          │
+                            gates (diff-check, tests, scans…)
+                                          │
+                              git push --atomic  →  deploy refs
+                                          │
+                                  post-push verify hooks
+```
+
+Agents commit their work and **enqueue** a branch. They never push deploy refs themselves. A single **runner** (or unattended **daemon**) claims the queue, builds a throwaway integration worktree on top of your integration branch, merges the queued branches in FIFO order, runs your gates once over the whole train, and only then pushes — atomically — to your deploy refs. Every important state is readable as JSON so an agent can follow the result instead of inferring it.
+
+## Quickstart
+
+```bash
+# Install the public alpha
+python -m pip install mergetrain
+
+# 1. Scaffold config + agent docs in your repo
+mergetrain init --project my-app --write
+
+# 2. An agent finishes work, commits, and enqueues its branch
+mergetrain enqueue --task "add health check" --branch agent/health --capture-sha
+
+# 3. See the queue and lock state (machine-readable)
+mergetrain status --json
+
+# 4. Watch the queue and runner locally (read-only)
+mergetrain dashboard
+
+# 5. Validate the whole train without shipping
+mergetrain run-batch --validate-only
+
+# 6. Ship — explicit, never implicit
+mergetrain run-batch --deploy
+```
+
+For an unreleased source checkout, use `python -m pip install -e .` instead.
+
+The dashboard is served at `http://127.0.0.1:8765/`. It streams structured
+runner phases, heartbeat freshness, job order, blocked reasons, recent activity,
+the exact current gate and command template, and the next safe action. `CONNECTED`
+describes the browser's data stream; `RUNNER ACTIVE` separately describes the
+process that owns the train. It has no mutation endpoints or deploy controls.
+
+Validation records an exact train identity, including every task HEAD and the
+integration base used for the check. The later deploy reassembles that same
+train on the current integration ref, reruns all gates, and refuses changed
+task branches. Newly queued work is not silently added to the approved train.
+
+Every agent-facing command is non-interactive and requires explicit intent: `--validate-only` or `--deploy`, never a bare `run-batch`.
+
+## Core concepts
+
+- **Job** — one task branch waiting in the queue, with the SHAs captured at enqueue time.
+- **Validated train** — an exact, deployable group of jobs that passed gates together and is waiting for explicit deploy approval.
+- **Runner lock** — gives every claim a unique lease token, heartbeats through long-running commands, and prevents a stale runner from overwriting a newer owner.
+- **Integration worktree** — a disposable, detached Git worktree built on your integration ref. The runner merges here, so agents never checkout or push the deploy branch.
+- **Gate** — a verification command (diff-check, tests, secret-scan…) run once over the assembled train *before* push. A gate failure means nothing ships.
+- **Verify hook** — a command run *after* push to confirm the deploy is live.
+- **Auto job** — a job enqueued with `--auto`, the only kind the unattended daemon will touch. Manual jobs are left for a human-initiated runner.
+
+Full reference in [docs/design.md](./docs/design.md) and the [CLI reference](./docs/cli.md).
+
+## When to use mergetrain
+
+| Your workflow is… | Use |
+|---|---|
+| PR-first, remote-CI-first, hosted platform | GitHub / GitLab merge queue, Mergify, Aviator |
+| Local agents in worktrees shipping to a deploy branch | **mergetrain** |
+
+mergetrain is **not** a general-purpose job queue (it won't replace Celery/RQ/Sidekiq), a CI provider, or a deploy provider. The core is provider-neutral: your push targets, test commands, and deploy checks live in config, not in mergetrain.
+
+## Configuration
+
+A single `.mergetrain.yaml` at your repo root holds all policy. The core stays neutral; you bring the commands.
+
+```yaml
+project:
+  name: my-app
+
+git:
+  remote: origin
+  integration_branch: main
+  push_refs: [main]          # atomic push targets on deploy
+
+queue:
+  lock_ttl_minutes: 30
+  heartbeat_interval_seconds: 10
+  command_timeout_seconds: 3600
+
+gates:
+  - name: diff-check
+    run: git diff --check ${integration_ref}..HEAD
+  - name: tests
+    run: python -m pytest
+
+deploy:
+  verify:
+    - name: live-health
+      run: curl -fsS https://example.invalid/health
+```
+
+See the [config reference](./docs/config.md) for the full schema, placeholders, and environment variables.
+
+## For AI agents
+
+mergetrain is designed so an agent can operate it from a short contract and JSON output, without guessing:
+
+1. Work on a task-specific branch in its own worktree.
+2. Commit before enqueuing.
+3. Never push deploy refs directly.
+4. Read `mergetrain doctor --json` / `status --json` before acting.
+5. Use `--auto` only after explicit human approval for unattended deploys.
+6. Let one runner or daemon own merge → test → push → verify.
+7. Fix `blocked`/`failed` work on the owning branch and enqueue a fresh clean job.
+
+`mergetrain init` writes `AGENTS.mergetrain.md` / `CLAUDE.mergetrain.md` so your agents pick this up automatically.
+
+## Documentation
+
+- [Quickstart](./docs/quickstart.md) · [Install](./docs/install.md)
+- [CLI reference](./docs/cli.md) — every command and flag
+- [Config reference](./docs/config.md) — `.mergetrain.yaml` schema, placeholders, env vars
+- [Design & architecture](./docs/design.md) — the model, data model, and safety guarantees
+- [Daemon](./docs/daemon.md) · [Failure modes](./docs/failure-modes.md) — operating it day to day
+- [Manage from your phone](./docs/mobile.md) — drive mergetrain via Cowork Dispatch
+- [Agent contract](./docs/agent-contract.md) — the rules agents follow
+- [Security](./docs/security.md) · [Adapter pattern](./docs/adapter-pattern.md) · [Development](./docs/development.md) · [Release](./docs/release.md)
+
+## Status
+
+`v0.1.0`, alpha. The core — queue, runner lock, merge train, gates, atomic push, auto-only daemon, JSON `doctor`/`status`, and the local read-only dashboard — is implemented with a passing test suite. Built for my own multi-agent workflow first; issues and ideas welcome. Review your config trust boundary, gate commands, and secret handling before enabling unattended deploys — see [security](./docs/security.md).
+
+## License
+
+Released under the [MIT License](./LICENSE).

mergetrain-0.1.0/README.md

@@ -0,0 +1,172 @@
+# mergetrain
+
+**A local-first merge-and-deploy queue for coding-agent worktrees.**
+
+mergetrain keeps its queue, coordination, merge assembly, and gate execution on
+your machine. Coding agents commit in separate worktrees; one local runner
+serializes their branches, validates the exact train, and pushes only after
+explicit approval. No hosted merge-queue service or CI provider is required.
+
+> **Local-first, not local-only.** Queue state, locking, train assembly, and
+> gates stay local. Configured Git remotes and post-deploy verification may
+> still use external services.
+
+> Status: alpha (`v0.1.0`). The core is implemented and tested; interfaces may still change. Built to scratch my own itch first — published in case it scratches yours too.
+
+---
+
+## The problem
+
+When several Codex/Claude/LLM sessions work on the same repo at the same time, each in its own worktree and branch, a few things break down:
+
+- It's unclear what order branches should land on the deploy branch.
+- If an agent runs `git push` itself, sessions overwrite each other or ship unverified combinations.
+- Each branch passes its own tests, but the *merge of several branches in sequence* can still be broken.
+- Conflicts, stale locks, duplicate enqueues, and "is the daemon allowed to deploy this?" all become judgment calls — and you do not want an LLM guessing at those.
+
+Hosted merge queues (GitHub Merge Queue, GitLab Merge Trains, Mergify, Aviator, bors) solve a related problem, but they are PR-first, remote-CI-first, and platform-first. mergetrain is for the other workflow: **local-agent, worktree-first, deploy-branch-first.**
+
+## How it works
+
+```
+  agent A ─┐
+  agent B ─┼─▶  mergetrain queue (SQLite)  ─▶  one runner (lock)
+  agent C ─┘                                      │
+                                                  ▼
+                          fresh integration worktree @ origin/main
+                                merge A → B → C  (the train)
+                                          │
+                            gates (diff-check, tests, scans…)
+                                          │
+                              git push --atomic  →  deploy refs
+                                          │
+                                  post-push verify hooks
+```
+
+Agents commit their work and **enqueue** a branch. They never push deploy refs themselves. A single **runner** (or unattended **daemon**) claims the queue, builds a throwaway integration worktree on top of your integration branch, merges the queued branches in FIFO order, runs your gates once over the whole train, and only then pushes — atomically — to your deploy refs. Every important state is readable as JSON so an agent can follow the result instead of inferring it.
+
+## Quickstart
+
+```bash
+# Install the public alpha
+python -m pip install mergetrain
+
+# 1. Scaffold config + agent docs in your repo
+mergetrain init --project my-app --write
+
+# 2. An agent finishes work, commits, and enqueues its branch
+mergetrain enqueue --task "add health check" --branch agent/health --capture-sha
+
+# 3. See the queue and lock state (machine-readable)
+mergetrain status --json
+
+# 4. Watch the queue and runner locally (read-only)
+mergetrain dashboard
+
+# 5. Validate the whole train without shipping
+mergetrain run-batch --validate-only
+
+# 6. Ship — explicit, never implicit
+mergetrain run-batch --deploy
+```
+
+For an unreleased source checkout, use `python -m pip install -e .` instead.
+
+The dashboard is served at `http://127.0.0.1:8765/`. It streams structured
+runner phases, heartbeat freshness, job order, blocked reasons, recent activity,
+the exact current gate and command template, and the next safe action. `CONNECTED`
+describes the browser's data stream; `RUNNER ACTIVE` separately describes the
+process that owns the train. It has no mutation endpoints or deploy controls.
+
+Validation records an exact train identity, including every task HEAD and the
+integration base used for the check. The later deploy reassembles that same
+train on the current integration ref, reruns all gates, and refuses changed
+task branches. Newly queued work is not silently added to the approved train.
+
+Every agent-facing command is non-interactive and requires explicit intent: `--validate-only` or `--deploy`, never a bare `run-batch`.
+
+## Core concepts
+
+- **Job** — one task branch waiting in the queue, with the SHAs captured at enqueue time.
+- **Validated train** — an exact, deployable group of jobs that passed gates together and is waiting for explicit deploy approval.
+- **Runner lock** — gives every claim a unique lease token, heartbeats through long-running commands, and prevents a stale runner from overwriting a newer owner.
+- **Integration worktree** — a disposable, detached Git worktree built on your integration ref. The runner merges here, so agents never checkout or push the deploy branch.
+- **Gate** — a verification command (diff-check, tests, secret-scan…) run once over the assembled train *before* push. A gate failure means nothing ships.
+- **Verify hook** — a command run *after* push to confirm the deploy is live.
+- **Auto job** — a job enqueued with `--auto`, the only kind the unattended daemon will touch. Manual jobs are left for a human-initiated runner.
+
+Full reference in [docs/design.md](./docs/design.md) and the [CLI reference](./docs/cli.md).
+
+## When to use mergetrain
+
+| Your workflow is… | Use |
+|---|---|
+| PR-first, remote-CI-first, hosted platform | GitHub / GitLab merge queue, Mergify, Aviator |
+| Local agents in worktrees shipping to a deploy branch | **mergetrain** |
+
+mergetrain is **not** a general-purpose job queue (it won't replace Celery/RQ/Sidekiq), a CI provider, or a deploy provider. The core is provider-neutral: your push targets, test commands, and deploy checks live in config, not in mergetrain.
+
+## Configuration
+
+A single `.mergetrain.yaml` at your repo root holds all policy. The core stays neutral; you bring the commands.
+
+```yaml
+project:
+  name: my-app
+
+git:
+  remote: origin
+  integration_branch: main
+  push_refs: [main]          # atomic push targets on deploy
+
+queue:
+  lock_ttl_minutes: 30
+  heartbeat_interval_seconds: 10
+  command_timeout_seconds: 3600
+
+gates:
+  - name: diff-check
+    run: git diff --check ${integration_ref}..HEAD
+  - name: tests
+    run: python -m pytest
+
+deploy:
+  verify:
+    - name: live-health
+      run: curl -fsS https://example.invalid/health
+```
+
+See the [config reference](./docs/config.md) for the full schema, placeholders, and environment variables.
+
+## For AI agents
+
+mergetrain is designed so an agent can operate it from a short contract and JSON output, without guessing:
+
+1. Work on a task-specific branch in its own worktree.
+2. Commit before enqueuing.
+3. Never push deploy refs directly.
+4. Read `mergetrain doctor --json` / `status --json` before acting.
+5. Use `--auto` only after explicit human approval for unattended deploys.
+6. Let one runner or daemon own merge → test → push → verify.
+7. Fix `blocked`/`failed` work on the owning branch and enqueue a fresh clean job.
+
+`mergetrain init` writes `AGENTS.mergetrain.md` / `CLAUDE.mergetrain.md` so your agents pick this up automatically.
+
+## Documentation
+
+- [Quickstart](./docs/quickstart.md) · [Install](./docs/install.md)
+- [CLI reference](./docs/cli.md) — every command and flag
+- [Config reference](./docs/config.md) — `.mergetrain.yaml` schema, placeholders, env vars
+- [Design & architecture](./docs/design.md) — the model, data model, and safety guarantees
+- [Daemon](./docs/daemon.md) · [Failure modes](./docs/failure-modes.md) — operating it day to day
+- [Manage from your phone](./docs/mobile.md) — drive mergetrain via Cowork Dispatch
+- [Agent contract](./docs/agent-contract.md) — the rules agents follow
+- [Security](./docs/security.md) · [Adapter pattern](./docs/adapter-pattern.md) · [Development](./docs/development.md) · [Release](./docs/release.md)
+
+## Status
+
+`v0.1.0`, alpha. The core — queue, runner lock, merge train, gates, atomic push, auto-only daemon, JSON `doctor`/`status`, and the local read-only dashboard — is implemented with a passing test suite. Built for my own multi-agent workflow first; issues and ideas welcome. Review your config trust boundary, gate commands, and secret handling before enabling unattended deploys — see [security](./docs/security.md).
+
+## License
+
+Released under the [MIT License](./LICENSE).

mergetrain-0.1.0/dashboard/AGENTS.md

@@ -0,0 +1,15 @@
+# Prototype Instructions
+
+Run the local server yourself and open the preview in the browser available to this environment. Do not give the user server-start instructions when you can run it.
+
+Before making substantial visual changes, use the Product Design plugin's `get-context` skill when the visual source is unclear or no longer matches the current goal. When the user gives durable prototype-specific design feedback, preferences, or decisions, record them in `AGENTS.md`.
+
+When implementing from a selected generated mock, treat that image as the source of truth for layout, component anatomy, density, spacing, color, typography, visible content, and hierarchy.
+
+## Selected direction
+
+- Use the approved hybrid: Live Track hierarchy (direction 3) with Signal Board clarity (direction 1).
+- Keep the interface read-only, single-repository, desktop-first, and local-only for v0.1.
+- Show actual runner phases, heartbeat freshness, blocked reason, activity, and the next safe action.
+- Use a warm off-white canvas, dark ink, blue active state, green success, amber attention, red failure, thin borders, and restrained radii.
+- Avoid literal train illustrations and action controls; the track is an information model, not decoration.

mergetrain-0.1.0/dashboard/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#fbfaf7" />
+    <meta name="description" content="Live, read-only local mergetrain status" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <title>mergetrain · live local status</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>