@2nspired/pigeon 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @2nspired/pigeon
+
+The bootstrap CLI for [Pigeon](https://github.com/2nspired/pigeon) — a local-first kanban board + MCP server that gives AI coding agents durable context across sessions.
+
+```bash
+npx @2nspired/pigeon init
+```
+
+One command, run from inside your project repo. It:
+
+1. Clones the latest Pigeon release into `~/.pigeon` (override with `PIGEON_HOME` or `--home`) and installs its dependencies.
+2. Creates/migrates the SQLite database.
+3. Registers the Pigeon MCP server with Claude Code (user scope via `claude mcp add`; falls back to a project-scoped `.mcp.json`).
+4. Registers your repo with Pigeon so `briefMe()` auto-detects it, writes a starter `tracker.md`, and installs the `/brief-me`, `/handoff`, and `/plan-card` slash commands plus the token-tracking Stop hook.
+5. On macOS, installs the always-on background service at `http://localhost:3100`.
+
+Re-running is safe — every step is idempotent.
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--ref <branch\|tag>` | Check out a specific ref instead of the latest release tag |
+| `--home <dir>` | Pigeon home checkout location (same as `PIGEON_HOME`) |
+| `--agent-name <name>` | Agent display name on the board (default `Claude`) |
+| `--no-claude` | Skip `claude mcp add`; write a project-scoped `.mcp.json` instead |
+| `--no-service` | Skip the macOS launchd service install |
+| `--no-register` | Skip registering the current repo with Pigeon |
+
+This package is only the installer — the app itself runs from the git checkout it creates. Full docs: <https://2nspired.github.io/pigeon/>.

package/bin/pigeon.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * `pigeon` — the published bootstrap for Pigeon (#314 Phase B).
+ *
+ *   npx @2nspired/pigeon init           full install (home checkout, DB, MCP,
+ *                                       project bind, macOS service, doctor)
+ *   npx @2nspired/pigeon connect [dir]  bind a project to an existing install
+ *
+ * This package is deliberately thin: Node built-ins only, no build step. The
+ * app itself runs from the git checkout `init` creates — see cli/lib/home.mjs
+ * for why it isn't shipped on npm.
+ */
+
+import { existsSync } from "node:fs";
+import { parseCliArgs, USAGE } from "../lib/args.mjs";
+import { connectProject, printConnectSnippet } from "../lib/connect.mjs";
+import { resolvePigeonHome } from "../lib/home.mjs";
+import { runInit } from "../lib/init.mjs";
+import * as ui from "../lib/ui.mjs";
+
+function main() {
+	const args = parseCliArgs(process.argv.slice(2));
+
+	if (args.help || (args.command === null && args.errors.length === 0)) {
+		console.log(USAGE);
+		return 0;
+	}
+	if (args.errors.length > 0) {
+		for (const error of args.errors) console.error(ui.color("red", `error: ${error}`));
+		console.error(`\n${USAGE}`);
+		return 1;
+	}
+
+	if (args.command === "init") {
+		runInit(args);
+		return 0;
+	}
+
+	// connect: requires an existing home checkout.
+	const home = resolvePigeonHome(process.env, args.home);
+	if (!existsSync(home)) {
+		console.error(
+			ui.color("red", `error: no Pigeon checkout at ${home} — run \`npx @2nspired/pigeon init\` first.`),
+		);
+		return 1;
+	}
+	const target = args.target ?? process.cwd();
+	const project = connectProject({
+		home,
+		targetDir: target,
+		agentName: args.agentName,
+		register: args.register,
+		writeMcpJson: true,
+	});
+	if (project) printConnectSnippet(home);
+	return 0;
+}
+
+try {
+	process.exit(main());
+} catch (err) {
+	console.error(ui.color("red", `\npigeon: ${err instanceof Error ? err.message : err}`));
+	process.exit(1);
+}

package/lib/args.mjs

@@ -0,0 +1,111 @@
+/**
+ * Argument parsing for the `pigeon` CLI — pure, no I/O, unit-tested.
+ *
+ * Zero-question by default: every flag is an opt-out or an override, never a
+ * prompt. `--yes` is accepted (and ignored) so scripted callers can be
+ * explicit about the default they're already getting.
+ */
+
+export const KNOWN_COMMANDS = ["init", "connect"];
+
+export const USAGE = `pigeon — one-command Pigeon install
+
+Usage:
+  npx @2nspired/pigeon init                 install Pigeon + connect this repo
+  npx @2nspired/pigeon connect [dir]        connect a project to an existing install
+
+Options:
+  --ref <branch|tag>     checkout ref for the home clone (default: latest release tag)
+  --home <dir>           Pigeon home checkout (default: $PIGEON_HOME or ~/.pigeon)
+  --agent-name <name>    agent display name on the board (default: Claude)
+  --no-claude            skip \`claude mcp add\`; write project .mcp.json instead
+  --no-service           skip the macOS launchd service install
+  --no-register          skip registering the current repo with Pigeon
+  --yes                  accepted for scripting; init is already zero-question
+  -h, --help             show this help
+`;
+
+/**
+ * @typedef {object} CliArgs
+ * @property {string | null} command
+ * @property {string | null} target   Positional target dir (connect only).
+ * @property {string | null} ref
+ * @property {string | null} home
+ * @property {string} agentName
+ * @property {boolean} claude    False when --no-claude was passed.
+ * @property {boolean} service   False when --no-service was passed.
+ * @property {boolean} register  False when --no-register was passed.
+ * @property {boolean} help
+ * @property {string[]} errors
+ */
+
+/**
+ * Parse `process.argv.slice(2)`. Never throws — collect errors so the caller
+ * can print usage plus every problem at once.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+export function parseCliArgs(argv) {
+	/** @type {CliArgs} */
+	const args = {
+		command: null,
+		target: null,
+		ref: null,
+		home: null,
+		agentName: "Claude",
+		claude: true,
+		service: true,
+		register: true,
+		help: false,
+		errors: [],
+	};
+
+	const takesValue = new Map([
+		["--ref", "ref"],
+		["--home", "home"],
+		["--agent-name", "agentName"],
+	]);
+
+	for (let i = 0; i < argv.length; i++) {
+		const token = argv[i];
+		if (token === "-h" || token === "--help") {
+			args.help = true;
+		} else if (token === "--no-claude") {
+			args.claude = false;
+		} else if (token === "--no-service") {
+			args.service = false;
+		} else if (token === "--no-register") {
+			args.register = false;
+		} else if (token === "--yes" || token === "-y") {
+			// Zero-question is already the default; accepted for scripting.
+		} else if (takesValue.has(token)) {
+			const value = argv[i + 1];
+			if (value === undefined || value.startsWith("--")) {
+				args.errors.push(`${token} requires a value`);
+			} else {
+				args[/** @type {"ref"|"home"|"agentName"} */ (takesValue.get(token))] = value;
+				i++;
+			}
+		} else if (token.startsWith("-")) {
+			args.errors.push(`Unknown option: ${token}`);
+		} else if (args.command === null) {
+			if (KNOWN_COMMANDS.includes(token)) {
+				args.command = token;
+			} else {
+				args.errors.push(`Unknown command: ${token}`);
+			}
+		} else if (args.command === "connect" && args.target === null) {
+			args.target = token;
+		} else {
+			args.errors.push(`Unexpected argument: ${token}`);
+		}
+	}
+
+	// AGENT_NAME lands verbatim in JSON we write — keep it JSON-safe.
+	if (/["\\\n\r]/.test(args.agentName)) {
+		args.errors.push("--agent-name must not contain quotes, backslashes, or newlines");
+	}
+
+	return args;
+}

