harnery 0.0.1 → 0.2.0

package/src/commands/docs.ts

@@ -0,0 +1,174 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { initDocsContext as initDocs, scanDocs } from "../lib/docs.ts";
+import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.ts";
+import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.ts";
+import {
+  countColdHandoffs,
+  initDocsContext as initDocsSweep,
+  runSweep,
+} from "../lib/docs-sweep.ts";
+
+function ensureContext(context: HarneryProgramContext | undefined): void {
+  if (!context?.repoRoot || !context?.submodules) {
+    throw new Error("docs commands require harnery to be configured with repoRoot + submodules");
+  }
+  const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
+  initDocs(opts);
+  initDocsIndex(opts);
+  initDocsLint({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+  initDocsSweep(opts);
+}
+
+let emit: EmitContext;
+
+export function registerDocsCommand(
+  program: Command,
+  emitParam: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  emit = emitParam;
+  const docs = program
+    .command("docs")
+    .description("Documentation tooling: freshness report, 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)
+    .option("--dir <name>", "Filter to a specific top-level directory")
+    .option("--no-submodules", "Exclude submodule files; only show parent repo docs")
+    .option("--commits <n>", "Number of recent commits to show per file", Number.parseInt, 1)
+    .option("--format <type>", "Output format: table, csv, json", "table")
+    .action(
+      async (opts: {
+        stale?: number;
+        dir?: string;
+        submodules?: boolean;
+        commits: number;
+        format: string;
+      }) => {
+        try {
+          ensureContext(context);
+          await handleDocs(opts);
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : String(err);
+          emit.error({ code: "docs_error", message: msg });
+        }
+      },
+    );
+
+  docs
+    .command("lint")
+    .description(
+      "Verify every repo matches the documentation contract (directory layout + naming rules)",
+    )
+    .option("--fast", "Skip content-reading checks; filename/structure only (for pre-commit)")
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--format <type>", "Output format: human, json", "human")
+    .action(async (opts: { fast?: boolean; repo?: string; format: string }) => {
+      try {
+        ensureContext(context);
+        await handleLint(opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "docs_error", message: msg });
+      }
+    });
+
+  docs
+    .command("sweep")
+    .description(
+      "Surface stalled lifecycle states: stalled plans, cold issues, unverified runbooks",
+    )
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--format <type>", "Output format: human, json", "human")
+    .action(async (opts: { repo?: string; format: string }) => {
+      try {
+        ensureContext(context);
+        await handleSweep(opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "docs_error", message: msg });
+      }
+    });
+
+  docs
+    .command("index")
+    .description("Regenerate index READMEs for docs/audits/ and docs/issues/ directories")
+    .option("--dry-run", "Show what would change, don't write files")
+    .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .action(async (opts: { dryRun?: boolean; repo?: string }) => {
+      try {
+        ensureContext(context);
+        await handleIndex(opts);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "docs_error", message: msg });
+      }
+    });
+}
+
+// --- Default `harn docs` (freshness report) ---
+
+async function handleDocs(opts: {
+  stale?: number;
+  dir?: string;
+  submodules?: boolean;
+  commits: number;
+  format: string;
+}): Promise<void> {
+  if (opts.format === "json") emit.config({ format: "json" });
+  else if (opts.format === "csv") emit.config({ format: "csv" });
+
+  const files = await scanDocs({
+    commitCount: opts.commits,
+    dir: opts.dir,
+    noSubmodules: opts.submodules === false,
+    staleDays: opts.stale,
+  });
+  emit.rows(files as unknown as Record<string, unknown>[]);
+}
+
+// --- `harn docs lint` ---
+
+async function handleLint(opts: { fast?: boolean; repo?: string; format: string }): Promise<void> {
+  const violations = await runLint({ fast: opts.fast, repo: opts.repo });
+  const errors = violations.filter((v) => v.severity === "error");
+  const warnings = violations.filter((v) => v.severity === "warning");
+  const cold = await countColdHandoffs();
+
+  emit.data({
+    fast: !!opts.fast,
+    repo: opts.repo ?? null,
+    error_count: errors.length,
+    warning_count: warnings.length,
+    cold_handoffs: cold,
+    violations,
+  });
+
+  if (errors.length > 0) emit.setExitCode(1);
+}
+
+// --- `harn docs sweep` ---
+
+async function handleSweep(opts: { repo?: string; format: string }): Promise<void> {
+  if (opts.format === "json") emit.config({ format: "json" });
+  const items = await runSweep({ repo: opts.repo });
+  emit.data(items);
+}
+
+// --- `harn docs index` ---
+
+async function handleIndex(opts: { dryRun?: boolean; repo?: string }): Promise<void> {
+  const results = await runIndex({ dryRun: opts.dryRun, repo: opts.repo });
+  emit.data({
+    dry_run: !!opts.dryRun,
+    repo: opts.repo ?? null,
+    counts: {
+      updated: results.filter((r) => r.status === "updated").length,
+      created: results.filter((r) => r.status === "created").length,
+      needs_markers: results.filter((r) => r.status === "needs-markers").length,
+      unchanged: results.filter((r) => r.status === "unchanged").length,
+    },
+    results,
+  });
+}

