worktree-for-agents 0.0.0-stage → 1.0.1

package/GUIDE.md

@@ -0,0 +1,45 @@
+You are going to implement a change, run a spec, or start a flow. Do you want to create a worktree to work in isolation?
+
+This guide explains how to use the `worktree-for-agents` manager to work
+isolated in a worktree before touching the main branch.
+
+## The seven tools
+
+The MCP service exposes exactly seven tools:
+
+- `worktree_create`: creates a worktree and its branch for a work identifier.
+- `worktree_complete`: merges the worktree into the base branch and removes the worktree.
+- `worktree_cleanup`: removes the worktree and its branch without merging.
+- `worktree_recover`: recovers a pending transaction by its identifier.
+- `worktree_list`: lists the repository worktrees.
+- `worktree_prune`: prunes worktree information that no longer exists.
+- `worktree_status`: shows the status of a work item.
+
+All of them require an absolute Git repository path in `repo`.
+
+## When to offer the worktree
+
+Before working on the main branch, offer to create a worktree with
+`worktree_create`. Work inside the worktree and then merge with
+`worktree_complete`. If the work is discarded, use `worktree_cleanup`.
+
+## Launch without bin
+
+The package exposes no bin or `npx`. The MCP service is launched with Node and the
+absolute package path:
+
+```sh
+node <package>/mcp-server.mjs
+```
+
+The CLI is launched the same way:
+
+```sh
+node <package>/worktree.mjs --version
+```
+
+The installation diagnostics are obtained with:
+
+```sh
+node <package>/setup.mjs
+```

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# Worktree manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standalone manager to create, complete, clean up, and recover worktrees of a
+Git repository. The project does not know FlowTask and does not depend on its paths, legacy
+refs, or coordination mechanisms.
+
+## Requirements
+
+- **Python 3.9 or later.** The entrypoint only checks that `python3` is
+  available on the `PATH`; the 3.9 floor is validated by the package postinstall
+  and `node <package>/setup.mjs`. The package uses only the standard library.
+- **Git 2.17.0 or later**, for `git worktree remove`, which is the most
+  recent command used by the manager. The test baseline is Git 2.54.0. The
+  manager does not check the Git version at runtime.
+- **Node 18 or later** for the `mcp-server.mjs`, `worktree.mjs`
+  and `setup.mjs` launchers.
+- **`bash`** to run the test suites.
+
+## Installation
+
+The manager is distributed as the npm package `worktree-for-agents`, version
+`1.0.0`, with no bin or `npx`:
+
+```sh
+npm install -g worktree-for-agents@latest
+pnpm add -g worktree-for-agents@latest
+```
+
+Check the installation diagnostics:
+
+```sh
+node <package>/setup.mjs
+```
+
+The repository clone is for development only. There is no `pip install` and no
+dependencies to resolve: the manager uses only the Python standard
+library. Once installed, the manager works without a network.
+
+## Quick start
+
+Global options go before the subcommand and `--repo` requires an absolute
+path.
+
+```text
+worktree.sh [--repo ABS] [--config ABS] [--json] create <id> [--base BRANCH] [--init-submodules] [--prepare] [--verify]
+worktree.sh [globals] complete <id> [--preserve-dirty] [--title TEXT] [--body TEXT]
+worktree.sh [globals] cleanup <id> [--discard]
+worktree.sh [globals] recover [<transaction-id>]
+worktree.sh [globals] prune
+worktree.sh [globals] list
+```
+
+Target-direct operates on the repository given in `--repo` and does not create a
+parent worktree nor modify its `HEAD`. Its syntax places `--parent-repo`
+after the action and requires `--submodule-path` in `create`:
+
+```text
+worktree.sh [--repo ABS] target-direct <action> <id> --parent-repo <parent> [--target submodule] [--submodule-path <REL>] [--base BRANCH] [--link-parent staged-only] [--descriptor PATH]
+```
+
+The actions are `create`, `link-parent`, `abort`, `complete` and `recover`, and the
+only supported link mode is `--link-parent staged-only`.
+
+`--json` publishes a single JSON document. `--request-json <file|->` publishes
+the same nine-key envelope used by the MCP transport, and optionally accepts `--json`.
+A dry run of `create` publishes `planned: true` and creates no
+worktree or branch.
+
+The MCP service is published over stdio. From the installed package it is launched without
+bin:
+
+```sh
+node <package>/mcp-server.mjs
+```
+
+The CLI is used the same way:
+
+```sh
+node <package>/worktree.mjs --version
+```
+
+The MCP `initialize` publishes the guide in `instructions`:
+
+```text
+You are going to implement a change, run a spec, or start a flow. Do you want to create a worktree to work in isolation?
+```
+
+For development, the transport also starts from the checkout:
+
+```sh
+PYTHONPATH=. python3 -m worktree_manager.mcp_transport
+```
+
+## Configuration
+
+The configuration is an optional `key=value` file, selected with
+`--config` or taken from `.worktree-manager.conf` at the repository root.
+The eleven keys and their default values are:
+
+| Key | Default | Restriction |
+|---|---|---|
+| `worktrees_dir` | `.worktrees` | Must not start with `-` |
+| `branch_prefix` | `worktree/` | — |
+| `state_dir` | `worktree-manager` | Safe relative path |
+| `backup_dir` | `backups` | Not an absolute path and contains no `..` |
+| `backup_ref_prefix` | `worktree-manager/backups` | No `..` |
+| `lock_dir` | `locks` | Safe relative path |
+| `prepare_command` | `''` (empty) | Required when `prepare_enabled=true` |
+| `verify_command` | `''` (empty) | Required when `verify_enabled=true` |
+| `prepare_enabled` | `false` | `true` or `false` |
+| `verify_enabled` | `false` | `true` or `false` |
+| `preserve_dirty` | `false` | `true` or `false` |
+
+Each key may appear only once. Unknown keys, malformed lines, invalid booleans, and unsafe paths are rejected as
+`invalid_configuration` with exit code `3`. The environment variable
+`WORKTREE_MANAGER_<KEY>`, with the key in uppercase, overrides the value
+read from the file.
+
+## Architecture
+
+`worktree.sh` is the entrypoint and delegates the lifecycle to the Python
+package `worktree_manager`, which runs with `python3 -m worktree_manager`. The package
+is the only lifecycle implementation: there is no alternative shell engine.
+
+The package is organized in modules with one responsibility each:
+
+| Module | Responsibility |
+| --- | --- |
+| `worktree_manager.cli` | Command dispatcher, target-direct dispatch, and output contract. |
+| `worktree_manager.configuration` | Reading and validating the `key=value` configuration. |
+| `worktree_manager.models` | Shared domain values: results, errors, and identities. |
+| `worktree_manager.output` | Publishing the result as readable text or as JSON. |
+| `worktree_manager.git_repository` | Shared Git access for the lifecycle modules. |
+| `worktree_manager.worktree_lifecycle` | `create`, `complete`, `cleanup`, and `prune` operations. |
+| `worktree_manager.commit_message` | Deterministic closing message composition and neutral fallback. |
+| `worktree_manager.target_direct_adapter` | Target-direct operations on a submodule. |
+| `worktree_manager.recovery_manager` | Recovery of pending transactions. |
+| `worktree_manager.transaction_journal` | Durable transaction and link journal. |
+| `worktree_manager.backup_store` | Retained backup references. |
+| `worktree_manager.lock_manager` | Mutual exclusion between processes. |
+| `worktree_manager.state_digest` | Canonical digest of the repository state and of a plan. |
+| `worktree_manager.mcp_server` | MCP service published over stdio. |
+| `worktree_manager.mcp_contract` | Strict versioned request and envelope contracts. |
+| `worktree_manager.mcp_operations` | Facade over the lifecycle and recovery services. |
+| `worktree_manager.mcp_transport` | Stdio transport entrypoint. |
+
+The package also contains the package marker `__init__.py` and the
+entrypoint `__main__.py`, which is what `python3 -m worktree_manager` runs.
+
+## Tests
+
+```sh
+bash tests/cli-usage.sh
+bash tests/cli-json.sh
+bash tests/compatibility.sh
+bash tests/smoke.sh
+bash tests/parity.sh
+PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_*.py'
+PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_mcp*.py' -v
+```
+
+## Documentation
+
+- [CLI output contract](docs/cli-contract-v1.md) — contract.
+- [MCP service contract](docs/mcp-contract.md) — contract.
+- [Installation and usage guide](docs/installation.md) — guide.
+- [History bash → Python](docs/history-bash-to-python.md) — notes, not a contract.
+
+Contracts pin the verifiable behavior. The guide explains how to use it.
+The history records the transition and does not replace the contracts.
+
+## Source and distribution
+
+This repository is the source of truth for the implementation, the contracts,
+the installation, and the manager history.
+
+The consumer that integrates this repository documents the adapter, the bridge, and
+the submodule boundary: **that integration documentation lives in the
+consumer repository**. The manager does not keep a vendored copy of itself
+and does not know the consumer.

