harnery 0.0.1 → 0.2.0

package/dist/commands/context.js

@@ -0,0 +1,185 @@
+import { buildContext, DEFAULT_SECTIONS, OPT_IN_SECTIONS, } from "../lib/context/index.js";
+/**
+ * `harn context`: one-shot orientation snapshot.
+ *
+ * Aggregates self / time / repo / commits / submodules / peers (default) plus
+ * opt-in services. Useful at session start, post-compaction, or before
+ * dispatching subagents. Fail-open per section.
+ */
+export function registerContextCommand(program, emit, context) {
+    program
+        .command("context")
+        .description(`One-shot orientation snapshot: self, repo, submodules, peers, recent commits. Default sections: ${DEFAULT_SECTIONS.join(" / ")}. Opt-in: ${OPT_IN_SECTIONS.join(" / ")}.`)
+        .option("--section <name>", `Limit to specific sections (comma-list or repeated; valid: ${[...DEFAULT_SECTIONS, ...OPT_IN_SECTIONS].join(", ")})`, collectSections, [])
+        .option("--include <name>", "Add an opt-in section (e.g. services)", collectSections, [])
+        .option("--show-clean", "Don't hide clean submodules")
+        .option("--json", "Structured JSON envelope")
+        .action(async (opts) => {
+        try {
+            const sections = opts.section.length > 0 ? opts.section : DEFAULT_SECTIONS;
+            const report = await buildContext({
+                sections,
+                include: opts.include,
+                showClean: opts.showClean,
+                repoRoot: context?.repoRoot,
+                submodules: context?.submodules,
+            });
+            if (opts.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+                return;
+            }
+            emit.text(`${renderReport(report)}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "context_failed", message: msg });
+            process.exit(1);
+        }
+    });
+}
+function collectSections(value, prev) {
+    const all = [...DEFAULT_SECTIONS, ...OPT_IN_SECTIONS];
+    const out = [...prev];
+    for (const tok of value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        if (!all.includes(tok)) {
+            throw new Error(`unknown section "${tok}". Valid: ${all.join(", ")}`);
+        }
+        if (!out.includes(tok))
+            out.push(tok);
+    }
+    return out;
+}
+// ─── TTY rendering ─────────────────────────────────────────────────────────
+function renderReport(r) {
+    const lines = [];
+    if (r.self)
+        lines.push(...renderSelf(r.self));
+    if (r.time)
+        lines.push(...renderTime(r.time));
+    if (r.repo)
+        lines.push(...renderRepo(r.repo));
+    if (r.commits)
+        lines.push(...renderCommits(r.commits));
+    if (r.submodules)
+        lines.push(...renderSubmodules(r.submodules));
+    if (r.peers)
+        lines.push(...renderPeers(r.peers));
+    if (r.services)
+        lines.push(...renderServices(r.services));
+    lines.push("");
+    lines.push(`(elapsed: ${r.meta.elapsed_ms}ms)`);
+    return lines.join("\n");
+}
+function section(header, body) {
+    return ["", `── ${header} ──`, ...body];
+}
+function renderSelf(s) {
+    if ("error" in s)
+        return section("self", [`  (unavailable: ${s.error})`]);
+    const body = [];
+    body.push(`  agent-${s.name ?? "?"}  (${formatAge(s.session_age_secs)} old, owner=${s.instance_id.slice(0, 8)}…)`);
+    if (s.task)
+        body.push(`  task:    "${s.task}"`);
+    if (s.last_tool) {
+        const target = s.last_tool_target ? `  ${truncate(s.last_tool_target, 80)}` : "";
+        body.push(`  last:    ${s.last_tool}${target}`);
+    }
+    if (s.files_held.length > 0) {
+        body.push(`  holds ${s.files_held.length} file(s):`);
+        for (const f of s.files_held.slice(0, 5))
+            body.push(`    ${f}`);
+        if (s.files_held.length > 5)
+            body.push(`    +${s.files_held.length - 5} more`);
+    }
+    else {
+        body.push("  files:   none held");
+    }
+    return section("self", body);
+}
+function renderTime(t) {
+    return section("time", [`  ${t.chicago}  (UTC: ${t.utc})`]);
+}
+function renderRepo(r) {
+    if ("error" in r)
+        return section("repo", [`  (unavailable: ${r.error})`]);
+    const parts = [];
+    const aheadBehind = r.ahead > 0 || r.behind > 0 ? ` (ahead ${r.ahead}, behind ${r.behind} vs origin)` : "";
+    parts.push(`  cwd:     ${r.cwd}`);
+    parts.push(`  branch:  ${r.branch}${aheadBehind}`);
+    const dirtyBits = [];
+    if (r.staged)
+        dirtyBits.push(`${r.staged} staged`);
+    if (r.modified)
+        dirtyBits.push(`${r.modified} modified`);
+    if (r.untracked)
+        dirtyBits.push(`${r.untracked} untracked`);
+    parts.push(`  status:  ${dirtyBits.length ? dirtyBits.join(", ") : "clean"}`);
+    return section("repo", parts);
+}
+function renderCommits(c) {
+    if ("error" in c)
+        return section("commits", [`  (unavailable: ${c.error})`]);
+    if (c.rows.length === 0)
+        return section("commits", ["  (none)"]);
+    return section("commits (last 3)", c.rows.map((row) => `  ${row.sha}  ${truncate(row.subject, 80)}`));
+}
+function renderSubmodules(s) {
+    if ("error" in s)
+        return section("submodules", [`  (unavailable: ${s.error})`]);
+    if (s.rows.length === 0) {
+        const tail = s.clean_omitted > 0 ? ` (${s.clean_omitted} clean omitted)` : "";
+        return section("submodules", [`  all clean${tail}`]);
+    }
+    const lines = s.rows.map((sm) => {
+        const aheadBehind = sm.ahead > 0 || sm.behind > 0 ? ` ±${sm.ahead}/${sm.behind}` : "";
+        const dirty = sm.dirty ? ` (${sm.modifiedFiles}m+${sm.untrackedFiles}u)` : "";
+        return `  ${sm.name.padEnd(28)} ${sm.branch}${aheadBehind}${dirty}`;
+    });
+    const tail = s.clean_omitted > 0 ? [`  (+${s.clean_omitted} clean omitted)`] : [];
+    return section("submodules", [...lines, ...tail]);
+}
+function renderPeers(p) {
+    if ("error" in p)
+        return section("peers", [`  (unavailable: ${p.error})`]);
+    if (p.rows.length === 0)
+        return section("peers", ["  (none active)"]);
+    const lines = p.rows.map((peer) => {
+        const taskBit = peer.task ? ` "${truncate(peer.task, 40)}"` : "";
+        const filesBit = peer.files > 0 ? `${peer.files}f` : "0f";
+        const lastBit = peer.last_tool ? `, last: ${peer.last_tool}` : "";
+        return `  agent-${peer.name.padEnd(12)}${taskBit}  (${peer.age_min}m old, ${filesBit}${lastBit})`;
+    });
+    return section("peers", lines);
+}
+function renderServices(s) {
+    if ("error" in s)
+        return section("services", [`  (unavailable: ${s.error})`]);
+    if (s.docker_compose.length === 0)
+        return section("services", ["  (no compose project running)"]);
+    const lines = s.docker_compose.map((sv) => `  ${sv.service.padEnd(20)} ${sv.status}`);
+    return section("services (docker compose)", lines);
+}
+// ─── Format helpers ────────────────────────────────────────────────────────
+function formatAge(secs) {
+    if (secs < 60)
+        return `${secs}s`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m`;
+    if (secs < 86400) {
+        const h = Math.floor(secs / 3600);
+        const m = Math.floor((secs % 3600) / 60);
+        return `${h}h ${m}m`;
+    }
+    const d = Math.floor(secs / 86400);
+    const h = Math.floor((secs % 86400) / 3600);
+    return `${d}d ${h}h`;
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n - 1)}…`;
+}

package/dist/commands/cookies.d.ts

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

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

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

package/dist/commands/cookies.js

@@ -0,0 +1,140 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { CookieJar } from "../lib/cookies/index.js";
+/**
+ * `cookies`: manage the local browser cookie store.
+ *
+ * Default store path: `~/.cache/harnery/cookies.json`. Override with
+ * `--store <path>` if you need a separate jar (e.g., one per environment).
+ * Format is CDP-native (compatible with Playwright/agent-browser).
+ */
+const DEFAULT_STORE = resolve(homedir(), ".cache", "harnery", "cookies.json");
+function jarFrom(opts) {
+    return new CookieJar({
+        path: opts.store ?? DEFAULT_STORE,
+        source: "bp-cookies",
+    });
+}
+// Module-scoped emit assigned by registerCookiesCommand; the module-level
+// helpers below close over this so the Commander .action callbacks stay
+// concise. Safe because the command tree is registered once at startup.
+let emit;
+export function registerCookiesCommand(program, emitParam) {
+    emit = emitParam;
+    const cmd = program
+        .command("cookies")
+        .description(`Manage the shared browser cookie store (default: ${DEFAULT_STORE}). Format is CDP-native (compatible with Playwright/agent-browser).`)
+        .option("--store <path>", "Override store path");
+    cmd.action((opts) => safe(() => runList(jarFrom(opts), {})));
+    cmd
+        .command("list")
+        .description("List cookies in the store, grouped by domain")
+        .option("--domain <domain>", "Filter by domain")
+        .option("--json", "Output as JSON")
+        .action((opts) => safe(() => runList(jarFrom({ ...cmd.opts(), ...opts }), opts)));
+    cmd
+        .command("set <name> <value>")
+        .description("Set a cookie in the store (creates the file if missing)")
+        .requiredOption("--domain <domain>", "Cookie domain (e.g., .example.com)")
+        .option("--path <path>", "Cookie path", "/")
+        .option("--secure", "HTTPS only")
+        .option("--httpOnly", "Prevent JavaScript access")
+        .option("--sameSite <policy>", "SameSite policy: Strict | Lax | None")
+        .option("--expires <unix-seconds>", "Unix timestamp; omit for session cookie")
+        .action((name, value, opts) => safe(() => runSet(jarFrom({ ...cmd.opts(), ...opts }), name, value, opts)));
+    cmd
+        .command("clear")
+        .description("Remove cookies from the store")
+        .option("--domain <domain>", "Drop cookies matching a single domain")
+        .option("--all", "Wipe everything (cookies + origins)")
+        .action((opts) => safe(() => runClear(jarFrom({ ...cmd.opts(), ...opts }), opts)));
+    cmd
+        .command("header <url>")
+        .description("Print a Cookie: header value for the given URL (empty if no match)")
+        .action((url, opts) => safe(() => {
+        const jar = jarFrom({ ...cmd.opts(), ...opts });
+        const out = jar.header(url);
+        if (out)
+            emit.text(`${out}\n`);
+    }));
+    cmd
+        .command("import <file>")
+        .description("Merge cookies from a JSON file (CDP/agent-browser shape)")
+        .option("--replace", "Replace the entire store instead of merging")
+        .action((file, opts) => safe(() => {
+        const jar = jarFrom({ ...cmd.opts(), ...opts });
+        const { count } = jar.import(file, opts);
+        emit.data({ ok: true, action: "import", count, file });
+    }));
+    cmd
+        .command("export <file>")
+        .description("Write the store to a file (for sharing with another tool)")
+        .action((file, opts) => safe(() => {
+        const jar = jarFrom({ ...cmd.opts(), ...opts });
+        const { count } = jar.export(file);
+        emit.file(file, { cookies: count });
+    }));
+    cmd
+        .command("info")
+        .description("Show store path, size, cookie counts, and exporting tool")
+        .option("--json", "Output as JSON")
+        .action((opts) => safe(() => runInfo(jarFrom({ ...cmd.opts(), ...opts }), opts)));
+}
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+function runList(jar, opts) {
+    if (opts.json)
+        emit.config({ format: "json" });
+    const cookies = jar.list({ domain: opts.domain });
+    emit.rows(cookies);
+}
+function runSet(jar, name, value, opts) {
+    const cookie = {
+        name,
+        value,
+        domain: opts.domain,
+        path: opts.path,
+        expires: opts.expires ? Number.parseFloat(opts.expires) : -1,
+        httpOnly: opts.httpOnly ?? false,
+        secure: opts.secure ?? false,
+        session: !opts.expires,
+        size: name.length + value.length,
+    };
+    if (opts.sameSite)
+        cookie.sameSite = opts.sameSite;
+    jar.set(cookie);
+    emit.data({ ok: true, action: "set", name, domain: opts.domain });
+}
+function runClear(jar, opts) {
+    if (!opts.domain && !opts.all) {
+        throw new Error("Specify --domain <domain> or --all");
+    }
+    const { before, after } = jar.clear(opts);
+    const removed = before - after;
+    emit.data({
+        ok: true,
+        action: "clear",
+        removed,
+        before,
+        after,
+        domain: opts.domain ?? null,
+        all: opts.all ?? false,
+    });
+}
+function runInfo(jar, opts) {
+    if (opts.json)
+        emit.config({ format: "json" });
+    const i = jar.info();
+    emit.data(i);
+}
+function safe(fn) {
+    try {
+        fn();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit.error({ code: "cookies_error", message: msg });
+        process.exit(1);
+    }
+}

package/dist/commands/docs.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerDocsCommand(program: Command, emitParam: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=docs.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/docs.js

@@ -0,0 +1,137 @@
+import { initDocsContext as initDocs, scanDocs } from "../lib/docs.js";
+import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.js";
+import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.js";
+import { countColdHandoffs, initDocsContext as initDocsSweep, runSweep, } from "../lib/docs-sweep.js";
+function ensureContext(context) {
+    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;
+export function registerDocsCommand(program, emitParam, context) {
+    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) => {
+        try {
+            ensureContext(context);
+            await handleDocs(opts);
+        }
+        catch (err) {
+            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) => {
+        try {
+            ensureContext(context);
+            await handleLint(opts);
+        }
+        catch (err) {
+            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) => {
+        try {
+            ensureContext(context);
+            await handleSweep(opts);
+        }
+        catch (err) {
+            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) => {
+        try {
+            ensureContext(context);
+            await handleIndex(opts);
+        }
+        catch (err) {
+            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) {
+    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);
+}
+// --- `harn docs lint` ---
+async function handleLint(opts) {
+    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) {
+    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) {
+    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/dist/commands/doctor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `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 type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+type Severity = "ok" | "warn" | "fail";
+interface Check {
+    name: string;
+    severity: Severity;
+    detail: string;
+    hint?: string;
+}
+export declare function registerDoctorCommand(program: Command, emit: EmitContext): void;
+export declare function runChecks(): Check[];
+export {};
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwC/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAWnC"}