package/lib/commands.mjs

@@ -0,0 +1,54 @@
+/**
+ * Slash-command install — the ONE implementation (port of
+ * `install_slash_commands` from `scripts/connect.sh`).
+ *
+ * Copies `<home>/.claude/commands/*.md` (/brief-me, /handoff, /plan-card)
+ * into the target project's `.claude/commands/`, as-is. Idempotent: a
+ * pre-existing file with the same name is left untouched so local edits
+ * survive re-runs.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Pure install plan: which command files to copy vs. leave alone.
+ *
+ * @param {string[]} sourceNames    `.md` filenames shipped by the checkout.
+ * @param {string[]} existingNames  Filenames already in the target dir.
+ * @returns {{ install: string[], skip: string[] }}
+ */
+export function planCommandInstall(sourceNames, existingNames) {
+	const existing = new Set(existingNames);
+	const install = [];
+	const skip = [];
+	for (const name of sourceNames) {
+		if (!name.endsWith(".md")) continue;
+		(existing.has(name) ? skip : install).push(name);
+	}
+	return { install, skip };
+}
+
+/**
+ * Install the checkout's slash commands into a project.
+ *
+ * @param {{ home: string, targetDir: string }} options
+ * @returns {{ installed: string[], skipped: string[] }}
+ */
+export function installSlashCommands({ home, targetDir }) {
+	const sourceDir = join(home, ".claude", "commands");
+	const destDir = join(targetDir, ".claude", "commands");
+
+	if (!existsSync(sourceDir)) return { installed: [], skipped: [] };
+	const sourceNames = readdirSync(sourceDir).filter((name) => name.endsWith(".md"));
+	if (sourceNames.length === 0) return { installed: [], skipped: [] };
+
+	const existingNames = existsSync(destDir) ? readdirSync(destDir) : [];
+	const plan = planCommandInstall(sourceNames, existingNames);
+
+	if (plan.install.length > 0) mkdirSync(destDir, { recursive: true });
+	for (const name of plan.install) {
+		copyFileSync(join(sourceDir, name), join(destDir, name));
+	}
+	return { installed: plan.install, skipped: plan.skip };
+}

package/lib/connect.mjs