package/docs/installation.md

@@ -0,0 +1,213 @@
+# Installation and usage of the worktree manager
+
+This guide explains how to install the manager as an npm package and how to use it
+on a test repository. Integration with a specific consumer
+is documented in the repository that integrates the manager.
+
+The examples use `$HOME` because `--repo` requires an absolute path. `<package>`
+is the installed package path.
+
+## 1. Requirements
+
+Check the available versions:
+
+```sh
+python3 --version
+git --version
+node --version
+```
+
+- **Python 3.9 or later.** The package postinstall checks the
+  3.9 floor and fails visibly if it is missing or older. `node
+  <package>/setup.mjs` reports the detected interpreter.
+- **Git 2.17.0 or later**, for `git worktree remove`. The test baseline is
+  Git 2.54.0. The manager does not check the Git version at runtime.
+- **Node 18 or later** for the `mcp-server.mjs`, `worktree.mjs`
+  and `setup.mjs` launchers.
+- **`bash`** to run the test suites.
+
+## 2. Install the package
+
+```sh
+npm install -g worktree-for-agents@latest
+pnpm add -g worktree-for-agents@latest
+```
+
+Check the diagnostics:
+
+```sh
+node <package>/setup.mjs
+```
+
+The package exposes no bin or `npx`: the MCP is launched with `node
+<package>/mcp-server.mjs` and the CLI with `node <package>/worktree.mjs`. The
+repository clone is for development only. There is no `pip install` and no
+dependencies to resolve: the manager uses only the Python standard
+library. Once installed, the manager works without a network.
+
+## 3. A test repository
+
+The manager requires the worktree path to be ignored by Git, and
+`.worktrees/` in `.gitignore` satisfies that condition.
+
+```sh
+mkdir "$HOME/demo" && cd "$HOME/demo"
+git init -b main
+git config user.name "Demo"
+git config user.email "demo@example.invalid"
+printf 'base\n' > file
+printf '.worktrees/\n' > .gitignore
+git add file .gitignore
+git commit -m "base"
+```
+
+Create the worktree:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" create demo --base main
+```
+
+What each step leaves behind:
+
+- `git init` creates the repository and its `main` branch.
+- The initial commit pins the base on top of which the worktree is built.
+- `create` creates the `worktree/demo` branch, the worktree at `$HOME/demo/.worktrees/demo`
+  and the transaction journal in the repository state directory.
+
+Check the status:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" list
+```
+
+Work inside the worktree and then merge it:
+
+```sh
+cd "$HOME/demo/.worktrees/demo"
+printf 'change\n' >> file
+git add file
+git commit -m "change"
+cd "$HOME/demo"
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" complete demo --base main
+```
+
+`complete` requires the repository to be on the base branch, the worktree to have
+no uncommitted changes, and the destination to have none either, unless
+`--preserve-dirty` is used. When finished, the change is merged as a squash
+commit on `main`, and the worktree and its branch are removed.
+
+To leave an expressive closing commit, pass `--title` and optionally
+`--body`:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" complete demo --base main \
+  --title "Demo closing" --body "Delivery: merged change. Reason: verification."
+```
+
+If `--title` is not passed, the manager uses the generic fallback:
+`Complete <work_id> (generic closure)` with the body
+`No delivery description was available at closure time.`.
+
+## 4. Configuration
+
+The configuration is a `key=value` file. The manager reads it from
+`.worktree-manager.conf` at the repository root, or from the file passed
+with `--config`, which must exist and be an absolute path. If both are
+given, `--config` wins. Afterwards, the environment variable
+`WORKTREE_MANAGER_<KEY>`, with the key in uppercase, overrides the value
+read from the file.
+
+The eleven keys and their default values are:
+
+| Key | Default | Restriction |
+|---|---|---|
+| `worktrees_dir` | `.worktrees` | Must not start with `-` |
+| `branch_prefix` | `worktree/` | — |
+| `state_dir` | `worktree-manager` | Safe relative path |
+| `backup_dir` | `backups` | Not an absolute path and contains no `..` |
+| `backup_ref_prefix` | `worktree-manager/backups` | No `..` |
+| `lock_dir` | `locks` | Safe relative path |
+| `prepare_command` | `''` (empty) | Required when `prepare_enabled=true` |
+| `verify_command` | `''` (empty) | Required when `verify_enabled=true` |
+| `prepare_enabled` | `false` | `true` or `false` |
+| `verify_enabled` | `false` | `true` or `false` |
+| `preserve_dirty` | `false` | `true` or `false` |
+
+Each key may appear only once. An unknown key, a line without
+`=`, an invalid boolean, or an unsafe path is rejected as
+`invalid_configuration` with exit code `3`, before any effect.
+
+## 5. Output contracts
+
+- `--json` publishes a single JSON document with seven keys: `contract_version`,
+  `tool_version`, `operation`, `result`, `data`, `warnings` and `error`.
+- `--request-json <file|->` publishes the same nine-key document used by
+  the MCP transport: the previous seven plus `repository` and
+  `transaction_id`. It optionally accepts `--json` and the published document
+  does not change.
+- A dry run of `create` publishes `planned: true` and creates no worktree or branch.
+  `init_submodules_result` is `planned` or `not_requested`, and `prepare` and
+  `verify` are `planned` or `skipped`.
+- The MCP service is published over stdio and exposes seven tools. From the
+  installed package it is launched without bin:
+
+```sh
+node <package>/mcp-server.mjs
+```
+
+  `initialize` publishes the guide in `instructions`:
+
+```text
+You are going to implement a change, run a spec, or start a flow. Do you want to create a worktree to work in isolation?
+```
+
+  For development, the transport also starts from the checkout:
+
+```sh
+PYTHONPATH=. python3 -m worktree_manager.mcp_transport
+```
+
+## 6. Tests
+
+```sh
+bash tests/cli-usage.sh
+bash tests/cli-json.sh
+bash tests/compatibility.sh
+bash tests/smoke.sh
+bash tests/parity.sh
+PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_*.py'
+PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_mcp*.py' -v
+```
+
+## 7. Consumption as a submodule and coexistence
+
+A consumer repository may materialize the manager as a submodule. The
+rule is unique: the materialized checkout and the registered gitlink must be the
+same commit.
+
+The npm package `worktree-for-agents` is independent of the submodule: it ships
+the Python runtime and works without a network once installed. `node
+<package>/setup.mjs` diagnoses which installation is active when the
+npm package, the global FlowTask copy, and the local submodule coexist. The repository
+clone is for development only and no other distribution is promised.
+
+## 8. Troubleshooting
+
+- **`python3` is not on the `PATH`.** The entrypoint exits with code `127`
+  and the message
+  `worktree manager requires Python 3 (python3) on PATH; install Python 3 and retry.`
+- **The package entrypoint is missing.** The entrypoint exits with
+  code `126` and the message
+  `worktree manager Python entry point is missing: <path>/worktree_manager/__main__.py`.
+- **The repository path is relative.** The operation is rejected with
+  code `invalid_repository`, exit code `3`, and the message
+  `Repository path must be absolute`.
+- **The Python version is older than 3.9.** The consumer installer reports
+  it as `python <version> is older than the required 3.9`. The entrypoint
+  of this repository does not check the version.
+
+## 9. What it does not cover
+
+This guide does not cover integration with a consumer: neither the adapter, nor the
+bridge, nor gitlink validation, nor the consumer installation procedure.
+That is documented in the consumer repository.

package/docs/mcp-contract.md

@@ -0,0 +1,78 @@
+# Worktree manager MCP service
+
+The optional stdio service starts independently from the existing CLI:
+
+```sh
+python3 -m worktree_manager.mcp_transport
+```
+
+It implements JSON-RPC `initialize`, `ping`, `tools/list` and `tools/call` and
+publishes exactly `worktree_create`, `worktree_complete`, `worktree_cleanup`,
+`worktree_recover`, `worktree_list`, `worktree_prune` and `worktree_status`.
+Each call requires an absolute existing Git repository path; the process
+working directory is never used as a repository default. Unknown arguments
+are rejected. Responses carry contract version 1, operation, repository,
+result, data, warnings, structured error and a nullable transaction ID.
+
+The `initialize` result carries `serverInfo.name "worktree-for-agents"` and
+an `instructions` field with the literal guide text:
+
+```text
+You are going to implement a change, run a spec, or start a flow. Do you want to create a worktree to work in isolation?
+```
+
+When installed from npm, the service is launched without a bin entry via:
+
+```sh
+node <package>/mcp-server.mjs
+```
+
+A rejected call publishes the same nine-key envelope as an accepted one, with
+`result` set to `failure` or `pending_intervention` and `error` carrying
+`code`, `message` and `exit_code`. The command line publishes that identical
+envelope for `--request-json`, so both transports can be read by one client.
+
+`worktree_create` accepts the optional booleans `init_submodules`, `prepare`
+and `verify`. They are off by default and report the observed state of each
+step; `prepare` and `verify` require the matching configured command and are
+rejected as `invalid_configuration` before any worktree or branch is created.
+
+Mutating dry runs do not invoke lifecycle operations. A per-call authorization is
+required only in an execution, that is, when `dry_run` is absent or `false`; a
+dry run of a destructive operation succeeds without it. A destructive execute
+accepts `authorization: "I_AUTHORIZE_THIS_CALL"` directly, or `confirm: true`,
+from which that authorization is derived. A `confirm: false` sent together with
+the literal is rejected as `authorization_mismatch`. A `cleanup` with a discard
+additionally requires the separate boolean `discard_consent: true`. A
+target-direct `create`, `complete` or `recover` has no safe simulation and is
+rejected as `unsupported_dry_run` with exit code `3` when a dry run is
+requested. Authorization is not retained across requests. Do not expose this
+local service to untrusted clients. CLI JSON v1 and its entrypoint remain
+unchanged.
+
+## End-to-end verification
+
+Run the real stdio client tests from the repository root:
+
+```sh
+PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_mcp*.py' -v
+MCP_E2E_EVIDENCE_DIR=<evidence-dir> \
+  PYTHONPATH=. python3 -m unittest discover -s tests -p 'test_mcp_e2e.py' -v
+```
+
+`test_mcp_e2e.py` uses isolated temporary Git repositories and launches the
+stdio server as a subprocess. It exercises discovery and every public tool,
+dry-run immutability, authorization and separate discard consent, transaction
+recovery, worktree/ref/index/status effects, plus MCP-vs-Python-CLI completion
+on independent equivalent repositories. When `MCP_E2E_EVIDENCE_DIR` is set,
+each test writes its request/response trace there as JSON. No evidence or Git
+fixture is written into the checked-out repository by default.
+
+## Closing message
+
+`worktree_complete` accepts `commit_title` and `commit_body` (optional strings).
+They are validated as strings and included in the plan hash only for this operation.
+The dry run publishes the composed `commit_subject` and `commit_body`; execute passes them
+to the lifecycle. If missing, the manager uses the neutral fallback
+`Complete <work_id> (generic closure)` / `No delivery description was available
+at closure time.`.

package/mcp-server.mjs

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { probePython } from "./scripts/python.mjs";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+const transport = join(packageDir, "worktree_manager", "mcp_transport.py");
+const entry = join(packageDir, "worktree_manager", "__main__.py");
+
+if (!existsSync(transport)) {
+  process.stderr.write(
+    "worktree-for-agents is incomplete: missing worktree_manager/mcp_transport.py. Reinstall the package.\n"
+  );
+  process.exit(126);
+}
+if (!existsSync(entry)) {
+  process.stderr.write(
+    "worktree-for-agents is incomplete: missing worktree_manager/__main__.py. Reinstall the package.\n"
+  );
+  process.exit(126);
+}
+
+const probed = probePython();
+if (!probed.version) {
+  process.stderr.write(
+    "worktree-for-agents requires Python 3.9 or later. Install Python 3.9+ and rerun the installation.\n"
+  );
+  process.exit(127);
+}
+
+const env = {
+  ...process.env,
+  PYTHONPATH: packageDir + (process.env.PYTHONPATH ? `:${process.env.PYTHONPATH}` : ""),
+};
+const child = spawn(probed.bin, ["-m", "worktree_manager.mcp_transport"], {
+  cwd: packageDir,
+  env,
+  stdio: "inherit",
+});
+const forward = (signal) => {
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill(signal);
+  }
+};
+process.on("SIGINT", () => forward("SIGINT"));
+process.on("SIGTERM", () => forward("SIGTERM"));
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code === null ? 1 : code);
+});

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "worktree-for-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Standalone Git worktree manager with a stdio MCP service usable by any coding agent",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "worktree.sh",
+    "worktree_manager/**/*.py",
+    "mcp-server.mjs",
+    "worktree.mjs",
+    "setup.mjs",
+    "GUIDE.md",
+    "README.md",
+    "docs/installation.md",
+    "docs/mcp-contract.md",
+    "scripts/python.mjs",
+    "scripts/postinstall.mjs"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepublishOnly": "node scripts/verify-package.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Saez520/worktree-manager.git"
+  },
+  "keywords": [
+    "git",
+    "worktree",
+    "mcp",
+    "coding-agent"
+  ]
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,11 @@
+import { probePython } from "./python.mjs";
+
+const probed = probePython();
+if (!probed.version) {
+  process.stderr.write(
+    "worktree-for-agents requires Python 3.9 or later. Install Python 3.9+ and rerun the installation.\n"
+  );
+  process.exit(1);
+}
+process.stdout.write(`worktree-for-agents: Python ${probed.version} (${probed.bin})\n`);
+process.stdout.write("Next: node <package>/setup.mjs\n");