@vola-trebla/croak 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vola-trebla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+# 🐸 croak
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Croak before you install.**
+
+`croak` checks what a package install — or an unfamiliar repo — is about to do
+**before any of its code runs on your machine**. It's built for AI coding agents
+first: when an agent reaches for `npm install`, croak stops it, explains why,
+and lets the agent fix its own mistake.
+
+> 🚧 **Status: early stage (0.x).** `croak repo`, the npm and pnpm install
+> checks, signature and provenance verification, the optional LLM layer and
+> the Claude Code hook work end to end, and each milestone since M1 has had a
+> security review. It is young software: use it, but don't make it your only
+> line of defense, and expect the CLI to change before 1.0. The
+> [roadmap](ROADMAP.md) shows what's done.
+
+---
+
+## 😱 The problem
+
+`npm install` doesn't just download code. It **runs** it: `postinstall`
+scripts, native builds, and whatever else a package decides to do — with your
+SSH keys, cloud tokens, `.env` files, and crypto wallets one `fs.readFile` away.
+
+And in 2026 this is happening constantly:
+- 📦 **Popular packages get hijacked.** A maintainer account is taken over, a
+  new version ships with a hidden dependency, its `postinstall` drops a remote
+  access trojan. It's live for hours before anyone notices.
+- 🤖 **AI agents install things without looking.** Models invent package names
+  that don't exist; attackers register those names and wait
+  (_slopsquatting_). The agent runs the install. Nobody reviews it.
+- 💼 **Fake job interviews.** "Here's our test assignment, just clone and run
+  `npm install`." The repo opens a VS Code task on folder open, or hides a
+  payload after 300 spaces in `tailwind.config.js`.
+- 🙈 **`--ignore-scripts` isn't enough.** Some attacks run through `binding.gyp`
+  and native builds, with no lifecycle scripts at all.
+
+## 🛂 What croak does
+
+Think of `npm install` as a courier whose parcels **unpack themselves**.
+croak is the customs officer at your door. It x-rays the contents as plain
+data and never lets anything inside run (how: [security model](docs/security-model.md)):
+
+|     | Check                                     | Catches                                                                                                                                      |
+| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔍  | **Does the sender exist?**                | hallucinated and typosquatted packages                                                                                                       |
+| ⚖️  | **What changed since the last delivery?** | a new dependency or install script that appeared in a patch release                                                                          |
+| 🩻  | **Will anything run on unpack?**          | `postinstall`, `binding.gyp`, prebuilt binaries, IDE autorun tasks                                                                           |
+| 🕵️  | **Is something hidden?**                  | obfuscated code, payloads in build configs                                                                                                   |
+| 🔏  | **Is the seal intact?**                   | a registry signature or [provenance](https://docs.npmjs.com/generating-provenance-statements) that doesn't verify, a build from another repo |
+| 🤖  | **Ask an expert (optional)**              | an LLM reviews the _diff_ between versions — and can only raise the alarm, never lower it                                                    |
+
+Then it gives a verdict — 🟢 **allow** (nothing suspicious found, not a
+guarantee), 🟡 **warn** (needs your attention, never "safe"), or 🔴 **block** — with
+reasons a human _and_ an agent can act on:
+
+```
+$ croak-install reactt-domm
+croak-install: a requested package does not exist on npm. Check the name:
+AI agents often invent plausible package names, and attackers register them.
+  reactt-domm: did you mean `react-dom`?
+
+$ croak-install esbuild
+croak plan - WARN
+  WARN   esbuild@0.28.2/package.json:10  repo/lifecycle-script
+           postinstall runs `node install.js` on install: network (install.js:93), process (install.js:95), decode (install.js:166)
+  INFO   package-lock.json  install/other-platform
+           25 package(s) built for other platforms not checked: npm will not install them on darwin-arm64
+```
+
+## 📦 Install and use
+
+```bash
+npm install -g @vola-trebla/croak   # Node 24.2+, macOS or Linux
+```
+
+Or once, without installing (fitting for a tool about installs: croak has
+no install scripts and one dependency, Anthropic's SDK):
+
+```bash
+npx @vola-trebla/croak repo ./that-test-assignment
+```
+
+### Two modes
+
+```bash
+croak-install [pkg]          # plan an npm install, check it before anything executes
+croak-install --pnpm [pkg]   # the same for pnpm
+croak repo .                 # scan an unfamiliar repo before you install or open it
+```
+
+Plus a **Claude Code hook** that puts croak in front of every install
+command an agent runs. Add it to `~/.claude/settings.json` (or a project's
+`.claude/settings.json`; croak never edits your config), with the path that
+`command -v croak-hook` prints:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/usr/local/bin/croak-hook",
+            "timeout": 300,
+            "onFailure": "block"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+🔴, an incomplete check, or a command croak cannot vouch for (yarn or bun, a
+custom registry, `npm i $PKG`, an `.npmrc` that points at a private
+registry) → the command is denied and the agent is told why;
+🟡 → Claude Code asks you; 🟢 → the hook stays silent and your normal
+permissions apply. `onFailure: "block"` matters: without it, Claude Code lets
+a command through when a hook crashes or times out. It needs Claude Code
+2.1.295 or later. The hook runs `node` from Claude Code's own PATH: if that
+finds a Node older than 24.2 (common with nvm when Claude Code starts from
+the desktop), every install is denied with a message saying so, so put
+Node 24 first on that PATH.
+
+**The AI layer (optional).** With `CROAK_LLM=1` and `ANTHROPIC_API_KEY` set
+(for the hook: in the environment Claude Code runs it with; for
+`croak plan`: `--llm`), croak asks Claude Haiku 5.5 about each package the
+rules only warned about, showing it what changed since the previous
+version. Its answer can only add a 🟡 or a 🔴, never remove one; without a
+key, or when the model fails, the rules decide alone. Only the diffs of
+public npm packages are sent, never your project's files. On croak's eval
+it turned four red-team variants of one decode-and-run payload from 🟡 into
+🔴 (none of their tricks fooled it) with no false alarms, and on 61 popular
+packages it added no blocks, for about $0.001 a package
+([eval/README.md](eval/README.md#llm-ablation-m5)).
+
+**`croak-install`** has npm resolve the install with `--package-lock-only
+--ignore-scripts` in an isolated temp directory (your project's lockfile is
+not touched), then `croak plan` checks every version that is not installed
+yet, transitive ones included (on a fresh clone, the whole lockfile): the lockfile (install scripts, sources, integrity),
+the registry (release age, provenance, publisher, look-alike names, brand-new
+packages and dependencies), the registry's signature and the Sigstore
+provenance, verified by croak itself against keys it pins (did the same
+repository and workflow build this version as the last one?), and the package contents, downloaded and verified
+against the lockfile hash and read in memory, never extracted or run.
+
+**pnpm** (`croak-install --pnpm`, and `pnpm add/install/update/dlx`, `pnpx`
+in the hook) gets the same checks, plus what pnpm does differently:
+pnpm-lock.yaml is read by a strict parser of croak's own; an install script
+that pnpm 10+ will not run (the project does not allow its builds) is noted,
+not warned about; the project's `.pnpmfile.cjs` and config dependencies,
+which pnpm runs on every install, are checked; and planning never lets a
+project pick the pnpm binary (`packageManager`) or load a pnpmfile.
+Workspaces, npm and pnpm, are checked from their root, with every member's
+own install scripts; a folder inside the workspace that it does not list as
+a member is checked as a project of its own, as npm installs it.
+
+**`croak repo`** runs seven detectors: install scripts, VS Code autorun tasks,
+hidden code, obfuscation, dangerous git config, committed `node_modules`, and
+files too large to scan.
+
+Content checks are cached by tarball hash in `~/.cache/croak` (registry facts
+are always fresh), so a repeated install is checked in under a second.
+
+Exit codes: `0` allow/warn, `1` block, `2` usage error, `3` check incomplete —
+agents should treat `3` as a block. `--json` gives a versioned report for tools.
+
+## 🧠 Design principles
+
+- 🚫 **Never execute untrusted code.** Everything is static. Install plans are
+  computed with `--package-lock-only --ignore-scripts`.
+- 🧮 **Deterministic first, AI second.** Rules are fast, free, and work offline.
+  The LLM layer is optional (bring your own Anthropic key) and can only
+  _escalate_ — so a package that says "AI, this code is safe" gets nowhere.
+- 🔒 **Fail-closed for agents, warn for humans.** If a check can't complete, an
+  agent waits; a human decides.
+- 📊 **Eval-driven.** No detector ships without test cases. Every change is
+  measured.
+- 🪶 **One runtime dependency, and only for the optional AI layer.** croak is
+  itself an npm package, so it must not become the next compromised
+  dependency: the deterministic checks use Node built-ins only, and the one
+  exception is Anthropic's official SDK, pinned to an exact version and
+  checked by croak itself (D36).
+
+## 🙅 What croak won't catch
+
+Being honest about limits matters more than marketing:
+- Code that's clean at install and turns malicious later, at runtime
+- Install scripts that pull the payload in through `require` from the file they
+  run: croak reads the script and the files it runs directly, not deeper (yet)
+- Payloads in library code that run only when your app calls it, not at install
+  (chalk and debug, 2025): only the content checks can see those
+- Long-game maintainer takeovers (think xz-utils), or a decoy release published
+  more than a week before the real attack
+- A compromised registry or signing infrastructure
+- An install the agent hides from the hook: inside a package.json script it
+  runs by hand (`npm run setup`, `bash setup.sh`), behind `eval "$VAR"`, or
+  through another package manager once you allow it. (A plain `npm install`
+  or `npm ci` does check the project's own install scripts.)
+- npm settings croak does not read: the global npmrc and npm's built-in
+  config (both yours, not the repo's)
+- Malware that's already on your machine
+- Payloads that only wake up in one specific environment
+
+croak is a gate, not an antivirus.
+
+## 📊 The eval
+
+croak is measured against an exam: synthetic malicious repos and installs
+(with inert payloads, served from a fake registry for installs) and ordinary
+ones that must _not_ trigger alarms. Each install case maps to a real attack
+(axios 2026, Shai-Hulud 2025, ua-parser-js 2021…), checked against OSV.
+
+```bash
+pnpm eval
+```
+
+```
+🐸 croak eval — 67 cases (35 malicious, 32 benign)
+  …
+  block recall  26/35   74%  ███████████████░░░░░
+  flag recall   35/35  100%  ████████████████████
+  false alarms   0/32    0%  ░░░░░░░░░░░░░░░░░░░░
+  rule recall   52/52  100%  ████████████████████
+```
+
+Synthetic cases are written by us, so two more runs check the noise on code we
+did not write: 13 pinned real-world repositories (`pnpm corpus`) and 61 pinned
+popular npm packages (`pnpm corpus:packages`: 0 blocks; the warnings are
+fresh releases and real install scripts). A case that ever passed is not
+allowed to fail again. Format, metrics and the real attacks behind each case:
+[eval/README.md](eval/README.md).
+
+## 🗺️ Roadmap
+
+|     | Milestone                                                                   |
+| --- | --------------------------------------------------------------------------- |
+| ✅  | **M0** — foundation: TypeScript, tests, CI, supply-chain-hardened workflows |
+| ✅  | **M1** — eval first: case format, runner, metrics, regression guard         |
+| ✅  | **M2** — `croak repo`: autorun configs, hidden code, obfuscation            |
+| ✅  | **M3** — npm install plans, registry and package-content signals            |
+| ✅  | **M4** — Claude Code hook, agent-friendly verdicts                          |
+| ✅  | **M5** — LLM triage of version diffs (Haiku by default)                     |
+| ✅  | **M6** — pnpm and workspaces                                                |
+| ✅  | **M7** — registry signatures + provenance verification                      |
+| ⏳  | **M8** — public release                                                     |
+| 💭  | Later: Python, shared signed verdicts, tarball vs source (D44)              |
+
+Details in [ROADMAP.md](ROADMAP.md); the reasoning behind every choice is in
+[docs/decisions.md](docs/decisions.md).
+
+## 🛠️ Development
+
+```bash
+nvm use                               # Node 24.2+
+pnpm install
+git config core.hooksPath .githooks   # pre-commit + pre-push checks
+pnpm check                            # lint + typecheck + invariants + tests
+pnpm eval                             # run the eval
+pnpm corpus:fetch && pnpm corpus      # false-alarm check on real repos (network)
+pnpm corpus:packages                  # false-alarm check on real npm packages (network)
+pnpm croak repo <path>                # run croak from source
+```
+
+Working with an AI agent on this repo? Start with [CLAUDE.md](CLAUDE.md).
+
+## 🎓 Origin story
+
+In 2013 I wrote a university thesis on elliptic-curve cryptography: point
+addition, Diffie–Hellman, a little C# client-server app. I didn't really get
+why any of it mattered.
+
+In 2026, those same curves sign the provenance of npm packages — and someone
+sent me a "test assignment" that I had an AI agent inspect before installing.
+It told me not to touch it.
+
+croak is what that thesis turns into thirteen years later.
+
+## 📄 License
+
+[MIT](LICENSE). Found a way around croak? See [SECURITY.md](SECURITY.md).

package/dist/cli.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, posix } from "node:path";
+import { parseArgs } from "node:util";
+import { runHook } from "./hook/hook.js";
+import { codeFingerprint, fileContentCache, } from "./install/content-cache.js";
+import { installedLockfile, installedPnpmLockfile, } from "./install/installed.js";
+import { suggestNames } from "./install/metadata.js";
+import { pnpmBuildPolicy } from "./install/pnpm-builds.js";
+import { isPnpmLockfile, parsePnpmLockfile } from "./install/pnpm-lockfile.js";
+import { pnpmfileFindings, projectScriptFindings, workspaceMembers, } from "./install/project.js";
+import { planToJson, renderPlan } from "./install/report.js";
+import { SanitizeError, sanitizePnpmWorkspace, sanitizeRootManifest, } from "./install/sanitize.js";
+import { planInstall, planInstallOnline, } from "./install/scan.js";
+import { workspaceRoot } from "./install/workspace.js";
+import { anthropicTriage, DEFAULT_MODEL } from "./llm/client.js";
+import { renderScan, scanToJson } from "./repo-report.js";
+import { ScanTargetError, scanRepoAt } from "./scan.js";
+import { aggregate } from "./verdict.js";
+export const VERSION = "0.1.0";
+/**
+ * 0 allow or warn (warnings are printed, the process succeeds),
+ * 1 block, 2 usage error, 3 the scan could not complete — agents treat 3 as
+ * a block (fail-closed).
+ */
+export const EXIT = { ok: 0, block: 1, usage: 2, incomplete: 3 };
+/** Conventional exit code for invalid command-line usage. */
+export const EXIT_USAGE = EXIT.usage;
+const DEFAULT_DEPS = {
+    scan: (root) => scanRepoAt(root),
+    emoji: false,
+};
+const HELP = `croak 🐸 — croak before you install
+
+Usage:
+  croak plan --after <lock> [--before <lock|none> | --installed <project>] [--project <dir>] [--member <dir>] [--llm]
+             [--pnpm-builds <dir> [--pnpm-version <v>]]
+             [--offline | --metadata-only] [--no-cache]
+                         judge an install from the lockfile npm planned
+  croak repo [path]      scan a repo before you install or open it (default: .)
+  croak hook plan|decide the Claude Code hook's steps (used by croak-hook)
+  croak --version
+  croak --help
+
+Options for repo:
+  --json                 machine-readable report
+  --plain                no emoji, even in a terminal
+
+Exit codes: 0 allow/warn · 1 block · 2 usage error · 3 scan incomplete
+`;
+function isParseArgsError(error) {
+    return (error instanceof TypeError &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code.startsWith("ERR_PARSE_ARGS_"));
+}
+function parse(argv) {
+    return parseArgs({
+        args: [...argv],
+        options: {
+            version: { type: "boolean", short: "v" },
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            plain: { type: "boolean" },
+            before: { type: "string" },
+            after: { type: "string" },
+            offline: { type: "boolean" },
+            "metadata-only": { type: "boolean" },
+            "no-cache": { type: "boolean" },
+            installed: { type: "string" },
+            project: { type: "string" },
+            member: { type: "string" },
+            llm: { type: "boolean" },
+            "pnpm-builds": { type: "string" },
+            "pnpm-version": { type: "string" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+}
+const usageError = (message) => ({
+    code: EXIT.usage,
+    stdout: "",
+    stderr: `croak: ${message}\n\n${HELP}`,
+});
+function exitCode(outcome) {
+    if (outcome.status === "incomplete")
+        return EXIT.incomplete;
+    return outcome.verdict === "block" ? EXIT.block : EXIT.ok;
+}
+async function runPlan(values, rest, deps) {
+    if (rest.length > 0)
+        return usageError(`plan takes no positional arguments, got ${rest.length}`);
+    if (values.after === undefined)
+        return usageError("plan needs --after <lockfile>");
+    const read = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
+    const load = (path) => {
+        try {
+            return read(path);
+        }
+        catch (error) {
+            return usageError(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const after = load(values.after);
+    if (typeof after !== "string")
+        return after;
+    let before;
+    if (values.installed !== undefined && values.before !== undefined)
+        return usageError("plan takes --before or --installed, not both");
+    if (values.installed !== undefined) {
+        // What is really in node_modules, verified folder by folder (D34).
+        const tryRead = (path) => {
+            try {
+                return read(path);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        // The installed tree of the manager that wrote the plan (D38).
+        before = isPnpmLockfile(after)
+            ? installedPnpmLockfile(values.installed, tryRead, (dir) => {
+                try {
+                    return readdirSync(dir);
+                }
+                catch {
+                    return [];
+                }
+            }, parsePnpmLockfile)
+            : installedLockfile(values.installed, tryRead);
+    }
+    else if (values.before !== undefined && values.before !== "none") {
+        const text = load(values.before);
+        if (typeof text !== "string")
+            return text;
+        before = text;
+    }
+    // pnpm's own rule for whose install scripts run, from the project's settings (D38).
+    const buildsDir = values["pnpm-builds"];
+    const builds = buildsDir === undefined || values["pnpm-version"] === undefined
+        ? undefined
+        : pnpmBuildPolicy({
+            packageJson: (() => {
+                try {
+                    return read(`${buildsDir}/package.json`);
+                }
+                catch {
+                    return undefined;
+                }
+            })(),
+            workspaceYaml: (() => {
+                try {
+                    return read(`${buildsDir}/pnpm-workspace.yaml`);
+                }
+                catch {
+                    return undefined;
+                }
+            })(),
+        }, values["pnpm-version"]);
+    // --offline: lockfile signals only, no registry requests (tests, air-gapped CI).
+    const outcome = values.offline === true
+        ? planInstall(before, after)
+        : await planInstallOnline(before, after, {
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+            ...(deps.cache === undefined || values["no-cache"] === true
+                ? {}
+                : { cache: deps.cache }),
+            content: values["metadata-only"] !== true,
+            ...(builds === undefined ? {} : { builds }),
+            ...(values.llm === true && deps.llm !== undefined
+                ? { llm: deps.llm }
+                : {}),
+        });
+    // --llm without a key: the rules decide, and the report says the model did not run.
+    const llmMissing = values.llm === true && deps.llm === undefined && values.offline !== true
+        ? [
+            {
+                ruleId: "llm/triage",
+                severity: "info",
+                file: "croak",
+                message: "--llm was asked for, but ANTHROPIC_API_KEY is not set: rules only",
+            },
+        ]
+        : [];
+    const tryRead = (path) => {
+        try {
+            return read(path);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const projectFs = {
+        read: tryRead,
+        kind: (path) => {
+            try {
+                const stats = lstatSync(path);
+                const kind = stats.isSymbolicLink()
+                    ? "symlink"
+                    : stats.isFile()
+                        ? "file"
+                        : "other";
+                return { kind, size: stats.size };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+    // A plain npm install or npm ci also runs the project's own install scripts
+    // (D35); pnpm runs the project's pnpmfile and config dependencies on every
+    // install (D39).
+    const project = values.project;
+    const extra = [
+        ...llmMissing,
+        // The pnpmfile check needs only the project; the version is for the build rule.
+        ...(buildsDir === undefined ? [] : pnpmfileFindings(buildsDir, projectFs)),
+        ...(project === undefined || outcome.status !== "complete"
+            ? []
+            : projectScriptFindings(project, projectFs, {
+                // The plan's lockfile parsed, so its members can be read (M6 review).
+                members: workspaceMembers(after),
+                pnpm: buildsDir !== undefined,
+            })),
+    ];
+    // The folder the install ran in must be a member of the workspace the plan
+    // was made at; otherwise the package manager installs elsewhere (M6 review).
+    const member = values.member;
+    const notMember = member !== undefined &&
+        outcome.status === "complete" &&
+        !workspaceMembers(after).includes(posix.normalize(member));
+    const judged = notMember
+        ? {
+            status: "incomplete",
+            reason: `${member} is inside a workspace that does not list it as a member, so the install would not run where croak planned it`,
+            durationMs: outcome.durationMs,
+        }
+        : outcome.status !== "complete" || extra.length === 0
+            ? outcome
+            : (() => {
+                const findings = [...extra, ...outcome.findings];
+                return { ...outcome, findings, verdict: aggregate(findings) };
+            })();
+    const stdout = values.json === true
+        ? planToJson(judged)
+        : renderPlan(judged, { emoji: deps.emoji && values.plain !== true });
+    return { code: exitCode(judged), stdout, stderr: "" };
+}
+/** Pure entry point: all I/O goes through deps. */
+export async function run(argv, deps = DEFAULT_DEPS) {
+    // What the planning wrapper may hand to pnpm from an untrusted project (D38).
+    if (argv[0] === "sanitize") {
+        const [, kind, file] = argv;
+        if (file === undefined ||
+            (kind !== "root-manifest" && kind !== "pnpm-workspace"))
+            return usageError("usage: croak sanitize root-manifest|pnpm-workspace <file>");
+        const read = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
+        try {
+            const text = read(file);
+            return {
+                code: EXIT.ok,
+                stdout: kind === "root-manifest"
+                    ? sanitizeRootManifest(text)
+                    : sanitizePnpmWorkspace(text),
+                stderr: "",
+            };
+        }
+        catch (error) {
+            if (error instanceof SanitizeError)
+                return usageError(error.message);
+            throw error;
+        }
+    }
+    // The workspace root croak-install plans at (D38): the same reading as the hook's.
+    if (argv[0] === "workspace-root") {
+        const [, manager, dir] = argv;
+        if (dir === undefined || (manager !== "npm" && manager !== "pnpm"))
+            return usageError("usage: croak workspace-root npm|pnpm <dir>");
+        const root = workspaceRoot(dir, manager, {
+            exists: existsSync,
+            readFile: deps.readFile ?? ((path) => readFileSync(path, "utf8")),
+        });
+        return {
+            code: EXIT.ok,
+            stdout: root === undefined ? "" : `${root}\n`,
+            stderr: "",
+        };
+    }
+    // Suggestions for package names npm does not have (croak-install on E404).
+    if (argv[0] === "suggest") {
+        const lines = argv.slice(1).flatMap((spec) => {
+            const names = suggestNames(decodeURIComponent(spec));
+            return names.length === 0
+                ? []
+                : [
+                    `  ${spec}: did you mean ${names.map((n) => `\`${n}\``).join(", ")}?\n`,
+                ];
+        });
+        return { code: EXIT.ok, stdout: lines.join(""), stderr: "" };
+    }
+    // The agent hook's two steps (scripts/croak-hook.sh); they read files only.
+    if (argv[0] === "hook")
+        return runHook(argv.slice(1), {
+            readFile: deps.readFile ?? ((path) => readFileSync(path, "utf8")),
+            exists: existsSync,
+            home: homedir(),
+            env: process.env,
+        });
+    let parsed;
+    try {
+        parsed = parse(argv);
+    }
+    catch (error) {
+        // Usage mistakes are explained, not crashed on; anything else is a bug.
+        if (!isParseArgsError(error))
+            throw error;
+        return usageError(error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.version === true)
+        return { code: EXIT.ok, stdout: `${VERSION}\n`, stderr: "" };
+    const [command, ...rest] = positionals;
+    if (values.help === true || command === undefined) {
+        return { code: EXIT.ok, stdout: HELP, stderr: "" };
+    }
+    if (command === "plan")
+        return await runPlan(values, rest, deps);
+    if (command !== "repo")
+        return usageError(`unknown command "${command}"`);
+    if (rest.length > 1)
+        return usageError(`repo takes one path, got ${rest.length}`);
+    let outcome;
+    try {
+        outcome = deps.scan(rest[0] ?? ".");
+    }
+    catch (error) {
+        if (!(error instanceof ScanTargetError))
+            throw error;
+        return usageError(error.message);
+    }
+    const stdout = values.json === true
+        ? scanToJson(outcome)
+        : renderScan(outcome, { emoji: deps.emoji && values.plain !== true });
+    return { code: exitCode(outcome), stdout, stderr: "" };
+}
+// Only touch the process when executed directly, not when imported by tests.
+if (import.meta.main) {
+    // Built on first use: fingerprinting croak's code costs a directory read.
+    let cache;
+    const contentCache = () => {
+        cache ??= fileContentCache(join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "croak", "content"), codeFingerprint(import.meta.dirname));
+        return cache;
+    };
+    const key = process.env.ANTHROPIC_API_KEY;
+    const result = await run(process.argv.slice(2), {
+        scan: (root) => scanRepoAt(root),
+        emoji: process.stdout.isTTY === true,
+        ...(key === undefined || key === ""
+            ? {}
+            : {
+                llm: { model: DEFAULT_MODEL, triage: anthropicTriage(key) },
+            }),
+        cache: {
+            get: (integrity, label) => contentCache().get(integrity, label),
+            set: (integrity, label, findings) => contentCache().set(integrity, label, findings),
+        },
+    });
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.code;
+}