@@ -0,0 +1,155 @@
+/**
+ * Project connection — the shared implementation behind `pigeon init` (when
+ * run inside a project repo), `pigeon connect`, `scripts/connect.sh`, and
+ * `scripts/setup.mts` step 3.
+ *
+ * Steps (each independently idempotent):
+ *   1. Register the repo with Pigeon (`scripts/register-repo.ts` in the home
+ *      checkout) so `Project.repoPath` is set and briefMe auto-detection
+ *      works — the #154 failure mode this CLI exists to close.
+ *   2. Starter `tracker.md` at the repo root (if absent).
+ *   3. Slash commands into `.claude/commands/` (existing files untouched).
+ *   4. Token-tracking Stop hook into user-level settings.json.
+ *   5. Optionally a project-scoped `.mcp.json` (the fallback when user-scope
+ *      `claude mcp add` isn't used).
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { basename, join } from "node:path";
+import { installSlashCommands } from "./commands.mjs";
+import { commandOnPath, run } from "./exec.mjs";
+import { manualMcpSnippet, writeProjectMcpJson } from "./mcp-config.mjs";
+import { installStopHook, resolveUserSettingsPath } from "./stop-hook.mjs";
+import { writeStarterTrackerMd } from "./tracker-template.mjs";
+import * as ui from "./ui.mjs";
+
+/**
+ * Git toplevel for `dir`, or null when not in a repo.
+ *
+ * @param {string} dir
+ */
+export function detectGitRoot(dir) {
+	const result = run("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+		capture: true,
+		allowFailure: true,
+	});
+	if (result.status !== 0) return null;
+	const top = result.stdout.trim();
+	return top ? realpathSync(top) : null;
+}
+
+/**
+ * Connect a project directory to a Pigeon home checkout.
+ *
+ * @param {{
+ *   home: string,
+ *   targetDir: string,
+ *   agentName?: string,
+ *   register?: boolean,
+ *   writeMcpJson?: boolean,
+ * }} options
+ * @returns {{ projectRoot: string | null, registered: boolean }}
+ */
+export function connectProject({
+	home,
+	targetDir,
+	agentName = "Claude",
+	register = true,
+	writeMcpJson = true,
+}) {
+	const resolvedTarget = realpathSync(targetDir);
+	if (resolvedTarget === realpathSync(home)) {
+		throw new Error(
+			"That's the Pigeon checkout itself — run this from the project you want to connect.",
+		);
+	}
+
+	const gitRoot = detectGitRoot(resolvedTarget);
+	const projectRoot = gitRoot ?? resolvedTarget;
+	const projectName = basename(projectRoot);
+	let registered = false;
+
+	// 1. Repo registration — sets Project.repoPath so briefMe auto-detects.
+	if (!gitRoot) {
+		ui.warn(`${resolvedTarget} is not inside a git repo — skipping registration.`);
+		ui.info("briefMe auto-detection needs a git root; run `git init` and re-run.");
+	} else if (!register) {
+		ui.skip("Repo registration skipped (--no-register).");
+	} else {
+		// Non-fatal: the remaining steps (tracker.md, commands, hook, .mcp.json)
+		// are still worth landing, and registration can be redone from a
+		// session via registerRepo (see docs/AGENT-GUIDE.md).
+		try {
+			run("npx", ["tsx", "scripts/register-repo.ts", gitRoot, projectName], { cwd: home });
+			registered = true;
+		} catch (err) {
+			ui.warn(`Repo registration failed: ${err instanceof Error ? err.message : err}`);
+			ui.info("Fix the install (npm run doctor in the checkout), then re-run connect.");
+		}
+	}
+
+	// 2. Starter tracker.md.
+	const trackerStatus = writeStarterTrackerMd({ targetDir: projectRoot, projectName });
+	if (trackerStatus === "created") {
+		ui.ok(`Starter tracker.md written to ${join(projectRoot, "tracker.md")} — edit it, agents read it live.`);
+	} else {
+		ui.skip("tracker.md already present (left as-is).");
+	}
+
+	// 3. Slash commands.
+	const commands = installSlashCommands({ home, targetDir: projectRoot });
+	if (commands.installed.length > 0) {
+		ui.ok(
+			`Installed ${commands.installed.map((n) => `/${n.replace(/\.md$/, "")}`).join(" ")} into .claude/commands/.`,
+		);
+	}
+	if (commands.skipped.length > 0) {
+		ui.skip(
+			`Slash commands already present: ${commands.skipped.map((n) => `/${n.replace(/\.md$/, "")}`).join(" ")}.`,
+		);
+	}
+
+	// 4. Stop hook (user-level, once per machine).
+	const settingsPath = resolveUserSettingsPath();
+	const hook = installStopHook({
+		settingsPath,
+		hookCommand: join(home, "scripts", "stop-hook.sh"),
+	});
+	if (hook.status === "installed") {
+		ui.ok(`Token-tracking Stop hook installed into ${settingsPath}.`);
+	} else if (hook.status === "already-installed") {
+		ui.skip(`Stop hook already installed in ${settingsPath}.`);
+	} else {
+		ui.warn(`Could not install the Stop hook: ${hook.detail}`);
+	}
+
+	// 5. Project-scoped .mcp.json (fallback / connect path).
+	if (writeMcpJson) {
+		const mcpStatus = writeProjectMcpJson({ targetDir: projectRoot, home, agentName });
+		if (mcpStatus === "created" || mcpStatus === "added") {
+			ui.ok(`Pigeon MCP server ${mcpStatus === "created" ? "written to" : "added to"} ${join(projectRoot, ".mcp.json")}.`);
+		} else if (mcpStatus === "already-configured") {
+			ui.skip(".mcp.json already lists Pigeon (left as-is).");
+		} else {
+			ui.warn(`.mcp.json exists but isn't valid JSON — add this under "mcpServers" yourself:`);
+			console.log(manualMcpSnippet(home));
+		}
+	}
+
+	return { projectRoot, registered };
+}
+
+/**
+ * Print the CLAUDE.md snippet (derived from the live tool manifest by the
+ * home checkout — see scripts/print-connect-snippet.ts, #187). Non-fatal.
+ *
+ * @param {string} home
+ */
+export function printConnectSnippet(home) {
+	if (!existsSync(join(home, "scripts", "print-connect-snippet.ts"))) return;
+	if (!commandOnPath("npx")) return;
+	console.log("");
+	console.log("Snippet for this project's CLAUDE.md / AGENTS.md:");
+	console.log("");
+	run("npx", ["tsx", "scripts/print-connect-snippet.ts"], { cwd: home, allowFailure: true });
+}

package/lib/exec.mjs

@@ -0,0 +1,44 @@
+/**
+ * Thin child-process helpers — Node built-ins only.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Run a command synchronously.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv, capture?: boolean, allowFailure?: boolean }} [options]
+ * @returns {{ status: number | null, stdout: string, stderr: string }}
+ */
+export function run(cmd, args, options = {}) {
+	const { cwd, env, capture = false, allowFailure = false } = options;
+	const result = spawnSync(cmd, args, {
+		cwd,
+		env: env ?? process.env,
+		stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+		encoding: "utf8",
+	});
+	if (result.error) throw result.error;
+	if (result.status !== 0 && !allowFailure) {
+		const detail = capture && result.stderr ? `\n${result.stderr.trim()}` : "";
+		throw new Error(`\`${cmd} ${args.join(" ")}\` exited with code ${result.status}${detail}`);
+	}
+	return {
+		status: result.status,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? "",
+	};
+}
+
+/**
+ * True when `name` resolves on PATH.
+ *
+ * @param {string} name
+ */
+export function commandOnPath(name) {
+	const probe = process.platform === "win32" ? "where" : "which";
+	const result = spawnSync(probe, [name], { stdio: "ignore" });
+	return result.status === 0;
+}

