@westbayberry/dg 1.3.3 → 2.0.0

package/dist/commands/explain.js

@@ -0,0 +1,100 @@
+import { EXIT_USAGE } from "./types.js";
+import { closestCommand } from "./suggest.js";
+export const EXPLANATIONS = {
+    "npm-lifecycle-script": {
+        what: "The package declares an install lifecycle script (preinstall/install/postinstall/prepare) that runs arbitrary code on your machine during 'npm install'.",
+        next: "Review the script in the package source. Prefer a version without install scripts, or install with --ignore-scripts."
+    },
+    "unverified-network-dependency": {
+        what: "A dependency is fetched from a raw URL (http/git) instead of the registry, so it has no registry identity or integrity to verify.",
+        next: "Pin the dependency to a registry version, or run 'dg verify <url>' before installing."
+    },
+    "local-artifact-dependency": {
+        what: "A dependency points at a local file path; its contents are whatever is on disk and are not registry-verified.",
+        next: "Run 'dg verify <path>' on the artifact, or replace it with a registry version."
+    },
+    malware: {
+        what: "The scanner confirmed this package version contains malicious code (for example credential theft or a backdoor).",
+        next: "Do not install it. Remove the dependency or pin a known-safe version; the dashboard link in the block shows the evidence."
+    },
+    policy: {
+        what: "Your organization or local policy denies this package, independent of a malware verdict.",
+        next: "Pick a compliant alternative, or ask your policy admin to allow it."
+    },
+    license: {
+        what: "The package license violates your license policy (for example a copyleft license your policy denies).",
+        next: "Replace the dependency, or update the license policy if the obligation is acceptable."
+    },
+    "hash-mismatch": {
+        what: "The downloaded artifact's hash does not match the artifact the scanner verified, which can indicate a tampered mirror or cache.",
+        next: "Clear your package cache and retry. If it persists, do not install and report it."
+    },
+    "private-upload-disabled": {
+        what: "The artifact comes from a private registry and private-artifact scanning is disabled, so the scanner never saw its contents.",
+        next: "Enable private artifact scanning (DG_SCAN_TARBALL_UPLOAD) or verify the artifact out of band."
+    },
+    "api-unavailable": {
+        what: "The scanner could not be reached, so no verdict exists for this install; policy decided fail-open or fail-closed.",
+        next: "Run 'dg doctor' and 'dg login' to check connectivity, then retry or re-check with 'dg verify'."
+    },
+    "quota-exceeded": {
+        what: "You've used your plan's monthly scan allowance, so this install could not be verified — it was blocked rather than installed unverified.",
+        next: "Upgrade your plan at westbayberry.com/pricing, or wait for your monthly limit to reset."
+    },
+    "api-timeout": {
+        what: "The scanner did not answer within the verdict timeout, so no verdict exists for this install.",
+        next: "Retry; if it persists, run 'dg doctor' to check connectivity."
+    },
+    "registry-timeout": {
+        what: "The upstream package registry did not respond, so the artifact was never fetched or verified.",
+        next: "Check the registry status and retry."
+    },
+    "analysis-incomplete": {
+        what: "The scanner analyzed only part of this package; the unanalyzed remainder is unverified, not safe.",
+        next: "Retry later, or override with --dg-force-install only if you accept the risk."
+    },
+    "unsupported-manager": {
+        what: "This package manager is gated in this dg build, so installs through it are not protected.",
+        next: "Use a supported manager through dg (npm, pnpm, yarn, pip, pipx, uv, uvx, cargo)."
+    },
+    "proxy-setup-failure": {
+        what: "dg's per-install enforcement proxy could not start, so protected installs fail closed rather than run unverified.",
+        next: "Run 'dg doctor' for the failing check, then retry."
+    }
+};
+export const explainCommand = {
+    name: "explain",
+    summary: "Explain a dg finding or block cause and what to do about it.",
+    usage: "dg explain <finding-or-cause-id>",
+    args: [{ name: "<id>", summary: "A finding id or block cause (see the list below)." }],
+    examples: ["dg explain malware", "dg explain quota-exceeded"],
+    details: [
+        `Known ids: ${Object.keys(EXPLANATIONS).sort().join(", ")}`
+    ],
+    handler: (context) => runExplain(context.args)
+};
+function runExplain(args) {
+    const id = args[0];
+    if (!id || args.length > 1) {
+        return {
+            exitCode: EXIT_USAGE,
+            stdout: "",
+            stderr: "dg explain: expected exactly one finding or cause id. Run 'dg explain --help'.\n"
+        };
+    }
+    const explanation = EXPLANATIONS[id];
+    if (!explanation) {
+        const suggestion = closestCommand(id, Object.keys(EXPLANATIONS));
+        const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+        return {
+            exitCode: EXIT_USAGE,
+            stdout: "",
+            stderr: `dg explain: unknown id '${id}'.${hint} Run 'dg explain --help' for the list.\n`
+        };
+    }
+    return {
+        exitCode: 0,
+        stdout: `${id}\n\n${explanation.what}\n\nNext: ${explanation.next}\n`,
+        stderr: ""
+    };
+}

