worktree-for-agents 0.0.0-stage → 1.0.0

package/GUIDE.md

@@ -0,0 +1,45 @@
+Vas a implementar un cambio, ejecutar una spec o iniciar un flujo. ¿Quieres crear un worktree para hacerlo aislado?
+
+Esta guía explica cómo usar el gestor `worktree-for-agents` para trabajar
+aislado en un worktree antes de tocar la rama principal.
+
+## Las siete herramientas
+
+El servicio MCP expone exactamente siete herramientas:
+
+- `worktree_create`: crea un worktree y su rama para un identificador de trabajo.
+- `worktree_complete`: integra el worktree en la rama base y retira el worktree.
+- `worktree_cleanup`: retira el worktree y su rama sin integrar.
+- `worktree_recover`: recupera una transacción pendiente por su identificador.
+- `worktree_list`: lista los worktrees del repositorio.
+- `worktree_prune`: poda la información de worktrees que ya no existen.
+- `worktree_status`: muestra el estado de un trabajo.
+
+Todas exigen una ruta absoluta de repositorio Git en `repo`.
+
+## Cuándo ofrecer el worktree
+
+Antes de trabajar en la rama principal, ofrece crear un worktree con
+`worktree_create`. Trabaja dentro del worktree y luego integra con
+`worktree_complete`. Si el trabajo se descarta, usa `worktree_cleanup`.
+
+## Lanzamiento sin bin
+
+El paquete no expone bin ni `npx`. El servicio MCP se lanza con Node y la
+ruta absoluta del paquete:
+
+```sh
+node <paquete>/mcp-server.mjs
+```
+
+La CLI se lanza del mismo modo:
+
+```sh
+node <paquete>/worktree.mjs --version
+```
+
+El diagnóstico de la instalación se obtiene con:
+
+```sh
+node <paquete>/setup.mjs
+```

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# Gestor de worktrees
 