package/lib/home.mjs

@@ -0,0 +1,201 @@
+/**
+ * The Pigeon home checkout — a full git clone the app actually runs from.
+ *
+ * `pigeon init` deliberately does NOT ship the app on npm: the launchd plist
+ * points at a directory, `pigeon-start.sh` execs `tsx` out of that
+ * directory's `node_modules`, and updates flow through `git pull` +
+ * `npm run service:update`. So this module's whole job is to make
+ * `~/.pigeon` (or `$PIGEON_HOME`) exist, be a Pigeon checkout, have deps
+ * installed, and have its SQLite schema migrated.
+ *
+ * Release-tag constraint (#314 Phase B): the default clone ref is the latest
+ * `vX.Y.Z` release tag, but releases up to and including v6.6.0 predate the
+ * native migrations helper (`scripts/db-migrate.ts`, Phase A). Rather than
+ * silently falling back to that checkout's legacy `db push` path — which the
+ * schema engine can't run against a DB any MCP server has touched — init
+ * fails with a message naming the fix (`--ref main` until the first
+ * post-v6.6.0 release is tagged).
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { run } from "./exec.mjs";
+
+export const PIGEON_REPO_URL = "https://github.com/2nspired/pigeon";
+export const MIGRATE_HELPER = "scripts/db-migrate.ts";
+/** Newest release that does NOT support `pigeon init` (predates Phase A). */
+export const LAST_UNSUPPORTED_RELEASE = "v6.6.0";
+
+/** Package names the home checkout may carry (post/pre-rebrand). */
+const PIGEON_PACKAGE_NAMES = new Set(["pigeon-mcp", "project-tracker"]);
+
+/**
+ * Resolve the home checkout path: `--home` flag, then `PIGEON_HOME`, then
+ * `~/.pigeon`.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @param {string | null} [homeFlag]
+ */
+export function resolvePigeonHome(env = process.env, homeFlag = null) {
+	if (homeFlag) return resolve(homeFlag);
+	if (env.PIGEON_HOME) return resolve(env.PIGEON_HOME);
+	return join(homedir(), ".pigeon");
+}
+
+/**
+ * Release tags (`vX.Y.Z`, no pre-releases) out of `git ls-remote --tags`
+ * output. Peeled `^{}` refs are folded into their tag name.
+ *
+ * @param {string} lsRemoteOutput
+ * @returns {string[]}
+ */
+export function parseReleaseTags(lsRemoteOutput) {
+	const tags = new Set();
+	for (const line of lsRemoteOutput.split("\n")) {
+		const match = /refs\/tags\/(v\d+\.\d+\.\d+)(\^\{\})?$/.exec(line.trim());
+		if (match) tags.add(match[1]);
+	}
+	return [...tags];
+}
+
+/**
+ * Numeric semver compare for `vX.Y.Z` tags. Positive when `a > b`.
+ *
+ * @param {string} a
+ * @param {string} b
+ */
+export function compareReleaseTags(a, b) {
+	const pa = a.slice(1).split(".").map(Number);
+	const pb = b.slice(1).split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		if (pa[i] !== pb[i]) return pa[i] - pb[i];
+	}
+	return 0;
+}
+
+/**
+ * Highest release tag, or null when none exist.
+ *
+ * @param {string[]} tags
+ * @returns {string | null}
+ */
+export function latestReleaseTag(tags) {
+	if (tags.length === 0) return null;
+	return tags.reduce((best, tag) => (compareReleaseTags(tag, best) > 0 ? tag : best));
+}
+
+/**
+ * Classify what's at the home path. Pure given the answers, unit-tested via
+ * the wrapper below.
+ *
+ * @param {{ exists: boolean, empty: boolean, hasGitDir: boolean, packageName: string | null }} probe
+ * @returns {"clone" | "reuse" | "conflict"}
+ */
+export function planHomeCheckout(probe) {
+	if (!probe.exists || probe.empty) return "clone";
+	if (probe.hasGitDir && probe.packageName !== null && PIGEON_PACKAGE_NAMES.has(probe.packageName)) {
+		return "reuse";
+	}
+	return "conflict";
+}
+
+/**
+ * @param {string} home
+ * @returns {"clone" | "reuse" | "conflict"}
+ */
+export function inspectHome(home) {
+	const exists = existsSync(home);
+	let empty = false;
+	let hasGitDir = false;
+	let packageName = null;
+	if (exists) {
+		empty = readdirSync(home).length === 0;
+		hasGitDir = existsSync(join(home, ".git"));
+		const packageJson = join(home, "package.json");
+		if (existsSync(packageJson)) {
+			try {
+				const parsed = JSON.parse(readFileSync(packageJson, "utf8"));
+				if (typeof parsed?.name === "string") packageName = parsed.name;
+			} catch {
+				// Unreadable package.json → treated as a conflict below.
+			}
+		}
+	}
+	return planHomeCheckout({ exists, empty, hasGitDir, packageName });
+}
+
+/**
+ * Ensure the home checkout exists. Returns what happened plus the ref used.
+ *
+ * @param {{ home: string, ref: string | null, repoUrl?: string }} options
+ * @returns {{ status: "cloned" | "reused", ref: string | null }}
+ */
+export function ensureHomeCheckout({ home, ref, repoUrl = PIGEON_REPO_URL }) {
+	const plan = inspectHome(home);
+
+	if (plan === "reuse") {
+		return { status: "reused", ref: null };
+	}
+	if (plan === "conflict") {
+		throw new Error(
+			`${home} exists but is not a Pigeon checkout. ` +
+				`Move it aside, or point --home / PIGEON_HOME somewhere else.`,
+		);
+	}
+
+	let cloneRef = ref;
+	if (!cloneRef) {
+		const lsRemote = run("git", ["ls-remote", "--tags", repoUrl], { capture: true });
+		cloneRef = latestReleaseTag(parseReleaseTags(lsRemote.stdout));
+		if (!cloneRef) {
+			throw new Error(
+				`No release tags found at ${repoUrl}. Pass --ref <branch|tag> (e.g. --ref main).`,
+			);
+		}
+	}
+
+	run("git", ["clone", "--depth", "1", "--branch", cloneRef, repoUrl, home]);
+	return { status: "cloned", ref: cloneRef };
+}
+
+/**
+ * Error text for a checkout that predates the Phase-A migrations helper.
+ * Exported so the message stays pinned by a unit test.
+ *
+ * @param {string} home
+ * @param {string | null} ref
+ */
+export function unsupportedCheckoutMessage(home, ref) {
+	const refLabel = ref ? `ref ${ref}` : "this checkout";
+	return (
+		`Pigeon at ${home} (${refLabel}) predates \`pigeon init\` — it has no ` +
+		`${MIGRATE_HELPER}, which ships in releases after ${LAST_UNSUPPORTED_RELEASE}. ` +
+		`Re-run with \`npx @2nspired/pigeon init --ref main\` (or a newer release tag once one exists), ` +
+		`or update the checkout: cd ${home} && git pull.`
+	);
+}
+
+/**
+ * `npm install` in the home checkout (idempotent; Prisma's postinstall
+ * regenerates the client).
+ *
+ * @param {string} home
+ */
+export function installHomeDeps(home) {
+	run("npm", ["install"], { cwd: home });
+}
+
+/**
+ * Apply pending migrations by invoking the Phase-A helper from the home
+ * checkout. Throws with a named minimum release when the checkout predates
+ * the helper (see module docs).
+ *
+ * @param {{ home: string, ref: string | null }} options
+ */
+export function applyHomeMigrations({ home, ref }) {
+	if (!existsSync(join(home, MIGRATE_HELPER))) {
+		throw new Error(unsupportedCheckoutMessage(home, ref));
+	}
+	run("npx", ["tsx", MIGRATE_HELPER], { cwd: home });
+}

