token-pilot 0.19.2 → 0.22.2

package/dist/cli/agent-frontmatter.js

@@ -0,0 +1,189 @@
+/**
+ * Agent-frontmatter helpers (subtask 3.1).
+ *
+ * Parses and writes YAML-style frontmatter in Claude Code agent .md files.
+ * Handles the three tools-field forms:
+ *   - wildcard   : "*" | "All tools"
+ *   - exclusion  : "All tools [except X, Y]"
+ *   - explicit   : "Read, Edit, Bash" | string[] (YAML list)
+ */
+// ─── parseFrontmatter ─────────────────────────────────────────────────────────
+/**
+ * Parse YAML-style frontmatter from an agent markdown file.
+ *
+ * Handles:
+ *  - Simple key: value pairs
+ *  - YAML list items (- value)
+ *  - Nested blocks (token_pilot: / sub-key: value)
+ *  - CRLF line endings
+ */
+export function parseFrontmatter(md) {
+    const match = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { meta: {}, body: md };
+    }
+    const yamlText = match[1];
+    const body = match[2] ?? "";
+    const meta = parseSimpleYaml(yamlText);
+    return { meta, body };
+}
+/**
+ * Parse a subset of YAML sufficient for agent frontmatter.
+ * Supports: scalar values, inline lists, block lists, nested maps.
+ */
+function parseSimpleYaml(text) {
+    const result = {};
+    const lines = text.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Skip empty lines
+        if (!line.trim()) {
+            i++;
+            continue;
+        }
+        // Top-level key: value
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (!kv) {
+            i++;
+            continue;
+        }
+        const key = kv[1];
+        const rawVal = kv[2].trim();
+        // Empty value → could be a nested block or inline list
+        if (rawVal === "") {
+            // Look ahead for indented lines (nested block or list)
+            const nested = [];
+            i++;
+            while (i < lines.length &&
+                (lines[i].startsWith("  ") || lines[i].startsWith("\t"))) {
+                nested.push(lines[i]);
+                i++;
+            }
+            if (nested.length === 0) {
+                result[key] = "";
+                continue;
+            }
+            // Check if it's a list (items start with "  - ")
+            if (nested[0].trim().startsWith("- ")) {
+                result[key] = nested.map((l) => l.trim().replace(/^-\s+/, ""));
+            }
+            else {
+                // Nested map — dedent and recurse
+                const dedented = nested.map((l) => l.replace(/^  /, "")).join("\n");
+                result[key] = parseSimpleYaml(dedented);
+            }
+            continue;
+        }
+        // Inline YAML list: [a, b, c]
+        if (rawVal.startsWith("[") && rawVal.endsWith("]")) {
+            result[key] = rawVal
+                .slice(1, -1)
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            i++;
+            continue;
+        }
+        // Boolean values
+        if (rawVal === "true") {
+            result[key] = true;
+            i++;
+            continue;
+        }
+        if (rawVal === "false") {
+            result[key] = false;
+            i++;
+            continue;
+        }
+        // Strip surrounding quotes
+        if ((rawVal.startsWith("'") && rawVal.endsWith("'")) ||
+            (rawVal.startsWith('"') && rawVal.endsWith('"'))) {
+            result[key] = rawVal.slice(1, -1);
+            i++;
+            continue;
+        }
+        result[key] = rawVal;
+        i++;
+    }
+    return result;
+}
+// ─── writeFrontmatter ─────────────────────────────────────────────────────────
+/**
+ * Serialize meta + body back to a markdown string with YAML frontmatter.
+ */
+export function writeFrontmatter({ meta, body }) {
+    const yaml = serializeYaml(meta);
+    return `---\n${yaml}---\n${body}`;
+}
+function serializeYaml(obj, indent = "") {
+    let out = "";
+    for (const [key, val] of Object.entries(obj)) {
+        if (val === null || val === undefined)
+            continue;
+        if (Array.isArray(val)) {
+            out += `${indent}${key}:\n`;
+            for (const item of val) {
+                out += `${indent}  - ${item}\n`;
+            }
+        }
+        else if (typeof val === "object") {
+            out += `${indent}${key}:\n`;
+            out += serializeYaml(val, indent + "  ");
+        }
+        else if (typeof val === "boolean") {
+            out += `${indent}${key}: ${val}\n`;
+        }
+        else {
+            // Quote strings containing special YAML chars
+            const s = String(val);
+            const needsQuote = /[:#\[\]{}&*!,|>'"%@`]/.test(s) || s.trim() !== s;
+            out += `${indent}${key}: ${needsQuote ? `"${s.replace(/"/g, '\\"')}"` : s}\n`;
+        }
+    }
+    return out;
+}
+// ─── parseToolsField ─────────────────────────────────────────────────────────
+/**
+ * Parse the tools field from an agent frontmatter into one of three forms.
+ *
+ * @param raw - Raw value from parsed frontmatter (string, string[], or undefined)
+ */
+export function parseToolsField(raw) {
+    // Array form — already a YAML list
+    if (Array.isArray(raw)) {
+        return {
+            kind: "explicit",
+            tools: raw.map((s) => s.trim()).filter(Boolean),
+        };
+    }
+    if (!raw) {
+        return { kind: "explicit", tools: [] };
+    }
+    const s = raw.trim();
+    // Strip surrounding quotes
+    const unquoted = (s.startsWith("'") && s.endsWith("'")) ||
+        (s.startsWith('"') && s.endsWith('"'))
+        ? s.slice(1, -1).trim()
+        : s;
+    // Wildcard forms
+    if (unquoted === "*" || unquoted === "All tools") {
+        return { kind: "wildcard" };
+    }
+    // Exclusion form: "All tools [except X, Y]" or "All tools except X, Y"
+    const exclusionMatch = unquoted.match(/^All tools\s+(?:\[except\s+|except\s+)(.*?)\]?$/i);
+    if (exclusionMatch) {
+        const excluded = exclusionMatch[1]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return { kind: "exclusion", excluded };
+    }
+    // Explicit comma-separated list
+    const tools = unquoted
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { kind: "explicit", tools };
+}
+//# sourceMappingURL=agent-frontmatter.js.map

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

