harnery 0.5.0 → 0.7.0

package/src/commands/devtools.ts

@@ -0,0 +1,284 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  cursorApiKeyPath,
+  type DevtoolName,
+  enrichFromApi,
+  type ProbeResult,
+  probeEndpoints,
+  readDevtools,
+  resolveCursorApiKey,
+  type ToolStatus,
+} from "../lib/devtools.ts";
+
+/**
+ * `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: readonly DevtoolName[] = ["claude-code", "codex", "cursor"];
+
+interface DevtoolsOpts {
+  format: string;
+  usage?: boolean;
+  windowDays: number;
+  tool?: string[];
+  noApi?: boolean;
+}
+
+export function registerDevtoolsCommand(program: Command, emit: EmitContext): void {
+  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: DevtoolsOpts) => {
+      const only = (opts.tool ?? []).filter((t): t is DevtoolName =>
+        VALID.includes(t as DevtoolName),
+      );
+      const bad = (opts.tool ?? []).filter((t) => !VALID.includes(t as DevtoolName));
+      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: Command, emit: EmitContext): void {
+  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: { tool: string[]; format: string }) => {
+      const only = (opts.tool ?? []).filter((t): t is DevtoolName =>
+        VALID.includes(t as DevtoolName),
+      );
+      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: Record<ProbeResult["outcome"], string> = {
+  ok: "✓",
+  rate_limited: "~",
+  no_credential: "-",
+  auth_rejected: "✗",
+  shape_changed: "✗",
+  unreachable: "✗",
+};
+
+function renderDoctor(results: ProbeResult[]): string {
+  if (!results.length) return "no probeable endpoints (Codex is local-only)";
+  const lines: string[] = [];
+  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: Command, emit: EmitContext): void {
+  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: string | undefined) => {
+      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(): Promise<string> {
+  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: string, prev: string[]): string[] {
+  return [...prev, value];
+}
+
+function renderTable(tools: ToolStatus[]): string {
+  const lines: string[] = [];
+  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: string, v: number | null) => (v != null ? `${label} ${v}%` : null);
+      const bars = [
+        pct("total", u.totalPercentUsed),
+        pct("api", u.apiPercentUsed),
+        pct("first-party", u.firstPartyPercentUsed),
+      ].filter((s): s is string => 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: boolean | null): string {
+  if (v === true) return "yes";
+  if (v === false) return "no";
+  return "unknown";
+}
+
+function fmtDate(iso: string): string {
+  // Keep the machine-readable ISO but drop milliseconds for readability.
+  return iso.replace(/\.\d{3}Z$/, "Z");
+}
+
+/** Cents → "$X.XX". */
+function fmtUsd(cents: number): string {
+  return `$${(cents / 100).toFixed(2)}`;
+}

package/src/commands/docs.ts

@@ -1,8 +1,13 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { initDocsContext as initDocs, scanDocs } from "../lib/docs.ts";
+import {
+  initDocsMigrationContext,
+  runFrontmatterMigration,
+} from "../lib/docs-frontmatter-migrate.ts";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.ts";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.ts";
+import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.ts";
 import {
   countColdHandoffs,
   initDocsContext as initDocsSweep,
@@ -15,8 +20,13 @@ function ensureContext(context: HarneryProgramContext | undefined): void {
   }
   const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
   initDocs(opts);
+  initDocsMigrationContext(opts);
   initDocsIndex(opts);
-  initDocsLint({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+  initDocsLint({
+    ...opts,
+    extraExcludedPrefixes: context.extraDocsExcludedPrefixes,
+    docsRootAllowlist: context.docsRootAllowlist,
+  });
   initDocsSweep(opts);
 }
 
@@ -30,7 +40,7 @@ export function registerDocsCommand(
   emit = emitParam;
   const docs = program
     .command("docs")
-    .description("Documentation tooling: freshness report, lint, sweep, index")
+    .description("Documentation tooling: freshness report, metadata, lint, sweep, index")
     // Options on the group itself back the default (no-subcommand) behavior.
     // See handleDocs below.
     .option("--stale <days>", "Only show files not committed in N+ days", Number.parseInt)
@@ -56,6 +66,37 @@ export function registerDocsCommand(
       },
     );
 
+  docs
+    .command("meta")
+    .description("Read YAML frontmatter from a documentation file")
+    .argument("<path>", "Markdown file path, relative to the project root or absolute")
+    .argument("[key]", "Optional top-level frontmatter key")
+    .option("--json", "Emit a requested key as JSON even in an interactive terminal")
+    .action(async (path: string, key: string | undefined, opts: { json?: boolean }) => {
+      try {
+        ensureContext(context);
+        handleMeta(context!.repoRoot!, path, key, opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "docs_error", message: msg });
+      }
+    });
+
+  docs
+    .command("frontmatter-migrate")
+    .description("Convert lifecycle docs from bold metadata headers to YAML frontmatter")
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--yes", "Apply changes; without this flag the command is a dry-run")
+    .action(async (opts: { repo?: string; yes?: boolean }) => {
+      try {
+        ensureContext(context);
+        handleFrontmatterMigration(opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "docs_error", message: msg });
+      }
+    });
+
   docs
     .command("lint")
     .description(
@@ -107,6 +148,49 @@ export function registerDocsCommand(
     });
 }
 