package/lib/init.mjs

@@ -0,0 +1,178 @@
+/**
+ * `pigeon init` — the whole install, in order, zero questions:
+ *
+ *   a. Home checkout at ~/.pigeon (PIGEON_HOME / --home; latest release tag,
+ *      --ref override)
+ *   b. npm install in the checkout
+ *   c. Apply DB migrations via the checkout's own Phase-A helper
+ *   d. Register the MCP server with Claude Code (user scope via
+ *      `claude mcp add`; project .mcp.json fallback)
+ *   e. Inside a project repo: repo registration + starter tracker.md +
+ *      slash commands + Stop hook
+ *   f. macOS: launchd service install (opt out with --no-service)
+ *   g. Doctor pass + colophon summary
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { connectProject, detectGitRoot, printConnectSnippet } from "./connect.mjs";
+import { commandOnPath, run } from "./exec.mjs";
+import {
+	applyHomeMigrations,
+	ensureHomeCheckout,
+	installHomeDeps,
+	resolvePigeonHome,
+} from "./home.mjs";
+import { buildClaudeMcpAddArgs, buildClaudeMcpGetArgs } from "./mcp-config.mjs";
+import * as ui from "./ui.mjs";
+
+const SERVICE_PLIST = "Library/LaunchAgents/com.2nspired.pigeon.plist";
+const BOARD_URL = "http://localhost:3100";
+
+/**
+ * Register the MCP server in Claude Code user scope. Returns true when user
+ * scope now covers this machine (so no project `.mcp.json` is needed).
+ *
+ * @param {{ home: string, agentName: string, useClaude: boolean }} options
+ */
+export function registerUserScope({ home, agentName, useClaude }) {
+	if (!useClaude) {
+		ui.skip("Claude Code user-scope registration skipped (--no-claude).");
+		return false;
+	}
+	if (!commandOnPath("claude")) {
+		ui.skip("`claude` not on PATH — falling back to a project-scoped .mcp.json.");
+		return false;
+	}
+
+	const probe = run("claude", buildClaudeMcpGetArgs(), { capture: true, allowFailure: true });
+	if (probe.status === 0) {
+		ui.skip("Pigeon is already registered with Claude Code.");
+		return true;
+	}
+
+	const add = run("claude", buildClaudeMcpAddArgs(home, agentName), {
+		capture: true,
+		allowFailure: true,
+	});
+	if (add.status === 0) {
+		ui.ok("Registered the Pigeon MCP server with Claude Code (user scope).");
+		return true;
+	}
+	ui.warn(`\`claude mcp add\` failed — falling back to a project-scoped .mcp.json.`);
+	if (add.stderr.trim()) ui.info(add.stderr.trim());
+	return false;
+}
+
+/**
+ * @param {import("./args.mjs").CliArgs} args
+ * @param {{ cwd?: string, platform?: NodeJS.Platform }} [context]
+ */
+export function runInit(args, context = {}) {
+	const cwd = context.cwd ?? process.cwd();
+	const platform = context.platform ?? process.platform;
+	const home = resolvePigeonHome(process.env, args.home);
+
+	// ─── a. Home checkout ────────────────────────────────────────────
+	ui.step("1/6 · Pigeon home checkout");
+	const checkout = ensureHomeCheckout({ home, ref: args.ref });
+	if (checkout.status === "cloned") {
+		ui.ok(`Cloned ${checkout.ref} into ${home}.`);
+	} else {
+		ui.skip(`Using the existing checkout at ${home}.`);
+		ui.info(`Update it any time: cd ${home} && git pull && npm run service:update`);
+	}
+
+	// ─── b. Dependencies ─────────────────────────────────────────────
+	ui.step("2/6 · Dependencies");
+	installHomeDeps(home);
+	ui.ok("npm install complete (Prisma client generated).");
+
+	// ─── c. Database migrations ──────────────────────────────────────
+	ui.step("3/6 · Database");
+	applyHomeMigrations({ home, ref: args.ref ?? checkout.ref });
+	ui.ok("Database ready.");
+
+	// ─── d. MCP registration ─────────────────────────────────────────
+	ui.step("4/6 · Claude Code");
+	const userScope = registerUserScope({
+		home,
+		agentName: args.agentName,
+		useClaude: args.claude,
+	});
+
+	// ─── e. Project connection ───────────────────────────────────────
+	ui.step("5/6 · This project");
+	const gitRoot = detectGitRoot(cwd);
+	const insideHome = gitRoot !== null && resolve(gitRoot) === resolve(home);
+	let project = null;
+	if (gitRoot && !insideHome) {
+		project = connectProject({
+			home,
+			targetDir: cwd,
+			agentName: args.agentName,
+			register: args.register,
+			writeMcpJson: !userScope,
+		});
+	} else if (insideHome) {
+		ui.skip("You're inside the Pigeon checkout itself — no project to connect here.");
+	} else {
+		ui.skip("Not inside a git repo — no project connected.");
+		ui.info("Later, from any project: npx @2nspired/pigeon connect");
+	}
+	if (!userScope && !project) {
+		ui.info("No .mcp.json written either — run `connect` from a project to get one.");
+	}
+
+	// ─── f. Background service ───────────────────────────────────────
+	ui.step("6/6 · Board service");
+	if (platform !== "darwin") {
+		ui.skip("Background service is macOS-only on this release.");
+		ui.info(`Run the board in the foreground: cd ${home} && npm run dev`);
+	} else if (!args.service) {
+		ui.skip("Service install skipped (--no-service).");
+		ui.info(`Install it later: cd ${home} && npm run service:install`);
+	} else if (existsSync(join(homedir(), SERVICE_PLIST))) {
+		ui.skip(`Service already installed — board at ${BOARD_URL}.`);
+	} else {
+		run("npm", ["run", "service:install"], { cwd: home });
+		ui.ok(`Board running at ${BOARD_URL} (launchd keeps it alive).`);
+	}
+
+	// ─── g. Doctor + colophon ────────────────────────────────────────
+	if (existsSync(join(home, "scripts", "doctor.ts"))) {
+		const doctor = run("npx", ["tsx", "scripts/doctor.ts"], { cwd: home, allowFailure: true });
+		if (doctor.status !== 0) {
+			ui.warn("Doctor flagged issues above — each comes with a copy-pasteable fix.");
+		}
+	}
+
+	if (project) printConnectSnippet(home);
+
+	printColophon({ home, platform, project, service: args.service });
+}
+
+/**
+ * Closing summary in colophon voice (#310): brief, warm, factual.
+ *
+ * @param {{ home: string, platform: NodeJS.Platform, project: { projectRoot: string | null, registered: boolean } | null, service: boolean }} options
+ */
+function printColophon({ home, platform, project, service }) {
+	const line = "─".repeat(56);
+	console.log("");
+	console.log(ui.color("dim", line));
+	console.log(`Pigeon lives in ${home}.`);
+	if (platform === "darwin" && service) {
+		console.log(`The board is at ${BOARD_URL} — it survives reboots.`);
+	}
+	if (project?.registered) {
+		console.log("This repo is registered; briefMe() will find it by path.");
+		console.log('Open Claude Code here and say "brief me" to start.');
+	} else if (project) {
+		console.log("This repo is connected. Register it any time with /brief-me.");
+	}
+	console.log(`Update later: cd ${home} && git pull && npm run service:update`);
+	console.log(ui.color("dim", line));
+	console.log("");
+}

