@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/cli/explain.js

@@ -1,159 +0,0 @@
-import { stringify as stringifyYaml } from "yaml";
-import { buildRecordHint, queryLedgerByTag, } from "../policies/index.js";
-import { decisionSortKey, decodeLedgerContent, } from "../io/ledger-record.js";
-import { resolveReadSessionId, } from "../runtime/session-id.js";
-import { EX_FAIL, EX_USAGE, HarnessExitError } from "./exit-codes.js";
-import { loadManifest } from "./loader.js";
-function defaultFetcher(opts) {
-    return async (sessionId) => {
-        const { manifest } = loadManifest(opts);
-        const server = manifest.tools.mcp.find((m) => m.name === "grounding-mcp");
-        if (!server) {
-            return { kind: "degraded", reason: "grounding-mcp not declared in manifest" };
-        }
-        const command = Array.isArray(server.command)
-            ? server.command
-            : server.command.trim().split(/\s+/);
-        return queryLedgerByTag({
-            mcpCommand: command,
-            ...(server.env && { mcpEnv: server.env }),
-            sessionId,
-            timeoutMs: server.health?.timeout_ms ?? 5_000,
-        });
-    };
-}
-function decodeAll(entries) {
-    const out = [];
-    for (const entry of entries) {
-        const payload = decodeLedgerContent(entry.content);
-        if (!payload)
-            continue;
-        out.push({ entry, payload });
-    }
-    return out;
-}
-function selectLatestForPolicy(entries, policyName) {
-    const matches = decodeAll(entries).filter((d) => d.payload.name === policyName);
-    if (matches.length === 0)
-        return null;
-    matches.sort((a, b) => decisionSortKey(b.entry, b.payload) - decisionSortKey(a.entry, a.payload));
-    return matches[0];
-}
-function selectLatestAny(entries, decisionFilter) {
-    const matches = decodeAll(entries).filter((d) => decisionFilter === undefined || d.payload.outcome === decisionFilter);
-    if (matches.length === 0)
-        return null;
-    matches.sort((a, b) => decisionSortKey(b.entry, b.payload) - decisionSortKey(a.entry, a.payload));
-    return matches[0];
-}
-export async function explain(policyName, opts = {}) {
-    const { manifest } = loadManifest(opts);
-    if (opts.last) {
-        const sessionId = resolveReadSessionId(opts.sessionId, opts.sessionDiscovery);
-        const fetch = opts.fetchLedger ?? defaultFetcher(opts);
-        const result = await fetch(sessionId);
-        if (result.kind === "degraded") {
-            throw new HarnessExitError(`cannot read audit log: ${result.reason}`, EX_FAIL);
-        }
-        const latest = selectLatestAny(result.entries, opts.decisionFilter);
-        if (!latest) {
-            const filterSuffix = opts.decisionFilter ? ` with outcome \`${opts.decisionFilter}\`` : "";
-            throw new HarnessExitError(`no recorded policy decisions${filterSuffix} for session \`${sessionId}\`; the ledger may be empty or grounding-mcp is unreachable`, EX_FAIL);
-        }
-        return { output: renderTrace(latest, manifest, sessionId, opts.json) };
-    }
-    if (policyName === undefined) {
-        throw new HarnessExitError("policy name is required (or pass --last to trace the most recent decision)", EX_USAGE);
-    }
-    const policy = manifest.policies.find((p) => p.name === policyName);
-    if (!policy) {
-        const available = manifest.policies.map((p) => p.name).join(", ") || "(none)";
-        throw new HarnessExitError(`no policy named "${policyName}" declared; available: ${available}`, EX_USAGE);
-    }
-    if (!opts.trace) {
-        // `operator_only: true` policies (task 2cc73f55) declare no
-        // `requires:` at all: there is no ledger contract to show, and no
-        // hint to build — the policy is an unconditional deny, full stop.
-        const projection = {
-            name: policy.name,
-            description: policy.description,
-            trigger: policy.trigger,
-            ...(policy.requires !== undefined && { requires: policy.requires }),
-            // toSatisfy mirrors the deny-time hint surfaced by `harness policy
-            // intercept`, so a contributor reading the policy under `harness
-            // explain <policy>` sees the same contract a blocked operator
-            // sees in Claude Code. Built from the un-substituted ledger_tag
-            // template (e.g. `review:${PR_NUMBER}`) so it reads as the policy
-            // contract, not a specific event's instance.
-            ...(policy.requires !== undefined && {
-                toSatisfy: buildRecordHint(policy.requires, policy.requires.ledger_tag),
-            }),
-            ...(policy.operator_only === true && {
-                toSatisfy: "none — operator_only: true is an unconditional deny; no in-session evidence can ever satisfy it",
-            }),
-            hook: policy.hook,
-            enforcement: policy.enforcement,
-            note: "run with --trace to see the last evaluation's full decision trail",
-        };
-        const output = opts.json
-            ? `${JSON.stringify(projection, null, 2)}\n`
-            : stringifyYaml(projection, { lineWidth: 0 });
-        return { output };
-    }
-    const sessionId = resolveReadSessionId(opts.sessionId, opts.sessionDiscovery);
-    const fetch = opts.fetchLedger ?? defaultFetcher(opts);
-    const result = await fetch(sessionId);
-    if (result.kind === "degraded") {
-        throw new HarnessExitError(`cannot read audit log: ${result.reason}`, EX_FAIL);
-    }
-    const latest = selectLatestForPolicy(result.entries, policyName);
-    if (!latest) {
-        throw new HarnessExitError(`no recorded evaluations for policy \`${policyName}\` in session \`${sessionId}\`; ` +
-            `the policy may not have fired yet, grounding-mcp is unreachable, or the ` +
-            `decisions landed under a different session (pass --session <id>)`, EX_FAIL);
-    }
-    return { output: renderTrace(latest, manifest, sessionId, opts.json) };
-}
-function renderTrace(latest, manifest, sessionId, json) {
-    const policy = manifest.policies.find((p) => p.name === latest.payload.name);
-    const trigger = policy?.trigger;
-    const projection = {
-        name: latest.payload.name,
-        decision: latest.payload.outcome,
-        enforcement: latest.payload.enforcement,
-        reason: latest.payload.reason,
-        ledgerTag: latest.payload.ledgerTag,
-        evaluatedAt: latest.payload.evaluatedAt,
-        triggerMatched: {
-            event: trigger?.event ?? "(unknown: policy not declared in current manifest)",
-            ...(trigger?.match !== undefined && { match: trigger.match }),
-            ...(trigger?.bash_match !== undefined && { bashMatch: trigger.bash_match }),
-        },
-        ...(latest.payload.risk && { classifier: latest.payload.risk }),
-        ...(latest.payload.environment && {
-            environment: latest.payload.environment,
-        }),
-        extract: latest.payload.extractValues,
-        ...(latest.payload.requiresEval && { requiresEval: latest.payload.requiresEval }),
-        ...(policy?.requires !== undefined && {
-            toSatisfy: buildRecordHint(policy.requires, latest.payload.ledgerTag),
-        }),
-        // operator_only: true (task 2cc73f55) — no requires: to build a hint
-        // from; the policy is an unconditional deny.
-        ...(policy?.operator_only === true && {
-            toSatisfy: "none — operator_only: true is an unconditional deny; no in-session evidence can ever satisfy it",
-        }),
-        // M7: surface the fail-closed unclassified flag in the trace so an
-        // operator can distinguish a real critical-severity deny from a
-        // fail-closed unclassified one via `explain --trace [--json]`.
-        // Absent when the payload lacks the field (pre-M7 rows or genuine hits).
-        ...(latest.payload.whenUnclassifiedFallback === true && {
-            whenUnclassifiedFallback: true,
-        }),
-        ledgerQuery: { verb: "ledger_summary", sessionId },
-    };
-    return json
-        ? `${JSON.stringify(projection, null, 2)}\n`
-        : stringifyYaml(projection, { lineWidth: 0 });
-}
-//# sourceMappingURL=explain.js.map

