@molecule/api-ai-tools 1.0.1 → 1.0.3

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T01:47:38.726Z
+Generated: 2026-08-13T21:34:34.535Z
 -->
 
 # @molecule/api-ai-tools
@@ -356,6 +356,20 @@ function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>
 
 **Returns:** Array of discovered skills with name, description, and path
 
+#### `isEnvFilePath(path)`
+
+Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+`.env`, `.env.<suffix>`, and `<name>.env`.
+
+```typescript
+function isEnvFilePath(path: string): boolean
+```
+
+- `path` — A workspace-relative or absolute file path.
+
+**Returns:** `true` when the file is an env file.
+
 #### `isValidGlob(pattern)`
 
 Validate that a glob/include pattern is safe (no shell metacharacters that could
@@ -399,6 +413,12 @@ function pathArgError(path: unknown, tool: string): string | null
 
 Redact values of common secret/credential patterns in text output.
 
+ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+NAME beside the value and therefore cannot tell a credential from ordinary
+code that happens to use a keyword-ish identifier. Use this for `.env` reads
+and command output (where an env dump is the actual threat); use
+{@link redactSecretsInCode} for source-file content.
+
 ```typescript
 function redactSecrets(s: string): string
 ```
@@ -407,6 +427,33 @@ function redactSecrets(s: string): string
 
 **Returns:** A redacted copy safe to surface to end users or models.
 
+#### `redactSecretsInCode(s)`
+
+CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+the JSON `KEY: 'value'` passes.
+
+Those passes match on the NAME next to a quoted value, so over source code they
+replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+'/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+password" string all became `'[REDACTED]'`. Because the agent writes back the
+content it reads, that token then lands in the user's project — measured at
+10,952 of 27,919 flagship template files before this split.
+
+No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+test helper is indistinguishable from a real credential by shape. So the
+name-keyed passes simply do not run over code. Credentials in source are still
+caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+which is what actually catches a secret sitting under an innocuous name.
+
+```typescript
+function redactSecretsInCode(s: string): string
+```
+
+- `s` — Source-file content or other code-shaped text.
+
+**Returns:** A redacted copy that preserves ordinary code verbatim.
+
 #### `resolvePath(path, projectRoot)`
 
 Normalize a path to be absolute within the project root.

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0nBxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAopBxF"}

package/dist/tools.js

@@ -7,7 +7,7 @@
  * @module
  */
 import { TOOL_SCHEMAS } from './schemas.js';
-import { checkBlockedCommand, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isValidGlob, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_SIZE, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, pathArgError, redactSecrets, resolvePath, shellQuote, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, isValidGlob, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_SIZE, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -71,6 +71,24 @@ export function buildTools(backend, config) {
             result = redactSecrets(result);
         return result;
     }
+    /**
+     * Sanitize FILE CONTENT for return to the model. Unlike {@link sanitizeOutput},
+     * this uses the code-safe redactor for ordinary source files — the name-keyed
+     * JSON passes destroy legitimate code, and the agent writes back what it reads,
+     * so an over-redacted read corrupts the user's project on the next write. Env
+     * files still get the full env-dump treatment, since that is where the shape
+     * those passes detect actually indicates a credential.
+     *
+     * @param s - Raw file contents.
+     * @param path - The file's path, used to decide the redaction grade.
+     * @returns Content safe to return to the model, with code preserved verbatim.
+     */
+    function sanitizeFileContent(s, path) {
+        let result = stripControlChars(s);
+        if (doRedact)
+            result = isEnvFilePath(path) ? redactSecrets(result) : redactSecretsInCode(result);
+        return result;
+    }
     // ── Diff computation ───────────────────────────────────────────
     /**
      * Compute a lightweight diff summary for telemetry and UI badges.
@@ -120,7 +138,7 @@ export function buildTools(backend, config) {
                     return {
                         error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
                     };
-                return { path, content: sanitizeOutput(content) };
+                return { path, content: sanitizeFileContent(content, path) };
             }
             catch (e) {
                 // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
@@ -363,7 +381,11 @@ export function buildTools(backend, config) {
             try {
                 const globArg = include ? `--include=${shellQuote(include)}` : '';
                 const result = await backend.run(`grep -rn ${globArg} ${grepExcludeArgs} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)} 2>/dev/null || true`, { timeout: 10000 });
-                const output = sanitizeOutput(result.stdout.trim());
+                // grep emits `<file>:<line>:<content>`, so redaction runs PER MATCH on the
+                // content alone: the file prefix would otherwise hide an env assignment from
+                // the line-anchored env pattern, and knowing each match's own path is what
+                // lets a hit inside a .env get full treatment while source stays verbatim.
+                const output = stripControlChars(result.stdout.trim());
                 if (!output)
                     return { pattern, path, matches: [] };
                 const matches = output
@@ -372,8 +394,8 @@ export function buildTools(backend, config) {
                     .map((line) => {
                     const m = line.match(/^(.+?):(\d+):(.*)$/);
                     return m
-                        ? { file: m[1], line: parseInt(m[2]), content: m[3] }
-                        : { file: '', line: 0, content: line };
+                        ? { file: m[1], line: parseInt(m[2]), content: sanitizeFileContent(m[3], m[1]) }
+                        : { file: '', line: 0, content: sanitizeFileContent(line, '') };
                 });
                 return { pattern, path, matches };
             }
@@ -506,7 +528,7 @@ export function buildTools(backend, config) {
                     return { error: symlinkErr };
                 try {
                     const content = await backend.readFile(path);
-                    return { name, path, content: sanitizeOutput(content) };
+                    return { name, path, content: sanitizeFileContent(content, path) };
                 }
                 catch (_error) {
                     // File not present at the given path — fall through to the error return below
@@ -523,7 +545,11 @@ export function buildTools(backend, config) {
                     continue;
                 try {
                     const content = await backend.readFile(skillPath);
-                    return { name, path: `${dir}/${name}/SKILL.md`, content: sanitizeOutput(content) };
+                    return {
+                        name,
+                        path: `${dir}/${name}/SKILL.md`,
+                        content: sanitizeFileContent(content, skillPath),
+                    };
                 }
                 catch (_error) {
                     // Skill file not present in this directory — try the next candidate

package/dist/utilities.d.ts

@@ -23,10 +23,47 @@ export declare const stripControlChars: (s: string) => string;
 /**
  * Redact values of common secret/credential patterns in text output.
  *
+ * ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+ * NAME beside the value and therefore cannot tell a credential from ordinary
+ * code that happens to use a keyword-ish identifier. Use this for `.env` reads
+ * and command output (where an env dump is the actual threat); use
+ * {@link redactSecretsInCode} for source-file content.
+ *
  * @param s - Log or command output that may contain `.env`-style secrets.
  * @returns A redacted copy safe to surface to end users or models.
  */
 export declare function redactSecrets(s: string): string;
+/**
+ * CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+ * the JSON `KEY: 'value'` passes.
+ *
+ * Those passes match on the NAME next to a quoted value, so over source code they
+ * replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+ * '/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+ * password" string all became `'[REDACTED]'`. Because the agent writes back the
+ * content it reads, that token then lands in the user's project — measured at
+ * 10,952 of 27,919 flagship template files before this split.
+ *
+ * No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+ * test helper is indistinguishable from a real credential by shape. So the
+ * name-keyed passes simply do not run over code. Credentials in source are still
+ * caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+ * detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+ * which is what actually catches a secret sitting under an innocuous name.
+ *
+ * @param s - Source-file content or other code-shaped text.
+ * @returns A redacted copy that preserves ordinary code verbatim.
+ */
+export declare function redactSecretsInCode(s: string): string;
+/**
+ * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+ * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+ * `.env`, `.env.<suffix>`, and `<name>.env`.
+ *
+ * @param path - A workspace-relative or absolute file path.
+ * @returns `true` when the file is an env file.
+ */
+export declare function isEnvFilePath(path: string): boolean;
 /**
  * Check if a command is blocked for security reasons. Returns error message or null if allowed.
  *

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAEE,CAAA;AAyDhD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAaD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAID,yCAAyC;AACzC,eAAO,MAAM,aAAa,QAAkB,CAAA;AAC5C,8CAA8C;AAC9C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAC9C,kDAAkD;AAClD,eAAO,MAAM,eAAe,QAAa,CAAA;AACzC,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,mHAW/B,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAyBf"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAEE,CAAA;AAyFhD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAsBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAID,yCAAyC;AACzC,eAAO,MAAM,aAAa,QAAkB,CAAA;AAC5C,8CAA8C;AAC9C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAC9C,kDAAkD;AAClD,eAAO,MAAM,eAAe,QAAa,CAAA;AACzC,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,mHAW/B,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAyBf"}

package/dist/utilities.js

@@ -39,7 +39,33 @@ s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
 // e.g. MAILGUN_APIKEY), and SERVICE_ACCOUNT were the gaps; `_KEY` already covers
 // OPENAI_KEY / *_ROLE_KEY.
 const SECRET_KEYWORDS = 'SECRET|PASSWORD|PASSWD|PWD|TOKEN|API_KEY|APIKEY|PRIVATE_KEY|DATABASE_URL|REDIS_URL|AUTH|CREDENTIAL|ACCESS_KEY|SIGNING_KEY|ENCRYPTION_KEY|CONNECTION_STRING|SERVICE_ACCOUNT|DSN|SMTP_PASS|_KEY';
-const SECRET_KEY_PATTERN = new RegExp(`^(.*(?:${SECRET_KEYWORDS})[A-Z0-9_]*)=(.+)$`, 'gim');
+/**
+ * A keyword-named `NAME=value` anywhere on a line — the ENV-DUMP grade pattern,
+ * used by {@link redactSecrets} for command output and `.env` reads. The permissive
+ * `.*` prefix is deliberate there: a leaked env var routinely arrives mid-line
+ * (`Error: DATABASE_URL=postgres://…` on stderr), and that output is shown to the
+ * model but never written back to a file, so over-matching costs nothing.
+ *
+ * The value must not open with `{` or `<`: an env value never does, but a JSX
+ * expression container or element always does. Without that guard this pattern ate
+ * `auth={authClient}` down to `auth=[REDACTED]`.
+ */
+const SECRET_KEY_PATTERN = new RegExp(`^(.*(?:${SECRET_KEYWORDS})[A-Za-z0-9_]*)=(?![{<])(.+)$`, 'gim');
+/**
+ * The same assignment anchored to a REAL env-assignment shape — line start (or
+ * `export `), a bare identifier, then `=` with no surrounding spaces. This is the
+ * CODE-SAFE form used by {@link redactSecretsInCode}.
+ *
+ * Anchoring matters because the loose form above matches any line with a keyword
+ * anywhere before an `=` and replaces the whole line tail. Over source code that
+ * destroyed ordinary lines, and since the executor writes back what it reads, the
+ * literal token landed in users' projects.
+ */
+const SECRET_ENV_ASSIGNMENT = new RegExp(
+// The leading name run allows EMPTY: a name that IS the keyword (`DATABASE_URL=`,
+// `SECRET=`) has nothing before it, and requiring a character there silently
+// un-masked exactly the plainest env vars.
+`^((?:export[ \\t]+)?[A-Za-z0-9_]*(?:${SECRET_KEYWORDS})[A-Za-z0-9_]*)=(?![{<])(.+)$`, 'gim');
 /** Catch JSON-formatted env dumps like { KEY: 'value' } from node/python. */
 const SECRET_JSON_DQ = new RegExp(`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)"(?:[^"\\\\]|\\\\.)*"`, 'gi');
 const SECRET_JSON_SQ = new RegExp(`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)'(?:[^'\\\\]|\\\\.)*'`, 'gi');
@@ -76,6 +102,12 @@ const jsonValueReplacer = (quote) => (match, prefix) => {
 /**
  * Redact values of common secret/credential patterns in text output.
  *
+ * ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+ * NAME beside the value and therefore cannot tell a credential from ordinary
+ * code that happens to use a keyword-ish identifier. Use this for `.env` reads
+ * and command output (where an env dump is the actual threat); use
+ * {@link redactSecretsInCode} for source-file content.
+ *
  * @param s - Log or command output that may contain `.env`-style secrets.
  * @returns A redacted copy safe to surface to end users or models.
  */
@@ -85,9 +117,54 @@ export function redactSecrets(s) {
         .replace(SECRET_JSON_DQ, jsonValueReplacer('"'))
         .replace(SECRET_JSON_SQ, jsonValueReplacer("'"));
 }
+/**
+ * CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+ * the JSON `KEY: 'value'` passes.
+ *
+ * Those passes match on the NAME next to a quoted value, so over source code they
+ * replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+ * '/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+ * password" string all became `'[REDACTED]'`. Because the agent writes back the
+ * content it reads, that token then lands in the user's project — measured at
+ * 10,952 of 27,919 flagship template files before this split.
+ *
+ * No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+ * test helper is indistinguishable from a real credential by shape. So the
+ * name-keyed passes simply do not run over code. Credentials in source are still
+ * caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+ * detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+ * which is what actually catches a secret sitting under an innocuous name.
+ *
+ * @param s - Source-file content or other code-shaped text.
+ * @returns A redacted copy that preserves ordinary code verbatim.
+ */
+export function redactSecretsInCode(s) {
+    return s.replace(SECRET_ENV_ASSIGNMENT, '$1=[REDACTED]');
+}
+/**
+ * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+ * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+ * `.env`, `.env.<suffix>`, and `<name>.env`.
+ *
+ * @param path - A workspace-relative or absolute file path.
+ * @returns `true` when the file is an env file.
+ */
+export function isEnvFilePath(path) {
+    const base = path.split('/').pop() ?? '';
+    return base === '.env' || base.startsWith('.env.') || base.endsWith('.env');
+}
 // ── Command blocking ──────────────────────────────────────────────────────────
-/** Commands that dump environment variables — blocked to prevent secret leakage. */
-const BLOCKED_COMMANDS = /(?:^|[;&|`]\s*|(?:sh|bash|zsh|dash)\s+-c\s+['"]?\s*)(?:\/usr\/bin\/)?(?:\benv\b|\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)/i;
+/**
+ * Commands that dump environment variables — blocked to prevent secret leakage.
+ *
+ * `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).
+ */
+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)/i;
 /** Block shell redirects from /proc environ. */
 const BLOCKED_PROC_REDIRECT = /(?:<\s*\/proc\/(?:\d+|self)\/environ)/i;
 /** Interpreter-based env dumping (python, node, ruby, perl). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "@molecule/api-ai": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.0.1",
+    "@molecule/api-ai": "1.2.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"