token-pilot 0.19.2 → 0.22.2

package/dist/cli/claudemd-hygiene.d.ts

@@ -0,0 +1,26 @@
+/**
+ * TP-rtg (part 2) — CLAUDE.md hygiene assessment.
+ *
+ * Claude Code injects the project's `CLAUDE.md` into every message. A
+ * 200-line rules file therefore costs thousands of tokens per turn.
+ * Community guide B3 recommends keeping it under 60 non-empty lines and
+ * loading deeper instructions on demand from `docs/`.
+ *
+ * This module only *measures*. It does not touch the file. The caller
+ * (doctor / init) decides how to surface the tip.
+ */
+export declare const CLAUDE_MD_LINE_THRESHOLD = 60;
+export type ClaudeMdAssessment = {
+    kind: "missing";
+} | {
+    kind: "ok";
+    path: string;
+    nonEmptyLines: number;
+} | {
+    kind: "bloated";
+    path: string;
+    nonEmptyLines: number;
+    threshold: number;
+};
+export declare function assessClaudeMd(projectRoot: string, threshold?: number): Promise<ClaudeMdAssessment>;
+//# sourceMappingURL=claudemd-hygiene.d.ts.map

package/dist/cli/claudemd-hygiene.js

@@ -0,0 +1,43 @@
+/**
+ * TP-rtg (part 2) — CLAUDE.md hygiene assessment.
+ *
+ * Claude Code injects the project's `CLAUDE.md` into every message. A
+ * 200-line rules file therefore costs thousands of tokens per turn.
+ * Community guide B3 recommends keeping it under 60 non-empty lines and
+ * loading deeper instructions on demand from `docs/`.
+ *
+ * This module only *measures*. It does not touch the file. The caller
+ * (doctor / init) decides how to surface the tip.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const CLAUDE_MD_LINE_THRESHOLD = 60;
+function countNonEmptyLines(content) {
+    let n = 0;
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        // Treat markdown horizontal rules as separators, not content.
+        if (/^-{3,}$|^_{3,}$|^\*{3,}$/.test(line))
+            continue;
+        n += 1;
+    }
+    return n;
+}
+export async function assessClaudeMd(projectRoot, threshold = CLAUDE_MD_LINE_THRESHOLD) {
+    const path = join(projectRoot, "CLAUDE.md");
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    const nonEmptyLines = countNonEmptyLines(content);
+    if (nonEmptyLines > threshold) {
+        return { kind: "bloated", path, nonEmptyLines, threshold };
+    }
+    return { kind: "ok", path, nonEmptyLines };
+}
+//# sourceMappingURL=claudemd-hygiene.js.map

package/dist/cli/doctor-drift.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Phase 3 subtask 3.7 — drift detection for blessed agents.
+ *
+ * A blessed file records `token_pilot.upstream_hash` at bless time. If the
+ * upstream (user or plugin scope) agent file changes later, our blessed copy
+ * silently ages — users could be running on a definition that no longer
+ * matches its upstream description or tool list. This function re-hashes
+ * every upstream referenced by a blessed file and reports mismatches.
+ *
+ * Integration: called from `handleDoctor` after the other doctor checks.
+ * Never throws; every error is swallowed and surfaced as a warning. Returns
+ * an array so callers can test the findings without stubbing stderr.
+ */
+export interface DriftFinding {
+    agentName: string;
+    blessedPath: string;
+    upstreamScope: "user" | "plugin" | string;
+    storedHash: string;
+    currentHash: string | null;
+    status: "drifted" | "missing-upstream" | "missing-fields";
+}
+export interface DetectDriftOptions {
+    projectRoot: string;
+    homeDir: string;
+}
+export declare function detectDrift(opts: DetectDriftOptions): Promise<DriftFinding[]>;
+/**
+ * Format a single finding as a human-readable stderr line.
+ */
+export declare function formatDriftFinding(f: DriftFinding): string;
+//# sourceMappingURL=doctor-drift.d.ts.map

package/dist/cli/doctor-drift.js