package/dist/cli/explain.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/cli/explain.ts"],"names":[],"mappings":"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"}

package/dist/cli/gc/index.d.ts

@@ -1,63 +0,0 @@
-import { type LoaderOptions } from "../loader.js";
-export declare const DEFAULT_RETENTION_DAYS = 30;
-export interface GcOptions extends LoaderOptions {
-    /** Artifacts older than this many days are candidates. Default 30. */
-    retentionDays?: number;
-    /** Delete when true; pure listing otherwise (the default). */
-    apply?: boolean;
-    /** Test seam: reports directory (default: env / manifest-anchored). */
-    reportsDir?: string;
-    /** Test seam: harness.generated directory (default: manifest-anchored). */
-    generatedDir?: string;
-    /** Test seam: clock anchor. */
-    now?: Date;
-}
-export type GcCategory = "report" | "parse-error" | "approval-marker" | "delegation" | "permission-mode-observation" | "in-flight-record";
-export interface GcCandidate {
-    filePath: string;
-    category: GcCategory;
-    /** Why this file aged out (status + age), for the listing UI. */
-    reason: string;
-}
-/**
- * A file gc could not read or parse (a delegation or in-flight record, or a
- * report entry that is oversized, not a regular file or unreadable): reported,
- * never a deletion candidate.
- */
-export interface GcUnparseable {
-    filePath: string;
-    category: GcCategory;
-    reason: string;
-}
-export interface GcResult {
-    retentionDays: number;
-    cutoffIso: string;
-    reportsDir: string;
-    /**
-     * null when the parse-errors sweep was skipped because `reportsDir`
-     * does not have the conventional `.understanding-gate/reports` shape
-     * (a custom `UNDERSTANDING_GATE_REPORT_DIR` pointing elsewhere would
-     * otherwise make "the sibling named parse-errors" an unrelated
-     * directory and gc would age out a stranger's files).
-     */
-    parseErrorsDir: string | null;
-    approvalsDir: string;
-    delegationsDir: string;
-    adoptionLedgerDir: string;
-    permissionModeObservationsDir: string;
-    inflightRecordsDir: string;
-    candidates: GcCandidate[];
-    /** Files inspected but left in place because they could not be read or parsed (delegations, in-flight records, unreadable report entries). */
-    unparseable: GcUnparseable[];
-    /** Files actually deleted (apply mode only). */
-    removed: string[];
-    /** Per-file deletion failures (apply mode only); never silent. */
-    failures: Array<{
-        filePath: string;
-        reason: string;
-    }>;
-    /** Count of artifacts inspected but kept (fresh, non-terminal, or unparseable). */
-    keptCount: number;
-    applied: boolean;
-}
-export declare function gc(opts?: GcOptions): GcResult;