package/dist/commands/guard-commit.js

@@ -0,0 +1,158 @@
+import { EXIT_USAGE } from "./types.js";
+import { resolvePresentation } from "../presentation/mode.js";
+import { createTheme } from "../presentation/theme.js";
+import { promptYesNo } from "../util/tty-prompt.js";
+import { applyGitHook, gitHookState, planGitHook, removeGitHookForRepo, resolveGitRepo, verifyGitHook } from "../setup/git-hook.js";
+export const guardCommitCommand = {
+    name: "guard-commit",
+    summary: "Scan staged dependencies before every commit in this repo.",
+    usage: "dg guard-commit [off | --check | --print] [--yes]",
+    args: [{ name: "[off]", summary: "Remove the hook and restore any hook it chained (alias remove/uninstall)." }],
+    flags: [
+        { flag: "--check", summary: "Verify the hook is installed and will actually fire." },
+        { flag: "--print", summary: "Preview what it will write, change nothing." },
+        { flag: "--yes", summary: "Install without the confirmation prompt (alias -y)." }
+    ],
+    examples: ["dg guard-commit", "dg guard-commit --check", "dg guard-commit off"],
+    details: [
+        "Installs a git pre-commit hook that scans staged lockfile changes and blocks a commit that would add a malicious dependency. Override a block with 'git commit --no-verify'.",
+        "It resolves the real hooks directory (honouring core.hooksPath/husky and worktrees) and chains any existing pre-commit hook. Tune behaviour with the gitHook.onWarn / gitHook.onIncomplete config keys."
+    ],
+    handler: (context) => run(context)
+};
+function parse(args) {
+    let off = false;
+    let check = false;
+    let print = false;
+    let yes = false;
+    for (const arg of args) {
+        if (arg === "off" || arg === "remove" || arg === "uninstall") {
+            off = true;
+        }
+        else if (arg === "install" || arg === "on") {
+            off = false;
+        }
+        else if (arg === "--check") {
+            check = true;
+        }
+        else if (arg === "--print") {
+            print = true;
+        }
+        else if (arg === "--yes" || arg === "-y") {
+            yes = true;
+        }
+        else {
+            return { error: `unknown argument '${arg}'` };
+        }
+    }
+    return { off, check, print, yes };
+}
+function run(context) {
+    const parsed = parse(context.args);
+    if ("error" in parsed) {
+        return {
+            exitCode: EXIT_USAGE,
+            stdout: "",
+            stderr: `dg guard-commit: ${parsed.error}. Usage: ${guardCommitCommand.usage}\n`
+        };
+    }
+    const theme = createTheme(resolvePresentation().color);
+    const repo = resolveGitRepo();
+    if ("error" in repo) {
+        return { exitCode: EXIT_USAGE, stdout: "", stderr: `dg guard-commit: ${repo.error}.\n` };
+    }
+    if (parsed.off) {
+        return remove(repo, theme);
+    }
+    if (parsed.check) {
+        return check(repo, theme);
+    }
+    if (parsed.print) {
+        return print(repo);
+    }
+    return install(repo, theme, parsed.yes);
+}
+function install(repo, theme, yes) {
+    const plan = planGitHook(repo);
+    const err = process.stderr;
+    const accent = (text) => theme.paint("accent", text);
+    const muted = (text) => theme.paint("muted", text);
+    if (resolvePresentation().mode === "rich" && !yes) {
+        err.write(`\n  Scan staged dependencies before every commit in ${accent(repo.root)}${muted(".")}\n`);
+        if (plan.willChain) {
+            err.write(`  ${muted("Your existing pre-commit hook will be kept and run after dg.")}\n`);
+        }
+        err.write(`  ${muted("Reversible with")} ${accent("dg guard-commit off")}${muted(".")}\n\n`);
+        const proceed = promptYesNo(`  ${accent("Proceed?")}`, true);
+        if (proceed === false) {
+            return { exitCode: 0, stdout: "", stderr: `  ${muted("cancelled — nothing written")}\n` };
+        }
+    }
+    const result = applyGitHook(repo);
+    if (result.active) {
+        return {
+            exitCode: 0,
+            stdout: "",
+            stderr: `\n  ${theme.paint("pass", "✓ commits in this repo are now scanned")}\n\n`
+        };
+    }
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `\n  ${theme.paint("warn", "⚠ installed, but it is not active yet:")}\n${renderChecks(result.checks, theme)}`
+    };
+}
+function check(repo, theme) {
+    if (gitHookState(repo) !== "managed") {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `  ${theme.paint("warn", "⚠")} not set up in this repo — run ${theme.paint("accent", "dg guard-commit")}\n`
+        };
+    }
+    const checks = verifyGitHook(repo);
+    const active = checks.every((entry) => entry.ok);
+    const head = active
+        ? `  ${theme.paint("pass", "✓ commit guard is active")}\n`
+        : `  ${theme.paint("warn", "⚠ commit guard is installed but not firing:")}\n`;
+    return { exitCode: active ? 0 : 1, stdout: "", stderr: `${head}${renderChecks(checks, theme)}` };
+}
+function print(repo) {
+    const plan = planGitHook(repo);
+    const lines = [
+        "dg guard-commit write plan",
+        "",
+        "No files are changed until you run dg guard-commit.",
+        `- write pre-commit hook: ${plan.context.hookTarget}`
+    ];
+    if (plan.willChain) {
+        lines.push("- back up + chain your existing hook so it still runs");
+    }
+    else if (plan.state === "managed") {
+        lines.push("- (a dg hook is already installed; it will be refreshed)");
+    }
+    lines.push("- record it for 'dg guard-commit off' / 'dg uninstall'");
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+function remove(repo, theme) {
+    const result = removeGitHookForRepo(repo);
+    if (result.found === 0) {
+        return {
+            exitCode: 0,
+            stdout: "",
+            stderr: `  ${theme.paint("muted", "no dg guard-commit hook in this repo")}\n`
+        };
+    }
+    const restored = result.removed.some((path) => path.includes(".dg-chained-"));
+    const note = restored ? ` ${theme.paint("muted", "(restored your previous hook)")}` : "";
+    return {
+        exitCode: 0,
+        stdout: "",
+        stderr: `  ${theme.paint("pass", "✓ removed dg commit guard")}${note}\n`
+    };
+}
+function renderChecks(checks, theme) {
+    return `${checks
+        .map((entry) => `    ${entry.ok ? theme.paint("pass", "✓") : theme.paint("block", "✘")} ${theme.paint("muted", entry.detail)}`)
+        .join("\n")}\n`;
+}

package/dist/commands/help.js

@@ -0,0 +1,74 @@
+const PRODUCT_DESCRIPTION = "Dependency Guardian supply-chain firewall CLI.";
+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) {
+    return command.summary.includes("prefix-mode routing");
+}
+export function renderRootHelp(version, commands, options = {}) {
+    const header = [
+        `dg ${version}`,
+        "",
+        PRODUCT_DESCRIPTION,
+        "",
+        "Usage:",
+        "  dg <command> [options]",
+        ""
+    ];
+    if (!options.all) {
+        const common = COMMON_COMMANDS
+            .map((name) => commands.find((command) => command.name === name))
+            .filter((command) => Boolean(command));
+        const lines = [
+            ...header,
+            "Protect installs:  dg npm install <pkg>      (or run 'dg setup' once)",
+            "Audit a project:   dg scan",
+            "",
+            "Common commands:"
+        ];
+        for (const command of common) {
+            lines.push(`  ${command.name.padEnd(12)} ${command.summary}`);
+        }
+        lines.push("", "Run 'dg <command> --help' for flags and examples, or 'dg --help-all' for every command.", GLOBAL_FLAGS_FOOTER);
+        return `${lines.join("\n")}\n`;
+    }
+    const wrappers = commands.filter(isWrapper);
+    const standalone = commands.filter((command) => !isWrapper(command));
+    const lines = [...header, "Commands:"];
+    for (const command of standalone) {
+        lines.push(`  ${command.name.padEnd(14)} ${command.summary}`);
+    }
+    lines.push("", "Package-manager prefix mode (run any through dg):", `  ${wrappers.map((command) => command.name).join(", ")}`);
+    lines.push("", "Run 'dg <command> --help' for that command's flags and examples.", GLOBAL_FLAGS_FOOTER);
+    return `${lines.join("\n")}\n`;
+}
+function column(rows) {
+    const width = Math.max(...rows.map((row) => row.left.length));
+    return rows.map((row) => `  ${row.left.padEnd(width)}  ${row.summary}`);
+}
+export function renderCommandHelp(command, path = [command.name]) {
+    const lines = [
+        `dg ${path.join(" ")}`,
+        "",
+        command.summary,
+        "",
+        "Usage:",
+        `  ${command.usage}`
+    ];
+    if (command.args && command.args.length > 0) {
+        lines.push("", "Arguments:", ...column(command.args.map((arg) => ({ left: arg.name, summary: arg.summary }))));
+    }
+    if (command.subcommands && command.subcommands.length > 0) {
+        lines.push("", "Subcommands:", ...column(command.subcommands.map((subcommand) => ({ left: subcommand.name, summary: subcommand.summary }))));
+    }
+    if (command.flags && command.flags.length > 0) {
+        lines.push("", "Flags:", ...column(command.flags.map((flag) => ({ left: flag.value ? `${flag.flag} ${flag.value}` : flag.flag, summary: flag.summary }))));
+    }
+    if (command.examples && command.examples.length > 0) {
+        lines.push("", "Examples:", ...command.examples.map((example) => `  ${example}`));
+    }
+    if (command.details.length > 0) {
+        lines.push("", ...command.details);
+    }
+    lines.push("", GLOBAL_FLAGS_FOOTER);
+    return `${lines.join("\n")}\n`;
+}