harnery 0.0.1 → 0.2.1

package/dist/commands/init.js

@@ -0,0 +1,288 @@
+/**
+ * `harn init`: idempotently wire harnery into a project.
+ *
+ * Two things a fresh consumer otherwise has to know to do by hand (both silent
+ * if skipped):
+ *   1. Create the `.harnery/` coord root; without it `findCoordRoot` returns
+ *      null and every hook no-ops forever.
+ *   2. Register the agent-hook entries in the harness settings file.
+ *
+ * Wires whichever harness `--harness` names (Claude Code `.claude/settings.json`,
+ * Cursor `.cursor/hooks.json`, or Codex `.codex/hooks.json`): the per-harness
+ * file path, event list, and hook-entry shape all come from HARNESS_SPECS.
+ *
+ * `harn init` does both, non-destructively: it merges hook entries into an
+ * existing settings file (preserving any other hooks) and skips entries that are
+ * already wired, so it's safe to re-run. `--dry-run` previews without writing.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_BIN_NAME, stripJsonComments } from "../core/config.js";
+import { HARNESS_SPECS, } from "../core/hooks/harness/events.js";
+// This file is src/commands/init.ts → harnery package root is two levels up.
+const HARNERY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export function registerInitCommand(program, emit, binName) {
+    program
+        .command("init")
+        .description("Bootstrap harnery in this project: create .harnery/ and wire the harness " +
+        "hooks (idempotent; safe to re-run). Use --dry-run to preview.")
+        .option("--harness <id>", "claude-code | cursor | codex", "claude-code")
+        .option("--dry-run", "Show what would change without writing")
+        .option("--project-root <path>", "Project root (default: git toplevel, else cwd)")
+        .action((opts) => {
+        const harness = opts.harness;
+        const spec = HARNESS_SPECS[harness];
+        if (!spec) {
+            emit.text(`Unknown harness '${opts.harness}'. Expected: claude-code | cursor | codex.`);
+            emit.setExitCode(1);
+            return;
+        }
+        const projectRoot = resolve(opts.projectRoot ?? gitTopLevel() ?? process.cwd());
+        const dryRun = opts.dryRun === true;
+        const actions = [];
+        // ── 1. coord root ──────────────────────────────────────────────────────
+        const coordDir = resolve(projectRoot, ".harnery");
+        if (existsSync(coordDir)) {
+            actions.push("· .harnery/ already exists");
+        }
+        else if (dryRun) {
+            actions.push("+ would create .harnery/ (+ .harnery/.gitignore)");
+        }
+        else {
+            mkdirSync(coordDir, { recursive: true });
+            // Runtime state is machine-local; don't let consumers commit heartbeats.
+            writeFileSync(resolve(coordDir, ".gitignore"), "*\n!.gitignore\n");
+            actions.push("+ created .harnery/ (+ .harnery/.gitignore)");
+        }
+        // ── 1b. stamp the host bin name ────────────────────────────────────────
+        // The coord binaries (agent-hook/agent-coord) and web UI run as harnery
+        // itself, so they can't see a consumer CLI's name; they read it back from
+        // config.jsonc. Standalone `harn` is the resolver's default, so only a
+        // consumer (binName ≠ "harn") needs the stamp.
+        if (binName && binName !== DEFAULT_BIN_NAME) {
+            const configPath = resolve(coordDir, "config.jsonc");
+            const stamp = stampBinName(configPath, binName, dryRun);
+            if (stamp)
+                actions.push(stamp);
+        }
+        // ── 2. harness hooks ───────────────────────────────────────────────────
+        const settingsPath = resolve(projectRoot, spec.settingsFile);
+        const agentHook = relative(projectRoot, resolve(HARNERY_ROOT, "bin", "agent-hook"));
+        let settings;
+        if (existsSync(settingsPath)) {
+            try {
+                settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+            }
+            catch (err) {
+                emit.text(`✗ ${rel(projectRoot, settingsPath)} exists but isn't valid JSON; refusing to ` +
+                    `overwrite. Fix it and re-run.\n  (${err.message})`);
+                emit.setExitCode(1);
+                return;
+            }
+        }
+        else {
+            settings = {};
+        }
+        const { wired, already } = wireHooks(settings, spec, agentHook, harness);
+        if (wired === 0) {
+            actions.push(`· all ${spec.events.length} ${harness} hooks already wired in ${rel(projectRoot, settingsPath)}`);
+        }
+        else if (dryRun) {
+            actions.push(`+ would wire ${wired} hook(s) into ${rel(projectRoot, settingsPath)} (${already} already present)`);
+        }
+        else {
+            mkdirSync(dirname(settingsPath), { recursive: true });
+            writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+            actions.push(`+ wired ${wired} hook(s) into ${rel(projectRoot, settingsPath)} (${already} already present)`);
+        }
+        emit.text(render(projectRoot, dryRun, actions));
+    });
+}
+/**
+ * Merge agent-hook entries into a harness settings object in place, idempotently.
+ * Preserves every existing hook; skips events already wired to
+ * `agent-hook <subcommand>`. Honors the harness's entry shape (Claude/Codex nest
+ * under an inner `hooks` array; Cursor uses a flat `{ command }`) and ensures the
+ * root `version` key when the harness requires one. Pure (no fs/git) so it's
+ * unit-testable.
+ *
+ * The trailing space in the match (`agent-hook ${subcommand} `) is load-bearing:
+ * it keeps `stop` from matching `stop-failure`.
+ */
+export function wireHooks(settings, spec, agentHookPath, harness) {
+    if (spec.rootVersion !== undefined && settings.version === undefined) {
+        settings.version = spec.rootVersion;
+    }
+    if (!settings.hooks)
+        settings.hooks = {};
+    let wired = 0;
+    let already = 0;
+    for (const { settingsKey, subcommand } of spec.events) {
+        const command = `bash ${agentHookPath} ${subcommand} --harness ${harness}`;
+        const groups = settings.hooks[settingsKey] ?? [];
+        const present = groups.some((g) => groupCommands(g).some((c) => c.includes(`agent-hook ${subcommand} `)));
+        if (present) {
+            already++;
+            continue;
+        }
+        groups.push(makeEntry(spec.entryShape, command));
+        settings.hooks[settingsKey] = groups;
+        wired++;
+    }
+    return { wired, already };
+}
+/**
+ * Inverse of {@link wireHooks}: strip every harnery-owned hook entry from a
+ * settings object in place, idempotently. A hook is "harnery's" when its command
+ * contains `agent-hook ` (the trailing space matches `agent-hook <subcommand>`),
+ * so any non-harnery hook the consumer added is preserved. Emptied
+ * `hooks[settingsKey]` arrays are dropped; an emptied `hooks` object is dropped
+ * entirely. Harness-agnostic (scans every key) so it removes entries left by any
+ * harness. Pure (no fs) so it's unit-testable. Returns the count removed and the
+ * count of non-harnery hooks left behind.
+ */
+export function unwireHooks(settings) {
+    if (!settings.hooks || typeof settings.hooks !== "object")
+        return { removed: 0, remaining: 0 };
+    let removed = 0;
+    for (const key of Object.keys(settings.hooks)) {
+        const groups = settings.hooks[key];
+        if (!Array.isArray(groups))
+            continue;
+        const kept = groups.filter((g) => !groupCommands(g).some((c) => c.includes("agent-hook ")));
+        removed += groups.length - kept.length;
+        // removing the emptied hook key is the intent (tiny one-shot object)
+        if (kept.length === 0)
+            delete settings.hooks[key];
+        else
+            settings.hooks[key] = kept;
+    }
+    let remaining = 0;
+    for (const groups of Object.values(settings.hooks)) {
+        if (Array.isArray(groups))
+            remaining += groups.length;
+    }
+    // drop the now-empty hooks object so callers see a clean shape
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    return { removed, remaining };
+}
+/** Build a hook entry in the harness's shape. */
+function makeEntry(shape, command) {
+    return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
+}
+/** Pull every command string out of a hook entry, regardless of shape. */
+function groupCommands(group) {
+    if ("command" in group && typeof group.command === "string")
+        return [group.command];
+    if ("hooks" in group && Array.isArray(group.hooks)) {
+        return group.hooks.map((h) => h.command).filter((c) => typeof c === "string");
+    }
+    return [];
+}
+/**
+ * Idempotently record `binName` in `.harnery/config.jsonc`, preserving any
+ * existing JSONC comments and the `files` section. Returns an action line, or
+ * null when nothing changed. Three cases:
+ *   - file absent → write a minimal commented stub;
+ *   - `binName` already present + matching → no-op;
+ *   - present-but-different value → comment-safe in-place value swap;
+ *   - key absent → splice it in as the first key (comment-safe).
+ */
+export function stampBinName(configPath, binName, dryRun) {
+    const rel = (p) => relative(dirname(dirname(configPath)), p) || p;
+    const quoted = JSON.stringify(binName);
+    if (!existsSync(configPath)) {
+        if (dryRun)
+            return `+ would stamp binName "${binName}" into ${rel(configPath)}`;
+        writeFileSync(configPath, `{\n  // Host CLI bin name, surfaced in agent-facing prompts + nudges.\n  "binName": ${quoted}\n}\n`);
+        return `+ stamped binName "${binName}" into ${rel(configPath)}`;
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonComments(raw)) ?? {};
+    }
+    catch {
+        // Unparseable config: don't clobber it; leave the bin name to env/manual fix.
+        return `· ${rel(configPath)} isn't valid JSONC; skipped binName stamp`;
+    }
+    if (parsed.binName === binName)
+        return null;
+    if (typeof parsed.binName === "string") {
+        // Existing value differs; swap it in place (keeps comments + layout).
+        const next = raw.replace(/("binName"\s*:\s*)"(?:[^"\\]|\\.)*"/, `$1${quoted}`);
+        if (dryRun)
+            return `~ would update binName → "${binName}" in ${rel(configPath)}`;
+        writeFileSync(configPath, next);
+        return `~ updated binName → "${binName}" in ${rel(configPath)}`;
+    }
+    // No binName key yet; splice it as the first key.
+    const keys = Object.keys(parsed);
+    let next;
+    if (keys.length === 0) {
+        next = `{\n  "binName": ${quoted}\n}\n`;
+    }
+    else {
+        // Insert after the first structural `{` (skipping leading ws + comments).
+        const at = firstBraceIndex(raw);
+        if (at < 0)
+            return `· ${rel(configPath)} has no object literal; skipped binName stamp`;
+        next = `${raw.slice(0, at + 1)}\n  "binName": ${quoted},${raw.slice(at + 1)}`;
+    }
+    if (dryRun)
+        return `+ would add binName "${binName}" to ${rel(configPath)}`;
+    writeFileSync(configPath, next);
+    return `+ added binName "${binName}" to ${rel(configPath)}`;
+}
+/** Index of the first structural `{`, skipping leading whitespace + comments. */
+function firstBraceIndex(raw) {
+    let i = 0;
+    while (i < raw.length) {
+        const ch = raw[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+            i++;
+        }
+        else if (ch === "/" && raw[i + 1] === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i++;
+        }
+        else if (ch === "/" && raw[i + 1] === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i++;
+            i += 2;
+        }
+        else if (ch === "{") {
+            return i;
+        }
+        else {
+            return -1;
+        }
+    }
+    return -1;
+}
+function render(projectRoot, dryRun, actions) {
+    const head = dryRun ? "harn init (dry run): no changes written" : "harn init";
+    const tail = dryRun
+        ? "\nRe-run without --dry-run to apply."
+        : "\nDone. Start a session and check `harn agents whoami`.";
+    return `${head}\n  root: ${projectRoot}\n${actions.map((a) => `  ${a}`).join("\n")}${tail}`;
+}
+function gitTopLevel() {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    const out = r.status === 0 ? r.stdout.trim() : "";
+    return out || null;
+}
+function rel(root, p) {
+    const r = relative(root, p);
+    return r || p;
+}

package/dist/commands/outline.d.ts

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

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

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