package/lib/mcp-config.mjs

@@ -0,0 +1,138 @@
+/**
+ * MCP registration — the ONE implementation of `.mcp.json` writing (used by
+ * `pigeon init`, `pigeon connect`, `scripts/connect.sh`, and
+ * `scripts/setup.mts`) plus the `claude mcp add` command construction for the
+ * preferred user-scope path.
+ *
+ * Per #154: NEVER hand-edit `~/.claude.json`. User-scope registration always
+ * shells out to the `claude` CLI; the only file this module writes is a
+ * project-scoped `.mcp.json`, which is a documented, project-owned surface.
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const MCP_SERVER_KEY = "pigeon";
+/** Pre-rebrand key — presence means "already configured", never rewritten here. */
+export const LEGACY_MCP_KEY = "project-tracker";
+
+/**
+ * Canonical MCP launch command for a home checkout.
+ *
+ * @param {string} home
+ */
+export function pigeonStartCommand(home) {
+	return join(home, "scripts", "pigeon-start.sh");
+}
+
+/**
+ * The `.mcp.json` server entry — same shape `scripts/connect.sh` has always
+ * written.
+ *
+ * @param {string} home
+ * @param {string} [agentName]
+ */
+export function pigeonServerEntry(home, agentName = "Claude") {
+	return {
+		command: pigeonStartCommand(home),
+		args: [],
+		env: { AGENT_NAME: agentName },
+	};
+}
+
+/**
+ * argv (after the binary name) for user-scope registration via the Claude
+ * Code CLI: `claude mcp add --scope user … pigeon -- <pigeon-start.sh>`.
+ *
+ * @param {string} home
+ * @param {string} [agentName]
+ * @returns {string[]}
+ */
+export function buildClaudeMcpAddArgs(home, agentName = "Claude") {
+	return [
+		"mcp",
+		"add",
+		"--scope",
+		"user",
+		"--env",
+		`AGENT_NAME=${agentName}`,
+		MCP_SERVER_KEY,
+		"--",
+		pigeonStartCommand(home),
+	];
+}
+
+/** argv to probe whether the server is already registered with Claude Code. */
+export function buildClaudeMcpGetArgs() {
+	return ["mcp", "get", MCP_SERVER_KEY];
+}
+
+/**
+ * Decide what to do with a project's `.mcp.json`. Pure — `rawText` is the
+ * current file contents or null when the file doesn't exist.
+ *
+ * @param {string | null} rawText
+ * @param {object} entry  Server entry from {@link pigeonServerEntry}.
+ * @returns {{ status: "create" | "add" | "already-configured" | "unparseable", json?: object }}
+ */
+export function planMcpJsonUpdate(rawText, entry) {
+	if (rawText === null || rawText.trim() === "") {
+		return { status: "create", json: { mcpServers: { [MCP_SERVER_KEY]: entry } } };
+	}
+
+	let parsed;
+	try {
+		parsed = JSON.parse(rawText);
+	} catch {
+		return { status: "unparseable" };
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { status: "unparseable" };
+	}
+
+	const servers = parsed.mcpServers;
+	if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+		if (MCP_SERVER_KEY in servers || LEGACY_MCP_KEY in servers) {
+			return { status: "already-configured" };
+		}
+	}
+
+	const json = {
+		...parsed,
+		mcpServers: {
+			...(servers && typeof servers === "object" && !Array.isArray(servers) ? servers : {}),
+			[MCP_SERVER_KEY]: entry,
+		},
+	};
+	return { status: "add", json };
+}
+
+/**
+ * Create or merge `<targetDir>/.mcp.json` with the Pigeon server entry.
+ * Atomic write (tempfile + rename); preserves every other key in the file.
+ *
+ * @param {{ targetDir: string, home: string, agentName?: string }} options
+ * @returns {"created" | "added" | "already-configured" | "unparseable"}
+ */
+export function writeProjectMcpJson({ targetDir, home, agentName = "Claude" }) {
+	const mcpFile = join(targetDir, ".mcp.json");
+	const rawText = existsSync(mcpFile) ? readFileSync(mcpFile, "utf8") : null;
+	const plan = planMcpJsonUpdate(rawText, pigeonServerEntry(home, agentName));
+
+	if (plan.status === "create" || plan.status === "add") {
+		const tmp = `${mcpFile}.pigeon.tmp`;
+		writeFileSync(tmp, `${JSON.stringify(plan.json, null, 2)}\n`, "utf8");
+		renameSync(tmp, mcpFile);
+		return plan.status === "create" ? "created" : "added";
+	}
+	return plan.status;
+}
+
+/**
+ * Manual snippet for the unparseable-`.mcp.json` case.
+ *
+ * @param {string} home
+ */
+export function manualMcpSnippet(home) {
+	return JSON.stringify({ [MCP_SERVER_KEY]: pigeonServerEntry(home) }, null, 2);
+}