@@ -0,0 +1,130 @@
+/**
+ * Phase 3 subtask 3.7 — drift detection for blessed agents.
+ *
+ * A blessed file records `token_pilot.upstream_hash` at bless time. If the
+ * upstream (user or plugin scope) agent file changes later, our blessed copy
+ * silently ages — users could be running on a definition that no longer
+ * matches its upstream description or tool list. This function re-hashes
+ * every upstream referenced by a blessed file and reports mismatches.
+ *
+ * Integration: called from `handleDoctor` after the other doctor checks.
+ * Never throws; every error is swallowed and surfaced as a warning. Returns
+ * an array so callers can test the findings without stubbing stderr.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { parseFrontmatter } from "./agent-frontmatter.js";
+import { scanAgents } from "./scan-agents.js";
+function currentBlessedHash(meta) {
+    const tp = meta.token_pilot;
+    if (!tp || tp.blessed !== true)
+        return null;
+    const upstream = typeof tp.upstream === "string" ? tp.upstream : null;
+    const hash = typeof tp.upstream_hash === "string" ? tp.upstream_hash : null;
+    if (!upstream || !hash)
+        return null;
+    return { upstream, hash };
+}
+async function sha256File(path) {
+    try {
+        const content = await readFile(path, "utf-8");
+        return createHash("sha256").update(content).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+export async function detectDrift(opts) {
+    const findings = [];
+    const projectAgentsDir = join(opts.projectRoot, ".claude", "agents");
+    let blessedFiles;
+    try {
+        const entries = await readdir(projectAgentsDir);
+        blessedFiles = entries.filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return findings;
+    }
+    // Build a single lookup from upstream scan for efficiency.
+    let upstreamAgents = [];
+    try {
+        upstreamAgents = await scanAgents({
+            projectRoot: opts.projectRoot,
+            homeDir: opts.homeDir,
+            pluginCacheGlob: [],
+        });
+    }
+    catch {
+        // If scan errors we can still report missing-upstream for each blessed
+        // file; keep going with an empty lookup.
+    }
+    const upstreamByName = new Map(upstreamAgents
+        .filter((a) => a.scope !== "project")
+        .map((a) => [a.name + "::" + a.scope, a]));
+    for (const file of blessedFiles) {
+        const fullPath = join(projectAgentsDir, file);
+        const name = file.replace(/\.md$/, "");
+        let meta;
+        try {
+            const body = await readFile(fullPath, "utf-8");
+            ({ meta } = parseFrontmatter(body));
+        }
+        catch {
+            continue;
+        }
+        const marker = currentBlessedHash(meta);
+        if (!marker)
+            continue;
+        const upstream = upstreamByName.get(name + "::" + marker.upstream);
+        if (!upstream) {
+            findings.push({
+                agentName: name,
+                blessedPath: fullPath,
+                upstreamScope: marker.upstream,
+                storedHash: marker.hash,
+                currentHash: null,
+                status: "missing-upstream",
+            });
+            continue;
+        }
+        const currentHash = await sha256File(upstream.path);
+        if (!currentHash) {
+            findings.push({
+                agentName: name,
+                blessedPath: fullPath,
+                upstreamScope: marker.upstream,
+                storedHash: marker.hash,
+                currentHash: null,
+                status: "missing-upstream",
+            });
+            continue;
+        }
+        if (currentHash !== marker.hash) {
+            findings.push({
+                agentName: name,
+                blessedPath: fullPath,
+                upstreamScope: marker.upstream,
+                storedHash: marker.hash,
+                currentHash,
+                status: "drifted",
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Format a single finding as a human-readable stderr line.
+ */
+export function formatDriftFinding(f) {
+    if (f.status === "drifted") {
+        return (`⚠ tp-${f.agentName}: upstream changed since bless (scope=${f.upstreamScope}). ` +
+            `Run: npx token-pilot bless-agents --re ${f.agentName}`);
+    }
+    if (f.status === "missing-upstream") {
+        return (`⚠ tp-${f.agentName}: upstream no longer found (scope=${f.upstreamScope}). ` +
+            `The blessed copy is orphaned; consider: npx token-pilot unbless-agents ${f.agentName}`);
+    }
+    return `⚠ tp-${f.agentName}: blessed frontmatter missing required fields`;
+}
+//# sourceMappingURL=doctor-drift.js.map