-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.
+Gestor standalone para crear, completar, limpiar y recuperar worktrees de un
+repositorio Git. El proyecto no conoce FlowTask ni depende de sus rutas, refs
+heredadas o mecanismos de coordinación.
+
+## Requisitos
+
+- **Python 3.9 o posterior.** El entrypoint sólo comprueba que `python3` esté
+  disponible en el `PATH`; el piso de 3.9 lo valida el postinstall del paquete
+  y `node <paquete>/setup.mjs`. El paquete usa sólo la biblioteca estándar.
+- **Git 2.17.0 o posterior**, por `git worktree remove`, que es el comando más
+  reciente que usa el gestor. La línea base de las pruebas es Git 2.54.0. El
+  gestor no comprueba la versión de Git en tiempo de ejecución.
+- **Node 18 o posterior** para los lanzadores `mcp-server.mjs`, `worktree.mjs`
+  y `setup.mjs`.
+- **`bash`** para ejecutar las suites de pruebas.
+
+## Instalación
+
+El gestor se distribuye como paquete npm `worktree-for-agents`, versión
+`1.0.0`, sin bin ni `npx`:
+
+```sh
+npm install -g worktree-for-agents@latest
+pnpm add -g worktree-for-agents@latest
+```
+
+Comprueba el diagnóstico de la instalación:
+
+```sh
+node <paquete>/setup.mjs
+```
+
+El clon del repositorio queda solo para desarrollo. No hay `pip install` ni
+dependencias que resolver: el gestor usa sólo la biblioteca estándar de
+Python. Una vez instalado, el gestor funciona sin red.
+
+## Uso rápido
+
+Las opciones globales van antes del subcomando y `--repo` exige una ruta
+absoluta.
+
+```text
+worktree.sh [--repo ABS] [--config ABS] [--json] create <id> [--base BRANCH] [--init-submodules] [--prepare] [--verify]
+worktree.sh [globales] complete <id> [--preserve-dirty] [--title TEXTO] [--body TEXTO]
+worktree.sh [globales] cleanup <id> [--discard]
+worktree.sh [globales] recover [<transaction-id>]
+worktree.sh [globales] prune
+worktree.sh [globales] list
+```
+
+Target-direct opera sobre el repositorio indicado en `--repo` y no crea un
+worktree del parent ni modifica su `HEAD`. Su sintaxis coloca `--parent-repo`
+después de la acción y exige `--submodule-path` en `create`:
+
+```text
+worktree.sh [--repo ABS] target-direct <acción> <id> --parent-repo <parent> [--target submodule] [--submodule-path <REL>] [--base BRANCH] [--link-parent staged-only] [--descriptor PATH]
+```
+
+Las acciones son `create`, `link-parent`, `abort`, `complete` y `recover`, y el
+único modo de enlace admitido es `--link-parent staged-only`.
+
+`--json` publica un único documento JSON. `--request-json <archivo|->` publica
+el mismo sobre de nueve claves que usa el transporte MCP, y acepta `--json` de
+forma opcional. Un dry run de `create` publica `planned: true` y no crea
+worktree ni rama.
+
+El servicio MCP se publica por stdio. Desde el paquete instalado se lanza sin
+bin:
+
+```sh
+node <paquete>/mcp-server.mjs
+```
+
+La CLI se usa del mismo modo:
+
+```sh
+node <paquete>/worktree.mjs --version
+```
+
+El `initialize` del MCP publica la guía en `instructions`:
+
+```text
+Vas a implementar un cambio, ejecutar una spec o iniciar un flujo. ¿Quieres crear un worktree para hacerlo aislado?
+```
+
+Para desarrollo, el transporte también arranca desde el checkout:
+
+```sh
+PYTHONPATH=. python3 -m worktree_manager.mcp_transport
+```
+
+## Configuración
+
+La configuración es un archivo opcional de `clave=valor`, seleccionado con
+`--config` o tomado de `.worktree-manager.conf` en la raíz del repositorio.
+Las once claves y sus valores por defecto son:
+
+| Clave | Por defecto | Restricción |
+|---|---|---|
+| `worktrees_dir` | `.worktrees` | No puede empezar por `-` |
+| `branch_prefix` | `worktree/` | — |
+| `state_dir` | `worktree-manager` | Ruta relativa segura |
+| `backup_dir` | `backups` | No es una ruta absoluta y no contiene `..` |
+| `backup_ref_prefix` | `worktree-manager/backups` | Sin `..` |
+| `lock_dir` | `locks` | Ruta relativa segura |
+| `prepare_command` | `''` (vacío) | Requerida cuando `prepare_enabled=true` |
+| `verify_command` | `''` (vacío) | Requerida cuando `verify_enabled=true` |
+| `prepare_enabled` | `false` | `true` o `false` |
+| `verify_enabled` | `false` | `true` o `false` |
+| `preserve_dirty` | `false` | `true` o `false` |
+
+Cada clave puede aparecer una sola vez. Las claves desconocidas, las líneas mal
+formadas, los booleanos inválidos y las rutas inseguras se rechazan como
+`invalid_configuration` con código de salida `3`. La variable de entorno
+`WORKTREE_MANAGER_<CLAVE>`, con la clave en mayúsculas, reemplaza el valor
+leído del archivo.
+
+## Arquitectura
+
+`worktree.sh` es el entrypoint y delega el lifecycle en el paquete Python
+`worktree_manager`, que se ejecuta con `python3 -m worktree_manager`. El paquete
+es la única implementación del lifecycle: no existe un motor shell alternativo.
+
+El paquete se organiza en módulos con una responsabilidad cada uno:
+
+| Módulo | Responsabilidad |
+| --- | --- |
+| `worktree_manager.cli` | Despachador de comandos, despacho target-direct y contrato de salida. |
+| `worktree_manager.configuration` | Lectura y validación de la configuración `clave=valor`. |
+| `worktree_manager.models` | Valores de dominio compartidos: resultados, errores e identidades. |
+| `worktree_manager.output` | Publicación del resultado como texto legible o como JSON. |
+| `worktree_manager.git_repository` | Acceso compartido a Git para los módulos del lifecycle. |
+| `worktree_manager.worktree_lifecycle` | Operaciones `create`, `complete`, `cleanup` y `prune`. |
+| `worktree_manager.commit_message` | Composición determinista del mensaje de cierre y fallback neutro. |
+| `worktree_manager.target_direct_adapter` | Operaciones target-direct sobre un submódulo. |
+| `worktree_manager.recovery_manager` | Recuperación de transacciones pendientes. |
+| `worktree_manager.transaction_journal` | Journal durable de transacciones y enlaces. |
+| `worktree_manager.backup_store` | Referencias de respaldo retenidas. |
+| `worktree_manager.lock_manager` | Exclusión mutua entre procesos. |
+| `worktree_manager.state_digest` | Digest canónico del estado del repositorio y de un plan. |
+| `worktree_manager.mcp_server` | Servicio MCP publicado por stdio. |
+| `worktree_manager.mcp_contract` | Contratos estrictos y versionados de petición y de sobre. |
+| `worktree_manager.mcp_operations` | Fachada sobre los servicios de lifecycle y de recuperación. |
+| `worktree_manager.mcp_transport` | Punto de entrada del transporte por stdio. |
+
+El paquete contiene además el marcador de paquete `__init__.py` y el punto de
+entrada `__main__.py`, que es lo que ejecuta `python3 -m worktree_manager`.
+
+## Pruebas
+
+```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
+```
+
+## Documentación
+
+- [Contrato de salida de la CLI](docs/cli-contract-v1.md) — contrato.
+- [Contrato del servicio MCP](docs/mcp-contract.md) — contrato.
+- [Guía de instalación y uso](docs/installation.md) — guía.
+- [Histórico bash → Python](docs/history-bash-to-python.md) — memoria, no contrato.
+
+Los contratos fijan el comportamiento verificable. La guía explica cómo usarlo.
+El histórico registra la transición y no sustituye a los contratos.
+
+## Fuente y distribución
+
+Este repositorio es la fuente de verdad de la implementación, de los contratos,
+de la instalación y del histórico del gestor.
+
+El consumidor que integra este repositorio documenta el adaptador, el bridge y
+la frontera del submódulo: **la documentación de esa integración vive en el
+repositorio consumidor**. El gestor no mantiene una copia vendorizada de sí
+mismo y no conoce al consumidor.

