@tokenbooks/wt 0.1.0

package/dist/schemas/config.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.schema.js","sourceRoot":"","sources":["../../src/schemas/config.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAElE,6CAA6C;AAChC,QAAA,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,WAAW,CAAC;IACzB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,+CAA+C;AAClC,QAAA,aAAa,GAAG,OAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC;AAEH,+CAA+C;AAClC,QAAA,aAAa,GAAG,OAAC,CAAC,MAAM,CAAC;IACpC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,mBAAW,CAAC;CAC9B,CAAC,CAAC;AAEH,gCAAgC;AACnB,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IACzD,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACpD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,qBAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,qBAAa,CAAC;IAChC,SAAS,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1C,WAAW,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACvC,CAAC,CAAC"}

package/dist/schemas/registry.schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/** Schema for a single worktree allocation */
+export declare const allocationSchema: z.ZodObject<{
+    worktreePath: z.ZodString;
+    branchName: z.ZodString;
+    dbName: z.ZodString;
+    redisDb: z.ZodNumber;
+    ports: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+/** Schema for .worktree-registry.json */
+export declare const registrySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    allocations: z.ZodRecord<z.ZodString, z.ZodObject<{
+        worktreePath: z.ZodString;
+        branchName: z.ZodString;
+        dbName: z.ZodString;
+        redisDb: z.ZodNumber;
+        ports: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/schemas/registry.schema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registrySchema = exports.allocationSchema = void 0;
+const zod_1 = require("zod");
+/** Schema for a single worktree allocation */
+exports.allocationSchema = zod_1.z.object({
+    worktreePath: zod_1.z.string().min(1),
+    branchName: zod_1.z.string().min(1),
+    dbName: zod_1.z.string().min(1),
+    redisDb: zod_1.z.number().int().min(1),
+    ports: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().positive()),
+    createdAt: zod_1.z.string().datetime(),
+});
+/** Schema for .worktree-registry.json */
+exports.registrySchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    allocations: zod_1.z.record(zod_1.z.string(), exports.allocationSchema),
+});
+//# sourceMappingURL=registry.schema.js.map

package/dist/schemas/registry.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.schema.js","sourceRoot":"","sources":["../../src/schemas/registry.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,8CAA8C;AACjC,QAAA,gBAAgB,GAAG,OAAC,CAAC,MAAM,CAAC;IACvC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,KAAK,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;IACxD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,yCAAyC;AAC5B,QAAA,cAAc,GAAG,OAAC,CAAC,MAAM,CAAC;IACrC,OAAO,EAAE,OAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,wBAAgB,CAAC;CACpD,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import type { z } from 'zod';
+import type { configSchema, serviceSchema, envFileSchema, patchSchema } from './schemas/config.schema';
+import type { registrySchema, allocationSchema } from './schemas/registry.schema';
+/** Declarative config loaded from wt.config.json */
+export type WtConfig = z.infer<typeof configSchema>;
+export type ServiceConfig = z.infer<typeof serviceSchema>;
+export type EnvFileConfig = z.infer<typeof envFileSchema>;
+export type PatchConfig = z.infer<typeof patchSchema>;
+/** Registry persisted at .worktree-registry.json */
+export type Registry = z.infer<typeof registrySchema>;
+export type Allocation = z.infer<typeof allocationSchema>;
+/** Context passed to env patcher with computed values for a slot */
+export interface PatchContext {
+    readonly dbName: string;
+    readonly redisDb: number;
+    readonly ports: Record<string, number>;
+}
+/** Result of CLI operations for --json output */
+export interface CliResult<T = unknown> {
+    readonly success: boolean;
+    readonly data?: T;
+    readonly error?: {
+        code: string;
+        message: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@tokenbooks/wt",
+  "version": "0.1.0",
+  "description": "Git worktree environment isolation CLI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tokenbooks/wt.git"
+  },
+  "main": "dist/cli.js",
+  "bin": {
+    "wt": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^14.0.0",
+    "pg": "^8.16.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/node": "^24.10.0",
+    "@types/pg": "^8.11.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "eslint": "^9.39.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.1",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20.19.0 || >=22.3.0"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/link-cli.js",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "lint": "eslint 'src/**/*.ts' '__tests__/**/*.ts'"
+  }
+}

