harnery 0.5.0 → 0.7.0

package/dist/commands/decision.js

@@ -0,0 +1,354 @@
+import { existsSync, readFileSync } from "node:fs";
+import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, } from "../core/agents/index.js";
+import { resolveBinName } from "../core/config.js";
+import { archiveDecision, claimDecision, DECISION_STAKES, fileDecision, isStakes, isStatus, isTier, isVerdict, listDecisions, reopenDecision, resolveDecision, reviewDecision, searchDecisions, showDecision, supersedeDecision, triageDecision, wontfixDecision, } from "../lib/decision/index.js";
+/**
+ * `harn decision`: the decision docket — a persistent queue of decisions an
+ * agent would otherwise route to a human, carried through triage → deliberation
+ * → an evidence-cited resolution → async review.
+ *
+ * The engine is generic: it stores `tier` (0/1/2) + `stakes` but never decides
+ * what belongs in which tier — that's host policy, applied by the filing agent
+ * (for a host, via its own decision skill + rubric).
+ */
+let emit;
+export function registerDecisionCommand(program, emitParam) {
+    emit = emitParam;
+    const bin = () => resolveBinName();
+    const root = program
+        .command("decision")
+        .alias("decisions")
+        .description("Decision docket: file a decision an agent would otherwise escalate, " +
+        "deliberate it, resolve with cited evidence, review async.");
+    // ── file ─────────────────────────────────────────────────────────────────
+    root
+        .command("file <question...>")
+        .description("File a decision into the docket. Tier/stakes are the filer's triage call.")
+        .option("--tier <0|1|2>", "Human-involvement tier (0 none, 1 review, 2 decide-with-brief)", "2")
+        .option("--stakes <small|medium|high>", "Reversal cost / blast radius", "medium")
+        .option("--context <text>", "Why it matters, what's blocked")
+        .option("--default-taken <text>", "What you proceeded with (always-proceed, tier 0/1)")
+        .option("--brief <path>", "Path to a markdown file with the long-form brief")
+        .option("--filed-by <name>", "Filer agent name (else resolved from heartbeat)")
+        .action((question, opts) => {
+        const coordRoot = coordRootOrExit();
+        const tier = parseTier(opts.tier);
+        const stakes = parseStakes(opts.stakes);
+        let brief;
+        if (opts.brief) {
+            if (!existsSync(opts.brief)) {
+                emit.error({ code: "no_brief_file", message: `brief file not found: ${opts.brief}` });
+                process.exit(1);
+            }
+            brief = readFileSync(opts.brief, "utf8");
+        }
+        const owner = resolveOwner();
+        const hb = owner ? readHeartbeat(owner) : null;
+        const r = fileDecision(coordRoot, {
+            question: question.join(" "),
+            tier,
+            stakes,
+            context: opts.context,
+            defaultTaken: opts.defaultTaken,
+            brief,
+            filedBy: opts.filedBy ?? hb?.name ?? undefined,
+            filedById: owner ?? undefined,
+        });
+        if (!r.ok)
+            return fail("file_failed", r.reason);
+        emitDecisionEvent("decision.filed", {
+            decision_id: r.manifest.decision_id,
+            tier,
+            stakes,
+        });
+        emit.data(r.manifest);
+    });
+    // ── list ─────────────────────────────────────────────────────────────────
+    root
+        .command("list")
+        .description("List docket decisions (default: active only, newest first).")
+        .option("--status <status>", "Filter by status")
+        .option("--tier <0|1|2>", "Filter by tier")
+        .option("--stakes <small|medium|high>", "Filter by stakes")
+        .option("--open", "Only non-terminal decisions (the live queue)")
+        .option("--archived", "Include archived (graduated/terminal) decisions")
+        .action((opts) => {
+        const coordRoot = coordRootOrExit();
+        const status = opts.status ? parseStatus(opts.status) : undefined;
+        const tier = opts.tier !== undefined ? parseTier(opts.tier) : undefined;
+        const stakes = opts.stakes ? parseStakes(opts.stakes) : undefined;
+        const rows = listDecisions(coordRoot, {
+            status,
+            tier,
+            stakes,
+            openOnly: opts.open,
+            includeArchived: opts.archived,
+        }).map(summarize);
+        emit.data({
+            rows,
+            meta: {
+                total: rows.length,
+                filter: { status, tier, stakes, open: !!opts.open, archived: !!opts.archived },
+            },
+        });
+    });
+    // ── show ─────────────────────────────────────────────────────────────────
+    root
+        .command("show <id>")
+        .description("Show one decision: manifest + long-form bodies.")
+        .action((id) => {
+        const coordRoot = coordRootOrExit();
+        const detail = showDecision(coordRoot, id);
+        if (!detail)
+            return fail("not_found", `no decision "${id}"`);
+        emit.data(detail);
+    });
+    // ── search ───────────────────────────────────────────────────────────────
+    root
+        .command("search <query...>")
+        .description("Substring search over questions, context, resolutions, bodies (incl. archive).")
+        .action((query) => {
+        const coordRoot = coordRootOrExit();
+        const hits = searchDecisions(coordRoot, query.join(" ")).map((h) => ({
+            ...summarize(h.manifest),
+            where: h.where,
+            snippet: h.snippet,
+        }));
+        emit.data({ rows: hits, meta: { total: hits.length, query: query.join(" ") } });
+    });
+    // ── claim ────────────────────────────────────────────────────────────────
+    root
+        .command("claim <id>")
+        .description("Claim a decision for deliberation (last-writer-wins).")
+        .option("--owner <id>", "Claim as this owner (else the current agent)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const owner = opts.owner ?? resolveOwner();
+        if (!owner) {
+            return fail("no_owner", `not in an agent session; pass --owner or run \`${bin()} agents whoami\` to check`);
+        }
+        const r = claimDecision(coordRoot, id, owner);
+        if (!r.ok)
+            return fail("claim_failed", r.reason);
+        emit.data(r.manifest);
+    });
+    // ── resolve ──────────────────────────────────────────────────────────────
+    root
+        .command("resolve <id>")
+        .description("Resolve a decision. Evidence (≥1 citation) is required.")
+        .requiredOption("--recommendation <text>", "The recommendation")
+        .option("--evidence <text>", "A cited fact (query run, file read, cost computed). Repeatable; ≥1 required.", collect, [])
+        .option("--confidence <text>", "Confidence in the recommendation")
+        .option("--reversal-cost <text>", "Cost to reverse if wrong")
+        .option("--wrong-if <text>", "What would make this wrong (pre-mortem)")
+        .option("--revisit-when <text>", "Revisit trigger")
+        .option("--resolved-by <name>", "Resolver (else the current agent)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const owner = resolveOwner();
+        const resolvedBy = opts.resolvedBy ?? (owner ? readHeartbeat(owner)?.name : undefined);
+        if (!resolvedBy) {
+            return fail("no_resolver", "pass --resolved-by (no agent session to infer it from)");
+        }
+        const r = resolveDecision(coordRoot, id, {
+            recommendation: opts.recommendation,
+            evidence: opts.evidence,
+            confidence: opts.confidence,
+            reversal_cost: opts.reversalCost,
+            wrong_if: opts.wrongIf,
+            revisit_when: opts.revisitWhen,
+            resolved_by: resolvedBy,
+        });
+        if (!r.ok)
+            return fail("resolve_failed", r.reason);
+        emitDecisionEvent("decision.resolved", {
+            decision_id: id,
+            tier: r.manifest.tier,
+            stakes: r.manifest.stakes,
+            confidence: opts.confidence ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── review ───────────────────────────────────────────────────────────────
+    root
+        .command("review <id>")
+        .description("Record a review verdict (calibration, not approval — work already proceeded).")
+        .requiredOption("--verdict <verdict>", "ratified | overridden | wrong-tier-high | wrong-tier-low")
+        .option("--note <text>", "Reviewer note")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        if (!isVerdict(opts.verdict)) {
+            return fail("bad_verdict", "verdict must be: ratified | overridden | wrong-tier-high | wrong-tier-low");
+        }
+        const r = reviewDecision(coordRoot, id, {
+            verdict: opts.verdict,
+            note: opts.note,
+        });
+        if (!r.ok)
+            return fail("review_failed", r.reason);
+        emitDecisionEvent("decision.reviewed", {
+            decision_id: id,
+            verdict: opts.verdict,
+            tier: r.manifest.tier,
+        });
+        emit.data(r.manifest);
+    });
+    // ── triage ─────────────────────────────────────────────────────────────────
+    // Re-set tier/stakes on an already-filed decision (e.g. after a sweeper or
+    // reviewer flags a wrong-tier). Cheap enough to surface in phase 1.
+    root
+        .command("triage <id>")
+        .description("Adjust an already-filed decision's tier/stakes.")
+        .option("--tier <0|1|2>", "New tier")
+        .option("--stakes <small|medium|high>", "New stakes")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        if (opts.tier === undefined && opts.stakes === undefined) {
+            return fail("nothing_to_do", "pass --tier and/or --stakes");
+        }
+        const r = triageDecision(coordRoot, id, {
+            tier: opts.tier !== undefined ? parseTier(opts.tier) : undefined,
+            stakes: opts.stakes !== undefined ? parseStakes(opts.stakes) : undefined,
+        });
+        if (!r.ok)
+            return fail("triage_failed", r.reason);
+        emit.data(r.manifest);
+    });
+    // ── archive ─────────────────────────────────────────────────────────────────
+    // The graduation exit: a reviewed decision's output has landed in a canonical
+    // home (an ADR, AGENTS.md, a code change), so the decision closes and moves to
+    // the archive, still searchable as precedent. `--graduated-to` records where.
+    root
+        .command("archive <id>")
+        .description("Archive a reviewed decision (terminal). Record where its output graduated.")
+        .option("--graduated-to <ref>", "Where the resolved output landed (e.g. docs/decisions.md#foo)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = archiveDecision(coordRoot, id, opts.graduatedTo);
+        if (!r.ok)
+            return fail("archive_failed", r.reason);
+        emitDecisionEvent("decision.archived", {
+            decision_id: id,
+            tier: r.manifest.tier,
+            graduated_to: opts.graduatedTo ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── reopen ───────────────────────────────────────────────────────────────────
+    // The inverse of archive: pull an archived decision back to `reviewed`. The one
+    // sanctioned way out of the terminal archive (e.g. a fat-fingered graduated_to
+    // or the wrong decision archived). Clears graduated_to; a re-archive sets it fresh.
+    root
+        .command("reopen <id>")
+        .alias("unarchive")
+        .description("Reopen an archived decision back to reviewed (the inverse of archive).")
+        .action((id) => {
+        const coordRoot = coordRootOrExit();
+        const r = reopenDecision(coordRoot, id);
+        if (!r.ok)
+            return fail("reopen_failed", r.reason);
+        emitDecisionEvent("decision.reopened", { decision_id: id, tier: r.manifest.tier });
+        emit.data(r.manifest);
+    });
+    // ── supersede ────────────────────────────────────────────────────────────────
+    root
+        .command("supersede <id>")
+        .description("Mark a decision superseded by a newer one (terminal).")
+        .option("--by <id>", "The superseding decision's id")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = supersedeDecision(coordRoot, id, opts.by);
+        if (!r.ok)
+            return fail("supersede_failed", r.reason);
+        emitDecisionEvent("decision.superseded", {
+            decision_id: id,
+            superseded_by: opts.by ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── wontfix ──────────────────────────────────────────────────────────────────
+    root
+        .command("wontfix <id>")
+        .description("Close an un-deliberated decision without action (terminal).")
+        .option("--reason <text>", "Why it's being closed")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = wontfixDecision(coordRoot, id, opts.reason);
+        if (!r.ok)
+            return fail("wontfix_failed", r.reason);
+        emitDecisionEvent("decision.wontfix", {
+            decision_id: id,
+            reason: opts.reason ?? null,
+        });
+        emit.data(r.manifest);
+    });
+}
+// ─── helpers ───────────────────────────────────────────────────────────────────
+function coordRootOrExit() {
+    const root = monorepoRoot();
+    if (!root) {
+        emit.error({
+            code: "no_coord_root",
+            message: "not in a coord-aware repo (no .harnery/ found)",
+        });
+        process.exit(1);
+    }
+    return root;
+}
+function fail(code, message) {
+    emit.error({ code, message: message ?? code });
+    process.exit(1);
+}
+function parseTier(raw) {
+    const n = Number.parseInt(raw, 10);
+    if (!isTier(n))
+        fail("bad_tier", `tier must be 0, 1, or 2 (got "${raw}")`);
+    return n;
+}
+function parseStakes(raw) {
+    if (!isStakes(raw))
+        fail("bad_stakes", `stakes must be ${DECISION_STAKES.join(" | ")} (got "${raw}")`);
+    return raw;
+}
+function parseStatus(raw) {
+    if (!isStatus(raw))
+        fail("bad_status", `unknown status "${raw}"`);
+    return raw;
+}
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/** Compact row for list/search output — the full manifest is available via `show`. */
+function summarize(m) {
+    return {
+        decision_id: m.decision_id,
+        status: m.status,
+        tier: m.tier,
+        stakes: m.stakes,
+        question: m.question,
+        filed_by: m.filed_by ?? null,
+        filed_at: m.filed_at,
+        claimed_by: m.claimed_by ?? null,
+        resolved: !!m.resolution,
+        reviewed: !!m.review,
+        graduated_to: m.graduated_to ?? null,
+    };
+}
+/**
+ * Emit a canonical `decision.*` event. Soft: no-ops when there's no agent
+ * session to attribute it to (operator-side filing). Powers the docket metrics
+ * without new telemetry plumbing.
+ */
+function emitDecisionEvent(type, data) {
+    const owner = resolveOwner();
+    if (!owner)
+        return;
+    const hb = readHeartbeat(owner);
+    emitCanonical({
+        type,
+        owner,
+        session: hb?.session_id ?? owner,
+        harness: normalizeHarness(hb?.platform),
+        data,
+    });
+}

package/dist/commands/deinit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA2GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}
+{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAanD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA+GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/commands/deinit.js

@@ -31,6 +31,7 @@ import { relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { DEFAULT_BIN_NAME } from "../core/config.js";
 import { HARNESS_SPECS } from "../core/hooks/harness/events.js";
+import { removeInstructions } from "../lib/instructions/apply.js";
 import { unwireHooks } from "./init.js";
 export function registerDeinitCommand(program, emit, binName) {
     // The interactive prompt + engine-removal hint are standalone-harn niceties.
@@ -113,6 +114,9 @@ export function registerDeinitCommand(program, emit, binName) {
                     `(${remaining} other hook(s) kept)`);
             }
         }
+        // ── 1b. agent-facing instructions block + skills ───────────────────────
+        const removed = removeInstructions(projectRoot, { harness, dryRun });
+        actions.push(...removed.actions, ...removed.warnings.map((w) => `! ${w}`));
         // ── 2. coord root (opt-in; destructive) ────────────────────────────────
         if (purgeState) {
             if (!coordExists) {

package/dist/commands/devtools.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerDevtoolsCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=devtools.d.ts.map

package/dist/commands/devtools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.d.ts","sourceRoot":"","sources":["../../src/commands/devtools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAkCnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAsDjF"}

package/dist/commands/devtools.js

@@ -0,0 +1,239 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { cursorApiKeyPath, enrichFromApi, probeEndpoints, readDevtools, resolveCursorApiKey, } from "../lib/devtools.js";
+/**
+ * `devtools`: report the local state of the AI coding agents harnery supports
+ * — Claude Code, Codex, and Cursor — in one place: logged-in status, plan/seat
+ * tier, auth expiry, session counts, and (where the tool keeps them locally)
+ * rate-limit / quota windows.
+ *
+ * Reads files on disk by default (no network). When a Cursor API key is
+ * configured (`devtools cursor-key set`), it additionally verifies the key and
+ * pulls Cloud Agent activity. `--usage` adds an opt-in windowed scan of local
+ * transcripts for approximate token totals.
+ */
+const VALID = ["claude-code", "codex", "cursor"];
+export function registerDevtoolsCommand(program, emit) {
+    const cmd = program
+        .command("devtools")
+        .description("Local status of the AI coding agents (Claude Code, Codex, Cursor)")
+        .option("--tool <name>", "Restrict to a tool (repeatable): claude-code | codex | cursor", collect, [])
+        .option("--usage", "Also scan local transcripts for approximate token totals (slower)")
+        .option("--window-days <n>", "With --usage: only count transcripts modified within N days", (v) => Number.parseInt(v, 10), 7)
+        .option("--no-api", "Skip the Cursor API enrichment even when a key is configured")
+        .option("--format <type>", "Output format: table, json", "table")
+        .action(async (opts) => {
+        const only = (opts.tool ?? []).filter((t) => VALID.includes(t));
+        const bad = (opts.tool ?? []).filter((t) => !VALID.includes(t));
+        if (bad.length) {
+            emit.error({
+                code: "bad_tool",
+                message: `unknown --tool: ${bad.join(", ")}`,
+                hint: `valid: ${VALID.join(", ")}`,
+            });
+            return;
+        }
+        const report = readDevtools({
+            usage: opts.usage,
+            windowDays: opts.windowDays,
+            only: only.length ? only : undefined,
+        });
+        // Auto-enrich when a Cursor key is configured (the user opted in by
+        // storing one); --no-api forces pure-local.
+        if (opts.noApi !== true)
+            await enrichFromApi(report);
+        if (opts.format === "json") {
+            emit.config({ format: "json" });
+            emit.data({ ok: true, ...report });
+            return;
+        }
+        emit.text(renderTable(report.tools));
+    });
+    registerCursorKeyCommand(cmd, emit);
+    registerDoctorCommand(cmd, emit);
+}
+/**
+ * `devtools doctor` — one live call per usage endpoint to check the integrations
+ * still work. Surfaces `auth_rejected` (our headers/token stopped being
+ * accepted) and `shape_changed` (response schema drifted) distinctly from a
+ * mere rate limit. Bypasses the cache; run occasionally, by hand.
+ */
+function registerDoctorCommand(parent, emit) {
+    parent
+        .command("doctor")
+        .description("Probe the usage endpoints once each to detect header/schema drift")
+        .option("--tool <name>", "Restrict to a tool (repeatable): claude-code | cursor", collect, [])
+        .option("--format <type>", "Output format: table, json", "table")
+        .action(async (opts) => {
+        const only = (opts.tool ?? []).filter((t) => VALID.includes(t));
+        const results = await probeEndpoints({ only: only.length ? only : undefined });
+        if (opts.format === "json") {
+            emit.config({ format: "json" });
+            emit.data({
+                ok: results.every((r) => r.outcome === "ok" || r.outcome === "rate_limited"),
+                results,
+            });
+            return;
+        }
+        emit.text(renderDoctor(results));
+    });
+}
+const DOCTOR_MARK = {
+    ok: "✓",
+    rate_limited: "~",
+    no_credential: "-",
+    auth_rejected: "✗",
+    shape_changed: "✗",
+    unreachable: "✗",
+};
+function renderDoctor(results) {
+    if (!results.length)
+        return "no probeable endpoints (Codex is local-only)";
+    const lines = [];
+    for (const r of results) {
+        lines.push(`${DOCTOR_MARK[r.outcome]} ${r.tool.padEnd(12)} ${r.outcome.padEnd(14)} ${r.detail}`);
+        lines.push(`   ${r.endpoint}${r.clientVersion ? `  (client ${r.clientVersion})` : ""}`);
+    }
+    lines.push("");
+    lines.push("✗ auth_rejected / shape_changed = the client's request contract likely changed — review the headers/parser.");
+    return lines.join("\n");
+}
+/** `devtools cursor-key set|clear|status` — store the machine-local Cursor API key. */
+function registerCursorKeyCommand(parent, emit) {
+    const key = parent
+        .command("cursor-key")
+        .description("Manage the Cursor API key used for the Cloud Agent enrichment");
+    key
+        .command("set [value]")
+        .description("Store a Cursor API key (reads stdin when [value] is omitted)")
+        .action(async (value) => {
+        const raw = value ?? (await readStdin());
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            emit.error({ code: "empty_key", message: "no key provided (arg or stdin)" });
+            return;
+        }
+        const path = cursorApiKeyPath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, trimmed, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        emit.file(path, { stored: true, length: trimmed.length });
+    });
+    key
+        .command("clear")
+        .description("Remove the stored Cursor API key")
+        .action(() => {
+        try {
+            rmSync(cursorApiKeyPath());
+        }
+        catch {
+            // already absent
+        }
+        emit.data({ ok: true, cleared: true });
+    });
+    key
+        .command("status")
+        .description("Report whether a Cursor key is configured (env or file)")
+        .action(() => {
+        const fromEnv = Boolean(process.env.CURSOR_API_KEY?.trim());
+        const resolved = resolveCursorApiKey();
+        emit.data({
+            ok: true,
+            configured: Boolean(resolved),
+            source: fromEnv ? "env" : resolved ? "file" : null,
+            path: cursorApiKeyPath(),
+        });
+    });
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        if (process.stdin.isTTY) {
+            resolve("");
+            return;
+        }
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => {
+            data += c;
+        });
+        process.stdin.on("end", () => resolve(data));
+    });
+}
+function collect(value, prev) {
+    return [...prev, value];
+}
+function renderTable(tools) {
+    const lines = [];
+    for (const t of tools) {
+        lines.push(`── ${t.tool} ${"─".repeat(Math.max(0, 40 - t.tool.length))}`);
+        if (!t.installed) {
+            lines.push("   not installed");
+            lines.push("");
+            continue;
+        }
+        lines.push(`   logged in    ${fmtBool(t.loggedIn)}`);
+        if (t.account)
+            lines.push(`   account      ${t.account}`);
+        if (t.plan)
+            lines.push(`   plan         ${t.plan}`);
+        if (t.rateLimitTier)
+            lines.push(`   rate tier    ${t.rateLimitTier}`);
+        if (t.authExpiresAt)
+            lines.push(`   auth expires ${fmtDate(t.authExpiresAt)}`);
+        if (t.sessions != null)
+            lines.push(`   sessions     ${t.sessions}`);
+        if (t.lastActivity)
+            lines.push(`   last active  ${fmtDate(t.lastActivity)}`);
+        if (t.quota?.length) {
+            for (const q of t.quota) {
+                const pct = q.usedPercent != null ? `${q.usedPercent}% used` : "usage unknown";
+                const reset = q.resetsAt ? `resets ${fmtDate(q.resetsAt)}` : "";
+                lines.push(`   quota (${q.window})   ${pct}${reset ? ` · ${reset}` : ""}`);
+            }
+        }
+        if (t.tokensUsed != null) {
+            lines.push(`   tokens       ${t.tokensUsed.toLocaleString()}`);
+        }
+        if (t.usage) {
+            const u = t.usage;
+            if (u.cycleEnd) {
+                const days = Math.round((Date.parse(u.cycleEnd) - Date.now()) / 86_400_000);
+                lines.push(`   plan resets  ${fmtDate(u.cycleEnd)} (${days}d)`);
+            }
+            const pct = (label, v) => (v != null ? `${label} ${v}%` : null);
+            const bars = [
+                pct("total", u.totalPercentUsed),
+                pct("api", u.apiPercentUsed),
+                pct("first-party", u.firstPartyPercentUsed),
+            ].filter((s) => s != null);
+            if (bars.length)
+                lines.push(`   usage        ${bars.join(" · ")}`);
+        }
+        if (t.spend?.limitCents != null) {
+            const label = t.spend.label.toLowerCase().padEnd(12).slice(0, 12);
+            lines.push(`   ${label} ${fmtUsd(t.spend.usedCents ?? 0)} / ${fmtUsd(t.spend.limitCents)}`);
+        }
+        if (t.api?.ok && t.api.cloudAgents) {
+            lines.push(`   cloud agents ${t.api.cloudAgents.total} (${t.api.cloudAgents.active} active)`);
+        }
+        for (const n of t.notes)
+            lines.push(`   · ${n}`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+function fmtBool(v) {
+    if (v === true)
+        return "yes";
+    if (v === false)
+        return "no";
+    return "unknown";
+}
+function fmtDate(iso) {
+    // Keep the machine-readable ISO but drop milliseconds for readability.
+    return iso.replace(/\.\d{3}Z$/, "Z");
+}
+/** Cents → "$X.XX". */
+function fmtUsd(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}

package/dist/commands/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAuB1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+EN"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8GN"}