package/docs/installation.md

@@ -0,0 +1,214 @@
+# Instalación y uso del gestor de worktrees
+
+Esta guía explica cómo instalar el gestor como paquete npm y cómo usarlo
+sobre un repositorio de prueba. La integración con un consumidor concreto
+se documenta en el repositorio que integra el gestor.
+
+Los ejemplos usan `$HOME` porque `--repo` exige una ruta absoluta. `<paquete>`
+es la ruta del paquete instalado.
+
+## 1. Requisitos
+
+Comprueba las versiones disponibles:
+
+```sh
+python3 --version
+git --version
+node --version
+```
+
+- **Python 3.9 o posterior.** El postinstall del paquete verifica el piso de
+  3.9 y falla de forma visible si falta o es anterior. `node
+  <paquete>/setup.mjs` informa el intérprete detectado.
+- **Git 2.17.0 o posterior**, por `git worktree remove`. La línea base de las
+  pruebas es Git 2.54.0. El gestor no comprueba la versión de Git en tiempo de
+  ejecución.
+- **Node 18 o posterior** para los lanzadores `mcp-server.mjs`, `worktree.mjs`
+  y `setup.mjs`.
+- **`bash`** para ejecutar las suites de pruebas.
+
+## 2. Instalar el paquete
+
+```sh
+npm install -g worktree-for-agents@latest
+pnpm add -g worktree-for-agents@latest
+```
+
+Comprueba el diagnóstico:
+
+```sh
+node <paquete>/setup.mjs
+```
+
+El paquete no expone bin ni `npx`: el MCP se lanza con `node
+<paquete>/mcp-server.mjs` y la CLI con `node <paquete>/worktree.mjs`. El clon
+del repositorio queda solo para desarrollo. No hay `pip install` ni
+dependencias que resolver: el gestor usa sólo la biblioteca estándar de
+Python. Una vez instalado, el gestor funciona sin red.
+
+## 3. Un repositorio de prueba
+
+El gestor exige que la ruta del worktree esté ignorada por Git, y
+`.worktrees/` en el `.gitignore` cumple esa condición.
+
+```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"
+```
+
+Crea el worktree:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" create demo --base main
+```
+
+Qué deja cada paso:
+
+- `git init` crea el repositorio y su rama `main`.
+- El commit inicial fija la base sobre la que se construye el worktree.
+- `create` crea la rama `worktree/demo`, el worktree en `$HOME/demo/.worktrees/demo`
+  y el journal de la transacción en el directorio de estado del repositorio.
+
+Comprueba el estado:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" list
+```
+
+Trabaja dentro del worktree y luego intégralo:
+
+```sh
+cd "$HOME/demo/.worktrees/demo"
+printf 'cambio\n' >> file
+git add file
+git commit -m "cambio"
+cd "$HOME/demo"
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" complete demo --base main
+```
+
+`complete` exige que el repositorio esté en la rama base, que el worktree no
+tenga cambios sin commitear y que el destino tampoco los tenga, salvo que se
+use `--preserve-dirty`. Al terminar, el cambio queda integrado como un commit
+de squash en `main`, y el worktree y su rama se retiran.
+
+Para dejar un commit de cierre diciente, pasa `--title` y, opcionalmente,
+`--body`:
+
+```sh
+"$HOME/worktree-manager/worktree.sh" --repo "$HOME/demo" complete demo --base main \
+  --title "Cierre de demo" --body "Entrega: cambio integrado. Motivo: verificacion."
+```
+
+Si no se pasa `--title`, el gestor usa el fallback generico:
+`Complete <work_id> (generic closure)` con el cuerpo
+`No delivery description was available at closure time.`.
+
+## 4. Configuración
+
+La configuración es un archivo de `clave=valor`. El gestor lo toma de
+`.worktree-manager.conf` en la raíz del repositorio, o del archivo que se le
+pase con `--config`, que debe existir y ser una ruta absoluta. Si se pasan
+ambos, `--config` prevalece. Después, la variable de entorno
+`WORKTREE_MANAGER_<CLAVE>`, con la clave en mayúsculas, reemplaza el valor
+leído del archivo.
+
+Las once claves y sus valores por defecto son:
+
+| Clave | Por defecto | Restricción |
+|---|---|---|
+| `worktrees_dir` | `.worktrees` | No puede empezar por `-` |
+| `branch_prefix` | `worktree/` | — |
+| `state_dir` | `worktree-manager` | Ruta relativa segura |
+| `backup_dir` | `backups` | No es una ruta absoluta y no contiene `..` |
+| `backup_ref_prefix` | `worktree-manager/backups` | Sin `..` |
+| `lock_dir` | `locks` | Ruta relativa segura |
+| `prepare_command` | `''` (vacío) | Requerida cuando `prepare_enabled=true` |
+| `verify_command` | `''` (vacío) | Requerida cuando `verify_enabled=true` |
+| `prepare_enabled` | `false` | `true` o `false` |
+| `verify_enabled` | `false` | `true` o `false` |
+| `preserve_dirty` | `false` | `true` o `false` |
+
+Cada clave puede aparecer una sola vez. Una clave desconocida, una línea sin
+`=`, un booleano inválido o una ruta insegura se rechazan como
+`invalid_configuration` con código de salida `3`, antes de cualquier efecto.
+
+## 5. Contratos de salida
+
+- `--json` publica un único documento JSON con siete claves: `contract_version`,
+  `tool_version`, `operation`, `result`, `data`, `warnings` y `error`.
+- `--request-json <archivo|->` publica el mismo documento de nueve claves que
+  usa el transporte MCP: las siete anteriores más `repository` y
+  `transaction_id`. Acepta `--json` de forma opcional y el documento publicado
+  no cambia.
+- Un dry run de `create` publica `planned: true` y no crea worktree ni rama.
+  `init_submodules_result` es `planned` o `not_requested`, y `prepare` y
+  `verify` son `planned` o `skipped`.
+- El servicio MCP se publica por stdio y expone siete herramientas. Desde el
+  paquete instalado se lanza sin bin:
+
+```sh
+node <paquete>/mcp-server.mjs
+```
+
+  El `initialize` publica la guía en `instructions`:
+
+```text
+Vas a implementar un cambio, ejecutar una spec o iniciar un flujo. ¿Quieres crear un worktree para hacerlo aislado?
+```
+
+  Para desarrollo, el transporte también arranca desde el checkout:
+
+```sh
+PYTHONPATH=. python3 -m worktree_manager.mcp_transport
+```
+
+## 6. Pruebas
+
+```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. Consumo como submódulo y coexistencia
+
+Un repositorio consumidor puede materializar el gestor como submódulo. La
+regla es única: el checkout materializado y el gitlink registrado deben ser el
+mismo commit.
+
+El paquete npm `worktree-for-agents` es independiente del submódulo: embarca
+el runtime Python y funciona sin red una vez instalado. `node
+<paquete>/setup.mjs` diagnostica qué instalación está activa cuando coexisten
+el paquete npm, la copia global de FlowTask y el submódulo local. El clon del
+repositorio queda solo para desarrollo y no se promete otra distribución.
+
+## 8. Solución de problemas
+
+- **`python3` no está en el `PATH`.** El entrypoint termina con el código `127`
+  y el mensaje
+  `worktree manager requires Python 3 (python3) on PATH; install Python 3 and retry.`
+- **Falta el punto de entrada del paquete.** El entrypoint termina con el
+  código `126` y el mensaje
+  `worktree manager Python entry point is missing: <ruta>/worktree_manager/__main__.py`.
+- **La ruta del repositorio es relativa.** La operación se rechaza con el
+  código `invalid_repository`, el código de salida `3` y el mensaje
+  `Repository path must be absolute`.
+- **La versión de Python es anterior a 3.9.** El instalador del consumidor lo
+  informa como `python <version> is older than the required 3.9`. El entrypoint
+  de este repositorio no comprueba la versión.
+
+## 9. Qué no cubre
+
+Esta guía no cubre la integración con un consumidor: ni el adaptador, ni el
+bridge, ni la validación del gitlink, ni el procedimiento de instalación del
+consumidor. Eso se documenta en el repositorio consumidor.

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
+Vas a implementar un cambio, ejecutar una spec o iniciar un flujo. ¿Quieres crear un worktree para hacerlo aislado?
+```
+
+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.
+
+## Mensaje de cierre
+
+`worktree_complete` acepta `commit_title` y `commit_body` (strings opcionales).
+Se validan como strings y se incluyen en el plan hash solo para esta operacion.
+El dry-run publica `commit_subject` y `commit_body` compuestos; execute los
+pasa al lifecycle. Si faltan, el gestor usa el fallback neutro
+`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.0",
+  "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");