@unbrained/pm-cli 2026.8.16 → 2026.8.17

package/dist/sdk/governance/assurance-action.js

@@ -1,7 +1,14 @@
+/**
+ * @module sdk/assurance-action
+ *
+ * Normalizes the assurance action vocabulary once for CLI, SDK, and MCP hosts.
+ */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="06d21369-1339-54b2-8d78-442f02e24cef")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="57c12241-812d-5db6-9a07-ca256152b130")}catch(e){}}();
+import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { stableStringify } from "../../core/shared/serialization.js";
 import { ASSURANCE_GATE_TRIGGERS, evaluateAssuranceGate, getAssuranceDeclaration, listAssuranceDeclarations, listAssuranceVerdicts, putAssuranceDeclaration, recordAssuranceVerdict, removeAssuranceDeclaration, } from "./assurance.js";
 import { ASSURANCE_PRESET_IDS, acceptAssuranceProposals, applyAssurancePreset, createAssurancePreset, deriveAssuranceProposals, promoteAssuranceAssertion, } from "./assurance-presets.js";
 import { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
@@ -9,6 +16,9 @@ import { normalizeAssuranceEvaluation, normalizeAssuranceMutation, } from "./ass
 import { createAssuranceWorkspaceContext, } from "./assurance-runtime.js";
 import { resolvePmRoot } from "../runtime-primitives.js";
 import { parseRuntimeInteger, readRuntimeString } from "../runtime-input.js";
+import { analyzeDefectChangeRisk, buildDefectRecurrenceIndex, parseDefectChangeRiskRequest, } from "./defect-recurrence.js";
+import { defectRecurrenceItemSignals } from "./defect-recurrence-signals.js";
+let riskIndexCache;
 /** Assurance registry and evaluation verbs shared by every transport. */
 export const ASSURANCE_ACTIONS = [
     "list",
@@ -21,6 +31,7 @@ export const ASSURANCE_ACTIONS = [
     "apply",
     "derive",
     "promote",
+    "risk",
 ];
 /** Assurance declaration kinds shared by every transport. */
 export const ASSURANCE_DECLARATION_KINDS = [
@@ -205,6 +216,87 @@ async function runGateAction(input, pmRoot, runtime) {
     }
     return verdict;
 }
+/** Normalize a request-validation failure into the shared usage-error contract. */
+function throwRiskUsageError(error) {
+    if (error instanceof PmCliError)
+        throw error;
+    throw new PmCliError(error instanceof Error
+        ? error.message
+        : "assurance risk request is invalid", EXIT_CODE.USAGE);
+}
+/** Parse JSON or object risk definitions without wrapping workspace failures. */
+function parseRiskActionRequest(input) {
+    if (input.limit !== undefined) {
+        throw new PmCliError("assurance risk does not accept --limit; set limit inside the risk definition", EXIT_CODE.USAGE);
+    }
+    let definition = input.definition;
+    if (typeof definition === "string") {
+        try {
+            definition = JSON.parse(definition);
+        }
+        catch (error) {
+            throw new PmCliError("assurance risk definition must be valid JSON", EXIT_CODE.USAGE, { reason: error instanceof Error ? error.message : "invalid_json" });
+        }
+    }
+    try {
+        return parseDefectChangeRiskRequest(definition);
+    }
+    catch (error) {
+        return throwRiskUsageError(error);
+    }
+}
+/** Derive the exact sparse replacement and deletion set for a cached index. */
+function changedRiskItemIds(cached, current) {
+    const changed = new Set();
+    for (const [itemId, itemFingerprint] of current) {
+        if (cached.item_fingerprints.get(itemId) !== itemFingerprint)
+            changed.add(itemId);
+    }
+    for (const itemId of cached.item_fingerprints.keys()) {
+        if (!current.has(itemId))
+            changed.add(itemId);
+    }
+    return changed;
+}
+/** Build and retain a safely invalidated bounded process-local recurrence index. */
+function buildCachedRiskIndex(pmRoot, request, items) {
+    const policySerialized = stableStringify(request.policy);
+    const cached = riskIndexCache?.pm_root === pmRoot ? riskIndexCache : undefined;
+    const itemFingerprints = new Map(items.map((item) => [
+        item.id,
+        createHash("sha256")
+            .update(stableStringify(defectRecurrenceItemSignals(item)))
+            .digest("hex"),
+    ]));
+    const reusable = cached?.policy_serialized === policySerialized ? cached : undefined;
+    const changed = reusable
+        ? changedRiskItemIds(reusable, itemFingerprints)
+        : new Set();
+    const index = buildDefectRecurrenceIndex(request.policy, reusable ? items.filter((item) => changed.has(item.id)) : items, reusable
+        ? { previous_index: reusable.index, changed_item_ids: [...changed] }
+        : {});
+    riskIndexCache = {
+        pm_root: pmRoot,
+        policy_serialized: policySerialized,
+        item_fingerprints: itemFingerprints,
+        index,
+    };
+    return index;
+}
+/** Evaluate one serialized change-risk request against authoritative PM metadata. */
+async function runRiskAction(input, pmRoot) {
+    const request = parseRiskActionRequest(input);
+    const context = await createAssuranceWorkspaceContext(pmRoot, {
+        include_history: false,
+        resolve_tree: false,
+    });
+    try {
+        return analyzeDefectChangeRisk(buildCachedRiskIndex(pmRoot, request, context.items), request.change, { cursor: request.cursor, limit: request.limit });
+    }
+    catch (error) {
+        return throwRiskUsageError(error);
+    }
+}
 /** Execute one assurance request through the public assurance SDK primitives. */
 export async function runAssuranceAction(input, global = {}, runtime = {}) {
     const action = parseAction(input.action);
@@ -221,6 +313,9 @@ export async function runAssuranceAction(input, global = {}, runtime = {}) {
     if (action === "run") {
         return runGateAction(input, pmRoot, runtime);
     }
+    if (action === "risk") {
+        return runRiskAction(input, pmRoot);
+    }
     const kind = parseKind(input.kind);
     if (action === "list")
         return listAssuranceDeclarations(pmRoot, kind);
@@ -282,4 +377,4 @@ export function runAssuranceDispatch(args, options, global) {
     }, global);
 }
 //# sourceMappingURL=assurance-action.js.map
-//# debugId=06d21369-1339-54b2-8d78-442f02e24cef
+//# debugId=57c12241-812d-5db6-9a07-ca256152b130

package/dist/sdk/governance/boundary-fixtures.d.ts

@@ -0,0 +1,86 @@
+/** Evidence source accepted for a captured boundary sample. */
+export declare const BOUNDARY_FIXTURE_CAPTURE_SOURCES: readonly ["captured_redacted", "captured_verbatim"];
+/** Captured boundary evidence source. */
+export type BoundaryFixtureCaptureSource = (typeof BOUNDARY_FIXTURE_CAPTURE_SOURCES)[number];
+/** Inventory record backed by a committed captured sample. */
+export interface CapturedBoundaryRecord {
+    /** Stable external-boundary identifier. */
+    id: string;
+    /** Production component that emits or obtains the value. */
+    producer: string;
+    /** Production component that parses or consumes the value. */
+    consumer: string;
+    /** Concise serialized-format description. */
+    format: string;
+    /** Relative path to a committed JSON fixture. */
+    fixture_path: string;
+}
+/** Inventory record explicitly waived until a bounded expiry. */
+export interface WaivedBoundaryRecord {
+    /** Stable external-boundary identifier. */
+    id: string;
+    /** Production component that emits or obtains the value. */
+    producer: string;
+    /** Production component that parses or consumes the value. */
+    consumer: string;
+    /** Concise serialized-format description. */
+    format: string;
+    /** Concrete reason a safe captured fixture is not available. */
+    waiver_reason: string;
+    /** Accountable PM item or team. */
+    waiver_owner: string;
+    /** ISO timestamp after which the waiver fails closed. */
+    waiver_expires_at: string;
+}
+/** One externally generated or consumed boundary inventory entry. */
+export type BoundaryInventoryRecord = CapturedBoundaryRecord | WaivedBoundaryRecord;
+/** Versioned project boundary inventory. */
+export interface BoundaryFixtureRegistry {
+    /** Serialized registry format. */
+    version: 1;
+    /** Human-readable statement of what source surfaces were inventoried. */
+    inventory_scope: string;
+    /** Captured or explicitly waived boundary records. */
+    boundaries: BoundaryInventoryRecord[];
+}
+/** Required shape of a committed captured boundary sample. */
+export interface BoundaryFixtureSample {
+    /** Serialized fixture format. */
+    version: 1;
+    /** Inventory boundary id proved by this sample. */
+    boundary_id: string;
+    /** Captured evidence classification; self-generated is intentionally absent. */
+    capture_source: BoundaryFixtureCaptureSource;
+    /** Where and how the original value was observed. */
+    capture_provenance: string;
+    /** Redactions applied before committing the sample. */
+    redactions: string[];
+    /** Redacted external input. */
+    input: unknown;
+    /** Redacted observed boundary value. */
+    observed: unknown;
+}
+/** Stable boundary-fixture governance finding. */
+export interface BoundaryFixtureFinding {
+    /** Boundary id, or registry for registry-wide defects. */
+    boundary_id: string;
+    /** Machine-readable failure kind. */
+    kind: "invalid_registry" | "duplicate_boundary" | "invalid_boundary" | "missing_fixture" | "invalid_fixture" | "fixture_boundary_mismatch" | "unsafe_fixture" | "invalid_waiver" | "expired_waiver";
+    /** Actionable explanation. */
+    detail: string;
+}
+/** Complete captured-boundary governance report. */
+export interface BoundaryFixtureReport {
+    /** Whether every inventoried boundary has safe current evidence. */
+    ok: boolean;
+    /** Total inventoried boundaries. */
+    boundary_count: number;
+    /** Boundaries backed by committed captured samples. */
+    captured_count: number;
+    /** Boundaries carrying live explicit waivers. */
+    waived_count: number;
+    /** Stable sorted failures. */
+    findings: BoundaryFixtureFinding[];
+}
+/** Validate an untrusted boundary registry and its already-loaded JSON samples. */
+export declare function evaluateBoundaryFixtures(registry: BoundaryFixtureRegistry, fixtures: Readonly<Record<string, unknown>>, now?: Date): BoundaryFixtureReport;

package/dist/sdk/governance/boundary-fixtures.js

@@ -0,0 +1,201 @@
+/**
+ * @module sdk/boundary-fixtures
+ *
+ * Validates captured external-boundary samples and explicit time-bounded
+ * waivers without allowing production code to manufacture its own fixtures.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3edb1f4f-d26e-51a8-b62a-caffdd3ac44b")}catch(e){}}();
+import { isRfc3339DateTime } from "../../core/shared/time.js";
+/** Evidence source accepted for a captured boundary sample. */
+export const BOUNDARY_FIXTURE_CAPTURE_SOURCES = [
+    "captured_redacted",
+    "captured_verbatim",
+];
+const SECRET_OR_PRIVATE_PATTERNS = [
+    { label: "home directory", pattern: /(?:\/home\/|\/Users\/)[^/\s"']+/u },
+    { label: "GitHub token", pattern: /\b(?:gh[oprsu]_[A-Za-z0-9_]{20,})\b/u },
+    { label: "npm token", pattern: /\bnpm_[A-Za-z0-9]{20,}\b/u },
+    {
+        label: "private key",
+        pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/u,
+    },
+];
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function validateSample(boundary, sample) {
+    if (typeof sample !== "object" || sample === null || Array.isArray(sample)) {
+        return [
+            {
+                boundary_id: boundary.id,
+                kind: "invalid_fixture",
+                detail: `${boundary.fixture_path} must contain a JSON object.`,
+            },
+        ];
+    }
+    const fixture = sample;
+    const findings = [];
+    if (fixture.boundary_id !== boundary.id) {
+        findings.push({
+            boundary_id: boundary.id,
+            kind: "fixture_boundary_mismatch",
+            detail: `${boundary.fixture_path} names ${String(fixture.boundary_id)} instead of ${boundary.id}.`,
+        });
+    }
+    if (fixture.version !== 1 ||
+        !BOUNDARY_FIXTURE_CAPTURE_SOURCES.includes(fixture.capture_source) ||
+        !nonEmpty(fixture.capture_provenance) ||
+        !Array.isArray(fixture.redactions) ||
+        !fixture.redactions.every(nonEmpty) ||
+        !("input" in fixture) ||
+        !("observed" in fixture)) {
+        findings.push({
+            boundary_id: boundary.id,
+            kind: "invalid_fixture",
+            detail: `${boundary.fixture_path} lacks captured provenance, redaction metadata, input, or observed output.`,
+        });
+    }
+    const serialized = JSON.stringify(sample);
+    for (const sensitive of SECRET_OR_PRIVATE_PATTERNS) {
+        if (sensitive.pattern.test(serialized)) {
+            findings.push({
+                boundary_id: boundary.id,
+                kind: "unsafe_fixture",
+                detail: `${boundary.fixture_path} contains a possible ${sensitive.label}.`,
+            });
+        }
+    }
+    return findings;
+}
+/** Evaluate the independent validity and expiry rules for one waiver record. */
+function evaluateBoundaryWaiver(boundary, nowMs) {
+    const expiresAt = Date.parse(boundary.waiver_expires_at);
+    const validWaiver = nonEmpty(boundary.waiver_reason) &&
+        nonEmpty(boundary.waiver_owner) &&
+        boundary.waiver_expires_at.endsWith("Z") &&
+        isRfc3339DateTime(boundary.waiver_expires_at) &&
+        Number.isFinite(expiresAt);
+    return {
+        captured: 0,
+        waived: validWaiver && expiresAt >= nowMs ? 1 : 0,
+        findings: !validWaiver
+            ? [
+                {
+                    boundary_id: boundary.id,
+                    kind: "invalid_waiver",
+                    detail: `Boundary ${boundary.id} waiver requires reason, owner, and an RFC 3339 UTC expiry.`,
+                },
+            ]
+            : expiresAt < nowMs
+                ? [
+                    {
+                        boundary_id: boundary.id,
+                        kind: "expired_waiver",
+                        detail: `Boundary ${boundary.id} waiver expired at ${boundary.waiver_expires_at}.`,
+                    },
+                ]
+                : [],
+    };
+}
+function evaluateBoundaryRecord(boundary, fixtures, nowMs) {
+    if (!nonEmpty(boundary.id) ||
+        !nonEmpty(boundary.producer) ||
+        !nonEmpty(boundary.consumer) ||
+        !nonEmpty(boundary.format)) {
+        const boundaryId = nonEmpty(boundary.id) ? boundary.id : "unknown";
+        return {
+            captured: 0,
+            waived: 0,
+            findings: [
+                {
+                    boundary_id: boundaryId,
+                    kind: "invalid_boundary",
+                    detail: "Each boundary requires non-empty id, producer, consumer, and format.",
+                },
+            ],
+        };
+    }
+    if ("fixture_path" in boundary) {
+        const sample = fixtures[boundary.fixture_path];
+        const findings = nonEmpty(boundary.fixture_path) && boundary.fixture_path in fixtures
+            ? validateSample(boundary, sample)
+            : [
+                {
+                    boundary_id: boundary.id,
+                    kind: "missing_fixture",
+                    detail: `Boundary ${boundary.id} fixture ${String(boundary.fixture_path)} is missing.`,
+                },
+            ];
+        return {
+            captured: findings.length === 0 ? 1 : 0,
+            waived: 0,
+            findings,
+        };
+    }
+    return evaluateBoundaryWaiver(boundary, nowMs);
+}
+/** Validate an untrusted boundary registry and its already-loaded JSON samples. */
+export function evaluateBoundaryFixtures(registry, fixtures, now = new Date()) {
+    const findings = [];
+    if (registry.version !== 1 ||
+        !nonEmpty(registry.inventory_scope) ||
+        !Array.isArray(registry.boundaries)) {
+        return {
+            ok: false,
+            boundary_count: 0,
+            captured_count: 0,
+            waived_count: 0,
+            findings: [
+                {
+                    boundary_id: "registry",
+                    kind: "invalid_registry",
+                    detail: "Boundary registry requires version 1, inventory_scope, and boundaries.",
+                },
+            ],
+        };
+    }
+    const ids = new Set();
+    let capturedCount = 0;
+    let waivedCount = 0;
+    for (const candidate of registry.boundaries) {
+        if (typeof candidate !== "object" ||
+            candidate === null ||
+            Array.isArray(candidate)) {
+            findings.push({
+                boundary_id: "unknown",
+                kind: "invalid_boundary",
+                detail: "Each boundary must be a JSON object.",
+            });
+            continue;
+        }
+        const boundary = candidate;
+        const boundaryId = nonEmpty(boundary.id) ? boundary.id : undefined;
+        if (boundaryId !== undefined && ids.has(boundaryId)) {
+            findings.push({
+                boundary_id: boundaryId,
+                kind: "duplicate_boundary",
+                detail: `Boundary ${boundaryId} is inventoried more than once.`,
+            });
+            continue;
+        }
+        if (boundaryId !== undefined)
+            ids.add(boundaryId);
+        const evaluated = evaluateBoundaryRecord(boundary, fixtures, now.getTime());
+        capturedCount += evaluated.captured;
+        waivedCount += evaluated.waived;
+        findings.push(...evaluated.findings);
+    }
+    findings.sort((left, right) => left.boundary_id !== right.boundary_id
+        ? left.boundary_id.localeCompare(right.boundary_id)
+        : left.kind.localeCompare(right.kind));
+    return {
+        ok: findings.length === 0,
+        boundary_count: registry.boundaries.length,
+        captured_count: capturedCount,
+        waived_count: waivedCount,
+        findings,
+    };
+}
+//# sourceMappingURL=boundary-fixtures.js.map
+//# debugId=3edb1f4f-d26e-51a8-b62a-caffdd3ac44b

package/dist/sdk/governance/defect-recurrence-signals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module sdk/defect-recurrence-signals
+ *
+ * Keeps the recurrence index's PM-item projection shared with transport caches
+ * without exposing internal full-record serialization as an invalidation rule.
+ */
+import type { AssuranceItemRecord } from "./assurance.js";
+import type { DefectChangeRiskInput } from "./defect-recurrence.js";
+/** Project one PM item to exactly the signals consumed by recurrence indexing. */
+export declare function defectRecurrenceItemSignals(item: AssuranceItemRecord): DefectChangeRiskInput;

package/dist/sdk/governance/defect-recurrence-signals.js

@@ -0,0 +1,25 @@
+/** Project one PM item to exactly the signals consumed by recurrence indexing. */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e78c3363-1741-52b9-8bd5-729e3ccada50")}catch(e){}}();
+export function defectRecurrenceItemSignals(item) {
+    return {
+        files: (Array.isArray(item.files) ? item.files : []).flatMap((entry) => {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                return [];
+            const value = entry.path;
+            return typeof value === "string" ? [value] : [];
+        }),
+        package_names: Array.isArray(item.package_names)
+            ? item.package_names.filter((value) => typeof value === "string")
+            : [],
+        item_ids: [item.id],
+        tags: Array.isArray(item.tags)
+            ? item.tags.filter((value) => typeof value === "string")
+            : [],
+        error_codes: Array.isArray(item.error_codes)
+            ? item.error_codes.filter((value) => typeof value === "string")
+            : [],
+    };
+}
+//# sourceMappingURL=defect-recurrence-signals.js.map
+//# debugId=e78c3363-1741-52b9-8bd5-729e3ccada50