harnery 0.36.0 → 0.38.0

package/src/commands/qa-verify.ts

@@ -0,0 +1,238 @@
+// `qa-verify <path>`: assess whether a qa-run result document is fresh
+// evidence for the invocation the caller has in mind. The assessment itself
+// is the pure assessQaRunEvidence contract; this command owns path
+// resolution (result file, run directory, or run parent via latest.json),
+// expectation collection from flags, and exit-code mapping.
+//
+// Toolkit tier: this module must not import src/core (layering check).
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { QA_RUN_LATEST_FILENAME, QA_RUN_RESULT_FILENAME } from "../lib/browser/qa-run.ts";
+import {
+  assessQaRunEvidence,
+  computeJobDigest,
+  type QaEvidenceAssessment,
+  type QaEvidenceExpectations,
+  validateQaRunJob,
+} from "../lib/browser/qa-run-contracts.ts";
+
+export interface QaVerifyOptions {
+  /** Exact run ID the evidence must carry (`--run-id`). */
+  runId?: string;
+  /** Revision the evidence must have tested (`--revision`). */
+  revision?: string;
+  /** Job file to reconstruct and digest-match (`--job`). */
+  job?: string;
+  /** Maximum age of completed_at, in minutes (`--max-age`). */
+  maxAge?: string;
+  /** Emit the assessment as JSON (`--json`). */
+  json?: boolean;
+}
+
+export interface QaVerifyDeps {
+  /** Evaluation instant for --max-age (ISO-8601). Default: current time. */
+  now?: string;
+}
+
+export interface QaVerifyOutcome {
+  /** 0 evidence fresh · 3 stale or unverifiable · 1 usage/unreadable/invalid job. */
+  exit: 0 | 1 | 3;
+  /** Present whenever the document was resolved and assessed. */
+  assessment?: QaEvidenceAssessment;
+  /** Absolute path of the result document that was (or would be) assessed. */
+  resultPath?: string;
+  /** Human-readable failure for exit-1 outcomes. */
+  error?: string;
+  /** Individual job-validation errors when --job failed validation. */
+  jobErrors?: string[];
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+type JsonRead = { ok: true; value: unknown } | { ok: false; error: string };
+
+function readJsonFile(path: string): JsonRead {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err: unknown) {
+    return { ok: false, error: `cannot read ${path}: ${describeError(err)}` };
+  }
+  try {
+    return { ok: true, value: JSON.parse(raw) };
+  } catch (err: unknown) {
+    return { ok: false, error: `${path} is not valid JSON: ${describeError(err)}` };
+  }
+}
+
+type PathResolution = { ok: true; path: string } | { ok: false; error: string };
+
+/** Resolve `<path>` to a result document: a file is the document itself; a
+ * directory is a run PARENT when it carries latest.json (follow the pointer's
+ * `result` path, relative to the directory) or a run directory when it
+ * carries the result file directly. */
+function resolveResultPath(inputPath: string): PathResolution {
+  const abs = resolve(inputPath);
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(abs);
+  } catch (err: unknown) {
+    return { ok: false, error: `cannot access ${abs}: ${describeError(err)}` };
+  }
+  if (stats.isFile()) return { ok: true, path: abs };
+  if (!stats.isDirectory()) {
+    return { ok: false, error: `${abs} is neither a file nor a directory` };
+  }
+  const pointerPath = join(abs, QA_RUN_LATEST_FILENAME);
+  if (existsSync(pointerPath)) {
+    const pointer = readJsonFile(pointerPath);
+    if (!pointer.ok) return pointer;
+    const record =
+      pointer.value && typeof pointer.value === "object" && !Array.isArray(pointer.value)
+        ? (pointer.value as Record<string, unknown>)
+        : {};
+    const rel = record.result;
+    if (typeof rel !== "string" || rel.length === 0) {
+      return { ok: false, error: `${pointerPath} carries no "result" path to follow` };
+    }
+    return { ok: true, path: resolve(abs, rel) };
+  }
+  const direct = join(abs, QA_RUN_RESULT_FILENAME);
+  if (existsSync(direct)) return { ok: true, path: direct };
+  return {
+    ok: false,
+    error:
+      `${abs} is a directory but contains neither ${QA_RUN_LATEST_FILENAME} ` +
+      `(expected for a run parent directory) nor ${QA_RUN_RESULT_FILENAME} ` +
+      "(expected for a run directory)",
+  };
+}
+
+/**
+ * Pure core of qa-verify: resolve `<path>` to a result document, collect the
+ * expectations the flags express, and assess. The commander action is a thin
+ * wrapper over this so the resolution and expectation paths test without a
+ * CLI harness.
+ */
+export function resolveAndAssess(
+  inputPath: string,
+  opts: QaVerifyOptions = {},
+  deps: QaVerifyDeps = {},
+): QaVerifyOutcome {
+  const resolved = resolveResultPath(inputPath);
+  if (!resolved.ok) return { exit: 1, error: resolved.error };
+  const resultPath = resolved.path;
+
+  const documentRead = readJsonFile(resultPath);
+  if (!documentRead.ok) return { exit: 1, error: documentRead.error, resultPath };
+  const document = documentRead.value;
+
+  // The directory the document was actually read from. assessQaRunEvidence
+  // compares it against the recorded run.out_dir, so a moved or copied
+  // result never verifies in its new home.
+  const expectations: QaEvidenceExpectations = { found_in_dir: dirname(resultPath) };
+  if (opts.runId !== undefined) expectations.run_id = opts.runId;
+  if (opts.revision !== undefined) expectations.tested_revision = opts.revision;
+  if (opts.maxAge !== undefined) {
+    const minutes = Number(opts.maxAge);
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+      return { exit: 1, error: "--max-age must be a positive number of minutes", resultPath };
+    }
+    expectations.max_age_ms = Math.round(minutes * 60_000);
+    if (deps.now !== undefined) expectations.now = deps.now;
+  }
+
+  if (opts.job !== undefined) {
+    const jobRead = readJsonFile(opts.job);
+    if (!jobRead.ok) return { exit: 1, error: jobRead.error, resultPath };
+    let jobDocument = jobRead.value;
+    if (jobDocument && typeof jobDocument === "object" && !Array.isArray(jobDocument)) {
+      // Reconstruct the EFFECTIVE job the way qa-run does: the invocation's
+      // target and mode are authoritative over the job file's, and the
+      // result document is the record of that invocation.
+      const resultRecord =
+        document && typeof document === "object" && !Array.isArray(document)
+          ? (document as Record<string, unknown>)
+          : {};
+      jobDocument = {
+        ...(jobDocument as Record<string, unknown>),
+        target: resultRecord.target,
+        mode: resultRecord.mode,
+      };
+    }
+    const validation = validateQaRunJob(jobDocument);
+    if (!validation.ok) {
+      return {
+        exit: 1,
+        error: `--job file ${opts.job} does not reconstruct a valid job for this result`,
+        jobErrors: validation.errors,
+        resultPath,
+      };
+    }
+    expectations.job_digest = computeJobDigest(validation.job);
+  }
+
+  const assessment = assessQaRunEvidence(document, expectations);
+  return { exit: assessment.fresh ? 0 : 3, assessment, resultPath };
+}
+
+export function registerQaVerifyCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("qa-verify <path>")
+    .description(
+      "Verify that a qa-run result is fresh evidence for a specific invocation: " +
+        "match its run identity (run_id, job digest, tested revision, age, and " +
+        "recorded output directory) against what the caller expects. Fail-closed: " +
+        "a document without a verifiable identity block is stale by definition.",
+    )
+    .option("--run-id <id>", "Exact run ID the evidence must carry.")
+    .option(
+      "--revision <sha>",
+      "Revision the evidence must have tested. A result whose revision source is " +
+        "unknown cannot satisfy this expectation.",
+    )
+    .option(
+      "--job <file>",
+      "Job document (JSON) to digest-match. Reconstructed the way qa-run builds the " +
+        "effective job: the result's target and mode overlay the file's before " +
+        "validation and digesting.",
+    )
+    .option("--max-age <minutes>", "Maximum age of the run's completed_at, in minutes.")
+    .option("--json", "Print the assessment (plus result_path) as JSON.")
+    .addHelpText(
+      "after",
+      "\n<path> may be a result file, a run directory (containing " +
+        `${QA_RUN_RESULT_FILENAME}), or a run parent directory (its ` +
+        `${QA_RUN_LATEST_FILENAME} pointer is followed).` +
+        "\n\nExit codes: 0 evidence fresh · 1 usage, unreadable input, or invalid job · " +
+        "3 evidence stale or unverifiable.",
+    )
+    .action((path: string, opts: QaVerifyOptions) => {
+      const outcome = resolveAndAssess(path, opts);
+      if (outcome.exit === 1 || !outcome.assessment) {
+        for (const message of outcome.jobErrors ?? []) emit.log(`job: ${message}`, "error");
+        emit.error({
+          code: "qa_verify_error",
+          message: outcome.error ?? "qa-verify could not assess the result",
+        });
+        process.exitCode = 1;
+        return;
+      }
+      const assessment = outcome.assessment;
+      if (opts.json) emit.data({ ...assessment, result_path: outcome.resultPath });
+      const runId = assessment.run?.run_id ?? "(no identity)";
+      const verdict = assessment.verdict ?? "(no verdict)";
+      emit.log(
+        `run ${runId}: verdict ${verdict} — evidence ${assessment.fresh ? "fresh" : "stale"} ` +
+          `(${outcome.resultPath})`,
+        assessment.fresh ? "info" : "warn",
+      );
+      for (const reason of assessment.reasons) emit.log(`stale: ${reason}`, "warn");
+      if (!assessment.fresh) process.exitCode = 3;
+    });
+}

package/src/commands/resources.ts

@@ -0,0 +1,38 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { sampleResources } from "../core/resources/index.ts";
+
+export function registerResourcesCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const resources = program
+    .command("resources")
+    .description("Observe local CPU and memory pressure by agent and process tree");
+
+  resources
+    .command("snapshot")
+    .description("Capture one machine and process-resource snapshot")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        emit.data(sampleResources(resolve(options.root ?? coordRoot(context))).snapshot);
+      } catch (error) {
+        fail(emit, "resource_snapshot_failed", error);
+      }
+    });
+}
+
+function coordRoot(context?: HarneryProgramContext): string {
+  return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+
+function fail(emit: EmitContext, code: string, error: unknown): void {
+  emit.error({
+    code,
+    message: error instanceof Error ? error.message : String(error),
+  });
+  emit.setExitCode(1);
+}