harnery 0.0.1 → 0.2.0

package/dist/lib/docs-sweep.js

@@ -0,0 +1,304 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+import { sh } from "./exec.js";
+// 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 = [];
+export function initDocsContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function submodulePath(name) {
+    return __resolveForDocs(REPO_ROOT, name);
+}
+function isSubmoduleInitialized(name) {
+    return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+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, file) {
+    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) {
+    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) {
+    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, repoPath, items) {
+    const plansDir = join(repoPath, "docs", "plans");
+    if (!existsSync(plansDir))
+        return;
+    const walk = (dir) => {
+        const out = [];
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            let st;
+            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, repoPath, items) {
+    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, repoPath, items) {
+    const handoffsDir = join(repoPath, "docs", "handoffs");
+    if (!existsSync(handoffsDir))
+        return;
+    const walk = (dir) => {
+        const out = [];
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            let st;
+            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, repoPath, items) {
+    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, repoPath, items) {
+    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;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue;
+        // For each topic dir, find .md files and check age
+        const walk = (dir) => {
+            const out = [];
+            for (const f of readdirSync(dir)) {
+                const fp = join(dir, f);
+                let s;
+                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, repoPath, items) {
+    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) {
+    const targets = [{ 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 = [];
+    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() {
+    const items = [];
+    await sweepHandoffs("(root)", REPO_ROOT, items);
+    return items.length;
+}

package/dist/lib/docs.d.ts

@@ -0,0 +1,27 @@
+export declare function initDocsContext(opts: {
+    repoRoot: string;
+    submodules: readonly string[];
+}): void;
+export interface DocCommit {
+    date: string;
+    message: string;
+}
+export interface DocFileInfo {
+    path: string;
+    dir: string;
+    commits: DocCommit[];
+    lastCommitDate: string | null;
+    lastCommitAgeDays: number | null;
+    untracked: boolean;
+}
+/**
+ * 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 declare function scanDocs(opts: {
+    commitCount?: number;
+    dir?: string;
+    noSubmodules?: boolean;
+    staleDays?: number;
+}): Promise<DocFileInfo[]>;
+//# sourceMappingURL=docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/lib/docs.ts"],"names":[],"mappings":"AAUA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAUD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAaD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA4DzB"}

package/dist/lib/docs.js

@@ -0,0 +1,142 @@
+import { existsSync as __existsSyncForDocs } from "node:fs";
+import { resolve as __resolveForDocs } from "node:path";
+import { sh } from "./exec.js";
+// 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 = [];
+export function initDocsContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function submodulePath(name) {
+    return __resolveForDocs(REPO_ROOT, name);
+}
+function isSubmoduleInitialized(name) {
+    return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
+}
+/** 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) {
+    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 = [];
+    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 = [];
+    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) {
+    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, prefix) {
+    // 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, commitCount, now) {
+    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 = 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) {
+    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/dist/lib/env.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function coordEnv(suffix: string): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3D"}

package/dist/lib/env.js

@@ -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) {
+    return process.env[`HARNERY_${suffix}`];
+}

package/dist/lib/exec.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+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 declare function exec(cmd: string[], opts?: ExecOpts): Promise<ExecResult>;
+/** Run a shell command via /bin/sh -c (for pipes, redirects, etc.) */
+export declare function sh(command: string, opts?: Omit<ExecOpts, "trim">): Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/lib/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/lib/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAmC5E;AAED,sEAAsE;AACtE,wBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG"}

package/dist/lib/exec.js

@@ -0,0 +1,54 @@
+/**
+ * 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";
+/**
+ * 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, opts = {}) {
+    const [file, ...args] = cmd;
+    return new Promise((resolveResult) => {
+        const proc = spawn(file, args, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: opts.env ?? { ...process.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const out = [];
+        const err = [];
+        proc.stdout?.on("data", (d) => out.push(d));
+        proc.stderr?.on("data", (d) => err.push(d));
+        const timeout = opts.timeout ?? 30_000;
+        const timer = setTimeout(() => proc.kill(), timeout);
+        const finish = (exitCode, errOverride) => {
+            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) => 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, opts = {}) {
+    return exec(["sh", "-c", command], opts);
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,29 @@
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+    magenta: (s: string) => string;
+};
+/** Placeholder shown when a value is missing (null/empty), e.g. an unknown branch or age. */
+export declare const NO_DATA = "\u2014";
+/**
+ * Pretty-print + ANSI-colorize a JSON value. 2-space indent. TTY-aware: when
+ * stdout is not a TTY, the underlying `c.*` helpers emit no ANSI codes, so
+ * output is plain text. Use this for `--pretty` flags on JSON-emitting commands.
+ *
+ * Colors: keys=cyan, strings=green, numbers=magenta, booleans=yellow, null=dim.
+ */
+export declare function colorJson(value: unknown, indent?: number): string;
+/** Render a table from rows of objects */
+export declare function table(rows: Record<string, unknown>[], opts?: {
+    maxColWidth?: number;
+}): string;
+/** Format rows as CSV */
+export declare function csv(rows: Record<string, unknown>[]): string;
+/** Print a labeled key-value section */
+export declare function kvLine(label: string, value: string, color?: (s: string) => string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,CAAC;cACF,MAAM;aACP,MAAM;eACJ,MAAM;aACR,MAAM;gBACH,MAAM;cACR,MAAM;cACN,MAAM;iBACH,MAAM;CACpB,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,OAAO,WAAM,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,MAAM,CA4C5D;AAED,0CAA0C;AAC1C,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,MAAM,CAiCR;AAgBD,yBAAyB;AACzB,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAM3D;AASD,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAG1F"}