@@ -0,0 +1,65 @@
+/**
+ * bless-agents CLI (subtasks 3.4 + 3.5).
+ *
+ * Given a Category-C ScannedAgent:
+ *  - Reads upstream file
+ *  - Extends tools list with the 6 mcp__token-pilot__* tool names
+ *  - Adds token_pilot frontmatter block with blessed marker
+ *  - Copies upstream body verbatim
+ *  - Writes atomically to ./.claude/agents/<name>.md
+ *
+ * Never overwrites a file without blessed:true unless --force.
+ * Never overwrites a user prior customisation (file without marker).
+ */
+import type { ScannedAgent } from "./scan-agents.js";
+export declare const TP_MCP_TOOLS: string[];
+export interface BlessOptions {
+    projectRoot: string;
+    tokenPilotVersion: string;
+    force: boolean;
+    dryRun: boolean;
+}
+export type BlessResult = {
+    kind: "blessed";
+    destPath: string;
+} | {
+    kind: "skipped";
+    reason: string;
+} | {
+    kind: "dry-run";
+    destPath: string;
+} | {
+    kind: "error";
+    reason: string;
+};
+export interface BlessSummary {
+    blessed: number;
+    skipped: number;
+    errors: number;
+}
+/**
+ * Bless a single Category-C agent.
+ * Reads upstream file, builds new frontmatter + body, writes atomically.
+ */
+export declare function blessAgent(agent: ScannedAgent, opts: BlessOptions): Promise<BlessResult>;
+/**
+ * Bless a list of agents and print a summary to stderr.
+ */
+export declare function blessAll(agents: ScannedAgent[], opts: BlessOptions): Promise<BlessSummary>;
+export type PromptChoice = "all" | "interactive" | "no";
+/**
+ * Present the classified list and ask the user what to do.
+ * Returns the choice or throws if stdin is not a TTY without --auto.
+ */
+export declare function promptBlessChoice(candidates: ScannedAgent[]): Promise<PromptChoice>;
+/**
+ * Interactive mode: ask per-agent.
+ * Returns list of agents the user confirmed.
+ */
+export declare function promptInteractive(candidates: ScannedAgent[]): Promise<ScannedAgent[]>;
+/**
+ * Main entry for `token-pilot bless-agents` command.
+ * Called from src/index.ts — delegates scanning + blessing.
+ */
+export declare function handleBlessAgents(argv: string[]): Promise<void>;
+//# sourceMappingURL=bless-agents.d.ts.map