+// --- `harn docs frontmatter-migrate` ---
+
+function handleFrontmatterMigration(opts: { repo?: string; yes?: boolean }): void {
+  const rows = runFrontmatterMigration({ repo: opts.repo, apply: !!opts.yes });
+  const counts = {
+    would_update: rows.filter((row) => row.status === "would-update").length,
+    updated: rows.filter((row) => row.status === "updated").length,
+    skipped: rows.filter((row) => row.status === "skipped").length,
+    errors: rows.filter((row) => row.status === "error").length,
+  };
+  emit.data({
+    dry_run: !opts.yes,
+    applied: !!opts.yes && counts.errors === 0,
+    aborted: !!opts.yes && counts.errors > 0,
+    repo: opts.repo ?? null,
+    counts,
+    rows,
+  });
+  if (counts.errors > 0) emit.setExitCode(1);
+}
+
+// --- `harn docs meta` ---
+
+function handleMeta(
+  repoRoot: string,
+  path: string,
+  key: string | undefined,
+  opts: { json?: boolean },
+): void {
+  const metadata = readDocsMetadata(repoRoot, path).data;
+  if (!key) {
+    emit.data(metadata);
+    return;
+  }
+
+  const value = readDocsMetadataKey(metadata, key, path);
+  if (opts.json || !process.stdout.isTTY || typeof value === "object") {
+    emit.data(value);
+    return;
+  }
+  emit.text(String(value));
+}
+
 // --- Default `harn docs` (freshness report) ---
 
 async function handleDocs(opts: {

package/src/commands/doctor.ts

@@ -251,16 +251,25 @@ function checkHarnessHooks(): Check {
   const bin = resolveBinName(root);
   const parts = drift.map((d) => {
     const bits: string[] = [];
+    if (d.parseError) bits.push(`invalid JSON (${d.parseError})`);
     if (d.missing.length > 0) {
       bits.push(`${d.missing.length} missing (${d.missing.map((m) => m.subcommand).join(", ")})`);
     }
     if (d.orphans.length > 0) bits.push(`${d.orphans.length} orphaned (${d.orphans.join(", ")})`);
+    if (d.invalidTopLevelKeys.length > 0) {
+      bits.push(`invalid fields (${d.invalidTopLevelKeys.join(", ")})`);
+    }
+    if (d.invalidEventKeys.length > 0) {
+      bits.push(`unsupported events (${d.invalidEventKeys.join(", ")})`);
+    }
     return `${d.settingsFile}: ${bits.join("; ")}`;
   });
-  const hasOrphans = drift.some((d) => d.orphans.length > 0);
-  const hint = hasOrphans
-    ? `run \`${bin} init\` to wire missing hooks; remove orphaned entries (renamed/dropped events) with \`${bin} deinit\` then \`${bin} init\``
-    : `run \`${bin} init\` to wire the new hook(s) (idempotent)`;
+  const needsManualRepair = drift.some(
+    (d) => d.parseError || d.invalidTopLevelKeys.length > 0 || d.invalidEventKeys.length > 0,
+  );
+  const hint = needsManualRepair
+    ? `repair the invalid harness settings, then run \`${bin} init\` to migrate harnery hooks`
+    : `run \`${bin} init\` to migrate the hook set (idempotent)`;
   return { name: "harness hooks", severity: "warn", detail: parts.join("  |  "), hint };
 }
 

package/src/commands/env.ts

@@ -1,11 +1,13 @@
 import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
 import type { Command } from "commander";
-import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import type { EmitContext, EnvCheck, EnvSection, HarneryProgramContext } from "../commander.ts";
 import { exec, sh } from "../lib/exec.ts";
 
 /**
- * `env`: show environment status across runtimes, docker, gcp, bq, git.
+ * `env`: show environment status across the generic sections (runtimes,
+ * docker, git) plus any sections the host registers via `context.envSections`.
+ * harnery core carries no provider-specific checks (a host adds e.g. gcp/bq).
  *
  * Monorepo state (repoRoot, submodules) flows in via HarneryProgramContext.
  * When neither is provided (harn invoked outside a monorepo), the git section
@@ -16,11 +18,9 @@ import { exec, sh } from "../lib/exec.ts";
  * metadata; defaultEmit just JSON-stringifies.
  */
 
-interface Check {
-  label: string;
-  value: string;
-  status?: "ok" | "missing" | "warn" | "info";
-}
+// Internal alias for the shared row type (exported from commander.ts so hosts
+// can type their own `envSections`).
+type Check = EnvCheck;
 
 export function registerEnvCommand(
   program: Command,
@@ -29,7 +29,7 @@ export function registerEnvCommand(
 ): void {
   program
     .command("env [section]")
-    .description("Show environment status (docker, gcp, bq, node, python, git)")
+    .description("Show environment status (runtimes, docker, git; hosts can add sections)")
     .action(async (section?: string) => {
       try {
         await handleEnv(section, emit, context);
@@ -46,12 +46,12 @@ async function handleEnv(
   emit: EmitContext,
   context: HarneryProgramContext | undefined,
 ): Promise<void> {
-  const sections: Record<string, () => Promise<Check[]>> = {
+  const sections: Record<string, EnvSection> = {
     runtimes: checkRuntimes,
     docker: checkDocker,
-    gcp: checkGcp,
-    bq: checkBigQuery,
     git: () => checkGit(context),
+    // Host-registered sections (e.g. gcp/bq) merge in after the generic ones.
+    ...(context?.envSections ?? {}),
   };
 
   if (section) {
@@ -153,72 +153,6 @@ async function checkDocker(): Promise<Check[]> {
   return checks;
 }
 
-async function checkGcp(): Promise<Check[]> {
-  const checks: Check[] = [];
-
-  const account = await sh("gcloud config get-value account 2>/dev/null").catch(() => ({
-    stdout: "",
-    exitCode: 1,
-    stderr: "",
-  }));
-  const project = await sh("gcloud config get-value project 2>/dev/null").catch(() => ({
-    stdout: "",
-    exitCode: 1,
-    stderr: "",
-  }));
-
-  if (account.exitCode === 0 && account.stdout) {
-    checks.push({ label: "GCP Account", value: account.stdout, status: "ok" });
-  } else {
-    checks.push({ label: "GCP Account", value: "not authenticated", status: "missing" });
-  }
-
-  if (project.exitCode === 0 && project.stdout) {
-    checks.push({ label: "GCP Project", value: project.stdout, status: "ok" });
-  } else {
-    checks.push({ label: "GCP Project", value: "not set", status: "missing" });
-  }
-
-  return checks;
-}
-
-async function checkBigQuery(): Promise<Check[]> {
-  const checks: Check[] = [];
-
-  const result = await sh("bq ls --max_results=1 2>/dev/null").catch(() => ({
-    stdout: "",
-    exitCode: 1,
-    stderr: "",
-  }));
-
-  if (result.exitCode === 0) {
-    checks.push({ label: "BigQuery", value: "connected", status: "ok" });
-  } else {
-    checks.push({ label: "BigQuery", value: "not connected (check GCP auth)", status: "missing" });
-  }
-
-  const datasets = await sh("bq ls --format=json --max_results=20 2>/dev/null").catch(() => ({
-    stdout: "",
-    exitCode: 1,
-    stderr: "",
-  }));
-
-  if (datasets.exitCode === 0 && datasets.stdout) {
-    try {
-      const ds = JSON.parse(datasets.stdout) as { datasetReference?: { datasetId?: string } }[];
-      const names = ds
-        .map((d) => d.datasetReference?.datasetId)
-        .filter(Boolean)
-        .join(", ");
-      if (names) checks.push({ label: "Datasets", value: names, status: "info" });
-    } catch {
-      // Ignore parse failures
-    }
-  }
-
-  return checks;
-}
-
 async function checkGit(context: HarneryProgramContext | undefined): Promise<Check[]> {
   const checks: Check[] = [];
   const cwd = context?.repoRoot ?? process.cwd();

package/src/commands/fetch.ts

@@ -80,7 +80,7 @@ async function runFetch(
 
   const jar =
     opts.cookies !== false
-      ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "bp-fetch" })
+      ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-fetch" })
       : null;
 
   const timeoutMs = Number.parseInt(opts.timeout, 10);