@westbayberry/dg 2.0.11 → 2.2.0

package/dist/commands/cooldown.js

@@ -0,0 +1,389 @@
+import { describeCooldownSettings, durationToDays, formatCooldownDuration } from "../policy/cooldown.js";
+import { readHeldPackages } from "../state/index.js";
+import { canonicalCooldownName } from "../policy/pypi-name.js";
+import { ConfigError, loadUserConfig, setConfigValue, updateUserConfig } from "../config/settings.js";
+import { appendCooldownExemptions, cooldownExemptionActive, CooldownExemptionCapError, findProjectRoot, loadDgFile, mutateDgFile, removeCooldownExemptions, resolveAcceptedBy } from "../project/dgfile.js";
+import { EXIT_USAGE } from "./types.js";
+export const cooldownCommand = {
+    name: "cooldown",
+    summary: "Hold new releases for a window before they can install, with per-package exemptions.",
+    usage: "dg cooldown [<window>|off] [--json] | dg cooldown exempt <name> [--reason <text>] [--expires <30d>] | dg cooldown rm <name>",
+    subcommands: [
+        { name: "list", summary: "Show the cooldown window and exemptions (default).", usage: "dg cooldown list [--json]", details: [], handler: () => unreachable() },
+        { name: "<window>", summary: "Set the window directly: dg cooldown 7d, dg cooldown 24h, dg cooldown off.", usage: "dg cooldown <7d|24h|off>", details: [], handler: () => unreachable() },
+        { name: "exempt", summary: "Always allow a package through cooldown.", usage: "dg cooldown exempt <name> [--reason <text>] [--expires <30d>] [--ecosystem npm|pypi]", details: [], handler: () => unreachable() },
+        { name: "rm", summary: "Drop an exemption so cooldown applies again.", usage: "dg cooldown rm <name> [--ecosystem npm|pypi]", details: [], handler: () => unreachable() },
+        { name: "prune", summary: "Remove expired exemptions.", usage: "dg cooldown prune", details: [], handler: () => unreachable() }
+    ],
+    flags: [
+        { flag: "--reason", value: "<text>", summary: "Why this package is exempt (stored in dg.json)." },
+        { flag: "--expires", value: "<30d>", summary: "Auto-expire the exemption after a duration (e.g. 14d, 90d)." },
+        { flag: "--ecosystem", value: "<npm|pypi>", summary: "Ecosystem when the name is not prefixed (default npm)." },
+        { flag: "--json", summary: "Machine-readable listing." }
+    ],
+    examples: [
+        "dg cooldown",
+        "dg cooldown 7d",
+        "dg cooldown off",
+        "dg cooldown exempt left-pad --reason 'vendored, pinned'",
+        "dg cooldown exempt pypi:requests --expires 30d",
+        "dg cooldown rm left-pad"
+    ],
+    details: [
+        "Cooldown quarantines releases younger than your configured window so a freshly-published compromised version can't install before anyone notices. An exemption opts one package out — use it for internal packages you publish and install immediately, or a dependency you've already vetted. Exemptions live in dg.json at the git root; an --expires window makes them self-revoke so the quarantine comes back on its own."
+    ],
+    handler: (context) => runCooldownCommand(context)
+};
+function unreachable() {
+    throw new Error("subcommand handled by the cooldown router");
+}
+export function runCooldownCommand(context, cwd = process.cwd(), env = process.env, now = new Date()) {
+    const [first, ...rest] = context.args;
+    if (first === undefined || first === "list" || first === "--json") {
+        const json = first === "--json" || rest.includes("--json");
+        const extras = rest.filter((arg) => arg !== "--json");
+        if (extras.length > 0) {
+            return usage(`unexpected argument '${extras[0]}'`);
+        }
+        return listExemptions(cwd, env, json, now);
+    }
+    if (first === "exempt") {
+        return addExemption(rest, cwd, env, now);
+    }
+    if (first === "rm" || first === "remove") {
+        return removeExemption(rest, cwd, env);
+    }
+    if (first === "prune") {
+        return pruneExemptions(rest, cwd, env, now);
+    }
+    if (/^(0|off|[1-9]\d{0,3}[hd])$/i.test(first)) {
+        return setWindow(first.toLowerCase(), rest, cwd, env, now);
+    }
+    return usage(`unknown subcommand '${first}'`);
+}
+function setWindow(window, rest, cwd, env, now) {
+    if (rest.length > 0) {
+        return usage(`unexpected argument '${rest[0]}'`);
+    }
+    try {
+        updateUserConfig((current) => setConfigValue(current, "cooldown.age", window), env);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            return usage(error.message);
+        }
+        throw error;
+    }
+    return listExemptions(cwd, env, false, now);
+}
+function parseFlags(args) {
+    const positionals = [];
+    let reason;
+    let expires;
+    let ecosystem;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        if (arg === "--reason" || arg === "--expires" || arg === "--ecosystem") {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { error: `${arg} needs a value` };
+            }
+            if (arg === "--reason")
+                reason = value;
+            else if (arg === "--expires")
+                expires = value;
+            else
+                ecosystem = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--reason="))
+            reason = arg.slice("--reason=".length);
+        else if (arg.startsWith("--expires="))
+            expires = arg.slice("--expires=".length);
+        else if (arg.startsWith("--ecosystem="))
+            ecosystem = arg.slice("--ecosystem=".length);
+        else if (arg.startsWith("--"))
+            return { error: `unknown flag '${arg}'` };
+        else
+            positionals.push(arg);
+    }
+    return {
+        positionals,
+        ...(reason !== undefined ? { reason } : {}),
+        ...(expires !== undefined ? { expires } : {}),
+        ...(ecosystem !== undefined ? { ecosystem } : {})
+    };
+}
+const EXEMPTION_NAME_RE = /^[@A-Za-z0-9][@A-Za-z0-9._/-]*$/u;
+function resolveTarget(token, ecosystemFlag) {
+    const colon = token.indexOf(":");
+    if (colon > 0) {
+        const prefix = token.slice(0, colon);
+        if (prefix === "npm" || prefix === "pypi" || prefix === "cargo") {
+            return validatedTarget(prefix, token.slice(colon + 1), token);
+        }
+        return { error: `unknown ecosystem prefix '${prefix}:' (only npm:, pypi:, and cargo: are supported)` };
+    }
+    const eco = ecosystemFlag ?? "npm";
+    if (eco !== "npm" && eco !== "pypi" && eco !== "cargo") {
+        return { error: `--ecosystem must be npm, pypi, or cargo, got '${eco}'` };
+    }
+    return validatedTarget(eco, token, token);
+}
+function validatedTarget(ecosystem, name, token) {
+    if (name.length === 0) {
+        return { error: `'${token}' has no package name` };
+    }
+    if (!EXEMPTION_NAME_RE.test(name)) {
+        return { error: `'${name}' is not a valid package name (no spaces, control characters, or '*' globs; use config cooldown.exempt for globs)` };
+    }
+    return { ecosystem, name: canonicalName(ecosystem, name) };
+}
+function canonicalName(ecosystem, name) {
+    return canonicalCooldownName(ecosystem, name);
+}
+function expiresAtFrom(expires, now) {
+    if (expires === undefined || expires === "off" || expires === "never") {
+        return {};
+    }
+    const days = durationToDays(expires);
+    if (days <= 0) {
+        if (/^[1-9]\d*(h|d)$/.test(expires)) {
+            return { error: `--expires '${expires}' is too large (maximum is 9999d or 9999h)` };
+        }
+        return { error: `--expires must be a positive duration like 30d or 12h, got '${expires}'` };
+    }
+    return { value: new Date(now.getTime() + days * 24 * 60 * 60 * 1000).toISOString() };
+}
+function formatExpiryDisplay(expiresAt, acceptedAt) {
+    const expiry = Date.parse(expiresAt);
+    const accepted = Date.parse(acceptedAt);
+    if (Number.isFinite(expiry) && Number.isFinite(accepted) && expiry - accepted < 24 * 60 * 60 * 1000) {
+        return `${expiresAt.slice(0, 16).replace("T", " ")}Z`;
+    }
+    return expiresAt.slice(0, 10);
+}
+function addExemption(args, cwd, env, now) {
+    const parsed = parseFlags(args);
+    if ("error" in parsed) {
+        return usage(parsed.error);
+    }
+    if (parsed.positionals.length !== 1 || parsed.positionals[0] === undefined) {
+        return usage("exempt takes exactly one <name>");
+    }
+    const target = resolveTarget(parsed.positionals[0], parsed.ecosystem);
+    if ("error" in target) {
+        return usage(target.error);
+    }
+    const expiry = expiresAtFrom(parsed.expires, now);
+    if ("error" in expiry) {
+        return usage(expiry.error);
+    }
+    const located = locateWritableDgFile(cwd, env);
+    if ("error" in located) {
+        return located.error;
+    }
+    const exemption = {
+        ecosystem: target.ecosystem,
+        name: target.name,
+        reason: parsed.reason ?? "",
+        acceptedBy: resolveAcceptedBy(located.root, env),
+        ...(expiry.value ? { expiresAt: expiry.value } : {})
+    };
+    try {
+        mutateDgFile(located.root, env, (file) => appendCooldownExemptions(file, [exemption], now));
+    }
+    catch (error) {
+        if (error instanceof CooldownExemptionCapError) {
+            return { exitCode: 1, stdout: "", stderr: `dg cooldown: ${error.message}.\n` };
+        }
+        throw error;
+    }
+    const until = expiry.value ? ` until ${formatExpiryDisplay(expiry.value, now.toISOString())}` : "";
+    return {
+        exitCode: 0,
+        stdout: `Exempted ${target.ecosystem}:${target.name} from cooldown${until}.\n`,
+        stderr: ""
+    };
+}
+function removeExemption(args, cwd, env) {
+    const parsed = parseFlags(args);
+    if ("error" in parsed) {
+        return usage(parsed.error);
+    }
+    if (parsed.positionals.length !== 1 || parsed.positionals[0] === undefined) {
+        return usage("rm takes exactly one <name>");
+    }
+    const target = resolveTarget(parsed.positionals[0], parsed.ecosystem);
+    if ("error" in target) {
+        return usage(target.error);
+    }
+    const located = locateWritableDgFile(cwd, env);
+    if ("error" in located) {
+        return located.error;
+    }
+    const matches = (e) => e.ecosystem === target.ecosystem && e.name === target.name;
+    let removed = false;
+    mutateDgFile(located.root, env, (file) => {
+        if (!file.cooldownExemptions.some(matches)) {
+            return file;
+        }
+        removed = true;
+        return removeCooldownExemptions(file, matches);
+    });
+    if (!removed) {
+        return { exitCode: 1, stdout: "", stderr: `dg cooldown: ${target.ecosystem}:${target.name} is not exempt in ${located.file.path}.\n` };
+    }
+    return { exitCode: 0, stdout: `Removed cooldown exemption for ${target.ecosystem}:${target.name} — cooldown applies again.\n`, stderr: "" };
+}
+function pruneExemptions(args, cwd, env, now) {
+    if (args.length > 0) {
+        return usage(`unexpected argument '${args[0]}'`);
+    }
+    const located = locateWritableDgFile(cwd, env);
+    if ("error" in located) {
+        return located.error;
+    }
+    let pruned = 0;
+    mutateDgFile(located.root, env, (file) => {
+        const expired = (e) => !cooldownExemptionActive(e, now);
+        pruned = file.cooldownExemptions.filter(expired).length;
+        return pruned === 0 ? file : removeCooldownExemptions(file, expired);
+    });
+    return { exitCode: 0, stdout: `Pruned ${pruned} expired cooldown exemption${pruned === 1 ? "" : "s"}.\n`, stderr: "" };
+}
+function windowStatusLines(env) {
+    const config = loadUserConfig(env);
+    const window = describeCooldownSettings(config, env);
+    const windowLine = window === "off"
+        ? "off — new releases install immediately"
+        : `${window}      set: dg cooldown 3d`;
+    const unknownLine = config.cooldown.onUnknown === "block"
+        ? "block (no known publish date → held back)"
+        : "allow (no known publish date → not held back)";
+    return [
+        "Cooldown — versions published less than your window ago wait before installing.",
+        "",
+        `  window    ${windowLine}`,
+        `  unknown   ${unknownLine}`,
+        ""
+    ];
+}
+const EXEMPTION_FOOTER = [
+    "  add: dg cooldown exempt <name> [--expires 30d]   ·   remove: dg cooldown rm <name>",
+    "  An exemption waives only the wait — the package is still scanned. No CVE fast-track yet."
+];
+function renderTable(columns, rows) {
+    const widths = columns.map((label, column) => Math.max(label.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    const renderRow = (row) => `  ${row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd()}`;
+    return [renderRow(columns), ...rows.map(renderRow)];
+}
+function eligibleDisplay(entry, now) {
+    if (!entry.eligibleAt) {
+        return "unknown";
+    }
+    const eligible = Date.parse(entry.eligibleAt);
+    if (!Number.isFinite(eligible)) {
+        return "unknown";
+    }
+    const relative = formatCooldownDuration(Math.max(0, (eligible - now.getTime()) / 86_400_000));
+    return `${entry.eligibleAt.slice(0, 10)} (in ${relative})`;
+}
+function heldSectionLines(env, now) {
+    const held = readHeldPackages(env, now);
+    if (held.length === 0) {
+        return ["Currently held: none.", ""];
+    }
+    const rows = held.map((entry) => [
+        `${entry.ecosystem}:${entry.name}@${entry.version}`,
+        entry.publishedAt ? entry.publishedAt.slice(0, 10) : "-",
+        eligibleDisplay(entry, now)
+    ]);
+    return [
+        "Currently held:",
+        "",
+        ...renderTable(["PACKAGE", "PUBLISHED", "ELIGIBLE"], rows),
+        "",
+        "  release now: dg cooldown exempt <name>",
+        ""
+    ];
+}
+function listExemptions(cwd, env, json, now) {
+    const root = findProjectRoot(cwd, env);
+    if (!root) {
+        return { exitCode: EXIT_USAGE, stdout: "", stderr: "dg cooldown: not inside a git repository.\n" };
+    }
+    const file = loadDgFile(root);
+    if (file.exists && !file.readable) {
+        return { exitCode: 1, stdout: "", stderr: `dg cooldown: cannot use ${file.path} — ${file.failure ?? "unreadable"}.\n` };
+    }
+    const config = loadUserConfig(env);
+    if (json) {
+        return {
+            exitCode: 0,
+            stdout: `${JSON.stringify({
+                schemaVersion: 1,
+                path: file.path,
+                window: { effective: describeCooldownSettings(config, env), onUnknown: config.cooldown.onUnknown },
+                held: readHeldPackages(env, now),
+                cooldownExemptions: file.cooldownExemptions.map((e) => exemptionJson(e, now))
+            }, null, 2)}\n`,
+            stderr: ""
+        };
+    }
+    const header = [...windowStatusLines(env), ...heldSectionLines(env, now)];
+    if (file.cooldownExemptions.length === 0) {
+        const note = file.exists ? `No exemptions in ${file.path}.` : "No exemptions yet — add one with the command below.";
+        return { exitCode: 0, stdout: `${[...header, note, ...EXEMPTION_FOOTER].join("\n")}\n`, stderr: "" };
+    }
+    const rows = file.cooldownExemptions.map((e) => [
+        `${e.ecosystem}:${e.name}`,
+        e.reason || "-",
+        e.acceptedBy || "-",
+        e.acceptedAt.slice(0, 10) || "-",
+        e.expiresAt ? formatExpiryDisplay(e.expiresAt, e.acceptedAt) : "-",
+        cooldownExemptionActive(e, now) ? "active" : "expired"
+    ]);
+    const lines = [
+        ...header,
+        `Exemptions in ${file.path}:`,
+        "",
+        ...renderTable(["PACKAGE", "REASON", "BY", "WHEN", "EXPIRES", "STATUS"], rows),
+        "",
+        ...EXEMPTION_FOOTER
+    ];
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+function locateWritableDgFile(cwd, env) {
+    const root = findProjectRoot(cwd, env);
+    if (!root) {
+        return { error: { exitCode: EXIT_USAGE, stdout: "", stderr: "dg cooldown: not inside a git repository.\n" } };
+    }
+    const file = loadDgFile(root);
+    if (!file.readable) {
+        return { error: { exitCode: 1, stdout: "", stderr: `dg cooldown: cannot write ${file.path} — ${file.failure ?? "unreadable"}.\n` } };
+    }
+    return { root, file };
+}
+function exemptionJson(e, now) {
+    return {
+        ecosystem: e.ecosystem,
+        name: e.name,
+        reason: e.reason,
+        acceptedBy: e.acceptedBy,
+        acceptedAt: e.acceptedAt,
+        ...(e.expiresAt ? { expiresAt: e.expiresAt } : {}),
+        status: cooldownExemptionActive(e, now) ? "active" : "expired"
+    };
+}
+function usage(message) {
+    return {
+        exitCode: EXIT_USAGE,
+        stdout: "",
+        stderr: `dg cooldown: ${message}. Usage: ${cooldownCommand.usage}\n`
+    };
+}

package/dist/commands/decisions.js

@@ -0,0 +1,169 @@
+import { recordDecisionEvents } from "../decisions/remember-prompt.js";
+import { packageKey } from "../decisions/apply.js";
+import { findProjectRoot, loadDgFile, mutateDgFile, removeDecisions } from "../project/dgfile.js";
+import { EXIT_USAGE } from "./types.js";
+export const decisionsCommand = {
+    name: "decisions",
+    summary: "List or revoke remembered warn acceptances stored in dg.json.",
+    usage: "dg decisions [list] [--json] | dg decisions revoke <id|name[@version]>",
+    subcommands: [
+        { name: "list", summary: "Show every remembered acceptance (default).", usage: "dg decisions list [--json]", details: [], handler: () => unreachable() },
+        { name: "revoke", summary: "Remove an acceptance by id prefix, name, or name@version.", usage: "dg decisions revoke <id|name[@version]>", details: [], handler: () => unreachable() }
+    ],
+    flags: [{ flag: "--json", summary: "Machine-readable listing." }],
+    examples: ["dg decisions", "dg decisions list --json", "dg decisions revoke left-pad@1.3.0"],
+    details: [
+        "Acceptances live in dg.json at the git root and only ever soften how an acknowledged warn is presented — a block verdict is never suppressible. Revoking makes the warn surface again on the next scan."
+    ],
+    handler: (context) => runDecisionsCommand(context)
+};
+function unreachable() {
+    throw new Error("subcommand handled by the decisions router");
+}
+export function runDecisionsCommand(context, cwd = process.cwd(), env = process.env) {
+    const [first, ...rest] = context.args;
+    if (first === undefined || first === "list" || first === "--json") {
+        const json = first === "--json" || rest.includes("--json");
+        const extras = rest.filter((arg) => arg !== "--json");
+        if (extras.length > 0) {
+            return usage(`unexpected argument '${extras[0]}'`);
+        }
+        return listDecisions(cwd, env, json);
+    }
+    if (first === "revoke") {
+        const [selector, ...extra] = rest;
+        if (!selector || extra.length > 0) {
+            return usage("revoke takes exactly one <id|name[@version]>");
+        }
+        return revokeDecisions(selector, cwd, env);
+    }
+    return usage(`unknown subcommand '${first}'`);
+}
+function listDecisions(cwd, env, json) {
+    const located = locateDgFile(cwd, env);
+    if ("error" in located) {
+        return located.error;
+    }
+    if ("missing" in located) {
+        if (json) {
+            return { exitCode: 0, stdout: `${JSON.stringify({ schemaVersion: 1, path: null, decisions: [] }, null, 2)}\n`, stderr: "" };
+        }
+        return { exitCode: 0, stdout: `No dg.json at ${located.missing} — nothing remembered yet.\n`, stderr: "" };
+    }
+    const file = located.file;
+    if (json) {
+        return {
+            exitCode: 0,
+            stdout: `${JSON.stringify({ schemaVersion: 1, path: file.path, decisions: file.decisions.map((entry) => entryJson(entry)) }, null, 2)}\n`,
+            stderr: ""
+        };
+    }
+    if (file.decisions.length === 0) {
+        return { exitCode: 0, stdout: `No remembered acceptances in ${file.path}.\n`, stderr: "" };
+    }
+    const rows = file.decisions.map((entry) => [
+        entry.id.slice(0, 8),
+        `${entry.ecosystem}:${entry.name}@${scopeLabel(entry)}`,
+        findingsLabel(entry),
+        entry.acceptedBy,
+        entry.acceptedAt.slice(0, 10) || "-",
+        entry.expiresAt ? entry.expiresAt.slice(0, 10) : "-",
+        isExpired(entry) ? "expired" : "active"
+    ]);
+    const header = ["ID", "PACKAGE", "ACCEPTED FINDINGS", "BY", "WHEN", "EXPIRES", "STATUS"];
+    const widths = header.map((label, column) => Math.max(label.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    const renderRow = (row) => row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd();
+    const lines = [
+        `Remembered acceptances in ${file.path} (warns only — blocks are never suppressible):`,
+        "",
+        renderRow(header),
+        ...rows.map(renderRow),
+        "",
+        `Revoke with: dg decisions revoke <id|name[@version]>`
+    ];
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+function revokeDecisions(selector, cwd, env) {
+    const located = locateDgFile(cwd, env);
+    if ("error" in located) {
+        return located.error;
+    }
+    if ("missing" in located) {
+        return { exitCode: 1, stdout: "", stderr: `dg decisions: nothing to revoke — no dg.json at ${located.missing} yet.\n` };
+    }
+    let matched = [];
+    mutateDgFile(located.root, env, (file) => {
+        matched = file.decisions.filter((entry) => matchesSelector(entry, selector));
+        if (matched.length === 0) {
+            return file;
+        }
+        return removeDecisions(file, new Set(matched.map((entry) => entry.id)));
+    });
+    if (matched.length === 0) {
+        return { exitCode: 1, stdout: "", stderr: `dg decisions: nothing matches '${selector}' in ${located.file.path}.\n` };
+    }
+    recordDecisionEvents("decision.revoked", matched.map((entry) => `${entry.ecosystem}:${packageKey(entry.name, scopeLabel(entry))}`), `revoked via dg decisions (${selector})`, env);
+    const lines = matched.map((entry) => `Revoked ${entry.ecosystem}:${entry.name}@${scopeLabel(entry)} (${entry.id.slice(0, 8)}) — the warn will surface again.`);
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+function locateDgFile(cwd, env) {
+    const root = findProjectRoot(cwd, env);
+    if (!root) {
+        return { error: { exitCode: EXIT_USAGE, stdout: "", stderr: "dg decisions: not inside a git repository.\n" } };
+    }
+    const file = loadDgFile(root);
+    if (!file.exists) {
+        return { missing: root };
+    }
+    if (!file.readable) {
+        return { error: { exitCode: 1, stdout: "", stderr: `dg decisions: cannot use ${file.path} — ${file.failure ?? "unreadable"}.\n` } };
+    }
+    return { root, file };
+}
+function matchesSelector(entry, selector) {
+    if (selector.length >= 4 && entry.id.startsWith(selector)) {
+        return true;
+    }
+    const at = selector.lastIndexOf("@");
+    if (at > 0) {
+        const name = selector.slice(0, at);
+        const version = selector.slice(at + 1);
+        return entry.name === name && entry.scope.kind === "exact" && entry.scope.version === version;
+    }
+    return entry.name === selector;
+}
+function scopeLabel(entry) {
+    return entry.scope.kind === "exact" ? entry.scope.version : "*";
+}
+function findingsLabel(entry) {
+    const pairs = Object.entries(entry.findings).map(([category, severity]) => `${category}:${severity}`);
+    return pairs.length > 0 ? pairs.sort().join(",") : "(action-only warn)";
+}
+function isExpired(entry) {
+    if (!entry.expiresAt) {
+        return false;
+    }
+    const expiry = Date.parse(entry.expiresAt);
+    return !Number.isFinite(expiry) || expiry <= Date.now();
+}
+function entryJson(entry) {
+    return {
+        id: entry.id,
+        ecosystem: entry.ecosystem,
+        name: entry.name,
+        scope: entry.scope,
+        findings: entry.findings,
+        reason: entry.reason,
+        acceptedBy: entry.acceptedBy,
+        acceptedAt: entry.acceptedAt,
+        ...(entry.expiresAt ? { expiresAt: entry.expiresAt } : {}),
+        status: isExpired(entry) ? "expired" : "active"
+    };
+}
+function usage(message) {
+    return {
+        exitCode: EXIT_USAGE,
+        stdout: "",
+        stderr: `dg decisions: ${message}. Usage: ${decisionsCommand.usage}\n`
+    };
+}

package/dist/commands/doctor.js

@@ -33,7 +33,7 @@ async function doctorHandler(args) {
     const theme = createTheme(resolvePresentation().color);
     return {
         exitCode: hasFailure ? 1 : 0,
-        stdout: json ? `${JSON.stringify(report, null, 2)}\n` : renderDoctorReport(report, theme, verbose),
+        stdout: json ? `${JSON.stringify({ schemaVersion: 1, ...report }, null, 2)}\n` : renderDoctorReport(report, theme, verbose),
         stderr: ""
     };
 }

package/dist/commands/help.js

@@ -1,4 +1,4 @@
-const PRODUCT_DESCRIPTION = "Dependency Guardian supply-chain firewall CLI.";
+const PRODUCT_DESCRIPTION = "Dependency Guardian";
 const COMMON_COMMANDS = ["scan", "verify", "audit", "licenses", "setup", "guard-commit", "doctor", "login"];
 const GLOBAL_FLAGS_FOOTER = "Global: --help/-h · --version/-v · --json (where supported) · --no-color / --force-color (also NO_COLOR, FORCE_COLOR).";
 function isWrapper(command) {

package/dist/commands/licenses.js

@@ -1,9 +1,10 @@
-import { mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { launchScanTui, shouldLaunchScanTui } from "../scan-ui/launch.js";
+import { writeReportAtomic } from "../util/report-writer.js";
 import { basename, dirname, relative, resolve, sep } from "node:path";
 import { scanProject } from "../scan/discovery.js";
 import { isSupportedLockfilePath, verifyLockfile } from "../verify/preflight.js";
-import { EXIT_USAGE_VERDICT } from "./types.js";
+import { EXIT_ANALYSIS_INCOMPLETE, EXIT_USAGE_VERDICT } from "./types.js";
 const LICENSE_RISKS = [
     "network-copyleft",
     "no-license",
@@ -39,7 +40,7 @@ export const licensesCommand = {
     examples: ["dg licenses", "dg licenses --markdown -o licenses.md", "dg licenses --fail-on strong-copyleft,network-copyleft"],
     details: [
         "Reports project and lockfile license metadata without running package managers or package code.",
-        "License exports support text, JSON, CSV, and Markdown with stable exit codes for policy gates."
+        "License exports support text, JSON, CSV, and Markdown. Exit codes: 0 pass, 2 policy block, 4 report error, 64 usage error."
     ],
     handler: (context) => runLicensesCommand(context.args)
 };
@@ -60,13 +61,13 @@ async function runLicensesCommand(args) {
         }
         catch (error) {
             return {
-                exitCode: 1,
+                exitCode: EXIT_ANALYSIS_INCOMPLETE,
                 stdout: "",
                 stderr: `dg licenses TUI failed: ${error instanceof Error ? error.message : "unknown error"}\n`
             };
         }
         return {
-            exitCode: 0,
+            exitCode: typeof process.exitCode === "number" ? process.exitCode : 0,
             stdout: "",
             stderr: ""
         };
@@ -78,7 +79,7 @@ async function runLicensesCommand(args) {
     }
     catch (error) {
         return {
-            exitCode: 1,
+            exitCode: EXIT_ANALYSIS_INCOMPLETE,
             stdout: "",
             stderr: `dg licenses failed: ${error instanceof Error ? error.message : "unknown license error"}\n`
         };
@@ -91,7 +92,7 @@ async function runLicensesCommand(args) {
         }
         catch (error) {
             return {
-                exitCode: 1,
+                exitCode: EXIT_ANALYSIS_INCOMPLETE,
                 stdout: "",
                 stderr: `dg licenses could not write ${parsed.outputPath}: ${error instanceof Error ? error.message : "unknown write error"}\n`
             };
@@ -329,7 +330,7 @@ function classifyLicense(license) {
 }
 function renderLicenseReport(report, format) {
     if (format === "json") {
-        return `${JSON.stringify(report, null, 2)}\n`;
+        return `${JSON.stringify({ schemaVersion: 1, ...report }, null, 2)}\n`;
     }
     if (format === "csv") {
         return renderCsv(report);
@@ -392,7 +393,7 @@ function renderMarkdown(report) {
     return `${lines.join("\n")}\n`;
 }
 function exitCodeForReport(report) {
-    return report.status === "block" ? 1 : 0;
+    return report.status === "block" ? 2 : 0;
 }
 function usageError(message) {
     return {
@@ -401,19 +402,6 @@ function usageError(message) {
         stderr: `dg licenses: ${message}. Usage: dg licenses [path] [--json|--csv|--markdown] [--output <path>] [--fail-on <risk[,risk...]>] [--deny-license <id>]\n`
     };
 }
-function writeReportAtomic(outputPath, contents) {
-    const directory = dirname(outputPath);
-    mkdirSync(directory, { recursive: true });
-    const temporaryPath = `${outputPath}.${process.pid}.${Date.now()}.tmp`;
-    try {
-        writeFileSync(temporaryPath, contents, "utf8");
-        renameSync(temporaryPath, outputPath);
-    }
-    catch (error) {
-        rmSync(temporaryPath, { force: true });
-        throw error;
-    }
-}
 function dedupeEntries(entries) {
     const seen = new Set();
     const deduped = [];