@vola-trebla/croak 0.0.0-stage → 0.1.0

package/dist/detectors/unscanned.js

@@ -0,0 +1,41 @@
+import { isInNodeModules } from "./node-modules-present.js";
+/** Code that a JS toolchain, an IDE, or git may execute or load. */
+const CODE = /\.(?:[cm]?[jt]sx?|json|sh|bash|zsh|py|rb|pl|ps1|gyp)$/;
+const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json"]);
+/** Type declarations are never executed, and lib.dom.d.ts alone is over 1 MB. */
+const DECLARATIONS = /\.d\.[cm]?ts$/;
+/**
+ * Safety floor: a code file too large to read was not scanned, so the repo is
+ * not clean. Padding a config past the read limit must not hide a payload.
+ */
+export function unscannedWith({ jsonIsData, downgradeInstalled, }) {
+    return (repo) => repo.entries
+        .filter((entry) => entry.kind === "oversized")
+        .filter((entry) => {
+        const name = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+        return (entry.path.startsWith(".git/") ||
+            /(?:^|\/)\.husky\//.test(entry.path) ||
+            (CODE.test(name) && !LOCKFILES.has(name) && !DECLARATIONS.test(name)));
+    })
+        .map((entry) => {
+        const name = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+        const data = jsonIsData && name.endsWith(".json") && name !== "package.json";
+        // Bundles over the limit are normal in installed dependencies; the
+        // presence of node_modules itself is flagged by repo/node-modules-present.
+        const installed = downgradeInstalled && isInNodeModules(entry.path);
+        return {
+            ruleId: "repo/unscanned",
+            severity: installed || data ? "info" : "warn",
+            file: entry.path,
+            message: data
+                ? `${entry.size} bytes exceeds the read limit; not scanned (JSON data, not executed)`
+                : installed
+                    ? `${entry.size} bytes exceeds the read limit; not scanned (installed dependency)`
+                    : `${entry.size} bytes exceeds the read limit; not scanned`,
+        };
+    });
+}
+export const unscanned = unscannedWith({
+    jsonIsData: false,
+    downgradeInstalled: true,
+});

package/dist/hook/hook.js