package/dist/cli/bless-agents.js

@@ -0,0 +1,307 @@
+/**
+ * bless-agents CLI (subtasks 3.4 + 3.5).
+ *
+ * Given a Category-C ScannedAgent:
+ *  - Reads upstream file
+ *  - Extends tools list with the 6 mcp__token-pilot__* tool names
+ *  - Adds token_pilot frontmatter block with blessed marker
+ *  - Copies upstream body verbatim
+ *  - Writes atomically to ./.claude/agents/<name>.md
+ *
+ * Never overwrites a file without blessed:true unless --force.
+ * Never overwrites a user prior customisation (file without marker).
+ */
+import { readFile, writeFile, mkdir, rename, access } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline";
+import { parseFrontmatter, writeFrontmatter } from "./agent-frontmatter.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const TP_MCP_TOOLS = [
+    "mcp__token-pilot__smart_read",
+    "mcp__token-pilot__read_symbol",
+    "mcp__token-pilot__read_for_edit",
+    "mcp__token-pilot__outline",
+    "mcp__token-pilot__find_usages",
+    "mcp__token-pilot__explore_area",
+];
+// ─── Core: blessAgent ─────────────────────────────────────────────────────────
+/**
+ * Bless a single Category-C agent.
+ * Reads upstream file, builds new frontmatter + body, writes atomically.
+ */
+export async function blessAgent(agent, opts) {
+    const destPath = join(opts.projectRoot, ".claude", "agents", `${agent.name}.md`);
+    // ── Check destination ──────────────────────────────────────────────────────
+    let destExists = false;
+    try {
+        await access(destPath);
+        destExists = true;
+    }
+    catch {
+        destExists = false;
+    }
+    if (destExists) {
+        let destContent;
+        try {
+            destContent = await readFile(destPath, "utf-8");
+        }
+        catch (err) {
+            return {
+                kind: "error",
+                reason: `Cannot read existing destination: ${err instanceof Error ? err.message : err}`,
+            };
+        }
+        const { meta: destMeta } = parseFrontmatter(destContent);
+        const isOurBlessed = destMeta.token_pilot !== null &&
+            typeof destMeta.token_pilot === "object" &&
+            destMeta.token_pilot.blessed === true;
+        if (isOurBlessed && !opts.force) {
+            return {
+                kind: "skipped",
+                reason: `already blessed — use --force to re-bless`,
+            };
+        }
+        if (!isOurBlessed) {
+            // Exists without our marker → user's prior customisation → always skip
+            return {
+                kind: "skipped",
+                reason: `prior customisation exists without blessed marker — skipping to respect user override`,
+            };
+        }
+        // isOurBlessed && force → fall through to overwrite
+    }
+    // ── Read upstream ──────────────────────────────────────────────────────────
+    let upstreamContent;
+    try {
+        upstreamContent = await readFile(agent.path, "utf-8");
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            reason: `Cannot read upstream file ${agent.path}: ${err instanceof Error ? err.message : err}`,
+        };
+    }
+    const { meta: upstreamMeta, body: upstreamBody } = parseFrontmatter(upstreamContent);
+    // ── Build new tools list ───────────────────────────────────────────────────
+    // Start from the upstream tools (may be string or array), add TP tools
+    let existingTools = [];
+    if (Array.isArray(upstreamMeta.tools)) {
+        existingTools = upstreamMeta.tools.map((t) => String(t).trim());
+    }
+    else if (typeof upstreamMeta.tools === "string") {
+        existingTools = upstreamMeta.tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    // De-duplicate: add only missing TP tools
+    const newTools = [...existingTools];
+    for (const t of TP_MCP_TOOLS) {
+        if (!newTools.includes(t)) {
+            newTools.push(t);
+        }
+    }
+    // ── Compute upstream hash ─────────────────────────────────────────────────
+    const upstreamHash = createHash("sha256")
+        .update(upstreamContent)
+        .digest("hex");
+    // ── Build new meta ─────────────────────────────────────────────────────────
+    const newMeta = {
+        name: upstreamMeta.name ?? agent.name,
+        description: upstreamMeta.description ?? agent.description,
+        tools: newTools,
+        token_pilot: {
+            blessed: true,
+            upstream: agent.scope,
+            blessed_at: new Date().toISOString(),
+            token_pilot_version: opts.tokenPilotVersion,
+            upstream_hash: upstreamHash,
+        },
+    };
+    // ── Dry run ────────────────────────────────────────────────────────────────
+    if (opts.dryRun) {
+        return { kind: "dry-run", destPath };
+    }
+    // ── Write atomically ───────────────────────────────────────────────────────
+    const newContent = writeFrontmatter({ meta: newMeta, body: upstreamBody });
+    const destDir = dirname(destPath);
+    await mkdir(destDir, { recursive: true });
+    const tmpPath = `${destPath}.tmp-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmpPath, newContent, "utf-8");
+        await rename(tmpPath, destPath);
+    }
+    catch (err) {
+        // Clean up tmp on failure
+        try {
+            await writeFile(tmpPath, ""); // truncate so rename can't partially exist
+        }
+        catch {
+            // ignore
+        }
+        return {
+            kind: "error",
+            reason: `Write failed: ${err instanceof Error ? err.message : err}`,
+        };
+    }
+    return { kind: "blessed", destPath };
+}
+// ─── blessAll ─────────────────────────────────────────────────────────────────
+/**
+ * Bless a list of agents and print a summary to stderr.
+ */
+export async function blessAll(agents, opts) {
+    const summary = { blessed: 0, skipped: 0, errors: 0 };
+    for (const agent of agents) {
+        const result = await blessAgent(agent, opts);
+        switch (result.kind) {
+            case "blessed":
+                summary.blessed++;
+                break;
+            case "skipped":
+            case "dry-run":
+                summary.skipped++;
+                break;
+            case "error":
+                summary.errors++;
+                process.stderr.write(`token-pilot bless-agents: error on ${agent.name}: ${result.reason}\n`);
+                break;
+        }
+    }
+    if (!opts.dryRun) {
+        process.stderr.write(`Blessed ${summary.blessed} agent${summary.blessed === 1 ? "" : "s"} to .claude/agents/. Start a new Claude Code session to pick them up.\n`);
+    }
+    return summary;
+}
+/**
+ * Present the classified list and ask the user what to do.
+ * Returns the choice or throws if stdin is not a TTY without --auto.
+ */
+export async function promptBlessChoice(candidates) {
+    if (!process.stdin.isTTY) {
+        process.stderr.write("Run with --auto to install non-interactively, or from a TTY.\n");
+        process.exit(1);
+    }
+    process.stderr.write(`\nFound ${candidates.length} agent(s) to bless:\n`);
+    for (const a of candidates) {
+        process.stderr.write(`  - ${a.name} (${a.scope})\n`);
+    }
+    process.stderr.write("\nCreate project-level overrides with MCP tools added?\n");
+    process.stderr.write("  [a] Yes, all\n  [i] Interactive (ask per agent)\n  [n] No, cancel\n\n> ");
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        rl.question("", (answer) => {
+            rl.close();
+            const a = answer.trim().toLowerCase();
+            if (a === "a" || a === "all")
+                resolve("all");
+            else if (a === "i" || a === "interactive")
+                resolve("interactive");
+            else
+                resolve("no");
+        });
+    });
+}
+/**
+ * Interactive mode: ask per-agent.
+ * Returns list of agents the user confirmed.
+ */
+export async function promptInteractive(candidates) {
+    const chosen = [];
+    for (const agent of candidates) {
+        const answer = await new Promise((resolve) => {
+            process.stderr.write(`Bless ${agent.name} (${agent.scope})? [y/n] `);
+            const rl = createInterface({
+                input: process.stdin,
+                output: process.stderr,
+            });
+            rl.question("", (a) => {
+                rl.close();
+                resolve(a.trim().toLowerCase());
+            });
+        });
+        if (answer === "y" || answer === "yes") {
+            chosen.push(agent);
+        }
+    }
+    return chosen;
+}
+// ─── CLI entry ────────────────────────────────────────────────────────────────
+/**
+ * Main entry for `token-pilot bless-agents` command.
+ * Called from src/index.ts — delegates scanning + blessing.
+ */
+export async function handleBlessAgents(argv) {
+    const { scanAgents, classifyAgent } = await import("./scan-agents.js");
+    const { homedir } = await import("node:os");
+    const { existsSync } = await import("node:fs");
+    const auto = argv.includes("--auto");
+    const force = argv.includes("--force");
+    const dryRun = argv.includes("--dry-run");
+    const homeDir = homedir();
+    const projectRoot = process.cwd();
+    // Derive token-pilot version from package.json
+    let tpVersion = "0.0.0";
+    try {
+        const pkgPath = new URL("../../package.json", import.meta.url);
+        const pkg = JSON.parse(await readFile(pkgPath.pathname, "utf-8"));
+        tpVersion = pkg.version;
+    }
+    catch {
+        // fallback
+    }
+    // Build plugin cache globs
+    const pluginCacheBase = join(homeDir, ".claude", "plugins", "cache");
+    const pluginCacheGlob = existsSync(pluginCacheBase)
+        ? [`${pluginCacheBase}/**/agents/*.md`]
+        : [];
+    let agents;
+    try {
+        agents = await scanAgents({ projectRoot, homeDir, pluginCacheGlob });
+    }
+    catch (err) {
+        process.stderr.write(`token-pilot bless-agents: scan failed: ${err instanceof Error ? err.message : err}\n`);
+        process.exit(1);
+    }
+    // Filter to Category-C candidates only
+    const candidates = agents.filter((a) => classifyAgent(a) === "C");
+    if (candidates.length === 0) {
+        process.stderr.write("No Category-C agents found. All agents already have token-pilot MCP access or no agents are installed.\n");
+        process.exit(0);
+    }
+    const opts = {
+        projectRoot,
+        tokenPilotVersion: tpVersion,
+        force,
+        dryRun,
+    };
+    let toProcess = candidates;
+    if (!auto) {
+        // Interactive or TTY check
+        if (!process.stdin.isTTY) {
+            process.stderr.write("Run with --auto to install non-interactively, or from a TTY.\n");
+            process.exit(1);
+        }
+        const choice = await promptBlessChoice(candidates);
+        if (choice === "no") {
+            process.stderr.write("Cancelled.\n");
+            process.exit(0);
+        }
+        if (choice === "interactive") {
+            toProcess = await promptInteractive(candidates);
+            if (toProcess.length === 0) {
+                process.stderr.write("No agents selected.\n");
+                process.exit(0);
+            }
+        }
+    }
+    const summary = await blessAll(toProcess, opts);
+    if (summary.errors > 0) {
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=bless-agents.js.map

package/dist/cli/claudeignore.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TP-rtg (part 1) — `.claudeignore` generator.
+ *
+ * The `.claudeignore` file is a community convention (mirrors `.gitignore`):
+ * Claude Code and other tools skip listed paths when building context.
+ * Populating it with sensible defaults gives a one-time, permanent drop in
+ * per-message token cost (node_modules, dist, lockfiles etc.).
+ *
+ * Non-destructive: we never overwrite a user-owned file. The file we
+ * generate carries a magic comment so the tool can recognise its own
+ * past output on re-run and refresh the defaults in place.
+ */
+export declare const CLAUDEIGNORE_MANAGED_MARKER = "# token-pilot managed defaults (safe to edit; marker keeps this file auto-refreshable)";
+export declare const DEFAULT_IGNORE_ENTRIES: readonly string[];
+export type ClaudeIgnoreStatus = {
+    kind: "absent";
+} | {
+    kind: "managed";
+} | {
+    kind: "user-owned";
+};
+/**
+ * Determine the current state of `<projectRoot>/.claudeignore`:
+ * absent, written by us (managed), or authored by the user (user-owned).
+ */
+export declare function claudeIgnoreStatus(projectRoot: string): Promise<ClaudeIgnoreStatus>;
+/**
+ * Write (or refresh) the default `.claudeignore`. Returns true when we
+ * actually touched the file, false when we refused to avoid clobbering
+ * user content.
+ */
+export declare function writeDefaultClaudeIgnore(projectRoot: string): Promise<boolean>;
+//# sourceMappingURL=claudeignore.d.ts.map

package/dist/cli/claudeignore.js

@@ -0,0 +1,88 @@
+/**
+ * TP-rtg (part 1) — `.claudeignore` generator.
+ *
+ * The `.claudeignore` file is a community convention (mirrors `.gitignore`):
+ * Claude Code and other tools skip listed paths when building context.
+ * Populating it with sensible defaults gives a one-time, permanent drop in
+ * per-message token cost (node_modules, dist, lockfiles etc.).
+ *
+ * Non-destructive: we never overwrite a user-owned file. The file we
+ * generate carries a magic comment so the tool can recognise its own
+ * past output on re-run and refresh the defaults in place.
+ */
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+export const CLAUDEIGNORE_MANAGED_MARKER = "# token-pilot managed defaults (safe to edit; marker keeps this file auto-refreshable)";
+export const DEFAULT_IGNORE_ENTRIES = [
+    "node_modules/",
+    "dist/",
+    "build/",
+    ".next/",
+    ".nuxt/",
+    ".turbo/",
+    "__pycache__/",
+    ".venv/",
+    "venv/",
+    "target/",
+    "coverage/",
+    ".coverage/",
+    "*.min.js",
+    "*.min.css",
+    "*.map",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "Cargo.lock",
+    "Pipfile.lock",
+    "poetry.lock",
+    "composer.lock",
+];
+function pathFor(projectRoot) {
+    return join(projectRoot, ".claudeignore");
+}
+/**
+ * Determine the current state of `<projectRoot>/.claudeignore`:
+ * absent, written by us (managed), or authored by the user (user-owned).
+ */
+export async function claudeIgnoreStatus(projectRoot) {
+    const p = pathFor(projectRoot);
+    try {
+        await access(p);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    try {
+        const content = await readFile(p, "utf-8");
+        if (content.includes(CLAUDEIGNORE_MANAGED_MARKER))
+            return { kind: "managed" };
+        return { kind: "user-owned" };
+    }
+    catch {
+        return { kind: "user-owned" };
+    }
+}
+/**
+ * Write (or refresh) the default `.claudeignore`. Returns true when we
+ * actually touched the file, false when we refused to avoid clobbering
+ * user content.
+ */
+export async function writeDefaultClaudeIgnore(projectRoot) {
+    const status = await claudeIgnoreStatus(projectRoot);
+    if (status.kind === "user-owned")
+        return false;
+    const body = `${CLAUDEIGNORE_MANAGED_MARKER}\n` +
+        `# Paths Claude Code and friendly tools will skip when building context.\n` +
+        `# Remove or edit entries; the marker line above keeps this file refreshable\n` +
+        `# by \`token-pilot init\` / \`token-pilot doctor\`.\n\n` +
+        DEFAULT_IGNORE_ENTRIES.join("\n") +
+        "\n";
+    try {
+        await writeFile(pathFor(projectRoot), body);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=claudeignore.js.map