@vola-trebla/croak 0.1.0 → 0.1.1

package/dist/signals/shell.js

@@ -1,12 +1,3 @@
-/**
- * A small, defensive shell parser for package.json scripts. It understands
- * quoting, pipes, command lists, `$(...)`, backticks, `<(...)`, subshells,
- * redirects, and `sh -c '...'` — enough to see what a script really runs,
- * without one fragile regex. It never executes anything.
- *
- * Linear scanning only; input length and nesting depth are capped so hostile
- * scripts cannot make it hang.
- */
 export const MAX_SCRIPT_LENGTH = 10_000;
 const MAX_DEPTH = 8;
 const DOWNLOADERS = new Set([
@@ -24,7 +15,6 @@ const DOWNLOADERS = new Set([
     "certutil",
     "bitsadmin",
 ]);
-/** Commands that execute code they are given via stdin, arguments, or files. */
 const INTERPRETERS = new Set([
     "sh",
     "bash",
@@ -75,7 +65,6 @@ const WRAPPERS = new Set([
     "setsid",
     "ionice",
 ]);
-/** Shell keywords that start or end a compound command, not a command name. */
 const RESERVED = new Set([
     "{",
     "}",
@@ -96,7 +85,6 @@ const RESERVED = new Set([
 ]);
 const PACKAGE_RUNNERS = new Set(["npm", "pnpm", "yarn"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
-/** Package-manager subcommands that are not package.json script names. */
 const PM_BUILTINS = new Set([
     "install",
     "i",
@@ -129,9 +117,7 @@ const PM_BUILTINS = new Set([
     "set",
     "help",
 ]);
-/** npm runs these scripts without `run`. */
 const NPM_SCRIPT_ALIASES = new Set(["test", "start", "stop", "restart"]);
-/** The package.json script a package-manager command runs, if any. */
 function scriptName(name, args) {
     if (!PACKAGE_RUNNERS.has(name) && name !== "bun")
         return undefined;
@@ -147,7 +133,6 @@ function scriptName(name, args) {
 }
 class ParseError extends Error {
 }
-/** Index just past the `close` that balances the opener before `start`. */
 function findClose(input, start, open, close) {
     let depth = 1;
     for (let i = start; i < input.length; i++) {
@@ -260,7 +245,6 @@ function parse(input, depth) {
         }
         else if (ch === '"') {
             const end = findDoubleQuoteEnd(input, i + 1);
-            // Inside double quotes, $(...) and backticks still run.
             const body = input.slice(i + 1, end);
             for (let j = 0; j < body.length; j++) {
                 if (body[j] === "\\") {
@@ -300,7 +284,6 @@ function parse(input, depth) {
             i = close;
         }
         else if (ch === "#" && !inWord) {
-            // A comment runs to the end of the line, quotes and all.
             const newline = input.indexOf("\n", i);
             i = (newline === -1 ? input.length : newline) - 1;
         }
@@ -308,7 +291,6 @@ function parse(input, depth) {
             !inWord &&
             words.length === 0 &&
             (next === " " || next === "\t" || next === "\n")) {
-            // { …; } groups commands like a subshell does.
             const close = findClose(input, i + 1, "{", "}");
             subshell = parse(input.slice(i + 1, close - 1), depth + 1);
             i = close - 1;
@@ -335,7 +317,6 @@ function parse(input, depth) {
             endPipeline();
         }
         else if (ch === ">" || ch === "<") {
-            // A leading fd number (2>) belongs to the redirect, not to a word.
             if (inWord && /^\d+$/.test(text) && subs.length === 0) {
                 text = "";
                 inWord = false;
@@ -359,14 +340,12 @@ function parse(input, depth) {
     endPipeline();
     return script;
 }
-// ---------------------------------------------------------------- analysis
 const basename = (path) => path.slice(path.lastIndexOf("/") + 1);
 const normalizeName = (word) => basename(word)
     .toLowerCase()
     .replace(/\.exe$/, "");
 const stripDot = (path) => path.startsWith("./") ? path.slice(2) : path;
 const urlFileName = (url) => basename(url.split(/[?#]/)[0] ?? "");
-/** The real command after env assignments and wrappers, with its arguments. */
 const NPX_LIKE = new Set(["npx", "pnpx", "bunx"]);
 const WORKSPACE_FLAGS = new Set([
     "-r",
@@ -379,7 +358,6 @@ const WORKSPACE_FLAGS = new Set([
     "-ws",
     "--if-present",
 ]);
-/** The real command after env assignments and wrappers, with its arguments. */
 function resolveCommand(command) {
     const words = [...command.words];
     const modifiers = [];
@@ -400,7 +378,6 @@ function resolveCommand(command) {
         if (WRAPPERS.has(name)) {
             words.shift();
             const flags = [];
-            // Skip wrapper flags (sudo -u user, nice -n 5, npx --yes).
             while (words[0]?.text.startsWith("-")) {
                 const flag = words.shift()?.text ?? "";
                 flags.push(flag);
@@ -409,10 +386,8 @@ function resolveCommand(command) {
                     words.shift();
                 }
             }
-            // timeout's first operand is the duration, not the command.
             if (name === "timeout" && /^\d/.test(words[0]?.text ?? ""))
                 words.shift();
-            // A bare npx runs a local bin; npx with flags or any other wrapper changes what runs.
             if (!NPX_LIKE.has(name) || flags.length > 0)
                 modifiers.push(`runs through ${name}${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`);
             continue;
@@ -459,7 +434,6 @@ function addLocal(acc, path) {
     if (!acc.localFiles.includes(clean))
         acc.localFiles.push(clean);
 }
-/** Files a downloader writes, so a later command that runs them is caught. */
 function downloadTargets(name, args, redirects) {
     const targets = [];
     const url = args.find((a) => /^[a-z]+:\/\//i.test(a.text))?.text ?? "";
@@ -468,7 +442,6 @@ function downloadTargets(name, args, redirects) {
         const flag = args[i]?.text ?? "";
         const value = args[i + 1]?.text;
         if (name === "curl") {
-            // -o FILE, also inside a cluster such as -sSLo FILE
             if ((flag === "--output" || /^-[a-zA-Z]*o$/.test(flag)) &&
                 value !== undefined)
                 targets.push(value);
@@ -476,7 +449,6 @@ function downloadTargets(name, args, redirects) {
                 targets.push(urlFileName(url));
         }
         if (name === "wget") {
-            // -O FILE, -qO FILE, -qO- (stdout), --output-document=FILE
             const cluster = /^-[a-zA-Z]*O(.*)$/.exec(flag);
             const long = flag.startsWith("--output-document")
                 ? (flag.split("=")[1] ?? value)
@@ -522,7 +494,6 @@ function walkCommand(command, acc, depth) {
     const script = scriptName(name, args);
     if (script !== undefined)
         acc.runScripts.push(script);
-    // Running a file the script downloaded earlier.
     if (acc.downloaded.has(stripDot(raw)) ||
         args.some((a) => INTERPRETERS.has(name) && acc.downloaded.has(stripDot(a.text)))) {
         acc.downloadExecute = true;
@@ -535,7 +506,6 @@ function walkCommand(command, acc, depth) {
     }
     const interpreter = INTERPRETERS.has(name);
     if (interpreter) {
-        // bash <(curl …), sh -c "$(curl …)", eval "$(curl …)"
         const fed = [...args, ...command.redirects.map((r) => r.target)].some((w) => w.subs.some(hasNetwork));
         if (fed)
             acc.downloadExecute = true;
@@ -543,7 +513,6 @@ function walkCommand(command, acc, depth) {
     if (raw.includes("/") && !interpreter && !downloader)
         addLocal(acc, raw);
     if (SHELLS.has(name)) {
-        // -c, also inside a cluster such as -ec or -xc
         const c = args.findIndex((a) => /^-[a-zA-Z]*c[a-zA-Z]*$/.test(a.text));
         const body = c === -1 ? undefined : args[c + 1];
         if (body !== undefined) {
@@ -595,7 +564,6 @@ function walkCommand(command, acc, depth) {
     }
     return { downloader, interpreter };
 }
-/** A command with a process substitution whose first command is an interpreter, as in `tee >(sh)`. */
 function feedsInterpreter(command) {
     return command.words.some((word) => word.subs.some((sub) => {
         const first = sub[0]?.[0];
@@ -608,7 +576,6 @@ function walkScript(script, acc, depth) {
         let downloaded = false;
         for (const command of pipeline) {
             const { downloader, interpreter } = walkCommand(command, acc, depth);
-            // curl … | sh, curl … | tee f | sh, curl … | tee >(sh)
             if ((interpreter || feedsInterpreter(command)) && downloaded)
                 acc.downloadExecute = true;
             if (downloader)
@@ -678,11 +645,6 @@ export function analyzeShell(command) {
         unparsable: false,
     };
 }
-/**
- * Commands in the order the shell would run them (pipelines and lists
- * flattened), for callers that need argument-level detail, such as the agent
- * hook. Undefined when the text cannot be parsed or is longer than maxLength.
- */
 export function shellCommands(input, maxLength = MAX_SCRIPT_LENGTH) {
     if (input.length > maxLength)
         return undefined;
@@ -695,8 +657,6 @@ export function shellCommands(input, maxLength = MAX_SCRIPT_LENGTH) {
             return undefined;
         throw error;
     }
-    // $(…) and backticks run before their command, in a subshell: each comes
-    // first as a group of its own, so an install inside one is seen.
     const flatten = (s) => s.flatMap((pipeline) => pipeline.flatMap((command) => {
         const subs = [
             ...command.words.flatMap((w) => w.subs),

package/dist/signals/text.js

@@ -1,2 +1 @@
-/** npm, VS Code, and most JSON readers ignore a leading UTF-8 byte-order mark. */
 export const stripBom = (text) => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;

package/dist/ui.js

@@ -1,4 +1,3 @@
-// Every icon is a single wide (2-column) emoji, so text after it stays aligned.
 export const VERDICT_ICON = {
     allow: "🟢",
     warn: "🟡",

package/dist/verdict.js

@@ -11,7 +11,6 @@ const SEVERITY_VERDICT = {
     warn: "warn",
     block: "block",
 };
-/** The verdict is the most severe finding; info findings and no findings mean allow. */
 export function aggregate(findings) {
     return findings.reduce((worst, finding) => {
         const verdict = SEVERITY_VERDICT[finding.severity];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vola-trebla/croak",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Croak before you install: a pre-execution gate for package installs, built for AI agents",
   "keywords": [
     "security",