package/lib/stop-hook.mjs

@@ -0,0 +1,115 @@
+/**
+ * Stop-hook install — the ONE implementation (port of the inline Node script
+ * that used to live in `scripts/connect.sh`, #217).
+ *
+ * Wires Pigeon's token-tracking Stop hook into the user-level Claude Code
+ * `settings.json` once per machine. Idempotent: an existing hook whose
+ * command ends in `stop-hook.sh` (any install path) is recognized and left
+ * alone; everything else in the file is preserved.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * User-level settings.json to install the hook into. Order:
+ *   1. `PIGEON_USER_SETTINGS` — explicit override; also the test/CI escape
+ *      hatch so dry-runs never mutate a real settings file (#217).
+ *   2. `$CLAUDE_CONFIG_DIR/settings.json` when the user relocated their
+ *      Claude config.
+ *   3. `~/.claude-alt/settings.json` when that directory exists (mirrors
+ *      `resolveClaudeConfigPaths` in src/lib/doctor/config-paths.ts).
+ *   4. `~/.claude/settings.json` — the default.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @param {string} [home]  Home directory override for tests.
+ */
+export function resolveUserSettingsPath(env = process.env, home = homedir()) {
+	if (env.PIGEON_USER_SETTINGS) return resolve(env.PIGEON_USER_SETTINGS);
+	if (env.CLAUDE_CONFIG_DIR) return resolve(env.CLAUDE_CONFIG_DIR, "settings.json");
+	const claudeAlt = join(home, ".claude-alt");
+	if (existsSync(claudeAlt)) return join(claudeAlt, "settings.json");
+	return join(home, ".claude", "settings.json");
+}
+
+/**
+ * True when the settings object already carries a Pigeon Stop hook. Matches
+ * by suffix so moved checkouts are still recognized — mirrors
+ * `configHasTokenHook()` in src/server/services/token-usage-service.ts.
+ *
+ * @param {unknown} settings
+ */
+export function hasPigeonStopHook(settings) {
+	if (settings === null || typeof settings !== "object") return false;
+	const stop = /** @type {{ hooks?: { Stop?: unknown } }} */ (settings).hooks?.Stop;
+	if (!Array.isArray(stop)) return false;
+	for (const group of stop) {
+		const inner = group?.hooks;
+		if (!Array.isArray(inner)) continue;
+		for (const hook of inner) {
+			if (
+				hook &&
+				typeof hook === "object" &&
+				hook.type === "command" &&
+				typeof hook.command === "string" &&
+				(hook.command.endsWith("/stop-hook.sh") || hook.command.endsWith("\\stop-hook.sh"))
+			) {
+				return true;
+			}
+		}
+	}
+	return false;
+}
+
+/**
+ * Merge the Pigeon Stop hook into a settings object. Pure: returns a new
+ * object; `changed: false` means the hook was already present.
+ *
+ * @param {Record<string, unknown>} settings
+ * @param {string} hookCommand  Absolute path to `<home>/scripts/stop-hook.sh`.
+ * @returns {{ changed: boolean, settings: Record<string, unknown> }}
+ */
+export function mergeStopHook(settings, hookCommand) {
+	if (hasPigeonStopHook(settings)) return { changed: false, settings };
+
+	const hooks =
+		settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+			? { .../** @type {Record<string, unknown>} */ (settings.hooks) }
+			: {};
+	const stop = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
+	stop.push({ hooks: [{ type: "command", command: hookCommand }] });
+	hooks.Stop = stop;
+
+	return { changed: true, settings: { ...settings, hooks } };
+}
+
+/**
+ * Install the Stop hook into `settingsPath` (atomic tempfile + rename).
+ *
+ * @param {{ settingsPath: string, hookCommand: string }} options
+ * @returns {{ status: "installed" | "already-installed" | "error", detail?: string }}
+ */
+export function installStopHook({ settingsPath, hookCommand }) {
+	let existing = {};
+	if (existsSync(settingsPath)) {
+		try {
+			const raw = readFileSync(settingsPath, "utf8");
+			if (raw.trim().length > 0) existing = JSON.parse(raw);
+		} catch (err) {
+			return { status: "error", detail: `cannot parse ${settingsPath}: ${err.message}` };
+		}
+		if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+			return { status: "error", detail: `${settingsPath} is not a JSON object — left untouched` };
+		}
+	}
+
+	const { changed, settings } = mergeStopHook(existing, hookCommand);
+	if (!changed) return { status: "already-installed" };
+
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	const tmp = `${settingsPath}.pigeon.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+	renameSync(tmp, settingsPath);
+	return { status: "installed" };
+}

package/lib/tracker-template.mjs

@@ -0,0 +1,63 @@
+/**
+ * Starter `tracker.md` — the runtime board-policy surface, hot-reloaded on
+ * every MCP call. The template ships the day-one schema (schema_version 1)
+ * with the optional keys present as commented examples, so a human can turn
+ * policy on by uncommenting rather than by reading docs first.
+ *
+ * Must stay parseable by `loadTrackerPolicy` in
+ * src/lib/services/tracker-policy.ts (front-matter + body).
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Same slug shape `scripts/register-repo.ts` derives from the project name.
+ *
+ * @param {string} name
+ */
+export function slugify(name) {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+/**
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function starterTrackerMd(projectName) {
+	const slug = slugify(projectName) || "my-project";
+	return `---
+schema_version: 1
+project_slug: ${slug}
+# Require a short \`intent\` (the "why", ≤120 chars) on these MCP tools:
+# intent_required_on:
+#   - moveCard
+#   - deleteCard
+# Per-column guidance agents see when moving cards:
+# columns:
+#   "In Progress":
+#     prompt: Move a card here before starting work on it, with a short intent.
+---
+
+${projectName} — describe the project in a few sentences: what it is, what
+"done" looks like, and anything an AI agent should know before touching the
+board. Agents read this file on every MCP call, so edits take effect
+immediately. Keep it short; the board itself carries the work.
+`;
+}
+
+/**
+ * Write a starter `tracker.md` at the project root if absent.
+ *
+ * @param {{ targetDir: string, projectName: string }} options
+ * @returns {"created" | "exists"}
+ */
+export function writeStarterTrackerMd({ targetDir, projectName }) {
+	const path = join(targetDir, "tracker.md");
+	if (existsSync(path)) return "exists";
+	writeFileSync(path, starterTrackerMd(projectName), "utf8");
+	return "created";
+}

package/lib/ui.mjs

@@ -0,0 +1,51 @@
+/**
+ * Terminal output helpers — mirrors the palette in `scripts/doctor.ts` so the
+ * CLI and the doctor pass read as one voice.
+ */
+
+const COLORS = {
+	reset: "\x1b[0m",
+	dim: "\x1b[2m",
+	bold: "\x1b[1m",
+	green: "\x1b[32m",
+	red: "\x1b[31m",
+	yellow: "\x1b[33m",
+	cyan: "\x1b[36m",
+	gray: "\x1b[90m",
+};
+
+const noColor = process.env.NO_COLOR === "1" || !process.stdout.isTTY;
+
+/**
+ * @param {keyof typeof COLORS} c
+ * @param {string} s
+ */
+export function color(c, s) {
+	return noColor ? s : `${COLORS[c]}${s}${COLORS.reset}`;
+}
+
+/** @param {string} title */
+export function step(title) {
+	console.log("");
+	console.log(color("bold", title));
+}
+
+/** @param {string} message */
+export function ok(message) {
+	console.log(`${color("green", "✓")} ${message}`);
+}
+
+/** @param {string} message */
+export function skip(message) {
+	console.log(`${color("gray", "·")} ${message}`);
+}
+
+/** @param {string} message */
+export function warn(message) {
+	console.log(`${color("yellow", "!")} ${message}`);
+}
+
+/** @param {string} message */
+export function info(message) {
+	console.log(`  ${color("dim", message)}`);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@2nspired/pigeon",
+	"version": "0.1.0",
+	"description": "One-command installer for Pigeon — a local-first kanban board + MCP server for AI-assisted development. Run `npx @2nspired/pigeon init`.",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"pigeon": "bin/pigeon.mjs"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/2nspired/pigeon.git",
+		"directory": "cli"
+	},
+	"homepage": "https://2nspired.github.io/pigeon/",
+	"bugs": {
+		"url": "https://github.com/2nspired/pigeon/issues"
+	},
+	"keywords": [
+		"pigeon",
+		"kanban",
+		"mcp",
+		"claude-code",
+		"ai-agents",
+		"local-first"
+	]
+}