@molecule/api-ai-tools 1.11.0 → 1.12.0

package/dist/utilities.js

@@ -5,7 +5,7 @@
  * @module
  */
 import { posix } from 'path';
-import { commandSegments, locatedCommandSegments, statementArgumentEnd, withoutTimeoutWrapper, } from './command-position.js';
+import { commandSegments, executedCommands, locatedCommandSegments, statementArgumentEnd, withoutTimeoutWrapper, } from './command-position.js';
 import { classifyRunFailure } from './failure-kind.js';
 import { commandRunsNoTests } from './no-test-run.js';
 import { isDiagnosisRun, scopedRerunCommand, suiteCommandTarget, suiteRunInTheWay, withoutHeredocs, withSuiteConfig, } from './suite-overlap.js';
@@ -163,8 +163,41 @@ export function redactSecrets(s) {
 export function redactSecretsInCode(s) {
     return s.replace(SECRET_ENV_ASSIGNMENT, '$1=[REDACTED]');
 }
+/**
+ * The placeholder the output filter substitutes for a hidden value. Copying it into
+ * application configuration changes the value rather than recovering it. The write
+ * tools check for added occurrences ({@link addedRedactionMask}); intentional literals
+ * require the caller's explicit per-call declaration.
+ *
+ * Only the shapes a value can take count: quoted (`'[REDACTED]'`, `"[REDACTED]"`) or
+ * assigned (`=[REDACTED]`). Prose that mentions the token is ordinary text.
+ */
+const REDACTION_MASK = /'\[REDACTED\]'|"\[REDACTED\]"|=[ \t]*\[REDACTED\]/g;
+/**
+ * The redaction mask `next` adds over `previous`, or null when it adds none.
+ *
+ * `previous` is the file's previous content for `write_file`, and the replacement's own
+ * `old_string` for `edit_file` — an edit that carries an existing mask through (a file that
+ * already had one, read back and rewritten) adds no occurrence. A new occurrence may
+ * be copied output or intentional source; the caller declares the latter explicitly.
+ *
+ * @param next - The content about to be written (or the replacement's `new_string`).
+ * @param previous - The content it replaces, already on disk (or the `old_string`).
+ * @returns The added mask as written (`'[REDACTED]'`, `"[REDACTED]"`, `=[REDACTED]`), or null.
+ */
+export function addedRedactionMask(next, previous) {
+    const before = previous.match(REDACTION_MASK)?.length ?? 0;
+    const after = next.match(REDACTION_MASK) ?? [];
+    if (after.length <= before)
+        return null;
+    return after[before] ?? after[0] ?? '[REDACTED]';
+}
 /** Source-file extensions a printing command's output is read as code for. */
 const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?|css|scss|html|vue|svelte|md|sql|hurl)$/;
+/** Programs whose output is file NAMES or counts, never another file's content. */
+const INSPECTION_PROGRAMS = new Set(['find', 'ls', 'wc']);
+/** `find` options that run a program or write a file — not read-only inspection. */
+const FIND_NOT_INSPECTION = /^-(?:exec|execdir|ok|okdir|delete|fls|fprint|fprint0|fprintf)/;
 /**
  * A literal argument, not a shell expansion. The shared parser owns statement boundaries;
  * this deliberately small word grammar only decides whether an argument can read other data.
@@ -253,9 +286,46 @@ function sourcePrintFiles(program, args) {
  * @returns True when the command prints source files, with only literal headings and filters.
  */
 export function printsOnlySource(command) {
+    return printsOnly(command, false);
+}
+/**
+ * Whether a shell command only INSPECTS the workspace WITHOUT printing a file's contents:
+ * it prints source files (a pure literal read, {@link printsOnlySource}), lists names
+ * (`ls`, `find`), or counts lines (`wc`) — joined by `;`, `&&` or `|`, with literal
+ * `echo`/`printf` headings and `cd`.
+ *
+ * Its output is code or names, not an env dump, so it gets the code-safe redaction
+ * ({@link redactSecretsInCode}) instead of the name-keyed env-dump passes. Without this,
+ * ordinary code values such as `tokenKey: 'jwtToken'` in a mixed source read and
+ * `ls | head` command would be masked by the environment-dump rules.
+ *
+ * A RECURSIVE SEARCH IS NOT INSPECTION (`grep -rn x .`, `rg x src/`): its output is the
+ * content of whichever files matched, including `.env` files and JSON secret dumps, so it
+ * keeps the full grade. A path with no extension is not evidence that it is a directory —
+ * `/dev/stdin` and an ordinary `secrets` file read the same way.
+ *
+ * Env dumps keep the full grade: `.env` anywhere in the command, `env`/`printenv`, a
+ * non-literal or redirecting form, and an interpreter one-liner (`node -e`, `python -c`)
+ * all return false.
+ *
+ * @param command - The shell command.
+ * @returns True when the command only reads or lists workspace content.
+ */
+export function isReadOnlyInspection(command) {
+    return printsOnly(command, true);
+}
+/**
+ * The one segment grammar both grades share: literal words only, no wrapper or group, no
+ * backgrounding, and every byte between segments a separator.
+ *
+ * @param command - The shell command.
+ * @param inspection - Also accept name/count listing (`ls`, `find`, `wc`).
+ * @returns True when every segment is allowed and at least one prints something.
+ */
+function printsOnly(command, inspection) {
     if (/\.env\b/.test(command))
         return false;
-    let readsSource = false;
+    let prints = false;
     let previousEnd = 0;
     for (const located of locatedCommandSegments(command)) {
         const { segment, start, end, programOffset, separator, terminator } = located;
@@ -302,6 +372,13 @@ export function printsOnlySource(command) {
                 return false;
             }
         }
+        else if (inspection && INSPECTION_PROGRAMS.has(program) && separator !== '|') {
+            // Names and counts only — nothing here can be another file's content. `find` is the
+            // exception that can run a program or write a file.
+            if (program === 'find' && args.some((arg) => FIND_NOT_INSPECTION.test(arg)))
+                return false;
+            prints = true;
+        }
         else {
             const filter = separator === '|';
             if (!(filter ? /^(?:head|tail|sort|uniq|wc|cut|nl|grep)$/ : /^(?:cat|head|tail|nl|sed|grep|rg)$/).test(program)) {
@@ -319,11 +396,11 @@ export function printsOnlySource(command) {
                     !files.every((file) => !file.startsWith('-') && SOURCE_FILE_RE.test(file))) {
                     return false;
                 }
-                readsSource = true;
+                prints = true;
             }
         }
     }
