@tokenbooks/wt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ledgertech Inc.
+
+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.

package/README.md

@@ -0,0 +1,395 @@
+# wt — Git Worktree Environment Isolation
+
+A CLI tool that gives each git worktree its own Postgres database, Redis database index, ports, and `.env` files. Prevents worktrees from corrupting each other's data.
+
+## The Problem
+
+When you use `git worktree add` for parallel development, all worktrees share the same database, Redis instance, and ports. This means:
+
+- Schema migrations in one worktree break another
+- BullMQ/Redis queues collide across worktrees
+- Two dev servers can't run simultaneously on the same port
+- `.env` files point to the same resources everywhere
+
+`wt` solves this by assigning each worktree an isolated **slot** (1–15) that determines its database name, Redis DB index, and port range.
+
+## How It Works
+
+Each worktree gets a numbered slot. The slot determines everything:
+
+| Resource | Formula | Slot 0 (main) | Slot 1 | Slot 2 | Slot 3 |
+|----------|---------|:-:|:-:|:-:|:-:|
+| Database | `{baseName}_wt{slot}` | `mydb` | `mydb_wt1` | `mydb_wt2` | `mydb_wt3` |
+| Redis DB | `slot` | `/0` | `/1` | `/2` | `/3` |
+| Ports | `slot * stride + defaultPort` | 3000, 3001 | 3100, 3101 | 3200, 3201 | 3300, 3301 |
+
+- **Database**: Created via `CREATE DATABASE ... TEMPLATE` (fast filesystem copy, not dump/restore)
+- **Redis**: Uses a different DB index per worktree (Redis supports 0–15)
+- **Ports**: Offset by `portStride` (default 100) per slot
+- **Env files**: Copied from main worktree and patched with the slot's values
+
+## Quick Start
+
+### 1. Install
+
+**Global** (available in all repos):
+
+```bash
+pnpm add -g @tokenbooks/wt
+```
+
+**Per-project** (recommended for teams — version-locked in package.json):
+
+```bash
+pnpm add -D @tokenbooks/wt
+```
+
+### 2. Create `wt.config.json`
+
+Create this file in your repository root and commit it. See [Configuration Reference](#configuration-reference) for full details.
+
+```json
+{
+  "baseDatabaseName": "myapp",
+  "baseWorktreePath": ".worktrees",
+  "portStride": 100,
+  "maxSlots": 15,
+  "services": [
+    { "name": "web", "defaultPort": 3000 },
+    { "name": "api", "defaultPort": 4000 }
+  ],
+  "envFiles": [
+    {
+      "source": ".env",
+      "patches": [
+        { "var": "DATABASE_URL", "type": "database" }
+      ]
+    },
+    {
+      "source": "backend/.env",
+      "patches": [
+        { "var": "DATABASE_URL", "type": "database" },
+        { "var": "REDIS_URL", "type": "redis" },
+        { "var": "PORT", "type": "port", "service": "api" }
+      ]
+    },
+    {
+      "source": "frontend/.env",
+      "patches": [
+        { "var": "PORT", "type": "port", "service": "web" },
+        { "var": "API_URL", "type": "url", "service": "api" }
+      ]
+    }
+  ],
+  "postSetup": ["npm install"],
+  "autoInstall": true
+}
+```
+
+### 3. Add `.worktree-registry.json` to `.gitignore`
+
+```bash
+echo ".worktree-registry.json" >> .gitignore
+```
+
+### 4. Use it
+
+```bash
+# Create a worktree with full isolation
+wt new feat/my-feature
+
+# List all worktree allocations
+wt list
+
+# Check health
+wt doctor
+
+# Clean up
+wt remove feat-my-feature
+```
+
+### 5. Claude Code skill (optional)
+
+The package ships with a `/wt` skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). To enable it, symlink from your project:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/@tokenbooks/wt/skills/wt/SKILL.md .claude/skills/wt.md
+```
+
+Then use `/wt init`, `/wt new feat/foo`, `/wt doctor`, etc. inside Claude Code.
+
+## Commands
+
+### `wt new <branch> [--slot N] [--no-install] [--json]`
+
+Creates a new git worktree and sets up its isolated environment:
+
+1. Allocates the next available slot (or uses `--slot N`)
+2. Runs `git worktree add .worktrees/<slug> -b <branch>`
+3. Creates a new Postgres database from the main DB as template
+4. Copies all configured `.env` files, patching each with slot-specific values
+5. Runs `postSetup` commands (unless `--no-install`)
+
+### `wt setup [path] [--no-install] [--json]`
+
+Sets up an existing worktree that was created manually or by another tool. Useful when:
+
+- You ran `git worktree add` directly
+- A worktree's env files need regenerating
+- Called automatically by the `post-checkout` hook
+
+If the worktree already has a slot allocation, it reuses it.
+
+### `wt remove <path-or-slot> [--keep-db] [--json]`
+
+Removes a worktree and cleans up its resources:
+
+1. Drops the worktree's Postgres database (unless `--keep-db`)
+2. Runs `git worktree remove`
+3. Removes the allocation from the registry
+
+Accepts either a path (`.worktrees/feat-my-feature`) or a slot number (`3`).
+
+### `wt list [--json]`
+
+Shows all worktree allocations with their slot, branch, database, Redis DB, ports, and status (ok/stale).
+
+### `wt doctor [--fix] [--json]`
+
+Runs diagnostics:
+
+- **Stale entries**: Registry points to a path that no longer exists
+- **Missing databases**: Allocated DB doesn't exist in Postgres
+- **Missing env files**: Expected env files not found in worktree
+- **Orphaned databases**: `{baseName}_wt*` databases not in the registry
+
+Use `--fix` to auto-repair stale entries and drop orphaned databases.
+
+### JSON output
+
+All commands support `--json` for machine-readable output:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Or on error:
+
+```json
+{
+  "success": false,
+  "error": { "code": "NO_SLOTS", "message": "All 15 slots are occupied." }
+}
+```
+
+## Configuration Reference
+
+### `wt.config.json`
+
+This file lives in your repository root and is committed to version control.
+
+```typescript
+{
+  // Required: name of your main Postgres database
+  "baseDatabaseName": string,
+
+  // Directory for worktrees, relative to repo root (default: ".worktrees")
+  "baseWorktreePath": string,
+
+  // Port offset per slot (default: 100)
+  "portStride": number,
+
+  // Maximum number of concurrent worktrees (default: 15, max: 15)
+  "maxSlots": number,
+
+  // Services that need port allocation
+  "services": [
+    { "name": string, "defaultPort": number }
+  ],
+
+  // Env files to copy and patch for each worktree
+  "envFiles": [
+    {
+      "source": string,        // Path relative to repo root
+      "patches": [
+        {
+          "var": string,       // Env var name to patch
+          "type": string,      // "database" | "redis" | "port" | "url"
+          "service": string    // Required for "port" and "url" types
+        }
+      ]
+    }
+  ],
+
+  // Commands to run in the worktree after env setup (default: [])
+  "postSetup": string[],
+
+  // Whether to run postSetup automatically (default: true)
+  "autoInstall": boolean
+}
+```
+
+### Patch Types
+
+| Type | What it patches | Input | Output (slot 3) |
+|------|----------------|-------|------------------|
+| `database` | Replaces DB name in a Postgres URL | `postgresql://u:p@host:5432/myapp?schema=public` | `postgresql://u:p@host:5432/myapp_wt3?schema=public` |
+| `redis` | Replaces or appends DB index in a Redis URL | `redis://:pass@host:6379/0` | `redis://:pass@host:6379/3` |
+| `port` | Replaces the entire value with the allocated port | `4000` | `4300` |
+| `url` | Replaces the port number inside a URL | `http://localhost:4000/api` | `http://localhost:4300/api` |
+
+The `port` and `url` types require a `service` field that matches a name in `services`.
+
+### `.worktree-registry.json`
+
+Auto-managed file at the repo root. **Add to `.gitignore`** — it's machine-local.
+
+```json
+{
+  "version": 1,
+  "allocations": {
+    "1": {
+      "worktreePath": "/absolute/path/to/.worktrees/feat-auth",
+      "branchName": "feat/auth",
+      "dbName": "myapp_wt1",
+      "redisDb": 1,
+      "ports": { "web": 3100, "api": 4100 },
+      "createdAt": "2026-02-17T14:30:00Z"
+    }
+  }
+}
+```
+
+## Git Hook: Automatic Setup
+
+Add a `post-checkout` hook so `wt setup` runs automatically when switching branches inside a worktree. With [Husky](https://typicode.github.io/husky/):
+
+Create `.husky/post-checkout`:
+
+```bash
+#!/bin/bash
+
+prev_head="$1"
+new_head="$2"
+is_branch="$3"
+
+# Only run on branch checkout (not file checkout)
+[ "$is_branch" = "0" ] && exit 0
+
+# Detect if we're in a worktree (not main)
+git_common=$(git rev-parse --git-common-dir 2>/dev/null)
+git_dir=$(git rev-parse --git-dir 2>/dev/null)
+[ "$git_common" = "$git_dir" ] && exit 0
+
+# Resolve main worktree path
+main_worktree=$(cd "$git_common/.." && pwd -P)
+
+# Find wt: local install first, then global
+wt_bin="$main_worktree/node_modules/.bin/wt"
+if [ ! -f "$wt_bin" ]; then
+  wt_bin=$(command -v wt 2>/dev/null || true)
+fi
+
+if [ -z "$wt_bin" ]; then
+  echo "Warning: wt CLI not found. Install globally (pnpm add -g @tokenbooks/wt) or locally (pnpm add -D @tokenbooks/wt)."
+  exit 0
+fi
+
+echo "Setting up worktree environment..."
+"$wt_bin" setup "$(pwd -P)" --json 2>/dev/null && echo "Worktree ready!" || {
+  echo "Warning: Auto-setup failed. Run 'wt setup' manually."
+  exit 0
+}
+```
+
+The hook checks for a local install first (`node_modules/.bin/wt`), then falls back to a global `wt` on PATH.
+
+## Setup Guide for LLM Agents
+
+If you are an LLM agent setting up `wt` for a repository, follow these steps:
+
+### Step 1: Discover the project structure
+
+Identify these from the repository:
+
+- **Database URL format**: Search `.env` files for `DATABASE_URL`. Extract the database name (the path segment after the port, before `?`).
+- **Redis URL format**: Search for `REDIS_URL`. Note whether it ends with `/0` or has no DB index.
+- **Services and ports**: Find all dev server commands and their default ports. Check `package.json` scripts, `docker-compose.yml`, and framework configs.
+- **Env files**: List all `.env` files (not `.env.example`). These are the files that need patching.
+
+### Step 2: Map env vars to patch types
+
+For each `.env` file, identify which variables need patching:
+
+| If the variable contains... | Use patch type |
+|----------------------------|----------------|
+| A Postgres connection URL (`postgresql://...`) | `database` |
+| A Redis connection URL (`redis://...`) | `redis` |
+| Just a port number (`3000`) | `port` + service name |
+| A URL with a port (`http://localhost:3000/...`) | `url` + service name |
+
+Variables that don't match any pattern (API keys, secrets, feature flags) should NOT be patched.
+
+### Step 3: Build `wt.config.json`
+
+Using the discovered information, construct the config:
+
+```
+1. baseDatabaseName = the DB name from the main DATABASE_URL
+2. services = each dev server as { name, defaultPort }
+3. envFiles = each .env file with its patches
+4. postSetup = the install command for the package manager (npm install, pnpm install, etc.)
+```
+
+Validate that:
+- Every `port` and `url` patch has a `service` that exists in `services`
+- The `portStride` (default 100) doesn't cause port collisions with other local services
+- `maxSlots * portStride` doesn't push ports into reserved ranges (e.g., above 65535)
+
+### Step 4: Install and test
+
+```bash
+# Install wt
+pnpm add -D @tokenbooks/wt
+
+# Add to .gitignore
+echo ".worktree-registry.json" >> .gitignore
+
+# Verify
+wt list          # Should show "No worktree allocations found."
+wt doctor        # Should show "All checks passed."
+
+# Smoke test (creates a real worktree + database)
+wt new test/wt-smoke --no-install
+wt list          # Should show the new allocation
+wt remove test-wt-smoke
+wt list          # Should be empty again
+```
+
+### Step 5: Add convenience scripts (optional)
+
+```json
+{
+  "scripts": {
+    "wt": "wt",
+    "wt:new": "wt new",
+    "wt:list": "wt list",
+    "wt:doctor": "wt doctor"
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 20.19.0
+- PostgreSQL (running, accessible via `DATABASE_URL` in root `.env`)
+- Redis (if using `redis` patch type)
+- Git (for worktree operations)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const new_1 = require("./commands/new");
+const setup_1 = require("./commands/setup");
+const remove_1 = require("./commands/remove");
+const list_1 = require("./commands/list");
+const doctor_1 = require("./commands/doctor");
+const git_1 = require("./core/git");
+const program = new commander_1.Command();
+program
+    .name('wt')
+    .description('Git worktree environment isolation CLI')
+    .version('0.1.0');
+program
+    .command('new')
+    .description('Create a new worktree with isolated environment')
+    .argument('<branch>', 'Branch name to create or checkout')
+    .option('--slot <n>', 'Force a specific slot number')
+    .option('--no-install', 'Skip post-setup commands')
+    .option('--json', 'Output as JSON', false)
+    .action(async (branch, opts) => {
+    await (0, new_1.newCommand)(branch, {
+        json: opts.json,
+        install: opts.install,
+        slot: opts.slot,
+    });
+});
+program
+    .command('setup')
+    .description('Set up environment for an existing worktree')
+    .argument('[path]', 'Worktree path (default: current directory)')
+    .option('--no-install', 'Skip post-setup commands')
+    .option('--json', 'Output as JSON', false)
+    .action(async (targetPath, opts) => {
+    await (0, setup_1.setupCommand)(targetPath, {
+        json: opts.json,
+        install: opts.install,
+    });
+});
+program
+    .command('remove')
+    .description('Remove a worktree and clean up its resources')
+    .argument('<path-or-slot>', 'Worktree path or slot number')
+    .option('--keep-db', 'Keep the database (do not drop)', false)
+    .option('--json', 'Output as JSON', false)
+    .action(async (pathOrSlot, opts) => {
+    await (0, remove_1.removeCommand)(pathOrSlot, {
+        json: opts.json,
+        keepDb: opts.keepDb,
+    });
+});
+program
+    .command('list')
+    .description('List all worktree allocations')
+    .option('--json', 'Output as JSON', false)
+    .action((opts) => {
+    const repoRoot = (0, git_1.getMainWorktreePath)();
+    (0, list_1.listCommand)(repoRoot, { json: opts.json });
+});
+program
+    .command('doctor')
+    .description('Diagnose and fix worktree environment issues')
+    .option('--fix', 'Auto-repair stale entries and orphaned databases', false)
+    .option('--json', 'Output as JSON', false)
+    .action(async (opts) => {
+    await (0, doctor_1.doctorCommand)({ json: opts.json, fix: opts.fix });
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,7 @@
+interface DoctorOptions {
+    readonly json: boolean;
+    readonly fix: boolean;
+}
+/** Run diagnostics on the worktree registry and databases */
+export declare function doctorCommand(options: DoctorOptions): Promise<void>;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctorCommand = doctorCommand;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const registry_1 = require("../core/registry");
+const database_1 = require("../core/database");
+const git_1 = require("../core/git");
+const setup_1 = require("./setup");
+const output_1 = require("../output");
+/** Read DATABASE_URL from the main worktree's .env file */
+function readDatabaseUrl(mainRoot) {
+    const envPath = path.join(mainRoot, '.env');
+    const content = fs.readFileSync(envPath, 'utf-8');
+    const match = content.match(/^DATABASE_URL=["']?([^"'\n]+)/m);
+    if (!match?.[1]) {
+        throw new Error('DATABASE_URL not found in .env');
+    }
+    return match[1];
+}
+/** Run diagnostics on the worktree registry and databases */
+async function doctorCommand(options) {
+    try {
+        const mainRoot = (0, git_1.getMainWorktreePath)();
+        const config = (0, setup_1.loadConfig)(mainRoot);
+        let registry = (0, registry_1.readRegistry)(mainRoot);
+        const databaseUrl = readDatabaseUrl(mainRoot);
+        const issues = [];
+        // Check each allocation
+        for (const [slotStr, allocation] of Object.entries(registry.allocations)) {
+            const slot = Number(slotStr);
+            // Check if worktree path exists
+            if (!fs.existsSync(allocation.worktreePath)) {
+                const issue = {
+                    type: 'stale_entry',
+                    slot,
+                    detail: `Path does not exist: ${allocation.worktreePath}`,
+                    fixed: options.fix,
+                };
+                issues.push(issue);
+                if (options.fix) {
+                    registry = (0, registry_1.removeAllocation)(registry, slot);
+                }
+            }
+            // Check if database exists
+            const dbOk = await (0, database_1.databaseExists)(databaseUrl, allocation.dbName);
+            if (!dbOk) {
+                issues.push({
+                    type: 'missing_db',
+                    slot,
+                    detail: `Database does not exist: ${allocation.dbName}`,
+                });
+            }
+            // Check if env files exist in the worktree
+            if (fs.existsSync(allocation.worktreePath)) {
+                for (const envFile of config.envFiles) {
+                    const envPath = path.join(allocation.worktreePath, envFile.source);
+                    if (!fs.existsSync(envPath)) {
+                        issues.push({
+                            type: 'missing_env',
+                            slot,
+                            detail: `Missing env file: ${envFile.source}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Detect orphaned databases
+        const pattern = `${config.baseDatabaseName}_wt%`;
+        const allDbs = await (0, database_1.listDatabasesByPattern)(databaseUrl, pattern);
+        const registeredDbNames = new Set(Object.values(registry.allocations).map((a) => a.dbName));
+        for (const dbName of allDbs) {
+            if (!registeredDbNames.has(dbName)) {
+                const issue = {
+                    type: 'orphaned_db',
+                    detail: `Orphaned database: ${dbName}`,
+                    fixed: options.fix,
+                };
+                issues.push(issue);
+                if (options.fix) {
+                    await (0, database_1.dropDatabase)(databaseUrl, dbName, config.baseDatabaseName);
+                }
+            }
+        }
+        // Save registry if fixes were applied
+        if (options.fix) {
+            (0, registry_1.writeRegistry)(mainRoot, registry);
+        }
+        // Output
+        const result = { issues, totalIssues: issues.length, fixed: options.fix };
+        if (options.json) {
+            console.log((0, output_1.formatJson)((0, output_1.success)(result)));
+            return;
+        }
+        if (issues.length === 0) {
+            console.log('All checks passed. No issues found.');
+            return;
+        }
+        console.log(`Found ${issues.length} issue(s):\n`);
+        for (const issue of issues) {
+            const prefix = issue.fixed ? '[FIXED]' : '[ISSUE]';
+            const slotInfo = issue.slot !== undefined ? ` (slot ${issue.slot})` : '';
+            console.log(`  ${prefix} ${issue.type}${slotInfo}: ${issue.detail}`);
+        }
+        if (!options.fix && issues.some((i) => i.type === 'stale_entry' || i.type === 'orphaned_db')) {
+            console.log('\nRun with --fix to auto-repair stale entries and orphaned databases.');
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json) {
+            console.log((0, output_1.formatJson)((0, output_1.error)('DOCTOR_FAILED', message)));
+        }
+        else {
+            console.error(`Doctor failed: ${message}`);
+        }
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+interface ListOptions {
+    readonly json: boolean;
+}
+/** List all worktree allocations */
+export declare function listCommand(repoRoot: string, options: ListOptions): void;
+export {};