harnery 0.36.0 → 0.38.0

package/dist/commands/qa-verify.js

@@ -0,0 +1,180 @@
+// `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 { QA_RUN_LATEST_FILENAME, QA_RUN_RESULT_FILENAME } from "../lib/browser/qa-run.js";
+import { assessQaRunEvidence, computeJobDigest, validateQaRunJob, } from "../lib/browser/qa-run-contracts.js";
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function readJsonFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        return { ok: false, error: `cannot read ${path}: ${describeError(err)}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (err) {
+        return { ok: false, error: `${path} is not valid JSON: ${describeError(err)}` };
+    }
+}
+/** 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) {
+    const abs = resolve(inputPath);
+    let stats;
+    try {
+        stats = statSync(abs);
+    }
+    catch (err) {
+        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
+            : {};
+        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, opts = {}, deps = {}) {
+    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 = { 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
+                : {};
+            jobDocument = {
+                ...jobDocument,
+                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, emit) {
+    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, opts) => {
+        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/dist/commands/resources.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/commands/resources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG1E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAgBN"}

package/dist/commands/resources.js

@@ -0,0 +1,29 @@
+import { resolve } from "node:path";
+import { sampleResources } from "../core/resources/index.js";
+export function registerResourcesCommand(program, emit, context) {
+    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) => {
+        try {
+            emit.data(sampleResources(resolve(options.root ?? coordRoot(context))).snapshot);
+        }
+        catch (error) {
+            fail(emit, "resource_snapshot_failed", error);
+        }
+    });
+}
+function coordRoot(context) {
+    return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+function fail(emit, code, error) {
+    emit.error({
+        code,
+        message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+}

package/dist/commands/review-pack.d.ts

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

package/dist/commands/review-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-pack.d.ts","sourceRoot":"","sources":["../../src/commands/review-pack.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA4U1E,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAu6BN"}