harnery 0.0.1 → 0.2.1

package/src/lib/docs-sweep.ts

@@ -0,0 +1,348 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+import { sh } from "./exec.ts";
+
+// Module-level docs context, initialized by initDocsContext() before any
+// other function in this file is called. The repo root + submodule list
+// are passed via the context provided to registerDocsCommand.
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+
+export function initDocsContext(opts: { repoRoot: string; submodules: readonly string[] }): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+}
+
+function submodulePath(name: string): string {
+  return __resolveForDocs(REPO_ROOT, name);
+}
+
+function isSubmoduleInitialized(name: string): boolean {
+  return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/**
+ * Surfaces stalled lifecycle states across the monorepo: plans in-progress
+ * too long, open issues gone cold, runbooks that haven't been verified, etc.
+ *
+ * This is the opposite of `docs --stale`, which flags file-level freshness.
+ * Sweep only flags items where the lifecycle state (status header + mtime)
+ * suggests attention is needed.
+ *
+ * Audit files and issue files under `docs/audits/` are explicitly **not**
+ * flagged for age; they're immutable records by design.
+ */
+
+export interface SweepOpts {
+  repo?: string;
+}
+
+export interface SweepItem {
+  kind: SweepKind;
+  repo: string;
+  path: string; // relative to monorepo root
+  ageDays: number;
+  message: string;
+}
+
+export type SweepKind =
+  | "stalled-plan" // status: in-progress, untouched >90d
+  | "unarchived-shipped" // status: shipped, in plans/ (not archive/) >180d
+  | "open-issue-cold" // status: open, untouched >30d
+  | "cold-handoff" // status: open, untouched >30d (docs/handoffs/)
+  | "runbook-unverified" // docs/runbook.md untouched >180d
+  | "topic-doc-stale" // docs/<topic>/... untouched >365d
+  | "decisions-dormant"; // docs/decisions.md untouched >180d (active repos)
+
+const STALLED_PLAN_DAYS = 90;
+const UNARCHIVED_SHIPPED_DAYS = 180;
+const OPEN_ISSUE_DAYS = 30;
+const COLD_HANDOFF_DAYS = 30;
+const RUNBOOK_DAYS = 180;
+const TOPIC_DOC_DAYS = 365;
+const DECISIONS_DORMANT_DAYS = 180;
+
+/** Days since last git commit touching a file */
+async function lastCommitAgeDays(cwd: string, file: string): Promise<number | null> {
+  const result = await sh(`git log -1 --format=%aI -- "${file}"`, { cwd });
+  if (result.exitCode !== 0 || !result.stdout.trim()) return null;
+  const ms = Date.now() - new Date(result.stdout.trim()).getTime();
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+/** Days since ANY commit in the repo (measures repo activity) */
+async function lastRepoCommitAgeDays(cwd: string): Promise<number | null> {
+  const result = await sh("git log -1 --format=%aI", { cwd });
+  if (result.exitCode !== 0 || !result.stdout.trim()) return null;
+  const ms = Date.now() - new Date(result.stdout.trim()).getTime();
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+function readStatus(filePath: string): string | null {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const head = content.split("\n").slice(0, 20).join("\n");
+    const m = head.match(/\*\*Status:\*\*\s*([a-zA-Z][a-zA-Z-]*)/);
+    return m ? m[1]!.toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function sweepPlans(repoName: string, repoPath: string, items: SweepItem[]): Promise<void> {
+  const plansDir = join(repoPath, "docs", "plans");
+  if (!existsSync(plansDir)) return;
+
+  const walk = (dir: string): string[] => {
+    const out: string[] = [];
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      let st: ReturnType<typeof statSync> | undefined;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        out.push(...walk(full));
+      } else if (entry.endsWith(".md") && entry !== "README.md") {
+        out.push(full);
+      }
+    }
+    return out;
+  };
+
+  const files = walk(plansDir);
+  for (const full of files) {
+    const rel = relative(repoPath, full);
+    const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
+    const isArchived = rel.includes("/archive/");
+    const status = readStatus(full);
+    const age = await lastCommitAgeDays(repoPath, rel);
+    if (age == null) continue;
+
+    if (!isArchived && status === "in-progress" && age > STALLED_PLAN_DAYS) {
+      items.push({
+        kind: "stalled-plan",
+        repo: repoName,
+        path: displayPath,
+        ageDays: age,
+        message: `plan is in-progress, last touched ${age}d ago; confirm still active or bump status`,
+      });
+    }
+    if (!isArchived && status === "shipped" && age > UNARCHIVED_SHIPPED_DAYS) {
+      items.push({
+        kind: "unarchived-shipped",
+        repo: repoName,
+        path: displayPath,
+        ageDays: age,
+        message: `plan is shipped but still in docs/plans/ after ${age}d; move to docs/plans/archive/`,
+      });
+    }
+  }
+}
+
+async function sweepIssues(repoName: string, repoPath: string, items: SweepItem[]): Promise<void> {
+  const issuesDir = join(repoPath, "docs", "issues");
+  if (!existsSync(issuesDir)) return;
+
+  for (const entry of readdirSync(issuesDir)) {
+    if (!entry.endsWith(".md") || entry === "README.md") continue;
+    const full = join(issuesDir, entry);
+    const rel = join("docs", "issues", entry);
+    const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
+    const status = readStatus(full);
+    if (status !== "open") continue;
+    const age = await lastCommitAgeDays(repoPath, rel);
+    if (age == null || age <= OPEN_ISSUE_DAYS) continue;
+    items.push({
+      kind: "open-issue-cold",
+      repo: repoName,
+      path: displayPath,
+      ageDays: age,
+      message: `issue still marked open after ${age}d; resolve, mark wontfix, or triage`,
+    });
+  }
+}
+
+async function sweepHandoffs(
+  repoName: string,
+  repoPath: string,
+  items: SweepItem[],
+): Promise<void> {
+  const handoffsDir = join(repoPath, "docs", "handoffs");
+  if (!existsSync(handoffsDir)) return;
+
+  const walk = (dir: string): string[] => {
+    const out: string[] = [];
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      let st: ReturnType<typeof statSync> | undefined;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        out.push(...walk(full));
+      } else if (entry.endsWith(".md")) {
+        out.push(full);
+      }
+    }
+    return out;
+  };
+
+  for (const full of walk(handoffsDir)) {
+    const rel = relative(repoPath, full);
+    const status = readStatus(full);
+    if (status !== "open") continue;
+    const age = await lastCommitAgeDays(repoPath, rel);
+    if (age == null || age <= COLD_HANDOFF_DAYS) continue;
+    const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
+    items.push({
+      kind: "cold-handoff",
+      repo: repoName,
+      path: displayPath,
+      ageDays: age,
+      message: `handoff still marked open after ${age}d; resolve, abandon, or note current progress`,
+    });
+  }
+}
+
+async function sweepRunbook(repoName: string, repoPath: string, items: SweepItem[]): Promise<void> {
+  const runbook = join(repoPath, "docs", "runbook.md");
+  if (!existsSync(runbook)) return;
+  const age = await lastCommitAgeDays(repoPath, "docs/runbook.md");
+  if (age == null || age <= RUNBOOK_DAYS) return;
+  const displayPath = join(repoName === "(root)" ? "" : repoName, "docs/runbook.md");
+  items.push({
+    kind: "runbook-unverified",
+    repo: repoName,
+    path: displayPath,
+    ageDays: age,
+    message: `runbook hasn't been edited in ${age}d; re-verify procedures`,
+  });
+}
+
+async function sweepTopicDocs(
+  repoName: string,
+  repoPath: string,
+  items: SweepItem[],
+): Promise<void> {
+  const docsDir = join(repoPath, "docs");
+  if (!existsSync(docsDir)) return;
+
+  // Skip known date-stamped or lifecycle-managed dirs
+  const skipDirs = new Set([
+    "audits",
+    "issues",
+    "plans",
+    "changelogs",
+    "emails", // parent-specific
+  ]);
+
+  for (const entry of readdirSync(docsDir)) {
+    if (skipDirs.has(entry)) continue;
+    const full = join(docsDir, entry);
+    let st: ReturnType<typeof statSync> | undefined;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+
+    // For each topic dir, find .md files and check age
+    const walk = (dir: string): string[] => {
+      const out: string[] = [];
+      for (const f of readdirSync(dir)) {
+        const fp = join(dir, f);
+        let s: ReturnType<typeof statSync> | undefined;
+        try {
+          s = statSync(fp);
+        } catch {
+          continue;
+        }
+        if (s.isDirectory()) out.push(...walk(fp));
+        else if (f.endsWith(".md")) out.push(fp);
+      }
+      return out;
+    };
+
+    for (const full2 of walk(full)) {
+      const rel = relative(repoPath, full2);
+      const age = await lastCommitAgeDays(repoPath, rel);
+      if (age == null || age <= TOPIC_DOC_DAYS) continue;
+      const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
+      items.push({
+        kind: "topic-doc-stale",
+        repo: repoName,
+        path: displayPath,
+        ageDays: age,
+        message: `topic doc untouched for ${age}d; confirm still accurate or archive`,
+      });
+    }
+  }
+}
+
+async function sweepDecisions(
+  repoName: string,
+  repoPath: string,
+  items: SweepItem[],
+): Promise<void> {
+  const decisions = join(repoPath, "docs", "decisions.md");
+  if (!existsSync(decisions)) return;
+  const age = await lastCommitAgeDays(repoPath, "docs/decisions.md");
+  const repoAge = await lastRepoCommitAgeDays(repoPath);
+  if (age == null || repoAge == null) return;
+  // Only flag if the repo is active (recent commits) but decisions haven't moved
+  if (age <= DECISIONS_DORMANT_DAYS) return;
+  if (repoAge > 30) return; // repo itself is dormant, nothing to decide
+  const displayPath = join(repoName === "(root)" ? "" : repoName, "docs/decisions.md");
+  items.push({
+    kind: "decisions-dormant",
+    repo: repoName,
+    path: displayPath,
+    ageDays: age,
+    message: `repo is active but decisions.md hasn't been appended to in ${age}d; any architectural choices undocumented?`,
+  });
+}
+
+export async function runSweep(opts: SweepOpts): Promise<SweepItem[]> {
+  const targets: { name: string; path: string }[] = [{ name: "(root)", path: REPO_ROOT }];
+  for (const name of SUBMODULES) {
+    if (!isSubmoduleInitialized(name)) continue;
+    targets.push({ name, path: submodulePath(name) });
+  }
+
+  const filter = opts.repo === "." ? "(root)" : opts.repo;
+  const filtered = filter ? targets.filter((t) => t.name === filter) : targets;
+
+  const items: SweepItem[] = [];
+  for (const { name, path } of filtered) {
+    await sweepPlans(name, path, items);
+    await sweepIssues(name, path, items);
+    await sweepHandoffs(name, path, items);
+    await sweepRunbook(name, path, items);
+    await sweepTopicDocs(name, path, items);
+    await sweepDecisions(name, path, items);
+  }
+
+  // Sort by severity proxy: oldest first within kind
+  items.sort((a, b) => b.ageDays - a.ageDays);
+  return items;
+}
+
+/**
+ * Cheap parent-repo-only count of `cold-handoff` items, used by `docs lint`
+ * to print a one-line nudge without running the full sweep across every
+ * submodule (handoffs live under the parent's docs/handoffs/ by convention).
+ */
+export async function countColdHandoffs(): Promise<number> {
+  const items: SweepItem[] = [];
+  await sweepHandoffs("(root)", REPO_ROOT, items);
+  return items.length;
+}