package/dist/cli/doctor-env-check.d.ts

@@ -0,0 +1,25 @@
+/**
+ * TP-c08 — detect Claude Code environment knobs that the community
+ * usage-limit guide (TP-yk9) calls out as giving 60-80% session savings
+ * with zero code change.
+ *
+ * This is pure advisory: we never modify the user's environment or
+ * settings file. `checkClaudeCodeEnv` returns a list of one-line tips,
+ * each pointing at a missing or wasteful knob. Empty list == all good.
+ */
+export interface EnvCheckInput {
+    /** Snapshot of process.env (pass in for testability). */
+    env: Record<string, string | undefined>;
+    /**
+     * Parsed contents of `~/.claude/settings.json`. Pass `null` / anything
+     * non-object to represent "file missing or unreadable".
+     */
+    settings: unknown;
+}
+export declare function checkClaudeCodeEnv(input: EnvCheckInput): string[];
+/**
+ * Load `~/.claude/settings.json` and run the pure check. Silent on I/O
+ * failures — a missing file simply means "no settings, all tips apply".
+ */
+export declare function runClaudeCodeEnvCheck(homeDirPath?: string, processEnv?: Record<string, string | undefined>): Promise<string[]>;
+//# sourceMappingURL=doctor-env-check.d.ts.map

package/dist/cli/doctor-env-check.js