package/src/commands/doctor.ts

@@ -0,0 +1,231 @@
+/**
+ * `harn doctor`: runtime + dependency check.
+ *
+ * Walks through every dependency harnery touches and reports presence,
+ * version, and OS-specific install hints. Returns a checklist:
+ *
+ *   ✓ ok: dep is present and recent enough
+ *   ⚠ warn: optional dep missing (feature degrades)
+ *   ✗ fail: required dep missing (commands will throw)
+ *
+ * Exits 0 unless a required dep is missing.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+
+type Severity = "ok" | "warn" | "fail";
+
+interface Check {
+  name: string;
+  severity: Severity;
+  detail: string;
+  hint?: string;
+}
+
+interface CheckOpts {
+  json?: boolean;
+}
+
+export function registerDoctorCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("doctor")
+    .description(
+      "Verify the runtime + optional deps harnery commands expect. Exits 0 " +
+        "unless a required dep (Node, git) is missing.",
+    )
+    .option("--json", "Machine-readable JSON output")
+    .action((opts: CheckOpts) => {
+      const checks = runChecks();
+      const requiredFailed = checks.some((c) => c.severity === "fail");
+
+      if (opts.json) {
+        emit.data({
+          checks,
+          summary: {
+            total: checks.length,
+            ok: checks.filter((c) => c.severity === "ok").length,
+            warn: checks.filter((c) => c.severity === "warn").length,
+            fail: checks.filter((c) => c.severity === "fail").length,
+          },
+        });
+        emit.setExitCode(requiredFailed ? 1 : 0);
+        return;
+      }
+
+      const symbols: Record<Severity, string> = { ok: "✓", warn: "⚠", fail: "✗" };
+      const widest = Math.max(...checks.map((c) => c.name.length));
+      const lines: string[] = [];
+      for (const c of checks) {
+        lines.push(`${symbols[c.severity]} ${c.name.padEnd(widest)}  ${c.detail}`);
+        if (c.hint) lines.push(`    ↳ ${c.hint}`);
+      }
+
+      const summary = `\n${checks.filter((c) => c.severity === "ok").length} ok, ${
+        checks.filter((c) => c.severity === "warn").length
+      } warn, ${checks.filter((c) => c.severity === "fail").length} fail`;
+      emit.text(`${lines.join("\n")}${summary}`);
+      emit.setExitCode(requiredFailed ? 1 : 0);
+    });
+}
+
+export function runChecks(): Check[] {
+  return [
+    checkNode(),
+    checkGit(),
+    checkBun(),
+    checkHarneryDir(),
+    checkRestic(),
+    checkRclone(),
+    checkPlaywright(),
+    checkPython(),
+  ];
+}
+
+function whichVersion(bin: string, args: string[] = ["--version"]): { ok: boolean; out: string } {
+  const r = spawnSync(bin, args, { encoding: "utf-8" });
+  if (r.status !== 0) return { ok: false, out: "" };
+  const out = (r.stdout || r.stderr).trim().split("\n")[0];
+  return { ok: true, out };
+}
+
+function checkNode(): Check {
+  const v = process.versions.node;
+  const major = Number.parseInt(v.split(".")[0], 10);
+  if (Number.isNaN(major) || major < 20) {
+    return {
+      name: "node",
+      severity: "fail",
+      detail: `${v} (need ≥ 20)`,
+      hint: "https://nodejs.org/en/download",
+    };
+  }
+  return { name: "node", severity: "ok", detail: v };
+}
+
+function checkGit(): Check {
+  const r = whichVersion("git");
+  if (!r.ok) {
+    return {
+      name: "git",
+      severity: "fail",
+      detail: "missing",
+      hint: macOrLinux("brew install git", "apt-get install -y git"),
+    };
+  }
+  return { name: "git", severity: "ok", detail: r.out.replace(/^git version\s*/, "") };
+}
+
+function checkBun(): Check {
+  const r = whichVersion("bun");
+  if (!r.ok) {
+    return {
+      name: "bun",
+      severity: "warn",
+      detail: "missing (Node-only mode: fine, just slower than bun-native)",
+      hint: "curl -fsSL https://bun.sh/install | bash",
+    };
+  }
+  return { name: "bun", severity: "ok", detail: r.out };
+}
+
+function checkRestic(): Check {
+  const r = whichVersion("restic", ["version"]);
+  if (!r.ok) {
+    return {
+      name: "restic",
+      severity: "warn",
+      detail: "missing (needed for `harn backup`)",
+      hint: macOrLinux("brew install restic", "apt-get install -y restic"),
+    };
+  }
+  return { name: "restic", severity: "ok", detail: r.out };
+}
+
+function checkRclone(): Check {
+  const r = whichVersion("rclone", ["version"]);
+  if (!r.ok) {
+    return {
+      name: "rclone",
+      severity: "warn",
+      detail: "missing (needed for `harn sync`)",
+      hint: "curl https://rclone.org/install.sh | sudo bash",
+    };
+  }
+  // first line is "rclone v1.XX.X"
+  return { name: "rclone", severity: "ok", detail: r.out };
+}
+
+function checkPlaywright(): Check {
+  // Check if playwright is importable + chromium installed.
+  try {
+    const moduleId = "playwright";
+    require.resolve(moduleId);
+  } catch {
+    return {
+      name: "playwright",
+      severity: "warn",
+      detail: "module missing (needed for `harn browse`)",
+      hint: "npm install -g playwright && npx playwright install chromium",
+    };
+  }
+  // Check chromium browser binary exists.
+  const home = os.homedir();
+  const candidates = [
+    path.join(home, ".cache", "ms-playwright"),
+    path.join(home, "Library", "Caches", "ms-playwright"),
+  ];
+  const found = candidates.find(existsSync);
+  if (!found) {
+    return {
+      name: "playwright",
+      severity: "warn",
+      detail: "module ok but no browsers installed",
+      hint: "npx playwright install chromium",
+    };
+  }
+  return { name: "playwright", severity: "ok", detail: `module + browsers at ${found}` };
+}
+
+function checkPython(): Check {
+  const r = whichVersion("python3");
+  if (!r.ok) {
+    return {
+      name: "python3",
+      severity: "warn",
+      detail: "missing (optional; some examples use python)",
+    };
+  }
+  return { name: "python3", severity: "ok", detail: r.out };
+}
+
+function checkHarneryDir(): Check {
+  // Walk up from cwd looking for .harnery/.
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(path.join(dir, ".harnery"))) {
+      return {
+        name: ".harnery/",
+        severity: "ok",
+        detail: path.join(dir, ".harnery"),
+      };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return {
+    name: ".harnery/",
+    severity: "warn",
+    detail: "no .harnery/ found above cwd",
+    hint: "create one with `mkdir -p .harnery/active` from your monorepo root",
+  };
+}
+
+function macOrLinux(mac: string, linux: string): string {
+  return os.platform() === "darwin" ? mac : linux;
+}