package/src/lib/docs.ts

@@ -0,0 +1,199 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+import { sh } from "./exec.ts";
+
+// Module-level docs context, initialized by initDocsContext() before any
+// other function in this file is called. The repo root + submodule list
+// are passed via the context provided to registerDocsCommand.
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+
+export function initDocsContext(opts: { repoRoot: string; submodules: readonly string[] }): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+}
+
+function submodulePath(name: string): string {
+  return __resolveForDocs(REPO_ROOT, name);
+}
+
+function isSubmoduleInitialized(name: string): boolean {
+  return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+
+export interface DocCommit {
+  date: string; // ISO date string
+  message: string; // First line of commit message
+}
+
+export interface DocFileInfo {
+  path: string; // Relative to repo root (e.g., "docs/foo.md" or "subdir/README.md")
+  dir: string; // Top-level directory (e.g., "docs", "subdir", "(root)")
+  commits: DocCommit[];
+  lastCommitDate: string | null; // ISO date or null if untracked
+  lastCommitAgeDays: number | null; // Days since last commit, or null if untracked
+  untracked: boolean;
+}
+
+/** Directories/patterns to skip even within git-tracked files */
+const SKIP_PATTERNS = [
+  /\/\.cursor\//,
+  /\/\.claude\//,
+  /\/\.pytest_cache\//,
+  /\/AGENTS\.md$/, // Auto-generated
+];
+
+/** Top-level directories to ignore by default (path prefix match) */
+const IGNORE_DIRS = ["docs/vendors"];
+
+/**
+ * Scan for .md files across the parent repo and all submodules.
+ * Uses `git ls-files` to only find tracked files (skips .venv, node_modules, etc.).
+ */
+export async function scanDocs(opts: {
+  commitCount?: number;
+  dir?: string;
+  noSubmodules?: boolean;
+  staleDays?: number;
+}): Promise<DocFileInfo[]> {
+  const commitCount = opts.commitCount ?? 1;
+  const now = Date.now();
+
+  // Collect tracked .md files from parent repo
+  const parentFiles = await getTrackedMdFiles(REPO_ROOT, "");
+
+  // Collect tracked .md files from each initialized submodule (unless --no-submodules)
+  let submoduleFiles: string[] = [];
+  if (!opts.noSubmodules) {
+    const submoduleResults = await Promise.all(
+      SUBMODULES.filter(isSubmoduleInitialized).map(async (name) => {
+        const cwd = submodulePath(name);
+        return getTrackedMdFiles(cwd, name);
+      }),
+    );
+    submoduleFiles = submoduleResults.flat();
+  }
+
+  let allFiles = [...parentFiles, ...submoduleFiles];
+
+  // Filter out skipped patterns and ignored directories
+  allFiles = allFiles.filter(
+    (f) =>
+      !SKIP_PATTERNS.some((p) => p.test(`/${f}`)) &&
+      !IGNORE_DIRS.some((d) => f.startsWith(`${d}/`)),
+  );
+
+  // Filter by directory if specified
+  if (opts.dir) {
+    // Treat "." as an alias for "(root)", the natural way to say "root-level files"
+    const dirFilter = opts.dir === "." ? "(root)" : opts.dir.toLowerCase();
+    allFiles = allFiles.filter((f) => {
+      const topDir = getTopDir(f).toLowerCase();
+      // Exact match first, fall back to substring
+      return topDir === dirFilter || topDir.includes(dirFilter);
+    });
+  }
+
+  // Fetch git history for all files, batched in parallel groups of 20
+  const results: DocFileInfo[] = [];
+  const batchSize = 20;
+
+  for (let i = 0; i < allFiles.length; i += batchSize) {
+    const batch = allFiles.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map((filePath) => getFileInfo(filePath, commitCount, now)),
+    );
+    results.push(...batchResults);
+  }
+
+  // Filter by stale days if specified
+  if (opts.staleDays) {
+    const minAge = opts.staleDays;
+    return results.filter(
+      (r) => r.untracked || (r.lastCommitAgeDays !== null && r.lastCommitAgeDays >= minAge),
+    );
+  }
+
+  return results;
+}
+
+/** Get top-level directory for grouping */
+function getTopDir(filePath: string): string {
+  const parts = filePath.split("/");
+  if (parts.length === 1) return "(root)";
+  return parts[0]!;
+}
+
+/** Get tracked .md files from a git repo */
+async function getTrackedMdFiles(cwd: string, prefix: string): Promise<string[]> {
+  // Use shell to avoid pathspec vs glob ambiguity; ** ensures recursive matching
+  const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd });
+  if (result.exitCode !== 0 || !result.stdout) return [];
+
+  return result.stdout
+    .split("\n")
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => (prefix ? `${prefix}/${f}` : f));
+}
+
+/** Get file info with git history */
+async function getFileInfo(
+  filePath: string,
+  commitCount: number,
+  now: number,
+): Promise<DocFileInfo> {
+  const dir = getTopDir(filePath);
+
+  // Determine which repo to query and the relative path within it
+  const { cwd, relativePath } = resolveFilePath(filePath);
+
+  const logResult = await sh(`git log -${commitCount} --format="%aI%x09%s" -- "${relativePath}"`, {
+    cwd,
+  });
+
+  if (logResult.exitCode !== 0 || !logResult.stdout.trim()) {
+    return {
+      path: filePath,
+      dir,
+      commits: [],
+      lastCommitDate: null,
+      lastCommitAgeDays: null,
+      untracked: true,
+    };
+  }
+
+  const commits: DocCommit[] = logResult.stdout
+    .trim()
+    .split("\n")
+    .map((line) => {
+      const [date, ...msgParts] = line.split("\t");
+      return { date: date!, message: msgParts.join("\t") };
+    });
+
+  const lastDate = commits[0]?.date ?? null;
+  const ageDays = lastDate
+    ? Math.floor((now - new Date(lastDate).getTime()) / (1000 * 60 * 60 * 24))
+    : null;
+
+  return {
+    path: filePath,
+    dir,
+    commits,
+    lastCommitDate: lastDate,
+    lastCommitAgeDays: ageDays,
+    untracked: false,
+  };
+}
+
+/** Resolve a monorepo-relative path to the correct git repo cwd + relative path */
+function resolveFilePath(filePath: string): { cwd: string; relativePath: string } {
+  for (const name of SUBMODULES) {
+    if (filePath.startsWith(`${name}/`)) {
+      return {
+        cwd: submodulePath(name),
+        relativePath: filePath.slice(name.length + 1),
+      };
+    }
+  }
+  return { cwd: REPO_ROOT, relativePath: filePath };
+}