package/skills/wt/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: wt
+description: Manage git worktree isolation — create, list, remove worktrees with isolated databases, Redis, and ports
+argument-hint: "[new|list|remove|doctor|setup|init] [args...]"
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+---
+
+# wt — Git Worktree Isolation
+
+You are managing git worktrees with isolated Postgres databases, Redis DB indexes, and ports using the `wt` CLI.
+
+## Routing
+
+Based on the first argument, perform one of the following:
+
+### `init` — First-time setup for a repository
+
+The user wants to set up `wt` in their project for the first time. Follow these steps exactly:
+
+**Step 1: Discover the project**
+
+Search the repository to find:
+- All `.env` files (not `.env.example`): `find . -name '.env' -not -path '*/node_modules/*' -not -path '*/.git/*'`
+- The `DATABASE_URL` value to extract the base database name (path segment after the port, before `?`)
+- Any `REDIS_URL` values and their format (with or without trailing `/0`)
+- All services and their default ports — check `package.json` scripts, `docker-compose.yml`, framework config files
+- The package manager in use (`pnpm`, `npm`, `yarn`) — check for lockfiles
+
+**Step 2: Map env vars to patch types**
+
+For each `.env` file, examine every variable and classify:
+
+| Variable contains | Patch type | Needs `service`? |
+|---|---|---|
+| Postgres connection URL (`postgresql://...`) | `database` | No |
+| Redis connection URL (`redis://...`) | `redis` | No |
+| Just a port number | `port` | Yes |
+| A URL containing a service port (`http://localhost:3000/...`) | `url` | Yes |
+| Anything else (API keys, secrets, flags) | Skip — do not patch | — |
+
+**Step 3: Generate `wt.config.json`**
+
+Build the config file at the repository root:
+
+```json
+{
+  "baseDatabaseName": "<extracted from DATABASE_URL>",
+  "baseWorktreePath": ".worktrees",
+  "portStride": 100,
+  "maxSlots": 15,
+  "services": [
+    { "name": "<service>", "defaultPort": <port> }
+  ],
+  "envFiles": [
+    {
+      "source": "<relative path to .env file>",
+      "patches": [
+        { "var": "<VAR_NAME>", "type": "<database|redis|port|url>", "service": "<name>" }
+      ]
+    }
+  ],
+  "postSetup": ["<install command>"],
+  "autoInstall": true
+}
+```
+
+Validation rules:
+- Every `port` and `url` patch must have a `service` that exists in `services`
+- `portStride` * `maxSlots` + max default port must be < 65535
+- `baseDatabaseName` must match the actual DB name in `DATABASE_URL`
+
+**Step 4: Install wt**
+
+```bash
+# Detect package manager and install
+pnpm add -D @tokenbooks/wt
+```
+
+**Step 5: Update .gitignore**
+
+Add `.worktree-registry.json` if not already present.
+
+**Step 6: Add convenience scripts to root package.json**
+
+```json
+{
+  "scripts": {
+    "wt": "wt",
+    "wt:new": "wt new",
+    "wt:list": "wt list",
+    "wt:doctor": "wt doctor"
+  }
+}
+```
+
+**Step 7: Create `.husky/post-checkout` hook** (if husky is installed)
+
+```bash
+#!/bin/bash
+prev_head="$1"
+new_head="$2"
+is_branch="$3"
+[ "$is_branch" = "0" ] && exit 0
+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
+main_worktree=$(cd "$git_common/.." && pwd -P)
+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."
+  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
+}
+```
+
+Make it executable: `chmod +x .husky/post-checkout`
+
+**Step 8: Smoke test**
+
+```bash
+wt list                              # Should show "No worktree allocations found."
+wt doctor                            # Should show "All checks passed."
+wt new test/wt-smoke --no-install    # Create a test worktree
+wt list                              # Should show the allocation
+wt remove test-wt-smoke              # Clean up
+```
+
+Present the results to the user.
+
+---
+
+### `new $1` — Create a new worktree
+
+Run:
+```bash
+wt new $1
+```
+
+If it fails, check `wt doctor` for diagnostics. Common issues:
+- All slots occupied → suggest `wt list` to find stale ones, then `wt remove`
+- Database connection failed → check that Postgres is running and `DATABASE_URL` in root `.env` is correct
+
+---
+
+### `list` — List all worktree allocations
+
+Run:
+```bash
+wt list
+```
+
+---
+
+### `remove $1` — Remove a worktree
+
+Run:
+```bash
+wt remove $1
+```
+
+Accepts either a path (`.worktrees/feat-auth`) or a slot number (`3`).
+
+If the user wants to keep the database, use `--keep-db`.
+
+---
+
+### `doctor` — Diagnose issues
+
+Run:
+```bash
+wt doctor
+```
+
+If issues are found, ask the user if they want to auto-fix:
+```bash
+wt doctor --fix
+```
+
+---
+
+### `setup` — Set up an existing worktree
+
+Run:
+```bash
+wt setup $1
+```
+
+Use this when a worktree was created with plain `git worktree add` instead of `wt new`.
+
+---
+
+### No arguments or unrecognized command
+
+Show a brief help:
+
+```
+Available commands:
+  /wt init              — Set up wt in a new repository (discovers env files, generates config)
+  /wt new <branch>      — Create a worktree with isolated DB, Redis, and ports
+  /wt list              — List all worktree allocations
+  /wt remove <target>   — Remove a worktree and clean up resources
+  /wt doctor            — Diagnose and fix environment issues
+  /wt setup [path]      — Set up an existing worktree
+```