@@ -0,0 +1,91 @@
+/**
+ * TP-c08 — detect Claude Code environment knobs that the community
+ * usage-limit guide (TP-yk9) calls out as giving 60-80% session savings
+ * with zero code change.
+ *
+ * This is pure advisory: we never modify the user's environment or
+ * settings file. `checkClaudeCodeEnv` returns a list of one-line tips,
+ * each pointing at a missing or wasteful knob. Empty list == all good.
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const MAX_THINKING_TOKENS_CAP = 16000;
+const MAX_AUTOCOMPACT_PCT = 80;
+function asRecord(x) {
+    if (x && typeof x === "object" && !Array.isArray(x)) {
+        return x;
+    }
+    return {};
+}
+/**
+ * Pull the effective value of a Claude Code env knob. Process env wins
+ * over `settings.env.*` because if Claude Code or the user's shell
+ * exported a value, that is what the child process actually sees.
+ */
+function effective(envKey, processEnv, settingsEnv) {
+    if (typeof processEnv[envKey] === "string" && processEnv[envKey] !== "") {
+        return processEnv[envKey];
+    }
+    const fromSettings = settingsEnv[envKey];
+    if (typeof fromSettings === "string" && fromSettings !== "") {
+        return fromSettings;
+    }
+    return undefined;
+}
+export function checkClaudeCodeEnv(input) {
+    const tips = [];
+    const settings = asRecord(input.settings);
+    const settingsEnv = asRecord(settings.env);
+    // CLAUDE_CODE_SUBAGENT_MODEL=haiku — biggest single knob for subagent
+    // savings (~80% cheaper than Sonnet for the exploration work delegates
+    // do). Unset → cost stays at default.
+    const subagentModel = effective("CLAUDE_CODE_SUBAGENT_MODEL", input.env, settingsEnv);
+    if (!subagentModel || subagentModel === "opus") {
+        tips.push(`CLAUDE_CODE_SUBAGENT_MODEL not set to haiku — add \`"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"\` under \`env\` in ~/.claude/settings.json to route subagents to Haiku (~80% cheaper).`);
+    }
+    // MAX_THINKING_TOKENS — Claude's hidden reasoning tokens default to
+    // 32000. Community finds 10000 saves ~70% with minimal quality loss.
+    const thinking = effective("MAX_THINKING_TOKENS", input.env, settingsEnv);
+    const thinkingNum = thinking ? Number.parseInt(thinking, 10) : null;
+    if (!thinking ||
+        thinkingNum === null ||
+        !Number.isFinite(thinkingNum) ||
+        thinkingNum > MAX_THINKING_TOKENS_CAP) {
+        tips.push(`MAX_THINKING_TOKENS ${thinking ? `is ${thinking}` : "unset (defaults to 32000)"} — add \`"MAX_THINKING_TOKENS": "10000"\` under \`env\` in ~/.claude/settings.json to cap hidden reasoning tokens (~70% saving).`);
+    }
+    // CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — compact at 50% instead of the
+    // default 95%. Keeps sessions healthier, fewer token cliffs.
+    const autocompact = effective("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE", input.env, settingsEnv);
+    const autoNum = autocompact ? Number.parseInt(autocompact, 10) : null;
+    if (!autocompact ||
+        autoNum === null ||
+        !Number.isFinite(autoNum) ||
+        autoNum > MAX_AUTOCOMPACT_PCT) {
+        tips.push(`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE ${autocompact ? `is ${autocompact}` : "unset"} — add \`"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"\` under \`env\` in ~/.claude/settings.json to compact context earlier (healthier sessions).`);
+    }
+    // settings.model — only flag if explicitly set to opus. Absence means
+    // Claude Code's own default, which may be the right choice for the
+    // user; we don't second-guess.
+    const model = settings.model;
+    if (typeof model === "string" && model === "opus") {
+        tips.push(`"model": "opus" in ~/.claude/settings.json defaults every session to Opus (~5× Sonnet cost). Set \`"model": "sonnet"\` if you don't actively need Opus reasoning on every task.`);
+    }
+    return tips;
+}
+/**
+ * Load `~/.claude/settings.json` and run the pure check. Silent on I/O
+ * failures — a missing file simply means "no settings, all tips apply".
+ */
+export async function runClaudeCodeEnvCheck(homeDirPath = homedir(), processEnv = process.env) {
+    let settings = {};
+    try {
+        const raw = await readFile(join(homeDirPath, ".claude", "settings.json"), "utf-8");
+        settings = JSON.parse(raw);
+    }
+    catch {
+        // Missing or malformed — treat as empty settings. Tips will surface.
+    }
+    return checkClaudeCodeEnv({ env: processEnv, settings });
+}
+//# sourceMappingURL=doctor-env-check.js.map

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

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+export type Scope = "user" | "project";
+export interface InstallOptions {
+    scope: Scope;
+    /** Used when scope === "project". */
+    projectRoot: string;
+    /** Used when scope === "user". */
+    homeDir: string;
+    /** Directory holding the rendered dist/agents/tp-*.md files. */
+    distAgentsDir: string;
+    /** When true, overwrite user-edited files (never no-hash files). */
+    force?: boolean;
+}
+export interface InstallResult {
+    /** Names of files actually written during this run. */
+    installed: string[];
+    /** Entries that were deliberately left alone; reason explains why. */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** Absolute path we wrote (or would have written) into. */
+    targetDir: string;
+}
+export declare function installAgents(opts: InstallOptions): Promise<InstallResult>;
+/**
+ * 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 declare function resolveDistAgentsDir(scriptUrl: string): string;
+/**
+ * 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 declare function promptYesNo(question: string, defaultYes?: boolean): Promise<boolean>;
+/**
+ * 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 declare function readPersistedScope(projectRoot: string): Promise<Scope | 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 declare function persistScope(projectRoot: string, scope: Scope): Promise<void>;
+/**
+ * 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 declare function handleInstallAgents(argv: string[], opts?: {
+    distAgentsDir?: string;
+    homeDir?: string;
+    projectRoot?: string;
+    isTTY?: boolean;
+}): Promise<number>;
+export interface StartupReminderOptions {
+    projectRoot: string;
+    homeDir: string;
+    /**
+     * If true, the reminder is suppressed. Callers pass
+     * `cfg.agents.reminder === false` here.
+     */
+    configSuppressed: boolean;
+    /** Environment snapshot to consult; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Pure, testable check: should the MCP startup emit the agent-install
+ * reminder right now?
+ */
+export declare function shouldEmitStartupReminder(opts: StartupReminderOptions): Promise<boolean>;
+export declare const STARTUP_REMINDER_MESSAGE: string;
+export declare function maybeEmitStartupReminder(opts: StartupReminderOptions): Promise<boolean>;
+/** Test-only: reset the single-fire guard. */
+export declare function _resetStartupReminderForTests(): void;
+//# sourceMappingURL=install-agents.d.ts.map