package/src/lib/env.ts

@@ -0,0 +1,12 @@
+/**
+ * Read a harnery environment variable by its suffix (the part after the
+ * `HARNERY_` prefix). Centralizes the env-var namespace so the prefix lives in
+ * exactly one place.
+ *
+ * Examples:
+ *   coordEnv("AGENT_COORD_OWNER")   → process.env.HARNERY_AGENT_COORD_OWNER
+ *   coordEnv("COORD_ROOT_OVERRIDE") → process.env.HARNERY_COORD_ROOT_OVERRIDE
+ */
+export function coordEnv(suffix: string): string | undefined {
+  return process.env[`HARNERY_${suffix}`];
+}

package/src/lib/exec.ts

@@ -0,0 +1,74 @@
+/**
+ * Generic process-spawn helpers shared by harnery commands. Callers pass
+ * `cwd` explicitly or fall back to `process.cwd()`.
+ *
+ * Built on `node:child_process` so it runs identically under Bun and Node.
+ * harnery's published package targets Node ≥ 20, and Bun implements the same
+ * module, so there's one implementation, not a runtime fork.
+ */
+
+import { spawn } from "node:child_process";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface ExecOpts {
+  cwd?: string;
+  timeout?: number;
+  env?: Record<string, string>;
+  trim?: boolean;
+}
+
+/**
+ * Run a shell command and return stdout/stderr/exitCode.
+ *
+ * `trim` defaults to true (back-compat with every existing caller). Pass
+ * `trim: false` when the consumer depends on leading whitespace. `git status
+ * --porcelain` is the canonical case: the first line of ` M PATH` output gets
+ * its leading space stripped by .trim(), shifting the X/Y status columns and
+ * breaking any positional parser. Trailing newline still gets dropped.
+ */
+export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
+  const [file, ...args] = cmd;
+  return new Promise<ExecResult>((resolveResult) => {
+    const proc = spawn(file, args, {
+      cwd: opts.cwd ?? process.cwd(),
+      env: opts.env ?? { ...process.env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    proc.stdout?.on("data", (d: Buffer) => out.push(d));
+    proc.stderr?.on("data", (d: Buffer) => err.push(d));
+
+    const timeout = opts.timeout ?? 30_000;
+    const timer = setTimeout(() => proc.kill(), timeout);
+
+    const finish = (exitCode: number, errOverride?: string): void => {
+      clearTimeout(timer);
+      const stdout = Buffer.concat(out).toString("utf-8");
+      const stderr = errOverride ?? Buffer.concat(err).toString("utf-8");
+      const shouldTrim = opts.trim !== false;
+      resolveResult({
+        stdout: shouldTrim ? stdout.trim() : stdout.replace(/\n$/, ""),
+        stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
+        exitCode,
+      });
+    };
+
+    // ENOENT (binary not found) and similar spawn failures surface here rather
+    // than throwing: resolve with 127 + the message so callers' exitCode
+    // branches handle it instead of crashing on an unhandled rejection.
+    proc.on("error", (e: Error) => finish(127, e.message));
+    proc.on("close", (code) => finish(code ?? 1));
+  });
+}
+
+/** Run a shell command via /bin/sh -c (for pipes, redirects, etc.) */
+export async function sh(command: string, opts: Omit<ExecOpts, "trim"> = {}): Promise<ExecResult> {
+  return exec(["sh", "-c", command], opts);
+}