-    return readsSource && /^[\s;]*$/.test(command.slice(previousEnd));
+    return prints && /^[\s;]*$/.test(command.slice(previousEnd));
 }
 /**
  * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
@@ -1301,30 +1378,127 @@ export function suiteRunPriorityLaunch(command, launch) {
     };
 }
 // ── Command blocking ──────────────────────────────────────────────────────────
+/** A word with one layer of matching shell quotes removed (`"/proc/self/environ"` → `/proc/self/environ`). */
+function shellWord(word) {
+    return word.replace(/^(['"])(.*)\1$/, '$2');
+}
+/** `/proc/<pid>/environ` and `/proc/self/environ` — a process's environment, as the kernel exposes it. */
+const PROC_ENVIRON = /^\/proc\/(?:\d+|self)\/environ(?:\/|$)/;
+/** Anything under `/proc`: a process's environment is one of the files there. */
+const PROC_PATH = /^\/proc(?:\/|$)/;
+/** The molecule platform's secrets dir — `/etc/mol/env` carries the vault + platform secrets. */
+const MOL_SECRETS = /^\/etc\/mol(?:\/|$)/;
+/**
+ * Whether one executed command reads a file that would print a process's environment or the
+ * platform's secrets.
+ *
+ * This is asked of the commands the shell RUNS ({@link executedCommands}), never of the command
+ * text: a file path quoted inside a grep pattern (`grep -E "ENV|/etc/mol" src`) is data a
+ * comparison reads, not a file this command opens. The shapes below are the ones that print:
+ * `cat` and its siblings of a `/proc/<pid>/environ`, a redirect's path handed to a reader
+ * (`xxd < /proc/self/environ`), and reads of `/etc/mol`, which is an env-dump by another door.
+ *
+ * @param program - The command's program, directory removed.
+ * @param args - Its arguments, as written.
+ * @returns True when the command reads one of those files.
+ */
+function readsSecretFile(program, args) {
+    const words = args.map(shellWord);
+    const first = words[0] ?? '';
+    switch (program) {
+        case 'cat':
+            return words.some((word) => /^\/etc\/environment(?:\/|\.|$)/.test(word) ||
+                word.startsWith('/root/.bashrc') ||
+                PROC_ENVIRON.test(word) ||
+                MOL_SECRETS.test(word));
+        case 'sed':
+        case 'awk':
+        case 'cp':
+            return words.some((word) => PROC_ENVIRON.test(word) || MOL_SECRETS.test(word));
+        case 'xargs':
+            return words.some((word) => PROC_ENVIRON.test(word));
+        case 'dd':
+            // `dd if=/proc/1/environ` carries the path inside its own argument.
+            return words.some((word) => /\/proc(?:\/|$)/.test(word) || MOL_SECRETS.test(word));
+        case 'base64':
+        case 'head':
+        case 'less':
+        case 'od':
+        case 'strings':
+        case 'tail':
+        case 'xxd':
+            return PROC_PATH.test(first) || words.some((word) => MOL_SECRETS.test(word));
+        default:
+            return false;
+    }
+}
 /**
- * Commands that dump environment variables — blocked to prevent secret leakage.
- * Also covers reads of `/etc/mol/…` (the molecule platform's secrets dir —
- * `/etc/mol/env` carries the vault + platform secrets inside a sandbox),
- * which is an env-dump by another door.
+ * Whether one executed command prints the environment instead of running something in it.
  *
- * `env` counts only when it DUMPS: bare, or with the `-0` / `--null` output
- * flags, followed by the end of the command or a separator / pipe / redirect.
- * `env -u KEY cmd`, `env KEY=value cmd` and `env -i cmd` run a command with a
- * changed environment and print nothing; an executor reaches for them to prove
- * a keyless build still succeeds, and blocking those sent it looking for
- * workarounds (X0 rehearsal 14).
+ * `env` counts only when it DUMPS: {@link executedCommands} reports it as the program only when
+ * nothing follows it, because `env -u KEY cmd`, `env KEY=value cmd` and `env -i cmd` run `cmd`
+ * with a changed environment and print nothing — an executor reaches for them to prove a keyless
+ * build still succeeds, and blocking those sent it looking for workarounds (X0 rehearsal 14).
+ * `export` / `set` / `declare` print every variable they carry when given nothing to set.
+ *
+ * @param program - The command's program, directory removed.
+ * @param args - Its arguments, as written.
+ * @returns True when the command prints the environment.
  */
-// `(?<!\\)`: a backslash-escaped `\|` is a literal in the shell (grep "a\|env"), not a pipe (X1 flash-m58).
-const BLOCKED_COMMANDS = /(?<!\\)(?:^|[;&|`]\s*|(?:sh|bash|zsh|dash)\s+-c\s+['"]?\s*)(?:\/usr\/bin\/)?(?:\benv(?:\s+(?:-0|--null|--))?\s*(?:$|[;&|>)`'"])|\bprintenv\b|\bexport\s*$|\bset\s*$|\bdeclare\s+-x|cat\s+\/etc\/environment|cat\s+\/root\/\.bashrc|cat\s+\/proc\/\d+\/environ|cat\s+\/proc\/self\/environ|strings\s+\/proc|xargs[^;&|\n]*\/proc\/[^;&|\n]*environ|less\s+\/proc|head\s+\/proc|tail\s+\/proc|xxd\s+\/proc|od\s+\/proc|base64\s+\/proc|dd\s[^\n]*\/proc|sed\s[^\n]*\/proc\/[^\n]*environ|awk\s[^\n]*\/proc\/[^\n]*environ|cp\s[^\n]*\/proc\/[^\n]*environ|(?:cat|less|head|tail|xxd|od|base64|strings|dd|cp|sed|awk)\s[^\n;&|]*\/etc\/mol(?:\/|\b))/i;
+function dumpsEnvironment(program, args) {
+    const words = args.map(shellWord);
+    if (program === 'env')
+        return true;
+    if (program === 'printenv')
+        return true;
+    if (program === 'export')
+        return words.every((word) => word === '-p' || word === '--print');
+    if (program === 'set')
+        return words.length === 0;
+    if (program === 'declare')
+        return (words.length === 0 ||
+            (words.every((word) => word.startsWith('-')) &&
+                words.some((word) => /^-[A-Za-z]*[px]/.test(word))));
+    return false;
+}
+/** Interpreters an env-dumping one-liner is written in (python, node, ruby, perl). */
+const INTERPRETER_PROGRAMS = new Set([
+    'node',
+    'perl',
+    'python',
+    'python2',
+    'python3',
+    'ruby',
+]);
+/** An inline program (`-e` / `-c`) that reads the environment and prints it. */
+const INTERPRETER_ENV_DUMP = /(?:^|\s)(?:-e|-c)\s[^\n]*(?:os\.environ|process\.env|ENV\[|%ENV|ENVIRON)/i;
+/**
+ * Whether one executed command dumps the environment from an inline interpreter program
+ * (`node -e 'console.log(process.env)'`).
+ *
+ * @param program - The command's program, directory removed.
+ * @param text - The program and its arguments as one line.
+ * @returns True when the inline program reads the environment.
+ */
+function dumpsEnvironmentFromInterpreter(program, text) {
+    return INTERPRETER_PROGRAMS.has(program) && INTERPRETER_ENV_DUMP.test(text);
+}
 /** Block shell redirects from /proc environ. */
 const BLOCKED_PROC_REDIRECT = /(?:<\s*\/proc\/(?:\d+|self)\/environ)/i;
 /** Block shell redirects from the molecule platform secrets dir (`/etc/mol`). */
 const BLOCKED_MOL_REDIRECT = /(?:<\s*\/etc\/mol)/i;
-/** Interpreter-based env dumping (python, node, ruby, perl). */
-const BLOCKED_INTERPRETER_ENV = /(?:python[23]?|node|ruby|perl)\s+(?:-e|-c)\s+[^\n]*(?:os\.environ|process\.env|ENV\[|%ENV|ENVIRON)/i;
 /**
  * Check if a command is blocked for security reasons. Returns error message or null if allowed.
  *
+ * The first check reads the commands the shell actually RUNS — the statements, a `sh -c`
+ * string's body, and every command substitution ({@link executedCommands}) — so a `|` inside a
+ * quoted grep alternation is data, not a pipeline: `grep -E "USER CALLS|ENV|BUTTON|passed|failed"
+ * app.log` prints log lines, and the `ENV` in its pattern started nothing (X0
+ * xr-molecule-flash-m331 blocked exactly that call as an environment dump, twice). What the
+ * shell DOES run stays visible through the same walk: `ls | env`, `bash -c 'env'`,
+ * `echo "$(printenv)"` and a nested `sh -c 'x; env'` are all commands, and so is `env` itself
+ * when nothing follows it.
+ *
  * @param command - Shell command string proposed for execution.
  * @returns A human-readable block reason, or `null` when the command is allowed.
  */
@@ -1341,13 +1515,14 @@ export function checkBlockedCommand(command) {
         "check the project's provisioned env file to see WHICH services exist. Printing them only " +
         'leaks secrets into the transcript. To check whether ONE variable is set without printing ' +
         'it: `test -n "$NAME" && echo set || echo missing`.';
-    if (BLOCKED_COMMANDS.test(command))
+    const statements = executedCommands(command);
+    if (statements.some((s) => dumpsEnvironment(s.program, s.args) || readsSecretFile(s.program, s.args)))
         return `Command blocked: dumping environment variables is not allowed.${envDumpSteer}`;
     if (BLOCKED_PROC_REDIRECT.test(command))
         return 'Command blocked: /proc/environ access is not allowed.' + envDumpSteer;
     if (BLOCKED_MOL_REDIRECT.test(command))
         return 'Command blocked: /etc/mol (platform secrets) access is not allowed.' + envDumpSteer;
-    if (BLOCKED_INTERPRETER_ENV.test(command))
+    if (statements.some((s) => dumpsEnvironmentFromInterpreter(s.program, s.text)))
         return `Command blocked: dumping the environment from an interpreter is not allowed.${envDumpSteer}`;
     return null;
 }
@@ -3882,11 +4057,8 @@ export function repeatingFailureNote(found, o) {
             `repeats this one cause. Stop it and fix that cause first: \`exec_command: ${o.stop}\`, ` +
             `then run the whole suite again. It is still going (${where}).${reproduce}`);
     }
-    // Everything else is a note on a run the wait is still waiting for, and both its shapes end the
-    // same way: the run finishes, because it is the only thing that names the causes this finding is
-    // not. What it does NOT carry is the "Stop it if every test fails this way" clause — that one
-    // belongs to a PROVEN cause the run is still walking (the sentence below), never to a lead:
-    // xr-molecule-flash-m99's executor read it on a shared duration and voided the run.
+    // The same predicate controls both an early return and stop advice. Without
+    // that verdict, neither a repeated error nor a shared duration asks for a stop.
     const keepGoing = `Let the rest of the run finish — it is the only thing that will name the causes that are NOT ` +
         `this one, and a run stopped at its first repeating cause costs a second whole run to find ` +
         `them. It is still going (${where}).`;
@@ -3894,10 +4066,9 @@ export function repeatingFailureNote(found, o) {
         return (`${found.count} different tests in this run have already failed the same way — ${signature} — ` +
             `so one cause is repeating:\n${rows}${more}\n` +
             (o.editsInvalidateRun
-                ? `Work out the fix now: apply it when the run ends, not while it walks. Stop it only if every test it walks `
-                : `Start fixing it now, while the run keeps walking. Stop it only if every test it walks `) +
-            `fails this same way (the app unreachable, a 5xx on every request, the same selector timing ` +
-            `out on every test of every file so far).${reproduce} ${keepGoing}${thenRun}`);
+                ? `Work out the fix now: apply it when the run ends, not while it walks.`
+                : `Start fixing it now, while the run keeps walking.`) +
+            `${reproduce} ${keepGoing}${thenRun}`);
     return (`${found.count} different tests in this run each failed after ~${found.seconds}s — the same ` +
         `duration to within half a second. A shared duration is a lead, not a cause: a suite whose ` +
         `config sets a timeout spends that timeout on every failure that waits for anything, so ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",