@gethmy/harness 1.0.0

package/src/cli.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * harmony-harness stage run --card <id> --stage <id> --workspace <id>
+ *                           --repo <path> --session <id>
+ *
+ * Prints one JSON object per motor event to stdout, newline delimited, then a
+ * final JSON result object. A driver reads these lines; a human reads a
+ * driver's rendering of them. The motor writes no prose — everything
+ * diagnostic goes to the log on stderr.
+ *
+ * This file is the wiring, and only the wiring: the decidable rules (argument
+ * validation, the fail-loud stage check, the prompt) live in `stage-cli.ts`
+ * where they are testable without a live API.
+ *
+ * What the motor reads from Harmony here is deliberately small: the ONE card it
+ * was invoked for, and only that card's `current_stage` / `playbook_id` /
+ * `playbook_version` (see harmony-client.ts). That is what lets it resolve the
+ * PINNED stage definition whose gate it must collect evidence against. It reads
+ * no other card, forms no verdict, and advances nothing.
+ */
+import {
+  type GateEvidenceContext,
+  gateEvaluate,
+  type PlaybookVersionDef,
+  toStageGateEvidenceInsert,
+} from "@harmony/shared";
+import type { PlaybookMetricDef } from "./exec-types.js";
+import {
+  buildGateCollectorRegistry,
+  collectGateEvidence,
+} from "./gate-collectors.js";
+import { HarmonyClient, readClientConfig } from "./harmony-client.js";
+import { log } from "./log.js";
+import { place, remove, runHeldOracle } from "./oracle.js";
+import { SdkAgentRunner } from "./sdk-agent-runner.js";
+import {
+  assertCardOnStage,
+  assertStageIsAgentRunnable,
+  buildStagePrompt,
+  buildStageRunnerConfig,
+  parseMetricsAllowlist,
+  parseStageRunArgs,
+  resolvePinnedStage,
+  STAGE_RUN_USAGE,
+} from "./stage-cli.js";
+import { runStage, type StageRunRequest } from "./stage-run.js";
+
+const TAG = "cli";
+
+/**
+ * Wall-clock cap for the `build_green` gate's build and lint steps. The motor
+ * holds no operator config of its own yet (the daemon's `AgentConfig` supplies
+ * one on its side), so this is the motor's own default until a driver passes
+ * one in — deliberately generous for a cold worktree, and never unbounded.
+ */
+const GATE_VERIFICATION_TIMEOUT_MS = 600_000;
+
+/**
+ * Run the stage's subagent to completion. The launch decides the role, the
+ * environment and the tool denies (runner.ts); `envKeysDroppedByLaunch` turns
+ * the launch's omissions into the DELETE the spawned child needs — omitting a
+ * key would not remove it, because the child's environment is rebuilt from the
+ * motor's own `process.env`.
+ *
+ * The subagent's own events are diagnostics, not the motor's protocol: stdout
+ * carries the newline-delimited motor events a driver parses, so these go to
+ * the log instead.
+ */
+async function runRole(
+  request: StageRunRequest,
+  prompt: string,
+): Promise<void> {
+  // `buildStageRunnerConfig` owns the role's env strip and tool deny — see
+  // stage-cli.ts for why they live behind a tested seam rather than inline here.
+  const launch = buildStageRunnerConfig({
+    role: request.role,
+    prompt,
+    repoPath: request.repoPath,
+    parentEnv: process.env,
+  });
+  const runner = new SdkAgentRunner(launch.config);
+
+  log.info(
+    TAG,
+    `Running stage ${request.stageId} as role ${launch.role ?? "(none — fail-closed)"}`,
+  );
+  for await (const event of runner.start({
+    // The Harmony agent-session id the runner LABELS its events with. It never
+    // enters the subagent's context: the prompt is built without it, and
+    // `RoleLaunch` has no field for it.
+    sessionId: request.sessionId,
+    cardId: request.cardId,
+    workspaceId: request.workspaceId,
+    prompt: launch.prompt,
+    cwd: launch.cwd,
+  })) {
+    if (event.kind === "error") {
+      log.warn(TAG, `subagent error: ${event.payload.message}`);
+    } else {
+      log.debug(TAG, `subagent ${event.kind}`);
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  const parsed = parseStageRunArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.message}\n${STAGE_RUN_USAGE}\n`);
+    process.exit(2);
+  }
+  const { cardId, stageId, workspaceId, repoPath, sessionId, metricsPath } =
+    parsed.args;
+
+  // The driver's metric allowlist for `custom` gates (--metrics, optional).
+  // Read + validated BEFORE anything runs: a driver that passed the flag wants
+  // it applied, so an unreadable file refuses the run instead of degrading to
+  // the empty allowlist. Absent flag ⇒ {} — a `custom` gate then blocks with
+  // the legible "metric not declared" reason, exactly as before.
+  let driverMetrics: Record<string, unknown> = {};
+  if (metricsPath !== null) {
+    const { readFileSync } = await import("node:fs");
+    driverMetrics = parseMetricsAllowlist(
+      readFileSync(metricsPath, "utf8"),
+      metricsPath,
+    );
+  }
+
+  const client = new HarmonyClient(readClientConfig(process.env));
+
+  // Fail loud, collect nothing, when the driver and the board disagree about
+  // which stage this card is on. See `assertCardOnStage`.
+  const card = await client.fetchStageCard(cardId);
+  assertCardOnStage(stageId, card);
+
+  // The PINNED stage definition, read from the frozen `playbook_versions`
+  // snapshot — never live `playbooks.steps`, so editing a playbook cannot
+  // retroactively change an in-flight card.
+  //
+  // The stage def is resolved ONCE and the gate is derived from it, rather than
+  // reading the gate with `resolveStageGate` and taking the stage off that.
+  // `resolveStageGate` answers null for "this stage declares no gate" and for
+  // "the pin is unusable" alike, which made an ungated stage silently lose both
+  // its declared `role` and its `entry_action` prompt. Here the two stay
+  // distinct: a stage with no gate still runs with everything else it declares,
+  // and only an unusable PIN refuses.
+  //
+  // A refusal is deliberate, and stricter than the old path: running a stage
+  // whose definition cannot be read would run the subagent with a fail-closed
+  // role, collect nothing, and record nothing — an ungated run that looks
+  // successful. Refusing before anything starts is the honest outcome.
+  if (!card.playbook_id || card.playbook_version == null) {
+    throw new Error(
+      `card ${cardId} carries no playbook pin (playbook_id / playbook_version) — refusing to run a stage whose definition cannot be read`,
+    );
+  }
+  const { version } = await client.request<{ version: PlaybookVersionDef }>(
+    "GET",
+    `/playbooks/${encodeURIComponent(card.playbook_id)}/versions/${card.playbook_version}`,
+  );
+  // `stageId` and the card's `current_stage` are already known to agree —
+  // `assertCardOnStage` above refused the run otherwise.
+  const pinned = resolvePinnedStage(version, stageId);
+  if (!pinned.ok) {
+    throw new Error(
+      `refusing to run stage "${stageId}" for card ${cardId}: ${pinned.reason}`,
+    );
+  }
+
+  // Refuse a human-owned stage HERE — after the pinned def is readable (that is
+  // where `owner` lives) and before the prompt, the subagent, or any write. See
+  // `assertStageIsAgentRunnable`: the driver, not the motor, decides to wait on
+  // a person, and the motor's job is to make running their stage impossible by
+  // accident.
+  assertStageIsAgentRunnable(pinned.stage);
+
+  const prompt = buildStagePrompt({ cardId, stageId, stage: pinned.stage });
+
+  const request: StageRunRequest = {
+    cardId,
+    stageId,
+    workspaceId,
+    repoPath,
+    sessionId,
+    role: pinned.stage.role ?? null,
+  };
+
+  const result = await runStage(request, {
+    // Already resolved above, because the stage's ROLE and prompt come off the
+    // same pinned def and have to be known before the subagent launches.
+    resolveGate: async () => pinned.gate,
+    runRole: (req) => runRole(req, prompt),
+    collect: async (req, gate) => {
+      const registry = buildGateCollectorRegistry({
+        build: {
+          worktreePath: req.repoPath,
+          buildTimeout: GATE_VERIFICATION_TIMEOUT_MS,
+          lintTimeout: GATE_VERIFICATION_TIMEOUT_MS,
+        },
+        // The metric allowlist is the DRIVER's, passed via --metrics — the
+        // motor still holds no operator config of its own. Without the flag
+        // this is {} and a `custom` gate reports "metric X is not declared",
+        // naming the config key to edit — a far better hold reason than the
+        // dispatcher's generic "no collector for kind custom". Both are
+        // `blocked`; only one tells the operator what to do about it.
+        // The cast mirrors how the daemon's own JSON config reaches the same
+        // collector: per-declaration validation is the collector's job and it
+        // fails closed with the key name on anything malformed.
+        command: {
+          worktreePath: req.repoPath,
+          metrics: driverMetrics as Record<string, PlaybookMetricDef>,
+        },
+        oracle: {
+          repoPath: req.repoPath,
+          sessionId: req.sessionId,
+          fetchOracle: (oracleCardId, oracleStageId, oracleSessionId) =>
+            client.fetchOracle(oracleCardId, oracleStageId, oracleSessionId),
+          place,
+          remove,
+          run: runHeldOracle,
+        },
+      });
+      return await collectGateEvidence(registry, {
+        cardId: req.cardId,
+        stageId: req.stageId,
+        gate,
+        workspaceId: req.workspaceId,
+      });
+    },
+  });
+
+  for (const event of result.events) {
+    process.stdout.write(`${JSON.stringify(event)}\n`);
+  }
+
+  if (result.evidence && pinned.gate) {
+    const context: GateEvidenceContext = {
+      cardId,
+      stageId,
+      gate: pinned.gate,
+      workspaceId,
+    };
+    // The stored row IS the evidence, and the human-advance edge re-evaluates
+    // it with this same pure function — that is the no-drift guarantee.
+    // `gateEvaluate` runs here ONLY to print a verdict for a human reader; the
+    // motor must not become a second authority on pass or fail. The write comes
+    // first, so a printed `gate_verdict` always implies a persisted row.
+    const evaluation = gateEvaluate(pinned.gate, result.evidence);
+    await client.recordStageGateEvidence(
+      toStageGateEvidenceInsert(context, result.evidence),
+    );
+    process.stdout.write(
+      `${JSON.stringify({ type: "gate_verdict", passed: evaluation.passed, findings: evaluation.findings })}\n`,
+    );
+  }
+
+  process.stdout.write(`${JSON.stringify({ type: "result", ...result })}\n`);
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  // `fetch` reports a transport failure as a bare "fetch failed" and puts the
+  // real reason (ECONNREFUSED, DNS, TLS) on `cause`. Fold it in — a driver that
+  // only sees "fetch failed" cannot tell a wrong URL from a down API.
+  const cause =
+    err instanceof Error && err.cause instanceof Error
+      ? ` (${err.cause.message})`
+      : "";
+  process.stderr.write(
+    `${JSON.stringify({ type: "error", message: `${message}${cause}` })}\n`,
+  );
+  process.exit(1);
+});