harnery 0.0.1 → 0.2.0

package/dist/commands/web.js

@@ -0,0 +1,165 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * `harn web`: Next.js dashboard for harnery's coord state.
+ *
+ * Subcommands:
+ *   up [--prod]:   start the server (dev mode default; --prod runs next start)
+ *   build:         next build (production bundle)
+ *   start:         next start (must `harn web build` first)
+ *
+ * Launches the Next.js app under `harnery/web/` against the user's current
+ * working directory. The web app reads `.harnery/` via `HARNERY_COORD_ROOT`;
+ * passing cwd here lets the dashboard show the right project regardless
+ * of where the user invokes `harn web up` from.
+ *
+ * Localhost-only by default. Network exposure is intentionally out of
+ * scope for v1.
+ */
+function webRoot() {
+    // src/commands/web.ts → src/ → harnery/ → harnery/web/
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..", "web");
+}
+function checkWebPresent(emit) {
+    const root = webRoot();
+    if (!existsSync(path.join(root, "package.json"))) {
+        emit.error({
+            code: "web_missing",
+            message: `harnery/web/ not found at ${root}`,
+            hint: "The dashboard ships with the harnery git repo, not the npm package (which is the CLI + " +
+                "coord engine only). Clone https://github.com/ryanjkelly/harnery, run `bun install`, then " +
+                "`harn web up --coord-root <your-project>` (or run it from inside that project). " +
+                "See https://harnery.com/cli/web/.",
+        });
+        return null;
+    }
+    return root;
+}
+function runner() {
+    // Prefer bun when available; fall back to npx/npm for plain Node installs.
+    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+    return r.status === 0 ? "bun" : "npx";
+}
+export function registerWebCommand(program, emit) {
+    const web = program
+        .command("web")
+        .description("Standalone read-only dashboard for harnery's coord state");
+    web
+        .command("up")
+        .description("Start the dashboard. Default: dev mode (HMR, no build needed). With " +
+        "--prod, runs next start (requires a prior `harn web build`).")
+        .option("-p, --port <port>", "Listen port", "9000")
+        .option("--coord-root <dir>", "Override the coord root (default: cwd; web walks up looking for .harnery/)")
+        .option("--prod", "Use next start instead of next dev (requires prior build)")
+        .action(async (opts) => {
+        const root = checkWebPresent(emit);
+        if (!root) {
+            process.exitCode = 1;
+            return;
+        }
+        const coordRoot = opts.coordRoot ?? process.cwd();
+        const port = String(opts.port);
+        const mode = opts.prod ? "start" : "dev";
+        if (opts.prod) {
+            const nextDir = path.join(root, ".next");
+            if (!existsSync(nextDir)) {
+                emit.error({
+                    code: "no_build",
+                    message: `--prod requires a prior build (no .next at ${nextDir})`,
+                    hint: "Run `harn web build` first.",
+                });
+                process.exitCode = 1;
+                return;
+            }
+        }
+        emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
+        emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+        const child = spawn(runner(), ["run", mode], {
+            cwd: root,
+            env: {
+                ...process.env,
+                HARNERY_COORD_ROOT: coordRoot,
+                HARNERY_WEB_PORT: port,
+            },
+            stdio: "inherit",
+        });
+        const cleanup = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        process.on("SIGINT", () => cleanup("SIGINT"));
+        process.on("SIGTERM", () => cleanup("SIGTERM"));
+        child.on("exit", (code, sig) => {
+            if (sig) {
+                emit.log(`web exited on ${sig}`, "info");
+            }
+            else if (code !== 0) {
+                emit.error({ code: "web_exit", message: `next exited with code ${code}` });
+                process.exitCode = code ?? 1;
+            }
+        });
+    });
+    web
+        .command("build")
+        .description("Build the production bundle (next build).")
+        .action(() => {
+        const root = checkWebPresent(emit);
+        if (!root) {
+            process.exitCode = 1;
+            return;
+        }
+        emit.log("running next build…", "info");
+        const r = spawnSync(runner(), ["run", "build"], {
+            cwd: root,
+            stdio: "inherit",
+        });
+        process.exitCode = r.status ?? 1;
+    });
+    web
+        .command("start")
+        .description("Start the production server (next start). Requires prior `harn web build`.")
+        .option("-p, --port <port>", "Listen port", "9000")
+        .option("--coord-root <dir>", "Override the coord root")
+        .action((opts) => {
+        const root = checkWebPresent(emit);
+        if (!root) {
+            process.exitCode = 1;
+            return;
+        }
+        const nextDir = path.join(root, ".next");
+        if (!existsSync(nextDir)) {
+            emit.error({
+                code: "no_build",
+                message: `no .next/ found at ${nextDir}`,
+                hint: "Run `harn web build` first.",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const coordRoot = opts.coordRoot ?? process.cwd();
+        const port = String(opts.port);
+        emit.log(`harn web · http://localhost:${port} (start)`, "info");
+        emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+        const child = spawn(runner(), ["run", "start"], {
+            cwd: root,
+            env: {
+                ...process.env,
+                HARNERY_COORD_ROOT: coordRoot,
+                HARNERY_WEB_PORT: port,
+            },
+            stdio: "inherit",
+        });
+        const cleanup = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        process.on("SIGINT", () => cleanup("SIGINT"));
+        process.on("SIGTERM", () => cleanup("SIGTERM"));
+        child.on("exit", (code) => {
+            process.exitCode = code ?? 0;
+        });
+    });
+}

package/dist/core/agents/canonical-emit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Emit canonical events by spawning `agent-coord emit-event`. Used by every
+ * `agents …` / `scratch` / `presence` write that has a canonical state event.
+ *
+ * Soft-fails: never throws into the caller. A failed emit logs to stderr
+ * (visible to operators in their terminal) but never breaks the CLI flow.
+ *
+ * Synchronous spawn: the projector runs before the CLI returns. ~20ms
+ * latency budget per call.
+ */
+export interface CanonicalEmitInput {
+    type: string;
+    owner: string;
+    session: string;
+    harness: "claude-code" | "cursor" | "codex";
+    data: Record<string, unknown>;
+    turnId?: string;
+    parentSessionId?: string;
+    parentTurnId?: string;
+}
+export declare function emitCanonical(input: CanonicalEmitInput): void;
+/**
+ * Normalize the heartbeat's `platform` field (which uses snake_case
+ * `claude_code`) to the canonical kebab-case Harness type.
+ */
+export declare function normalizeHarness(platform: string | undefined): "claude-code" | "cursor" | "codex";
+//# sourceMappingURL=canonical-emit.d.ts.map

package/dist/core/agents/canonical-emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-emit.d.ts","sourceRoot":"","sources":["../../../src/core/agents/canonical-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CA8B7D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAIjG"}

package/dist/core/agents/canonical-emit.js

@@ -0,0 +1,72 @@
+/**
+ * Emit canonical events by spawning `agent-coord emit-event`. Used by every
+ * `agents …` / `scratch` / `presence` write that has a canonical state event.
+ *
+ * Soft-fails: never throws into the caller. A failed emit logs to stderr
+ * (visible to operators in their terminal) but never breaks the CLI flow.
+ *
+ * Synchronous spawn: the projector runs before the CLI returns. ~20ms
+ * latency budget per call.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export function emitCanonical(input) {
+    const root = findRepoRoot();
+    if (!root)
+        return;
+    const binary = resolve(root, "harnery", "bin", "agent-coord");
+    if (!existsSync(binary))
+        return;
+    try {
+        const args = [
+            "emit-event",
+            "--type",
+            input.type,
+            "--owner",
+            input.owner,
+            "--session",
+            input.session,
+            "--harness",
+            input.harness,
+            "--data-json",
+            JSON.stringify(input.data),
+        ];
+        if (input.turnId)
+            args.push("--turn-id", input.turnId);
+        if (input.parentSessionId)
+            args.push("--parent-session-id", input.parentSessionId);
+        if (input.parentTurnId)
+            args.push("--parent-turn-id", input.parentTurnId);
+        spawnSync(binary, args, {
+            encoding: "utf8",
+            stdio: "ignore",
+            timeout: 3000,
+        });
+    }
+    catch {
+        /* never break the caller */
+    }
+}
+/**
+ * Normalize the heartbeat's `platform` field (which uses snake_case
+ * `claude_code`) to the canonical kebab-case Harness type.
+ */
+export function normalizeHarness(platform) {
+    if (platform === "cursor")
+        return "cursor";
+    if (platform === "codex")
+        return "codex";
+    return "claude-code";
+}
+function findRepoRoot(start = process.cwd()) {
+    let dir = resolve(start);
+    while (true) {
+        if (existsSync(join(dir, ".harnery")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/core/agents/cli-emit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI-side canonical event emission helper. Importable from any CLI surface
+ * to emit-then-project in one call.
+ *
+ * Pattern: every state-changing CLI command appends its event first, then
+ * runs the projector synchronously for the affected owner.
+ */
+import { type EmitInput, type Envelope } from "./events/emit.js";
+export interface EmitAndProjectResult {
+    envelope: Envelope;
+    projected: boolean;
+}
+/**
+ * Emit a canonical event AND synchronously project it into the owner's v2
+ * heartbeat. Idempotent on event_id: replays don't double-apply.
+ *
+ * Returns the emitted envelope so callers can inspect / log.
+ *
+ * Soft-fails on any internal error: never throws into the caller, because
+ * this runs inside operator-facing CLI commands and a corrupt events.ndjson
+ * line shouldn't break `agents set-task`.
+ */
+export declare function emitAndProject(input: EmitInput, opts?: {
+    coordRoot?: string;
+    skipProject?: boolean;
+}): EmitAndProjectResult | null;
+//# sourceMappingURL=cli-emit.d.ts.map

package/dist/core/agents/cli-emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-emit.d.ts","sourceRoot":"","sources":["../../../src/core/agents/cli-emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AAIvE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,oBAAoB,GAAG,IAAI,CAiC7B"}

package/dist/core/agents/cli-emit.js

@@ -0,0 +1,57 @@
+/**
+ * CLI-side canonical event emission helper. Importable from any CLI surface
+ * to emit-then-project in one call.
+ *
+ * Pattern: every state-changing CLI command appends its event first, then
+ * runs the projector synchronously for the affected owner.
+ */
+import { emit } from "./events/emit.js";
+import { findCoordRoot } from "./paths.js";
+import { projectHeartbeats } from "./state/heartbeat-projector.js";
+/**
+ * Emit a canonical event AND synchronously project it into the owner's v2
+ * heartbeat. Idempotent on event_id: replays don't double-apply.
+ *
+ * Returns the emitted envelope so callers can inspect / log.
+ *
+ * Soft-fails on any internal error: never throws into the caller, because
+ * this runs inside operator-facing CLI commands and a corrupt events.ndjson
+ * line shouldn't break `agents set-task`.
+ */
+export function emitAndProject(input, opts = {}) {
+    const root = opts.coordRoot ?? findCoordRoot();
+    if (!root)
+        return null;
+    try {
+        const envelope = emit(root, input);
+        let projected = false;
+        if (!opts.skipProject) {
+            try {
+                projectHeartbeats(root, [
+                    {
+                        schema_version: envelope.schema_version,
+                        event_id: envelope.event_id,
+                        event_type: envelope.event_type,
+                        ts: envelope.ts,
+                        instance_id: envelope.instance_id,
+                        session_id: envelope.session_id,
+                        parent_session_id: envelope.parent_session_id,
+                        turn_id: envelope.turn_id,
+                        parent_turn_id: envelope.parent_turn_id,
+                        harness: envelope.harness,
+                        source: envelope.source,
+                        data: envelope.data,
+                    },
+                ]);
+                projected = true;
+            }
+            catch {
+                /* projector failure is non-fatal; next agent-coord project run catches up */
+            }
+        }
+        return { envelope, projected };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/agents/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agent-coord` CLI entry point. Phase 1: every subcommand no-ops with a
+ * structured debug log. The one exception is `verdict`, which replies
+ * fail-open so adapters can already wire it up without affecting flow.
+ *
+ * Phase 2 replaces the no-op branches with real state projection + CLI
+ * handlers; Phase 4 flips the default so `harn agents …` shims through here.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/core/agents/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/core/agents/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}