token-pilot 0.19.1 → 0.22.2

package/dist/cli/install-agents.js

@@ -0,0 +1,402 @@
+/**
+ * Phase 5 subtasks 5.3 + 5.4 — install tp-* agents into the user's
+ * Claude Code agent registry.
+ *
+ * Copies every `tp-*.md` from `distAgentsDir` into either
+ * `<projectRoot>/.claude/agents/` (scope=project) or
+ * `<homeDir>/.claude/agents/` (scope=user).
+ *
+ * Idempotence states (see Phase 5 design):
+ *
+ *  - **unchanged-installed** — stored hash matches template hash → skip
+ *    (re-write would be a no-op).
+ *  - **template-upgraded** — stored hash differs from template hash AND
+ *    the file body still matches the stored hash (user did not edit) →
+ *    overwrite.
+ *  - **user-edited** — stored hash does not match the file body hash →
+ *    skip unless `force: true`.
+ *  - **no-hash** — file has no `token_pilot_body_hash` in frontmatter
+ *    → never overwrite. This is always treated as the user's own file,
+ *    even when `force: true`.
+ *
+ * Never throws on a per-file failure: the problem is recorded in
+ * `skipped` so the CLI can report it without aborting the rest.
+ */
+import { readdir, readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "./agent-frontmatter.js";
+function targetDirFor(opts) {
+    const root = opts.scope === "user" ? opts.homeDir : opts.projectRoot;
+    return join(root, ".claude", "agents");
+}
+function sha256(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract the body portion (everything after the closing `---\n`). */
+function extractBody(md) {
+    const m = md.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    return m ? m[1] : md;
+}
+/**
+ * Read a tp-*.md from disk and return the stored `token_pilot_body_hash`
+ * from frontmatter. Returns `null` when the field is absent — this
+ * marks the file as user-owned (no-hash state).
+ */
+async function readStoredHash(p) {
+    try {
+        const md = await readFile(p, "utf-8");
+        const { meta } = parseFrontmatter(md);
+        const stored = meta.token_pilot_body_hash;
+        return typeof stored === "string" && stored.length > 0 ? stored : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function installAgents(opts) {
+    const target = targetDirFor(opts);
+    const result = {
+        installed: [],
+        skipped: [],
+        targetDir: target,
+    };
+    let entries;
+    try {
+        entries = await readdir(opts.distAgentsDir);
+    }
+    catch (err) {
+        const msg = err.code ?? String(err);
+        throw new Error(`install-agents: distAgentsDir not readable (${opts.distAgentsDir}): ${msg}`);
+    }
+    const templates = entries.filter((f) => f.endsWith(".md") && f.startsWith("tp-"));
+    if (templates.length === 0) {
+        return result;
+    }
+    await mkdir(target, { recursive: true });
+    for (const entry of templates) {
+        const name = entry.replace(/\.md$/, "");
+        const distPath = join(opts.distAgentsDir, entry);
+        const targetPath = join(target, entry);
+        let templateMd;
+        try {
+            templateMd = await readFile(distPath, "utf-8");
+        }
+        catch {
+            result.skipped.push({ name, reason: "dist read failed" });
+            continue;
+        }
+        const templateHash = sha256(extractBody(templateMd));
+        if (!(await pathExists(targetPath))) {
+            // Fresh install.
+            try {
+                await writeFile(targetPath, templateMd);
+                result.installed.push(name);
+            }
+            catch {
+                result.skipped.push({ name, reason: "write failed" });
+            }
+            continue;
+        }
+        // Target exists — classify state.
+        const existing = await readFile(targetPath, "utf-8");
+        const storedHash = await readStoredHash(targetPath);
+        const currentBodyHash = sha256(extractBody(existing));
+        if (storedHash === null) {
+            // no-hash: user's own file. Never touch, even with --force.
+            result.skipped.push({
+                name,
+                reason: "not installed by token-pilot (no token_pilot_body_hash)",
+            });
+            continue;
+        }
+        // user-edited must be detected BEFORE the unchanged check, because a
+        // user may hand-edit an agent whose stored hash still equals the
+        // current template hash (common: local tweak, no template update).
+        if (currentBodyHash !== storedHash) {
+            if (opts.force) {
+                try {
+                    await writeFile(targetPath, templateMd);
+                    result.installed.push(name);
+                }
+                catch {
+                    result.skipped.push({ name, reason: "write failed" });
+                }
+            }
+            else {
+                result.skipped.push({
+                    name,
+                    reason: "edited by user (use --force to override)",
+                });
+            }
+            continue;
+        }
+        if (storedHash === templateHash) {
+            // unchanged-installed: silent skip (re-write would be a no-op).
+            result.skipped.push({ name, reason: "unchanged" });
+            continue;
+        }
+        // template-upgraded: user did not edit (currentBodyHash === storedHash)
+        // but the template has moved on — safe to overwrite.
+        try {
+            await writeFile(targetPath, templateMd);
+            result.installed.push(name);
+        }
+        catch {
+            result.skipped.push({ name, reason: "write failed" });
+        }
+    }
+    return result;
+}
+// ─── CLI wrapper ─────────────────────────────────────────────────────────────
+/**
+ * Resolve the dist/agents directory relative to the running `dist/index.js`
+ * entry. Works for both `npm run start` (dist/) and `npm pack`-installed
+ * users (node_modules/token-pilot/dist/agents/). Falls back to `templates/
+ * agents` only when we are clearly running from source (tests, dev mode).
+ */
+export function resolveDistAgentsDir(scriptUrl) {
+    // Compiled layout: dist/cli/install-agents.js → dist/agents/.
+    // One level up from our own file, then into agents/.
+    const here = dirname(fileURLToPath(scriptUrl));
+    return join(here, "..", "agents");
+}
+/** Read one line from an interactive TTY prompt. */
+async function promptLine(question) {
+    process.stderr.write(question);
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        rl.question("", (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Yes/no prompt used by other CLI entry points that want to offer
+ * an opt-in step (e.g. `token-pilot init` → "install agents now?").
+ * Returns false on non-TTY or ambiguous input; callers can pass a
+ * `defaultYes` to accept bare Enter as yes.
+ */
+export async function promptYesNo(question, defaultYes = true) {
+    if (!process.stdin.isTTY)
+        return false;
+    const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+    const ans = (await promptLine(question + suffix)).toLowerCase();
+    if (ans === "")
+        return defaultYes;
+    return ans === "y" || ans === "yes";
+}
+async function promptScope() {
+    process.stderr.write("\nWhere should token-pilot agents be installed?\n" +
+        "  [1] user     → ~/.claude/agents/tp-*.md (available in every project)\n" +
+        "  [2] project  → .claude/agents/tp-*.md (only this project)\n");
+    while (true) {
+        const ans = (await promptLine("Choice [1/2]: ")).toLowerCase();
+        if (ans === "1" || ans === "user")
+            return "user";
+        if (ans === "2" || ans === "project")
+            return "project";
+        process.stderr.write("Please enter 1 or 2.\n");
+    }
+}
+function parseFlag(argv, key) {
+    for (const a of argv) {
+        if (a === `--${key}` || a === `-${key}`)
+            return "true";
+        if (a.startsWith(`--${key}=`))
+            return a.slice(key.length + 3);
+    }
+    return undefined;
+}
+// ─── scope persistence in .token-pilot.json ─────────────────────────────────
+function configPath(projectRoot) {
+    return join(projectRoot, ".token-pilot.json");
+}
+/**
+ * Read `agents.scope` from `<projectRoot>/.token-pilot.json`. Returns
+ * null if the file is missing, unreadable, not valid JSON, or if the
+ * field is absent. Never throws — a bad config should not block install.
+ */
+export async function readPersistedScope(projectRoot) {
+    try {
+        const raw = await readFile(configPath(projectRoot), "utf-8");
+        const json = JSON.parse(raw);
+        const s = json.agents?.scope;
+        if (s === "user" || s === "project")
+            return s;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist `agents.scope` into `<projectRoot>/.token-pilot.json`, merging
+ * with any existing config. Failures are swallowed — persistence is a
+ * convenience, not a correctness requirement.
+ */
+export async function persistScope(projectRoot, scope) {
+    const p = configPath(projectRoot);
+    let existing = {};
+    try {
+        const raw = await readFile(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            existing = parsed;
+        }
+    }
+    catch {
+        /* fresh file */
+    }
+    const currentAgents = existing.agents ?? {};
+    const next = {
+        ...existing,
+        agents: { ...currentAgents, scope },
+    };
+    try {
+        await writeFile(p, JSON.stringify(next, null, 2) + "\n");
+    }
+    catch {
+        /* ignore — persistence is best-effort */
+    }
+}
+/**
+ * CLI entry: `token-pilot install-agents [--scope=user|project] [--force]`.
+ *
+ * Exit codes:
+ *   0 — something installed OR everything was deliberately skipped
+ *   1 — missing/unreadable dist/agents, or non-TTY without --scope
+ */
+export async function handleInstallAgents(argv, opts) {
+    const scopeArg = parseFlag(argv, "scope");
+    const force = parseFlag(argv, "force") !== undefined;
+    const projectRoot = opts?.projectRoot ?? process.cwd();
+    let scope;
+    if (scopeArg === "user" || scopeArg === "project") {
+        scope = scopeArg;
+    }
+    else if (scopeArg !== undefined) {
+        process.stderr.write(`install-agents: --scope must be 'user' or 'project', got '${scopeArg}'\n`);
+        return 1;
+    }
+    else {
+        // No flag — try persisted scope from .token-pilot.json, else prompt.
+        const persisted = await readPersistedScope(projectRoot);
+        if (persisted) {
+            scope = persisted;
+            process.stderr.write(`[token-pilot] Using persisted scope: ${scope} (from .token-pilot.json)\n`);
+        }
+        else {
+            const tty = opts?.isTTY ?? process.stdin.isTTY === true;
+            if (!tty) {
+                process.stderr.write("install-agents: --scope=user|project is required in non-interactive mode.\n");
+                return 1;
+            }
+            scope = await promptScope();
+        }
+    }
+    const distAgentsDir = opts?.distAgentsDir ?? resolveDistAgentsDir(import.meta.url);
+    try {
+        const result = await installAgents({
+            scope,
+            projectRoot,
+            homeDir: opts?.homeDir ?? homedir(),
+            distAgentsDir,
+            force,
+        });
+        const plural = (n, s) => (n === 1 ? s : s + "s");
+        if (result.installed.length > 0) {
+            // Best-effort persist the chosen scope so re-runs skip the prompt.
+            await persistScope(projectRoot, scope);
+            process.stderr.write(`\n[token-pilot] Installed ${result.installed.length} ${plural(result.installed.length, "agent")} ` +
+                `to ${result.targetDir}.\n` +
+                `Start a new Claude Code session to see them.\n`);
+        }
+        if (result.skipped.length > 0) {
+            process.stderr.write(`[token-pilot] Skipped ${result.skipped.length}:\n`);
+            for (const s of result.skipped) {
+                process.stderr.write(`  - ${s.name}: ${s.reason}\n`);
+            }
+        }
+        if (result.installed.length === 0 && result.skipped.length === 0) {
+            process.stderr.write(`[token-pilot] No tp-*.md found in ${distAgentsDir}. ` +
+                `Did you run \`npm run build\`?\n`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`install-agents: ${err.message}\n`);
+        return 1;
+    }
+}
+/**
+ * Scan both user-scope (`<homeDir>/.claude/agents`) and project-scope
+ * (`<projectRoot>/.claude/agents`) for any `tp-*.md`. The reminder fires
+ * only when nothing is found in either location.
+ */
+async function anyTpAgentInstalled(projectRoot, homeDir) {
+    for (const root of [projectRoot, homeDir]) {
+        try {
+            const entries = await readdir(join(root, ".claude", "agents"));
+            if (entries.some((f) => f.startsWith("tp-") && f.endsWith(".md"))) {
+                return true;
+            }
+        }
+        catch {
+            // Missing dir → this scope has nothing; keep checking.
+        }
+    }
+    return false;
+}
+/**
+ * Pure, testable check: should the MCP startup emit the agent-install
+ * reminder right now?
+ */
+export async function shouldEmitStartupReminder(opts) {
+    const env = opts.env ?? process.env;
+    if (env.TOKEN_PILOT_NO_AGENT_REMINDER === "1")
+        return false;
+    if (env.TOKEN_PILOT_SUBAGENT === "1")
+        return false;
+    if (opts.configSuppressed)
+        return false;
+    return !(await anyTpAgentInstalled(opts.projectRoot, opts.homeDir));
+}
+export const STARTUP_REMINDER_MESSAGE = "[token-pilot] tp-* agents not installed. Run `npx token-pilot install-agents` " +
+    "to enable guaranteed-savings subagents (scope: user or project — your choice).\n";
+/**
+ * Emit the reminder to stderr at most once per process. Safe to call
+ * multiple times; subsequent calls are no-ops.
+ */
+let startupReminderEmitted = false;
+export async function maybeEmitStartupReminder(opts) {
+    if (startupReminderEmitted)
+        return false;
+    if (!(await shouldEmitStartupReminder(opts)))
+        return false;
+    process.stderr.write(STARTUP_REMINDER_MESSAGE);
+    startupReminderEmitted = true;
+    return true;
+}
+/** Test-only: reset the single-fire guard. */
+export function _resetStartupReminderForTests() {
+    startupReminderEmitted = false;
+}
+//# sourceMappingURL=install-agents.js.map

package/dist/cli/save-doc.d.ts

@@ -0,0 +1,42 @@
+/**
+ * TP-89n — persist arbitrary research text so it survives compaction.
+ *
+ * `token-pilot save-doc <name>` reads text from stdin (or --content flag)
+ * and writes it to `.token-pilot/docs/<name>.md`. `token-pilot list-docs`
+ * enumerates what's been saved. Later, agents can re-read the file with
+ * `read_range` / `smart_read` instead of re-fetching the external source.
+ *
+ * Safety: name must be a slug (no path separators, no traversal, no
+ * whitespace/control chars). Overwrite is explicit.
+ */
+export declare const DOCS_SUBDIR = ".token-pilot/docs";
+export declare function normalizeDocName(raw: string): string;
+export interface SaveDocInput {
+    projectRoot: string;
+    name: string;
+    content: string;
+    overwrite?: boolean;
+}
+export interface SaveDocResult {
+    saved: boolean;
+    path?: string;
+    reason?: string;
+}
+export declare function saveDoc(input: SaveDocInput): Promise<SaveDocResult>;
+export interface DocEntry {
+    name: string;
+    path: string;
+    bytes: number;
+    mtimeMs: number;
+}
+export declare function listDocs(projectRoot: string): Promise<DocEntry[]>;
+/**
+ * CLI entry — returns exit code.
+ * Usage:
+ *   token-pilot save-doc <name> [--overwrite] [--content "text"]
+ *   token-pilot list-docs
+ * When --content is absent, reads from stdin.
+ */
+export declare function handleSaveDocCli(args: string[]): Promise<number>;
+export declare function handleListDocsCli(): Promise<number>;
+//# sourceMappingURL=save-doc.d.ts.map

package/dist/cli/save-doc.js

@@ -0,0 +1,145 @@
+/**
+ * TP-89n — persist arbitrary research text so it survives compaction.
+ *
+ * `token-pilot save-doc <name>` reads text from stdin (or --content flag)
+ * and writes it to `.token-pilot/docs/<name>.md`. `token-pilot list-docs`
+ * enumerates what's been saved. Later, agents can re-read the file with
+ * `read_range` / `smart_read` instead of re-fetching the external source.
+ *
+ * Safety: name must be a slug (no path separators, no traversal, no
+ * whitespace/control chars). Overwrite is explicit.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+export const DOCS_SUBDIR = ".token-pilot/docs";
+const NAME_RE = /^[A-Za-z0-9._-]+$/;
+export function normalizeDocName(raw) {
+    if (!raw)
+        throw new Error("invalid doc name: empty");
+    const trimmed = raw.endsWith(".md") ? raw.slice(0, -3) : raw;
+    if (!NAME_RE.test(trimmed)) {
+        throw new Error(`invalid doc name: ${JSON.stringify(raw)} — use [A-Za-z0-9._-] only`);
+    }
+    return trimmed;
+}
+export async function saveDoc(input) {
+    const name = normalizeDocName(input.name);
+    if (!input.content) {
+        return { saved: false, reason: "content is empty" };
+    }
+    const dir = join(input.projectRoot, DOCS_SUBDIR);
+    await fs.mkdir(dir, { recursive: true });
+    const path = join(dir, `${name}.md`);
+    if (!input.overwrite) {
+        try {
+            await fs.stat(path);
+            return {
+                saved: false,
+                path,
+                reason: `doc already exists at ${path}; pass --overwrite to replace`,
+            };
+        }
+        catch {
+            /* not present — proceed */
+        }
+    }
+    await fs.writeFile(path, input.content);
+    return { saved: true, path };
+}
+export async function listDocs(projectRoot) {
+    const dir = join(projectRoot, DOCS_SUBDIR);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith(".md"))
+            continue;
+        const full = join(dir, name);
+        try {
+            const s = await fs.stat(full);
+            if (!s.isFile())
+                continue;
+            out.push({
+                name: name.slice(0, -3),
+                path: full,
+                bytes: s.size,
+                mtimeMs: s.mtimeMs,
+            });
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+}
+/**
+ * CLI entry — returns exit code.
+ * Usage:
+ *   token-pilot save-doc <name> [--overwrite] [--content "text"]
+ *   token-pilot list-docs
+ * When --content is absent, reads from stdin.
+ */
+export async function handleSaveDocCli(args) {
+    const name = args.find((a) => !a.startsWith("--"));
+    if (!name) {
+        process.stderr.write('Usage: token-pilot save-doc <name> [--overwrite] [--content "text"]\n');
+        return 1;
+    }
+    const overwrite = args.includes("--overwrite");
+    const contentIdx = args.indexOf("--content");
+    let content;
+    if (contentIdx >= 0 && args[contentIdx + 1] !== undefined) {
+        content = args[contentIdx + 1];
+    }
+    else {
+        content = await readAllStdin();
+    }
+    try {
+        const res = await saveDoc({
+            projectRoot: process.cwd(),
+            name,
+            content,
+            overwrite,
+        });
+        if (res.saved) {
+            process.stdout.write(`Saved: ${res.path}\n`);
+            return 0;
+        }
+        process.stderr.write(`Not saved: ${res.reason ?? "unknown reason"}\n`);
+        return 1;
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+export async function handleListDocsCli() {
+    const docs = await listDocs(process.cwd());
+    if (docs.length === 0) {
+        process.stdout.write("No saved docs.\n");
+        return 0;
+    }
+    for (const d of docs) {
+        const kb = (d.bytes / 1024).toFixed(1);
+        process.stdout.write(`${d.name}\t${kb} KB\t${d.path}\n`);
+    }
+    return 0;
+}
+async function readAllStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+//# sourceMappingURL=save-doc.js.map

package/dist/cli/scan-agents.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Agent scanner + classifier (subtasks 3.2 + 3.3).
+ *
+ * Discovers agent .md files from three locations:
+ *   1. project .claude/agents/**\/*.md  (scope: 'project')
+ *   2. user   ~/.claude/agents/**\/*.md  (scope: 'user')
+ *   3. plugin-contributed agents         (scope: 'plugin')
+ *
+ * For each file: parses frontmatter, computes body hash, returns a ScannedAgent.
+ * Never throws — bad/unreadable files are skipped with a one-line stderr note.
+ * Symlinks pointing outside the scope's nominal root are skipped.
+ */
+import { type ParsedTools } from "./agent-frontmatter.js";
+export type AgentScope = "project" | "user" | "plugin";
+export type AgentCategory = "A" | "B" | "C";
+export interface ScannedAgent {
+    name: string;
+    path: string;
+    scope: AgentScope;
+    tools: ParsedTools;
+    description: string;
+    bodyHash: string;
+    blessed: boolean;
+}
+export interface ScanOptions {
+    projectRoot: string;
+    homeDir: string;
+    /** Pre-resolved glob patterns for plugin agent files (e.g. from ~/.claude/plugins/cache). */
+    pluginCacheGlob: string[];
+}
+/**
+ * Scan all agent directories and return parsed ScannedAgent entries.
+ * Never throws.
+ */
+export declare function scanAgents(opts: ScanOptions): Promise<ScannedAgent[]>;
+/**
+ * Classify an agent by its tools field.
+ *
+ * A — wildcard (tools: * | All tools) → already has MCP access
+ * A — explicit list that already contains mcp__token-pilot__* → already has access
+ * B — exclusion form where mcp__token-pilot__ is NOT excluded → has access
+ * C — explicit list without mcp__token-pilot__* → candidate for blessing
+ * C — exclusion form that explicitly excludes mcp__token-pilot__* → needs blessing
+ */
+export declare function classifyAgent(agent: ScannedAgent): AgentCategory;
+//# sourceMappingURL=scan-agents.d.ts.map