@deftai/directive 0.126.0-beta.2 → 0.126.1

package/dist/verify-session-ritual.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { type DirectivePosture, type VerifyResult } from "@deftai/directive-core/session";
+export interface VerifySessionRitualRunDeps {
+    readonly verifySessionRitual?: (projectRoot: string, options: {
+        tier: "quick" | "gated";
+        posture?: DirectivePosture;
+    }) => VerifyResult;
+}
+interface ParsedArgs {
+    projectRoot: string;
+    tier: "quick" | "gated";
+    posture: DirectivePosture | null;
+    emitJson: boolean;
+    error?: string;
+}
+/** Parse verify-session-ritual CLI args, mirroring scripts/verify_session_ritual.py. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** True when the ritual failure is the gated cache_fresh step (#3506 / #3507). */
+export declare function isCacheFreshFailureMessage(message: string): boolean;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[], deps?: VerifySessionRitualRunDeps): number;
+export {};
+//# sourceMappingURL=verify-session-ritual.d.ts.map

package/dist/verify-session-ritual.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitBypassWarning, emitVerifyJson, formatCacheFreshDeferSoftPath, occupancyAwareDenialMessage, verifySessionRitual, } from "@deftai/directive-core/session";
+function parsePosture(value) {
+    if (value === "read-only")
+        return "read-only";
+    if (value === "mutation" || value === "mutating")
+        return "mutation";
+    return null;
+}
+/** Parse verify-session-ritual CLI args, mirroring scripts/verify_session_ritual.py. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        tier: "quick",
+        posture: null,
+        emitJson: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--") {
+            continue;
+        }
+        if (arg === "--json") {
+            parsed.emitJson = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--tier") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --tier: expected one argument" };
+            }
+            if (value !== "quick" && value !== "gated") {
+                return { ...parsed, error: `argument --tier: invalid choice: '${value}'` };
+            }
+            parsed.tier = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--tier=")) {
+            const value = arg.slice("--tier=".length);
+            if (value !== "quick" && value !== "gated") {
+                return { ...parsed, error: `argument --tier: invalid choice: '${value}'` };
+            }
+            parsed.tier = value;
+        }
+        else if (arg === "--posture") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --posture: expected one argument" };
+            }
+            const posture = parsePosture(value);
+            if (posture === null) {
+                return {
+                    ...parsed,
+                    error: `argument --posture: invalid choice: '${value}' (expected read-only|mutation)`,
+                };
+            }
+            parsed.posture = posture;
+            i += 1;
+        }
+        else if (arg?.startsWith("--posture=")) {
+            const value = arg.slice("--posture=".length);
+            const posture = parsePosture(value);
+            if (posture === null) {
+                return {
+                    ...parsed,
+                    error: `argument --posture: invalid choice: '${value}' (expected read-only|mutation)`,
+                };
+            }
+            parsed.posture = posture;
+        }
+        else {
+            const error = `unrecognized argument: ${arg}`;
+            if (arg === "--session-id" || arg?.startsWith("--session-id=")) {
+                return {
+                    ...parsed,
+                    error: `${error} Drop the flag and retry deft verify:session-ritual -- --tier=gated.`,
+                };
+            }
+            return { ...parsed, error };
+        }
+    }
+    return parsed;
+}
+/** True when the ritual failure is the gated cache_fresh step (#3506 / #3507). */
+export function isCacheFreshFailureMessage(message) {
+    return message.includes("cache_fresh") || message.includes("cache-fresh");
+}
+/** Run the gate and return the process exit code. */
+export function run(argv, deps = {}) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_session_ritual: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const verify = deps.verifySessionRitual ?? verifySessionRitual;
+    const result = verify(projectRoot, {
+        tier: args.tier,
+        posture: args.posture ?? undefined,
+    });
+    const warning = emitBypassWarning(result);
+    const warningNeeded = result.bypassed && result.wouldFailCode !== null;
+    if (args.emitJson) {
+        process.stdout.write(`${emitVerifyJson(result)}\n`);
+    }
+    else if (result.code === 0) {
+        if (!warningNeeded) {
+            process.stdout.write(`${result.message}\n`);
+        }
+    }
+    else if (result.code === 1) {
+        const recoveryTier = result.recoveryTier ?? "cold";
+        const lines = [
+            occupancyAwareDenialMessage(projectRoot, result.message, { env: process.env }, recoveryTier),
+        ];
+        if (isCacheFreshFailureMessage(result.message)) {
+            lines.push(formatCacheFreshDeferSoftPath());
+        }
+        process.stderr.write(`${lines.join("\n")}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    if (warning.length > 0) {
+        process.stderr.write(`${warning}\n`);
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-session-ritual.js.map

package/dist/verify-source-cli/rule-ownership-lint.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    mapPath: string | null;
+    root: string | null;
+    error?: string;
+}
+/** Parse rule-ownership-lint CLI args, mirroring scripts/rule_ownership_lint.py. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=rule-ownership-lint.d.ts.map

package/dist/verify-source-cli/rule-ownership-lint.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateRuleOwnership } from "@deftai/directive-core/verify-source";
+/** Parse rule-ownership-lint CLI args, mirroring scripts/rule_ownership_lint.py. */
+export function parseArgs(argv) {
+    const parsed = { mapPath: null, root: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--map") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --map: expected one argument" };
+            }
+            parsed.mapPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--map=")) {
+            parsed.mapPath = arg.slice("--map=".length);
+        }
+        else if (arg === "--root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --root: expected one argument" };
+            }
+            parsed.root = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--root=")) {
+            parsed.root = arg.slice("--root=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`rule_ownership_lint: ${args.error}\n`);
+        return 2;
+    }
+    const root = resolve(args.root ?? ".");
+    const result = evaluateRuleOwnership(root, {
+        root,
+        mapPath: args.mapPath !== null ? resolve(args.mapPath) : undefined,
+    });
+    if (result.stream === "stdout") {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=rule-ownership-lint.js.map

package/dist/verify-source-cli/verify-biome-config.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    error?: string;
+}
+/** Parse verify-biome-config CLI args (#2190). */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-biome-config.d.ts.map

package/dist/verify-source-cli/verify-biome-config.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateBiomeConfigGuard } from "@deftai/directive-core/verify-source";
+/** Parse verify-biome-config CLI args (#2190). */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: "." };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_biome_config: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateBiomeConfigGuard(resolve(args.projectRoot));
+    if (result.code === 0) {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-biome-config.js.map

package/dist/verify-source-cli/verify-closing-keywords.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+export type RunGitFn = (args: readonly string[]) => {
+    readonly returncode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type RangeResolution = {
+    readonly kind: "pr";
+    readonly pr: string;
+} | {
+    readonly kind: "range";
+    readonly range: string;
+} | {
+    readonly kind: "missing-base";
+    readonly reason: string;
+} | {
+    readonly kind: "stale-base";
+    readonly reason: string;
+};
+export declare function defaultRunGit(args: readonly string[]): {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Resolve the candidate commit range against a merge-base, not a hardcoded
+ * origin/master two-dot range (#3969 Greptile leftover).
+ */
+export declare function resolveClosingKeywordsSource(env: NodeJS.ProcessEnv, runGit?: RunGitFn): RangeResolution;
+export declare function buildClosingKeywordsCheckArgv(env: NodeJS.ProcessEnv, extra?: readonly string[], runGit?: RunGitFn): {
+    argv: string[];
+    error?: string;
+};
+export declare function run(argv: string[], env?: NodeJS.ProcessEnv, invoke?: (args: readonly string[]) => number, runGit?: RunGitFn): number;
+//# sourceMappingURL=verify-closing-keywords.d.ts.map

package/dist/verify-source-cli/verify-closing-keywords.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { cmdPrCheckClosingKeywords } from "@deftai/directive-core/dist/pr-closing-keywords/main.js";
+const BASE_CANDIDATES = ["origin/master", "origin/main"];
+export function defaultRunGit(args) {
+    try {
+        const stdout = execFileSync("git", [...args], {
+            encoding: "utf8",
+            timeout: 30_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            returncode: typeof e.status === "number" ? e.status : 1,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+            stderr: typeof e.stderr === "string" ? e.stderr : String(e.message ?? ""),
+        };
+    }
+}
+function firstLine(text) {
+    return text.trim().split(/\r?\n/)[0] ?? "";
+}
+function shaOf(result) {
+    if (result.returncode !== 0)
+        return null;
+    const sha = firstLine(result.stdout);
+    return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : null;
+}
+function localDefaultFor(originRef) {
+    if (originRef.endsWith("/master") || originRef === "master")
+        return "master";
+    if (originRef.endsWith("/main") || originRef === "main")
+        return "main";
+    const slash = originRef.lastIndexOf("/");
+    return slash >= 0 ? originRef.slice(slash + 1) : null;
+}
+/** Remote-tracking ref name for `git fetch origin <name> --`. */
+function originFetchArg(originRef) {
+    if (!originRef.startsWith("origin/"))
+        return null;
+    const name = originRef.slice("origin/".length);
+    return name.length > 0 ? name : null;
+}
+/**
+ * Detect the locally observable stale-range enlargement without fetching:
+ * origin/<default> lags a descendant local default, and HEAD's merge-base
+ * against that local default is not the origin merge-base. Then
+ * origin/master..HEAD would include already-merged local-default commits.
+ */
+function staleRelativeToLocalDefault(originRef, originMergeBase, runGit) {
+    const localDefault = localDefaultFor(originRef);
+    if (localDefault === null)
+        return null;
+    const ahead = runGit(["merge-base", "--is-ancestor", originRef, localDefault]);
+    if (ahead.returncode !== 0)
+        return null;
+    const localMb = shaOf(runGit(["merge-base", localDefault, "HEAD"]));
+    if (localMb === null || localMb === originMergeBase)
+        return null;
+    return {
+        kind: "stale-base",
+        reason: originRef +
+            " lags local " +
+            localDefault +
+            " relative to HEAD, so the scan range would include already-merged commits. Recovery: git fetch origin " +
+            localDefault +
+            ".",
+    };
+}
+/**
+ * Resolve the candidate commit range against a merge-base, not a hardcoded
+ * origin/master two-dot range (#3969 Greptile leftover).
+ */
+export function resolveClosingKeywordsSource(env, runGit = defaultRunGit) {
+    const raw = env.GITHUB_PR_NUMBER ?? env.PR_NUMBER;
+    const pr = raw?.trim() ?? "";
+    if (/^\d+$/.test(pr)) {
+        return { kind: "pr", pr };
+    }
+    const bases = [
+        env.GITHUB_BASE_REF?.trim() ? `origin/${env.GITHUB_BASE_REF.trim()}` : null,
+        ...BASE_CANDIDATES,
+    ].filter((base) => base !== null && base.length > 0);
+    const seen = new Set();
+    for (const base of bases) {
+        if (seen.has(base))
+            continue;
+        seen.add(base);
+        const fetchArg = originFetchArg(base);
+        let fetched = false;
+        if (fetchArg !== null) {
+            // Scoped to this wrapper, not the whole check graph. CI uses --pr
+            // and never reaches this path.
+            fetched = runGit(["fetch", "origin", fetchArg, "--"]).returncode === 0;
+        }
+        const sha = shaOf(runGit(["merge-base", base, "HEAD"]));
+        if (sha === null)
+            continue;
+        if (!fetched) {
+            const stale = staleRelativeToLocalDefault(base, sha, runGit);
+            if (stale !== null)
+                return stale;
+            // Fetch failed and local evidence cannot prove freshness: do not
+            // scan a possibly stale origin merge-base.
+            continue;
+        }
+        return { kind: "range", range: `${sha}..HEAD` };
+    }
+    return {
+        kind: "missing-base",
+        reason: "no merge-base against origin/master or origin/main. Recovery: git fetch origin master.",
+    };
+}
+export function buildClosingKeywordsCheckArgv(env, extra = [], runGit = defaultRunGit) {
+    const source = resolveClosingKeywordsSource(env, runGit);
+    if (source.kind === "pr") {
+        return { argv: ["--mode", "both", "--pr", source.pr, ...extra] };
+    }
+    if (source.kind === "missing-base" || source.kind === "stale-base") {
+        return { argv: [], error: source.reason };
+    }
+    return { argv: ["--mode", "both", "--from-git-range", source.range, ...extra] };
+}
+export function run(argv, env = process.env, invoke = cmdPrCheckClosingKeywords, runGit = defaultRunGit) {
+    const built = buildClosingKeywordsCheckArgv(env, argv, runGit);
+    if (built.error !== undefined) {
+        process.stderr.write("verify:closing-keywords: fail -- " + built.error + "\n");
+        return 2;
+    }
+    return invoke(built.argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-closing-keywords.js.map

package/dist/verify-source-cli/verify-consumer-hard-stops.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    repo: string;
+    projectRoot: string;
+    changelog: string | null;
+    error?: string;
+}
+export interface HardStopCliSeams {
+    readonly inventory?: readonly Record<string, unknown>[];
+    readonly changelogText?: string;
+}
+/** Parse verify-consumer-hard-stops CLI args (#3900 / #3713). */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[], seams?: HardStopCliSeams): number;
+export {};
+//# sourceMappingURL=verify-consumer-hard-stops.d.ts.map

package/dist/verify-source-cli/verify-consumer-hard-stops.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateConsumerHardStopCensus, issueFromInventoryRow, parseClosesSet, } from "@deftai/directive-core/release";
+import { restIssueListOpenInventory } from "@deftai/directive-core/scm";
+/** Parse verify-consumer-hard-stops CLI args (#3900 / #3713). */
+export function parseArgs(argv) {
+    const parsed = { repo: "deftai/directive", projectRoot: ".", changelog: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            parsed.repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            parsed.repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--changelog") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --changelog: expected one argument" };
+            parsed.changelog = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--changelog=")) {
+            parsed.changelog = arg.slice("--changelog=".length);
+        }
+        else {
+            return { ...parsed, error: "unrecognized argument: " + String(arg) };
+        }
+    }
+    return parsed;
+}
+export function run(argv, seams = {}) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write("verify_consumer_hard_stops: " + args.error + "\n");
+        return 2;
+    }
+    const root = resolve(args.projectRoot);
+    let changelogText = seams.changelogText;
+    if (changelogText === undefined) {
+        const changelogPath = resolve(root, args.changelog ?? "CHANGELOG.md");
+        try {
+            changelogText = readFileSync(changelogPath, "utf8");
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            process.stderr.write("verify_consumer_hard_stops: could not read CHANGELOG (" + reason + ")\n");
+            return 2;
+        }
+    }
+    let rows;
+    try {
+        rows = seams.inventory ?? restIssueListOpenInventory(args.repo);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        process.stderr.write("verify_consumer_hard_stops: fail -- could not list open issues. Recovery: check gh auth and REST quota. " +
+            reason +
+            "\n");
+        return 2;
+    }
+    const issues = [];
+    for (const row of rows) {
+        const issue = issueFromInventoryRow(row);
+        if (issue !== null)
+            issues.push(issue);
+    }
+    const result = evaluateConsumerHardStopCensus({
+        issues,
+        closesSet: parseClosesSet(changelogText),
+    });
+    if (result.stream === "stdout") {
+        process.stdout.write(result.message + "\n");
+    }
+    else {
+        process.stderr.write(result.message + "\n");
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-consumer-hard-stops.js.map

package/dist/verify-source-cli/verify-contained-writes.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    enforce: boolean;
+    help?: boolean;
+    error?: string;
+}
+/** Parse verify-contained-writes CLI args (#2951). */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-contained-writes.d.ts.map

package/dist/verify-source-cli/verify-contained-writes.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * CLI for task verify:contained-writes (#2951 Phase 1).
+ * Fail-open by default; pass --enforce for fail-closed (later phases).
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateContainedWrites } from "@deftai/directive-core/verify-source";
+/** Parse verify-contained-writes CLI args (#2951). */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", enforce: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--enforce") {
+            parsed.enforce = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return { ...parsed, help: true };
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+const HELP_TEXT = "Usage: verify-contained-writes [--project-root <path>] [--enforce]\n" +
+    "  Inventory raw write sinks outside the allowlist (#2951).\n" +
+    "  Default: fail-open (exit 0 with advisory report).\n" +
+    "  --enforce: fail closed (exit 1) when non-allowlisted sinks remain.\n";
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.help === true) {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_contained_writes: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateContainedWrites({
+        projectRoot: resolve(args.projectRoot),
+        enforce: args.enforce,
+    });
+    if (result.stream === "stdout") {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-contained-writes.js.map