@molecule/api-ai-tools 1.11.1 → 1.13.0

package/dist/utilities.js

@@ -5,9 +5,10 @@
  * @module
  */
 import { posix } from 'path';
-import { commandSegments, executedCommands, locatedCommandSegments, statementArgumentEnd, withoutTimeoutWrapper, } from './command-position.js';
+import { commandSegments, executedCommands, locatedCommandSegments, statementArgumentEnd, statementBoundary, withoutTimeoutWrapper, } from './command-position.js';
 import { classifyRunFailure } from './failure-kind.js';
 import { commandRunsNoTests } from './no-test-run.js';
+import { PLAYWRIGHT_REPORT_ENV } from './playwright-report.js';
 import { isDiagnosisRun, scopedRerunCommand, suiteCommandTarget, suiteRunInTheWay, withoutHeredocs, withSuiteConfig, } from './suite-overlap.js';
 /**
  * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
@@ -163,8 +164,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 +287,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 +373,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 +397,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
@@ -535,10 +613,17 @@ function isStatusOnlyStep(step) {
  *   excludes by name ({@link DiagnosisRunContext}). A `--grep-invert` of exactly those is the
  *   request's own scope, not a diagnosis, so it keeps the suite's retries on a deployed proof
  *   (xr-molecule-flash-m170 +33:16).
- * @returns The command to run and one sentence per change made (empty when none), or `error` when
- *   the command starts the suite more than once.
- */
-export function streamingBackgroundCommand(command, context) {
+ * @param reportPath - Where this run should write Playwright's standard `json` report, when the
+ *   caller keeps one ({@link ./playwright-report.js}). The reporter is added to the run's own
+ *   reporter set, never in place of one, and its output goes to that file through
+ *   `PLAYWRIGHT_JSON_OUTPUT_FILE` — so the log, the executors' own reporters and every verdict
+ *   stay exactly as they are. Omitted, or a run whose reporter set is not this function's to place
+ *   (already names `json`, sets the variable itself, or whose runner cannot be located), leaves
+ *   the command untouched and the result's `reportPath` unset.
+ * @returns The command to run, one sentence per change made (empty when none), and the report path
+ *   when one was actually wired — or `error` when the command starts the suite more than once.
+ */
+export function streamingBackgroundCommand(command, context, reportPath) {
     // A command that runs no test is not a run to keep a growing log for: nothing about it is
     // rewritten (flash-m79's `--list` was read as a whole-suite run end to end, and got a ~4 KB
     // refusal to send itself again with `--max-failures=15`).
@@ -666,14 +751,26 @@ export function streamingBackgroundCommand(command, context) {
     // The last step's reporters: one printer, and it is `list`. Every branch below only ever moves
     // the command TO that shape — a reporter set is never left with two printers in it.
     const reporters = finalPlaywrightRun ? lastReporterFlag(lastStep) : null;
+    // The standard machine report this run may carry (`playwright-report.ts`). It is never taken from
+    // the executor: a reporter set already naming `json`, or a command that sets
+    // `PLAYWRIGHT_JSON_OUTPUT_FILE` itself, is the executor's own artifact and is left untouched.
+    const reportWanted = reportPath !== undefined &&
+        finalPlaywrightRun &&
+        !/(?:^|[\s;])PLAYWRIGHT_JSON_OUTPUT_FILE=/.test(out) &&
+        !(reporters?.values.includes('json') ?? false);
+    let report = null;
     if (reporters) {
         const printing = reporters.values.filter((v) => PRINTING_REPORTERS.has(v));
         // Already exactly `list`: the shape, and nothing printing beside it. Left verbatim — the
         // executor's own spelling of the command is not rewritten for nothing.
-        if (printing.length > 0 && !(printing.length === 1 && printing[0] === 'list')) {
+        const printerRewrite = printing.length > 0 && !(printing.length === 1 && printing[0] === 'list');
+        const addReport = reportWanted && !reporters.values.includes('json');
+        if (printerRewrite || addReport) {
             // The printing reporters become ONE `list`, in the place of the first of them; every other
             // reporter (a `json`/`html`/`junit` file the executor asked for, or one this build does not
-            // know) is left where it was.
+            // know) is left where it was. The machine report, when this run carries one, is appended to
+            // the same set: it writes the runner's own per-test identities and attachment paths to a
+            // file and prints nothing into the log.
             let placed = false;
             const kept = reporters.values
                 .map((v) => {
@@ -685,6 +782,11 @@ export function streamingBackgroundCommand(command, context) {
                 return 'list';
             })
                 .filter((v) => v !== null);
+            // The sentence below is about the reporTERS this run prints with, so it reads the set as it
+            // was rewritten — the machine report is written to a file and is no part of that sentence.
+            const printers = kept.join(',');
+            if (addReport)
+                kept.push('json');
             // Only the last step is rewritten, and its offsets are the parse's own. The punctuation
             // after the step (`; }`, or the `)` attached to it) is kept verbatim.
             out =
@@ -694,26 +796,39 @@ export function streamingBackgroundCommand(command, context) {
                     lastStep.slice(reporters.end) +
                     rawLastStep.slice(lastStep.length) +
                     out.slice(stepStart + rawLastStep.length);
-            changes.push(
-            // `list` was already there and a second printer sat beside it: that one is dropped. When
-            // no `list` was named at all, the printer is SWITCHED to it (flash-m62's `line`).
-            printing.includes('list')
-                ? `Dropped \`${printing
-                    .filter((v) => v !== 'list')
-                    .join(',')}\` from your \`--reporter=${reporters.values.join(',')}\`: ` +
-                    'two reporters that both print each failure write every test result into the log ' +
-                    'twice — the whole log doubled for nothing (X1 flash-m83) — so this run keeps ' +
-                    '`list` alone.'
-                : `Switched the test reporters to \`--reporter${reporters.separator}${kept.join(',')}\`: ` +
-                    '`list` writes each test result as it finishes and is the shape the platform reads ' +
-                    'back from a background run, and it is the only printing reporter — two of them ' +
-                    'write every result into the log twice (X1 flash-m83).');
+            if (printerRewrite) {
+                changes.push(
+                // `list` was already there and a second printer sat beside it: that one is dropped. When
+                // no `list` was named at all, the printer is SWITCHED to it (flash-m62's `line`).
+                printing.includes('list')
+                    ? `Dropped \`${printing
+                        .filter((v) => v !== 'list')
+                        .join(',')}\` from your \`--reporter=${reporters.values.join(',')}\`: ` +
+                        'two reporters that both print each failure write every test result into the log ' +
+                        'twice — the whole log doubled for nothing (X1 flash-m83) — so this run keeps ' +
+                        '`list` alone.'
+                    : `Switched the test reporters to \`--reporter${reporters.separator}${printers}\`: ` +
+                        '`list` writes each test result as it finishes and is the shape the platform reads ' +
+                        'back from a background run, and it is the only printing reporter — two of them ' +
+                        'write every result into the log twice (X1 flash-m83).');
+            }
+            if (addReport)
+                report = reportPath;
         }
     }
-    else if (finalPlaywrightRun && addToRun('--reporter=list')) {
+    else if (finalPlaywrightRun &&
+        addToRun(reportWanted ? '--reporter=list,json' : '--reporter=list')) {
+        if (reportWanted)
+            report = reportPath;
         changes.push('Added `--reporter=list` so each test result is written to the log as it finishes ' +
             '(the config reporter may print nothing until the end).');
     }
+    // The report's own file option, set once at the head of the whole command — the json reporter
+    // reads it from the environment, resolved against the runner's directory, so an absolute path is
+    // used and the file lands beside the task's own log whatever `cd` the run opens with.
+    if (report !== null) {
+        out = `export ${PLAYWRIGHT_REPORT_ENV}=${shellQuote(report)}; ${out}`;
+    }
     // The run's failures, in the log as they fail (see PLAYWRIGHT_FAILURES_INLINE_ENV), on EVERY
     // background command that is not a no-test invocation — not only the ones whose text this
     // reader can place the runner in. The executor starts the suite through its own wrapper often
@@ -748,7 +863,58 @@ export function streamingBackgroundCommand(command, context) {
         if (addToRun('--retries=0'))
             changes.push(`Added \`--retries=0\`: ${why}.`);
     }
-    return { command: out, changes };
+    return { command: out, changes, ...(report === null ? {} : { reportPath: report }) };
+}
+/**
+ * Put Playwright's standard `json` report on a FOREGROUND run that already names its own reporters.
+ *
+ * A background run is rewritten onto the platform's reporter anyway ({@link
+ * streamingBackgroundCommand}), so adding the machine report there costs nothing. A foreground run
+ * is not: its reporters are either the command's own flags or the suite's config, and replacing a
+ * config reporter would stop writing the artifact the executor configured. So this only ever
+ * APPENDS `json` to a `--reporter` set the command already wrote — the log keeps every printing
+ * reporter it had, the executor's file reporters keep their place, and the standard report goes to
+ * {@link PLAYWRIGHT_REPORT_ENV}'s file.
+ *
+ * A command that names no reporter at all is left exactly as written: its reporters are the suite
+ * config's, and this tool does not rewrite those. A command that already names `json`, or sets
+ * `PLAYWRIGHT_JSON_OUTPUT_FILE` itself, already has a report of its own — a path the executor chose
+ * is never overwritten.
+ *
+ * @param command - The command the executor sent, after every other rewrite.
+ * @param reportPath - The file this run's machine report should be written to.
+ * @returns The command to run and the report path when one was wired; `reportPath` is null when the
+ *   run was left untouched and no report may be expected.
+ */
+export function withPlaywrightRunReport(command, reportPath) {
+    const unchanged = { command, reportPath: null };
+    if (reportPath === '')
+        return unchanged;
+    if (!isPlaywrightRunCommand(command))
+        return unchanged;
+    if (/(?:^|[\s;])PLAYWRIGHT_JSON_OUTPUT_FILE=/.test(command))
+        return unchanged;
+    const run = lastSuiteRun(command);
+    const runner = run ? run.located[run.at] : undefined;
+    if (!runner || runner.start === null || runner.end === null)
+        return unchanged;
+    const at = statementArgumentEnd(command, runner.start, runner.end);
+    if (at === null)
+        return unchanged;
+    // The reporter flag the RUN's own statement names — not one an argument of another program
+    // carries (`grep --reporter x file`): the slice starts at the runner's own program word.
+    const flag = lastReporterFlag(command.slice(runner.start, at));
+    if (flag === null || flag.values.includes('json'))
+        return unchanged;
+    const start = runner.start + flag.start;
+    const end = runner.start + flag.end;
+    const rewritten = command.slice(0, start) +
+        `--reporter${flag.separator}${[...flag.values, 'json'].join(',')}` +
+        command.slice(end);
+    return {
+        command: `export ${PLAYWRIGHT_REPORT_ENV}=${shellQuote(reportPath)}; ${rewritten}`,
+        reportPath,
+    };
 }
 /**
  * How a shell command starts each runner whose whole-suite run saturates the
@@ -1171,6 +1337,10 @@ function lastSuiteRun(command) {
  * tail, and a 95-second walk's log held only the tally while the platform's own hold had handed
  * that command back).
  *
+ * The command around the dropped stages is left as written: a group they sit in keeps its closer
+ * (`( … | tail -25)` → `( … )`, never `( …` — xr-molecule-flash-m418 +23:31), and a stage the cut
+ * would leave a closer dangling inside is not dropped at all.
+ *
  * @param command - The shell command.
  * @returns The rewritten command and the stages dropped.
  */
@@ -1204,15 +1374,40 @@ export function stripTrailingSuiteFilters(command) {
     // A stage inside a nested `sh -c` string has no offsets in this command: nothing can be cut.
     if (previous.end === null || stage.start === null || lastDropped.end === null)
         return { command, dropped: '' };
+    // Every stage dropped must be provably whole inside the command's own structure. A group
+    // closer attached to one of them closes a group the pipeline below still runs in
+    // (`( … | tail -5) | cat`), and a stage that OPENS a group it does not close (`| { cat; }`) has
+    // its closer in a later statement — either cut would leave the punctuation dangling. Only the
+    // last stage may end on an enclosing closer, and it is kept ({@link statementBoundary}).
+    const boundaries = [];
+    for (let i = first; i <= end; i += 1) {
+        const droppedStage = located[i];
+        if (!droppedStage || droppedStage.end === null)
+            return { command, dropped: '' };
+        const boundary = statementBoundary(command, droppedStage.start, droppedStage.end);
+        if (boundary === null || boundary.leavesGroupOpen)
+            return { command, dropped: '' };
+        if (i < end && boundary.textEnd !== droppedStage.end)
+            return { command, dropped: '' };
+        boundaries.push(boundary);
+    }
+    const lastBoundary = boundaries[boundaries.length - 1];
+    if (lastBoundary === undefined)
+        return { command, dropped: '' };
+    // Where the dropped stages' own text ends. The tokenizer attaches the closer of an enclosing
+    // group to the stage's last word (`tail -25)`), so cutting at {@link LocatedSegment.end} deleted
+    // the `)` and left `( … 2>&1` — a command no shell parses, which the background runner rejected
+    // with `end of file unexpected` (xr-molecule-flash-m418 +23:31).
+    const dropEnd = lastBoundary.textEnd;
     const pipe = stage.between.indexOf('|');
     if (pipe < 0)
         return { command, dropped: '' };
     const cut = previous.end + pipe;
     // The stages dropped are a middle slice when a statement follows, so the text after them is
-    // kept — `; echo done` still runs.
+    // kept — `; echo done` still runs, and so does the punctuation closing the group they sat in.
     return {
-        command: `${command.slice(0, cut).trimEnd()}${command.slice(lastDropped.end)}`,
-        dropped: command.slice(cut, lastDropped.end).trim(),
+        command: `${command.slice(0, cut).trimEnd()}${command.slice(dropEnd)}`,
+        dropped: command.slice(cut, dropEnd).trim(),
     };
 }
 /**
@@ -3980,11 +4175,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}).`;
@@ -3992,10 +4184,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.1",
+  "version": "1.13.0",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "@types/node": "26.1.2",
     "esbuild": "0.28.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "repository": {
     "type": "git",