package/src/commands/edit-batch.ts

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+
+/**
+ * `harn edit-batch`: coordinated find/replace across N files in one call.
+ *
+ * Solves the recurring "rename oldName → newName everywhere" pattern that
+ * otherwise costs N sequential Edit tool calls. Literal-string by default;
+ * --regex flag treats the find string as a JS regex. --all flag replaces
+ * every occurrence per file (default: first match only, matching the Edit
+ * tool's default).
+ *
+ * Atomic per-file: writes to <path>.batch.tmp.<pid> then renames. If any
+ * file errors mid-batch, already-written files stay written: it's
+ * idempotent at the per-file level, not transactional across the set.
+ * Use --dry-run to preview before committing.
+ */
+export function registerEditBatchCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("edit-batch <old> <new> <files...>")
+    .description(
+      "Coordinated find/replace across N files (literal by default; --regex for pattern). " +
+        "Atomic per-file. Use --dry-run to preview.",
+    )
+    .option("--all", "Replace every occurrence in each file (default: first match only)")
+    .option("--regex", "Treat <old> as a JS regex (and <new> as the replacement template)")
+    .option(
+      "--regex-flags <flags>",
+      "Regex flags (e.g. 'i' for case-insensitive). Implies --regex.",
+      "",
+    )
+    .option("--dry-run", "Show what would change without writing")
+    .option("--require-match", "Fail (exit 1) if any file has zero matches")
+    .option("--json", "Structured JSON envelope")
+    .action(async (oldStr: string, newStr: string, files: string[], opts: EditBatchOpts) => {
+      try {
+        const result = await runEditBatch(oldStr, newStr, files, opts);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        emit.text(`${renderResult(result)}\n`);
+        if (opts.requireMatch && result.zero_match_files.length > 0) {
+          process.exit(1);
+        }
+      } catch (err) {
+        emit.error({ code: "edit_batch_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}
+
+interface EditBatchOpts {
+  all?: boolean;
+  regex?: boolean;
+  regexFlags?: string;
+  dryRun?: boolean;
+  requireMatch?: boolean;
+  json?: boolean;
+}
+
+interface FileResult {
+  path: string;
+  matched: number;
+  replaced: number;
+  bytes_before: number;
+  bytes_after: number;
+  written: boolean;
+  error: string | null;
+}
+
+interface EditBatchResult {
+  old: string;
+  new: string;
+  mode: "literal" | "regex";
+  all: boolean;
+  dry_run: boolean;
+  files: FileResult[];
+  total_matches: number;
+  total_replacements: number;
+  files_modified: number;
+  zero_match_files: string[];
+}
+
+async function runEditBatch(
+  oldStr: string,
+  newStr: string,
+  files: string[],
+  opts: EditBatchOpts,
+): Promise<EditBatchResult> {
+  if (files.length === 0) {
+    throw new Error("at least one file path required");
+  }
+  if (oldStr.length === 0) {
+    throw new Error("<old> string is empty");
+  }
+  const useRegex = !!opts.regex || (opts.regexFlags ?? "").length > 0;
+  let pattern: RegExp;
+  if (useRegex) {
+    let flags = opts.regexFlags ?? "";
+    if (opts.all && !flags.includes("g")) flags += "g";
+    try {
+      pattern = new RegExp(oldStr, flags);
+    } catch (err) {
+      throw new Error(`invalid regex: ${(err as Error).message}`);
+    }
+  } else {
+    // Literal-string mode: escape regex specials so the user can pass anything.
+    const escaped = oldStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    pattern = new RegExp(escaped, opts.all ? "g" : "");
+  }
+
+  const fileResults: FileResult[] = [];
+  for (const filePath of files) {
+    const abs = resolve(filePath);
+    const r: FileResult = {
+      path: filePath,
+      matched: 0,
+      replaced: 0,
+      bytes_before: 0,
+      bytes_after: 0,
+      written: false,
+      error: null,
+    };
+    try {
+      if (!existsSync(abs)) {
+        r.error = "file not found";
+        fileResults.push(r);
+        continue;
+      }
+      const before = readFileSync(abs, "utf8");
+      r.bytes_before = Buffer.byteLength(before, "utf8");
+
+      // Count matches independently of replace (handles both modes).
+      const countPattern = new RegExp(
+        pattern.source,
+        pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+      );
+      r.matched = (before.match(countPattern) || []).length;
+
+      if (r.matched === 0) {
+        fileResults.push(r);
+        continue;
+      }
+
+      const after = before.replace(pattern, newStr);
+      // The `g` flag (explicit --all OR passed via --regex-flags) is what actually
+      // controls replace-all behavior. Count what String.replace actually did,
+      // not what --all said.
+      const replacedAll = pattern.flags.includes("g");
+      r.replaced = replacedAll ? r.matched : Math.min(1, r.matched);
+      r.bytes_after = Buffer.byteLength(after, "utf8");
+
+      if (!opts.dryRun) {
+        const tmp = `${abs}.batch.tmp.${process.pid}`;
+        writeFileSync(tmp, after, "utf8");
+        const mode = statSync(abs).mode;
+        renameSync(tmp, abs);
+        // mode preservation: chmod after rename if needed.
+        // (omitted: writeFileSync defaults are fine; rename keeps inode anyway when same filesystem)
+        void mode;
+        r.written = true;
+      }
+      fileResults.push(r);
+    } catch (err) {
+      r.error = (err as Error).message;
+      fileResults.push(r);
+    }
+  }
+
+  const totalMatches = fileResults.reduce((acc, f) => acc + f.matched, 0);
+  const totalReplacements = fileResults.reduce((acc, f) => acc + f.replaced, 0);
+  const filesModified = fileResults.filter((f) => f.written).length;
+  const zeroMatch = fileResults.filter((f) => f.matched === 0 && !f.error).map((f) => f.path);
+
+  return {
+    old: oldStr,
+    new: newStr,
+    mode: useRegex ? "regex" : "literal",
+    all: !!opts.all,
+    dry_run: !!opts.dryRun,
+    files: fileResults,
+    total_matches: totalMatches,
+    total_replacements: totalReplacements,
+    files_modified: filesModified,
+    zero_match_files: zeroMatch,
+  };
+}
+
+function renderResult(r: EditBatchResult): string {
+  const lines: string[] = [];
+  const verb = r.dry_run ? "would replace" : "replaced";
+  lines.push(
+    `edit-batch · ${r.mode} · ${r.all ? "all" : "first"}-match · ${r.files.length} file(s)`,
+  );
+  lines.push(`  '${truncate(r.old, 60)}' → '${truncate(r.new, 60)}'`);
+  lines.push("");
+  for (const f of r.files) {
+    if (f.error) {
+      lines.push(`  ✗ ${f.path}  (error: ${f.error})`);
+      continue;
+    }
+    if (f.matched === 0) {
+      lines.push(`  · ${f.path}  (no match)`);
+      continue;
+    }
+    const tag = r.dry_run ? "?" : f.written ? "✓" : "·";
+    const delta = f.bytes_after - f.bytes_before;
+    const deltaStr = delta === 0 ? "0 bytes" : delta > 0 ? `+${delta} bytes` : `${delta} bytes`;
+    lines.push(
+      `  ${tag} ${f.path}  (${f.matched} match${f.matched === 1 ? "" : "es"}, ${verb} ${f.replaced}, ${deltaStr})`,
+    );
+  }
+  lines.push("");
+  lines.push(
+    `total: ${r.total_matches} match(es) across ${r.files.length} file(s); ` +
+      `${verb} ${r.total_replacements} in ${r.files_modified || (r.dry_run ? r.files.filter((f) => f.matched > 0).length : 0)} file(s)`,
+  );
+  if (r.zero_match_files.length > 0) {
+    lines.push(
+      `zero-match files: ${r.zero_match_files.length} (use --require-match to fail when this happens)`,
+    );
+  }
+  return lines.join("\n");
+}
+
+function truncate(s: string, n: number): string {
+  if (s.length <= n) return s;
+  return `${s.slice(0, n - 1)}…`;
+}