@@ -0,0 +1,391 @@
+import { posix } from "node:path";
+import { workspaceRoot } from "../install/workspace.js";
+import { parseYamlDocuments } from "../install/yaml.js";
+import { installIntents } from "./install-commands.js";
+export class HookInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HookInputError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The Bash command and directory from a PreToolUse event, or undefined for other tools. */
+function hookCommand(input) {
+    let data;
+    try {
+        data = JSON.parse(input);
+    }
+    catch {
+        throw new HookInputError("the hook input is not JSON");
+    }
+    if (!isRecord(data))
+        throw new HookInputError("the hook input is not an object");
+    if (data.tool_name !== "Bash")
+        return undefined;
+    const command = isRecord(data.tool_input)
+        ? data.tool_input.command
+        : undefined;
+    if (typeof command !== "string" ||
+        typeof data.cwd !== "string" ||
+        !data.cwd.startsWith("/"))
+        throw new HookInputError("the hook input has no Bash command or absolute cwd");
+    return { command, cwd: data.cwd };
+}
+/** Text that goes to the shell as one tab-separated field. */
+const SAFE = /^[^\t\n\r\0]+$/;
+const isSafeSpec = (spec) => SAFE.test(spec) && !spec.startsWith("-");
+/**
+ * npm's local prefix: the nearest directory, from `dir` up, with a
+ * package.json or a node_modules folder (as @npmcli/config does); `dir` itself
+ * when there is none. That is where npm installs, not where the agent is.
+ */
+function npmPrefix(dir, exists) {
+    for (let at = dir;; at = posix.dirname(at)) {
+        if (exists(posix.join(at, "package.json")) ||
+            exists(posix.join(at, "node_modules")))
+            return at;
+        if (at === "/")
+            return dir;
+    }
+}
+/**
+ * A registry that pnpm-workspace.yaml (pnpm 10+ settings) points pnpm at, or
+ * a setting there that runs the repo's code or trusts another server, or
+ * undefined.
+ */
+function workspaceRegistry(root, deps) {
+    const file = posix.join(root, "pnpm-workspace.yaml");
+    if (!deps.exists(file))
+        return undefined;
+    let docs;
+    try {
+        docs = parseYamlDocuments(deps.readFile(file));
+    }
+    catch {
+        return `${file} cannot be read`;
+    }
+    for (const doc of docs) {
+        if (!isRecord(doc))
+            continue;
+        for (const key of Object.keys(doc)) {
+            if (REGISTRY_KEY.test(key) ||
+                key === "registries" ||
+                key === "namedRegistries")
+                return `${file} sets ${key}`;
+            if (WORKSPACE_RUNNER_KEY.test(key))
+                return `${file} sets ${key}, which changes what pnpm runs or trusts`;
+        }
+    }
+    return undefined;
+}
+const PUBLIC_REGISTRY = /^https:\/\/registry\.npmjs\.org\/?$/;
+const REGISTRY_KEY = /(?:^|:)registry$|^replace-registry-host$/;
+/**
+ * Keys that load another config croak would not read, change what npm or
+ * pnpm runs scripts and git with, or let a proxy or certificate answer for
+ * the registry: with them, a warning the user approves would still run the
+ * repo's own shell, preload or binary, or packages croak never saw.
+ */
+const RUNNER_KEY = /^(?:userconfig|globalconfig|script-shell|node-options|shell|git|init-module|shell-emulator|global-pnpmfile|pnpmfile|proxy|https?-proxy|ca|cafile|cert|key|strict-ssl)$/;
+/**
+ * The same settings as pnpm-workspace.yaml writes them (M6 review): a shell or
+ * preload for scripts, a pnpmfile outside the project, and a proxy or
+ * certificate setting that lets another server answer for the registry.
+ */
+const WORKSPACE_RUNNER_KEY = /^(?:scriptShell|nodeOptions|shellEmulator|globalPnpmfile|proxy|https?Proxy|ca|cafile|cert|key|strictSsl|userconfig|globalconfig)$/;
+/** Where npm config sends npm somewhere croak does not check (D34), or undefined. */
+function foreignRegistry(prefix, deps) {
+    const env = Object.entries(deps.env ?? {});
+    // npm exports npm_config_userconfig when it launches a program; the file it
+    // names is checked like any other npmrc, rather than refused outright.
+    const named = env
+        .filter(([key]) => /^npm_config_(?:userconfig|globalconfig)$/i.test(key))
+        .map(([, value]) => value ?? "");
+    const project = posix.join(prefix, ".npmrc");
+    for (const file of [project, posix.join(deps.home, ".npmrc"), ...named]) {
+        if (file === "" || !deps.exists(file))
+            continue;
+        let text;
+        try {
+            text = deps.readFile(file);
+        }
+        catch {
+            return `${file} cannot be read`;
+        }
+        for (const raw of text.split("\n")) {
+            const line = raw.trim();
+            if (line === "" || /^[;#]/.test(line))
+                continue;
+            // ini sections group keys croak does not read: refuse rather than guess.
+            if (line.startsWith("["))
+                return `${file} uses [sections]`;
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            // Quotes around a key or value are stripped, as npm's ini parser does.
+            const unquote = (part) => part.trim().replace(/^(["'])(.*)\1$/, "$2");
+            const key = unquote(line.slice(0, eq));
+            const value = unquote(line.slice(eq + 1));
+            if (REGISTRY_KEY.test(key) && !PUBLIC_REGISTRY.test(value))
+                return `${file} sets ${key}`;
+            // The project's npmrc comes with the repo; the user's own files do not.
+            if (file === project && RUNNER_KEY.test(key))
+                return `${file} sets ${key}, which changes what npm runs or trusts`;
+        }
+    }
+    for (const [key, value] of env) {
+        const name = key.toLowerCase();
+        if (name.startsWith("npm_config_") &&
+            REGISTRY_KEY.test(name.slice(11).replace(/_/g, "-")) &&
+            !PUBLIC_REGISTRY.test(value ?? ""))
+            return `${key} is set`;
+    }
+    return undefined;
+}
+export function hookPlan(input, deps) {
+    const target = hookCommand(input);
+    if (target === undefined)
+        return { intents: [], checks: [] };
+    const intents = [];
+    const checks = [];
+    const unchecked = (command, reason) => {
+        intents.push({ kind: "unchecked", command, reason });
+    };
+    for (const intent of installIntents(target.command, target.cwd, deps.home)) {
+        if (intent.kind === "unchecked") {
+            intents.push(intent);
+            continue;
+        }
+        const packages = "packages" in intent ? intent.packages : [];
+        const manager = intent.manager ?? "npm";
+        const verb = manager === "pnpm"
+            ? {
+                install: "pnpm add",
+                update: "pnpm update",
+                ci: "pnpm install --frozen-lockfile",
+                run: "pnpm dlx",
+            }[intent.kind]
+            : {
+                install: "npm install",
+                update: "npm update",
+                ci: "npm ci",
+                run: "npx",
+            }[intent.kind];
+        const label = [verb, ...packages, "in", intent.dir].join(" ");
+        if (!SAFE.test(intent.dir) || !packages.every(isSafeSpec)) {
+            unchecked(label, "a package name or path in it cannot be checked safely");
+            continue;
+        }
+        if (!deps.exists(intent.dir)) {
+            unchecked(label, "its directory does not exist yet: create it in one command and install in the next, so croak can check the install");
+            continue;
+        }
+        const global = intent.kind === "install" && intent.global;
+        // A workspace installs at its root (D38): check there, with every member.
+        const local = npmPrefix(intent.dir, deps.exists);
+        const root = intent.kind === "run" || global
+            ? undefined
+            : workspaceRoot(local, manager, deps);
+        const prefix = root ?? local;
+        const registry = foreignRegistry(prefix, deps) ??
+            (manager === "pnpm" ? workspaceRegistry(prefix, deps) : undefined);
+        if (registry !== undefined) {
+            unchecked(label, `${manager} here uses a registry croak does not check (${registry}); croak checks the public npm registry only`);
+            continue;
+        }
+        if (manager === "npm" &&
+            intent.kind !== "run" &&
+            !global &&
+            deps.exists(posix.join(prefix, "npm-shrinkwrap.json"))) {
+            unchecked(label, "the project has an npm-shrinkwrap.json, which croak does not check yet");
+            continue;
+        }
+        let mode;
+        let specs = packages;
+        if (intent.kind === "ci")
+            mode = "ci";
+        else if (intent.kind === "run") {
+            // npx runs the prefix's own bin when it has one: no download.
+            // pnpm dlx always downloads.
+            specs = packages.filter((spec) => manager === "pnpm" ||
+                spec.includes("@", spec.startsWith("@") ? 1 : 0) ||
+                spec.includes("/") ||
+                !deps.exists(posix.join(prefix, "node_modules", ".bin", spec)));
+            if (specs.length === 0)
+                continue;
+            mode = "empty";
+        }
+        else if (global)
+            mode = "empty";
+        else if (deps.exists(posix.join(prefix, "package.json")))
+            mode = intent.kind === "update" ? "update" : "project";
+        else if (packages.length > 0)
+            mode = "empty";
+        else
+            continue; // npm install without a package.json installs nothing
+        intents.push(intent);
+        checks.push({
+            id: checks.length + 1,
+            manager,
+            mode,
+            // Where npm stands: croak-install finds the root itself, and checks
+            // that this folder is one of its members (M6 review).
+            dir: mode === "empty" ? intent.dir : local,
+            packages: specs,
+            label,
+        });
+    }
+    return { intents, checks };
+}
+/** One line per check for the shell: check <id> <manager> <mode> <dir> <package>… (tab-separated). */
+export function planLines(plan) {
+    return plan.checks
+        .map((c) => ["check", String(c.id), c.manager, c.mode, c.dir, ...c.packages].join("\t"))
+        .map((line) => `${line}\n`)
+        .join("");
+}
+const MAX_FINDINGS = 6;
+const DO_NOT_BYPASS = "Do not work around this check (another package manager, a different command, or editing files to install it); tell the user what croak found and let them decide.";
+/** One check's result as a verdict, with the findings worth showing. */
+function judge(result) {
+    // croak-install's own lines (and its did-you-mean hints) say more than npm's log.
+    const tail = (text) => {
+        const lines = text.trim().split("\n");
+        const own = lines.filter((l) => /^croak-install:|did you mean/.test(l.trim()));
+        return (own.length > 0 ? own : lines.slice(-4))
+            .map((l) => l.trim())
+            .join(" ")
+            .slice(0, 400);
+    };
+    if (result.code === 2 || result.code === undefined || result.code > 3)
+        return {
+            verdict: "block",
+            lines: [tail(result.stderr) || "croak-install could not run"],
+        };
+    let report;
+    try {
+        report = JSON.parse(result.stdout);
+    }
+    catch {
+        return {
+            verdict: "block",
+            lines: [
+                `the check did not finish: ${tail(result.stderr) || "no report"}`,
+            ],
+        };
+    }
+    if (!isRecord(report) || report.status !== "complete")
+        return {
+            verdict: "block",
+            lines: [
+                `the check is incomplete: ${isRecord(report) && typeof report.reason === "string" ? report.reason : "unknown reason"}`,
+            ],
+        };
+    const findings = Array.isArray(report.findings)
+        ? report.findings.filter(isRecord)
+        : [];
+    const shown = findings
+        .filter((f) => f.severity === "block" || f.severity === "warn")
+        .sort((a, b) => a.severity === b.severity ? 0 : a.severity === "block" ? -1 : 1);
+    const lines = shown
+        .slice(0, MAX_FINDINGS)
+        .map((f) => `${f.severity === "block" ? "🔴" : "🟡"} ${String(f.file)} ${String(f.ruleId)}: ${String(f.message)}`);
+    if (shown.length > MAX_FINDINGS)
+        lines.push(`…and ${shown.length - MAX_FINDINGS} more (run croak-install yourself to see all)`);
+    const verdict = report.verdict === "block" || report.verdict === "warn"
+        ? report.verdict
+        : "allow";
+    return { verdict, lines };
+}
+export function hookDecide(intents, results) {
+    const blocked = [];
+    const warned = [];
+    for (const intent of intents)
+        if (intent.kind === "unchecked")
+            blocked.push(`${intent.command.slice(0, 120)}: not checked, because ${intent.reason}.`);
+    for (const result of results) {
+        const { verdict, lines } = judge(result);
+        const entry = [
+            `${result.check.label}:`,
+            ...lines.map((l) => `  ${l}`),
+        ].join("\n");
+        if (verdict === "block")
+            blocked.push(entry);
+        else if (verdict === "warn")
+            warned.push(entry);
+    }
+    const output = (permissionDecision, reason) => ({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason: reason,
+        },
+    });
+    if (blocked.length > 0)
+        return output("deny", `🐸 croak blocked this command before it ran.\n${[...blocked, ...warned].join("\n")}\n${DO_NOT_BYPASS}`);
+    if (warned.length > 0)
+        return output("ask", `🐸 croak found things to review before this install runs (not a safe verdict):\n${warned.join("\n")}`);
+    return undefined;
+}
+/**
+ * `croak hook plan <input.json>` prints the plan: a `plan <json>` line, then
+ * the check lines. `croak hook decide <work>` reads that plan and each
+ * check's <id>.code / <id>.out / <id>.err from the work directory and prints
+ * the hook output, or nothing. Any error is the caller's cue to deny.
+ */
+export function runHook(args, deps) {
+    const [step, path] = args;
+    if (path === undefined || (step !== "plan" && step !== "decide"))
+        return {
+            code: 2,
+            stdout: "",
+            stderr: "usage: croak hook plan <input.json> | croak hook decide <work-dir>\n",
+        };
+    try {
+        return step === "plan" ? planStep(path, deps) : decideStep(path, deps);
+    }
+    catch (error) {
+        if (!(error instanceof HookInputError))
+            throw error;
+        return { code: 2, stdout: "", stderr: `${error.message}\n` };
+    }
+}
+function planStep(path, deps) {
+    const plan = hookPlan(deps.readFile(path), deps);
+    return {
+        code: 0,
+        stdout: `plan\t${JSON.stringify(plan)}\n${planLines(plan)}`,
+        stderr: "",
+    };
+}
+function decideStep(path, deps) {
+    const first = deps.readFile(posix.join(path, "plan")).split("\n")[0] ?? "";
+    if (!first.startsWith("plan\t"))
+        throw new HookInputError("the plan file is missing its plan line");
+    const plan = JSON.parse(first.slice("plan\t".length));
+    const read = (name) => {
+        try {
+            return deps.readFile(posix.join(path, name));
+        }
+        catch {
+            return undefined; // a missing result is judged as a check that did not run
+        }
+    };
+    const results = plan.checks.map((check) => {
+        const code = Number.parseInt(read(`${check.id}.code`) ?? "", 10);
+        return {
+            check,
+            code: Number.isNaN(code) ? undefined : code,
+            stdout: read(`${check.id}.out`) ?? "",
+            stderr: read(`${check.id}.err`) ?? "",
+        };
+    });
+    const output = hookDecide(plan.intents, results);
+    return {
+        code: 0,
+        stdout: output === undefined ? "" : `${JSON.stringify(output)}\n`,
+        stderr: "",
+    };
+}