@molecule/api-ai-tools 1.5.19 → 1.6.0

package/dist/command-position.js

@@ -0,0 +1,352 @@
+/**
+ * Command position: which program a shell segment actually RUNS, and which words are only
+ * arguments to something else.
+ *
+ * Every classifier that read a command as "this runs the suite" matched the runner's NAME
+ * anywhere in the text, so a runner named in an argument was read as an invocation: X1
+ * xr-molecule-flash-m81 (+20:03) sent
+ * `cd /workspace/fixtures/realworld/specs/api && ls && head -30 run-api-tests-hurl.sh` — two
+ * reads of a file that was already there — and the suite-overlap hold answered "a Playwright
+ * suite is already running against this app and database … wait for it", costing a minute of
+ * forced idling on a command that writes nothing and runs nothing. `cat`, `grep`, `sed -n`,
+ * `wc`, `ls` and `git show` of a runner script are the same shape.
+ *
+ * So this parser answers it in one place, for every caller: split the command at its pipeline
+ * and statement separators, take each segment's word in command position — after the wrapper
+ * prefixes a shell puts in front of it (`HOST=x sudo nice -n 10 npx`, `bash`, `timeout 280`) —
+ * and let the caller match its runner against THAT segment's text, never against the raw
+ * command. `{@link commandSegments}` returns the segments, and
+ * {@link runsInCommandPosition} asks one anchored pattern of them all.
+ *
+ * Not command position, and therefore not an invocation: a runner named as an argument
+ * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
+ * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
+ * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
+ * stripper first (`withoutHeredocs` in molecule-dev's suite checks).
+ *
+ * @module
+ */
+/** A command's words, quotes kept whole — the same reading a printed-source check uses. */
+const WORD = /"(?:\\.|[^"\\])*"|'[^']*'|\S+/g;
+/** Shell words that stand alone: grouping, never an argument. */
+const GROUPING = new Set(['(', ')', '{', '}']);
+/** How deep a `sh -c '<command>'` is opened before the parser leaves it alone. */
+const MAX_NESTING = 3;
+/** How many wrapper words one segment may carry before the parser gives up on it. */
+const MAX_WRAPPERS = 32;
+/**
+ * Words that run in front of the real program: a scheduler, a privilege wrapper, a process
+ * launcher, or a name that simply runs the next word (`command ls`, `exec ls`). All of them
+ * leave what runs unchanged, so all of them are stripped.
+ */
+const LAUNCHERS = new Set([
+    'command',
+    'doas',
+    'env',
+    'exec',
+    'ionice',
+    'nice',
+    'nohup',
+    'setsid',
+    'sudo',
+    'time',
+    'timeout',
+]);
+/** The shells whose `-c '<command>'` argument is a command of its own. */
+const SHELLS = new Set(['ash', 'bash', 'dash', 'ksh', 'sh', 'zsh']);
+/** Package runners that run the program named after them (`npx playwright test`). */
+const PACKAGE_RUNNERS = new Set(['bunx', 'npx', 'pnpx']);
+/** Package managers whose sub-command runs a package's binary (`bun x`, `pnpm dlx`, `npm exec`). */
+const PACKAGE_RUNNER_HEADS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
+/**
+ * The sub-commands that run a package's binary, after a {@link PACKAGE_RUNNER_HEADS} word. Its
+ * other sub-commands are the program itself, not a wrapper: `yarn test` and `bun run build` run
+ * a script of the project's, and nothing is stripped from them.
+ */
+const PACKAGE_RUNNER_SUBCOMMANDS = new Set(['dlx', 'exec', 'x']);
+/** Wrapper flags that are followed by their own value (`sudo -u root`, `timeout -k 5`). */
+const WRAPPER_VALUE_FLAGS = {
+    env: ['-S', '--split-string', '-u', '--unset', '-C', '--chdir'],
+    ionice: ['-c', '--class', '-n', '--classdata', '-p', '--pid', '-P', '--pgid', '-u', '--uid'],
+    nice: ['-n', '--adjustment'],
+    sudo: [
+        '-C',
+        '--chdir',
+        '-g',
+        '--group',
+        '-p',
+        '--prompt',
+        '-r',
+        '--role',
+        '-t',
+        '--type',
+        '-u',
+        '--user',
+        '-U',
+        '--other-user',
+    ],
+    time: ['-f', '--format', '-o', '--output'],
+    timeout: ['-k', '--kill-after', '-s', '--signal'],
+};
+/** An environment assignment (`HOST=…`, `BASE_URL="…"`): it runs nothing of its own. */
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** A wrapper's own duration — `timeout 280 …`, `timeout 1m …` — which is not a flag. */
+const DURATION = /^\d+(?:\.\d+)?[smhd]?$/;
+/**
+ * A word without its shell quotes.
+ *
+ * @param word - One word of a segment.
+ * @returns The word with a leading and a trailing quote character removed.
+ */
+function unquoted(word) {
+    return word.replace(/^['"]|['"]$/g, '');
+}
+/**
+ * A word's program name: quotes removed, directory removed (`/usr/bin/hurl` → `hurl`). A scoped
+ * package keeps its scope — the `/` in `@usebruno/cli` is part of the name, not a directory.
+ *
+ * @param word - One word of a segment.
+ * @returns The bare name.
+ */
+function programName(word) {
+    const bare = unquoted(word);
+    if (bare.startsWith('@'))
+        return bare;
+    const parts = bare.split('/');
+    return parts[parts.length - 1] ?? '';
+}
+/**
+ * How many of a wrapper's own words follow it — its flags, and each value flag's value.
+ *
+ * @param words - The segment's words.
+ * @param from - The index just after the wrapper.
+ * @param wrapper - The wrapper's program name.
+ * @returns The count of words the wrapper owns.
+ */
+function flagWords(words, from, wrapper) {
+    const withValue = WRAPPER_VALUE_FLAGS[wrapper] ?? [];
+    let count = 0;
+    while (from + count < words.length && (words[from + count] ?? '').startsWith('-')) {
+        const flag = words[from + count] ?? '';
+        // `--flag=value` carries its value inside the same word.
+        count += !flag.includes('=') && withValue.includes(flag) ? 2 : 1;
+    }
+    return count;
+}
+/**
+ * The `-c '<command>'` string a shell was handed, or null when the shell was given a FILE
+ * (`bash run.sh`) — the wrapper walk then steps past its flags instead.
+ *
+ * @param words - The segment's words.
+ * @param from - The index just after the shell's name.
+ * @returns The command string unquoted, or null.
+ */
+function nestedCommand(words, from) {
+    for (let i = from; i < words.length; i++) {
+        const word = words[i] ?? '';
+        if (!word.startsWith('-'))
+            return null;
+        // A flag cluster holding `c` is `-c` (`bash -lc '…'`, `sh -ec '…'`).
+        if (/^-[A-Za-z]*c[A-Za-z]*$/.test(word) || word === '--command') {
+            const next = words[i + 1];
+            return next === undefined ? null : unquoted(next);
+        }
+    }
+    return null;
+}
+/**
+ * Where the program starts in one segment's words.
+ *
+ * @param words - The segment's words, quotes kept.
+ * @returns The index of the word in command position (one past the end when the segment runs
+ *   nothing), and the command string of a `sh -c '<command>'` this segment turns out to be.
+ */
+function commandStart(words) {
+    let at = 0;
+    for (let guard = 0; guard < MAX_WRAPPERS && at < words.length; guard++) {
+        const word = words[at] ?? '';
+        if (ENV_ASSIGNMENT.test(word)) {
+            at += 1;
+            continue;
+        }
+        const name = programName(word);
+        // `! cmd` inverts an exit status: what runs is still the word after it.
+        if (name === '!') {
+            at += 1;
+            continue;
+        }
+        if (SHELLS.has(name)) {
+            const nested = nestedCommand(words, at + 1);
+            if (nested !== null)
+                return { at, nested };
+            at += 1 + flagWords(words, at + 1, name);
+            continue;
+        }
+        if (PACKAGE_RUNNERS.has(name)) {
+            at += 1 + flagWords(words, at + 1, name);
+            continue;
+        }
+        if (PACKAGE_RUNNER_HEADS.has(name) &&
+            PACKAGE_RUNNER_SUBCOMMANDS.has(unquoted(words[at + 1] ?? ''))) {
+            at += 2 + flagWords(words, at + 2, name);
+            continue;
+        }
+        if (!LAUNCHERS.has(name))
+            return { at, nested: null };
+        at += 1 + flagWords(words, at + 1, name);
+        if (name === 'timeout' && DURATION.test(words[at] ?? ''))
+            at += 1;
+    }
+    return { at, nested: null };
+}
+/**
+ * A command's statements and pipeline stages, split where the shell splits them — inside quotes
+ * and inside a command substitution, a `|`, `;` or `&&` belongs to that command, not to this one.
+ *
+ * A single `&` separates only when it backgrounds a command: the one in a redirect (`2>&1`,
+ * `&>log`) is part of the word it sits in.
+ *
+ * @param command - The shell command.
+ * @returns Each segment's text, in order, with empty ones dropped.
+ */
+function splitSegments(command) {
+    const parts = [];
+    let buffer = '';
+    let quote = null;
+    let substitutions = 0;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i] ?? '';
+        if (quote !== null) {
+            buffer += char;
+            if (char === '\\' && quote === '"' && i + 1 < command.length) {
+                buffer += command[i + 1] ?? '';
+                i += 1;
+            }
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            buffer += char;
+            continue;
+        }
+        if (char === '\\' && i + 1 < command.length) {
+            buffer += char + (command[i + 1] ?? '');
+            i += 1;
+            continue;
+        }
+        if (char === '$' && command[i + 1] === '(') {
+            substitutions += 1;
+            buffer += char;
+            continue;
+        }
+        if (substitutions > 0) {
+            if (char === '(')
+                substitutions += 1;
+            else if (char === ')')
+                substitutions -= 1;
+            buffer += char;
+            continue;
+        }
+        const next = command[i + 1];
+        if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
+            parts.push(buffer);
+            buffer = '';
+            i += 1;
+            continue;
+        }
+        if (char === ';' || char === '|' || char === '\n') {
+            parts.push(buffer);
+            buffer = '';
+            continue;
+        }
+        if (char === '&' && command[i - 1] !== '>' && next !== '>') {
+            parts.push(buffer);
+            buffer = '';
+            continue;
+        }
+        buffer += char;
+    }
+    parts.push(buffer);
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+/**
+ * One segment's words: quotes kept whole, grouping parentheses dropped, and a `(` written
+ * against the first word taken off it (`(npx playwright test)`).
+ *
+ * @param text - One segment's text.
+ * @returns The words.
+ */
+function segmentWords(text) {
+    const words = text.match(WORD) ?? [];
+    const cleaned = words.filter((word) => !GROUPING.has(word));
+    const first = cleaned[0];
+    if (first !== undefined) {
+        const bare = first.replace(/^[({]+/, '');
+        if (bare === '')
+            cleaned.shift();
+        else
+            cleaned[0] = bare;
+    }
+    return cleaned;
+}
+/**
+ * The segments of a command, each with its program and arguments — the answer every classifier
+ * that reads a command as "this runs the suite" is asking for.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage that runs something, in order.
+ */
+export function commandSegments(command) {
+    return segmentsOf(command, 0);
+}
+/**
+ * {@link commandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
+ * {@link MAX_NESTING} allows.
+ *
+ * @param command - The shell command.
+ * @param depth - How many `sh -c` strings this command already sits inside.
+ * @returns The segments.
+ */
+function segmentsOf(command, depth) {
+    if (typeof command !== 'string' || depth > MAX_NESTING)
+        return [];
+    const out = [];
+    for (const text of splitSegments(command)) {
+        const words = segmentWords(text);
+        if (words.length === 0)
+            continue;
+        const start = commandStart(words);
+        if (start.nested !== null) {
+            out.push(...segmentsOf(start.nested, depth + 1));
+            continue;
+        }
+        const word = words[start.at];
+        // Only wrappers and assignments: nothing this segment runs.
+        if (word === undefined)
+            continue;
+        const program = programName(word);
+        const args = words.slice(start.at + 1);
+        out.push({ program, args, text: [program, ...args].join(' ') });
+    }
+    return out;
+}
+/**
+ * Whether any segment of the command runs a program whose command-position text matches
+ * `pattern` — the one question a runner-kind table asks.
+ *
+ * The pattern is matched against `program` and its arguments as one line, so it must be
+ * anchored at `^`; it must not carry the `g` flag (a pattern shared between calls would then
+ * carry its own match position from one segment to the next).
+ *
+ * @param command - The shell command.
+ * @param pattern - An anchored pattern for the runner's invocation.
+ * @returns True when a segment in command position matches.
+ */
+export function runsInCommandPosition(command, pattern) {
+    return commandSegments(command).some((segment) => {
+        pattern.lastIndex = 0;
+        return pattern.test(segment.text);
+    });
+}

package/dist/index.d.ts

@@ -26,9 +26,13 @@
  * - **`read_file` takes `paths` as well as `path`.** An agent that issues one
  *   tool call per model round-trip pays a full round-trip per file, so a project
  *   survey costs minutes; batched, the same reads cost one call each 25 files
- *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
- *   stopped). Each entry carries its own content or its own error, so one bad
- *   path never fails the batch.
+ *   (`MAX_BATCH_READ_FILES`). One result is capped at `MAX_READ_CALL_CHARS`, the
+ *   ceiling the request side puts on a single tool result: whole files are
+ *   returned up to it and every path past that is named in `note` and listed as
+ *   `not returned`, so a file is never handed back in part — the shape that lost
+ *   the middle of a ten-file batch to the request-side cut (X0 flash-m81). Each
+ *   entry carries its own content or its own error, so one bad path never fails
+ *   the batch.
  * - **`edit_file` shows the result, so the model need not re-read.** A
  *   successful edit returns `excerpt`: each edited region as it now reads, with
  *   1-based line numbers (`N: text`) and a few lines of context, capped at
@@ -116,7 +120,9 @@
 export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
+export * from './command-position.js';
 export * from './input-normalizer.js';
+export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -26,9 +26,13 @@
  * - **`read_file` takes `paths` as well as `path`.** An agent that issues one
  *   tool call per model round-trip pays a full round-trip per file, so a project
  *   survey costs minutes; batched, the same reads cost one call each 25 files
- *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
- *   stopped). Each entry carries its own content or its own error, so one bad
- *   path never fails the batch.
+ *   (`MAX_BATCH_READ_FILES`). One result is capped at `MAX_READ_CALL_CHARS`, the
+ *   ceiling the request side puts on a single tool result: whole files are
+ *   returned up to it and every path past that is named in `note` and listed as
+ *   `not returned`, so a file is never handed back in part — the shape that lost
+ *   the middle of a ten-file batch to the request-side cut (X0 flash-m81). Each
+ *   entry carries its own content or its own error, so one bad path never fails
+ *   the batch.
  * - **`edit_file` shows the result, so the model need not re-read.** A
  *   successful edit returns `excerpt`: each edited region as it now reads, with
  *   1-based line numbers (`N: text`) and a few lines of context, capped at
@@ -116,7 +120,9 @@
 export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
+export * from './command-position.js';
 export * from './input-normalizer.js';
+export * from './no-test-run.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/no-test-run.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The runner invocations that print information and run no test — the one classifier every
+ * site asks before it treats a command as a test run.
+ *
+ * A Playwright CLI has subcommands and flags that never start a test: `playwright test --list`
+ * prints the tests it would run and exits, `show-report`/`show-trace` open a saved report,
+ * `codegen` records one, `install` fetches browsers, `merge-reports` joins blobs, and
+ * `--help`/`--version` print and exit. Vitest lists with `vitest list` / `--list` and hurl
+ * prints with `--help`/`--version`, the same way.
+ *
+ * Every check in the platform read such a command as a whole-suite run, because each one
+ * matched the runner's NAME. X1 xr-molecule-flash-m79's first Playwright command was a config
+ * check — a config written to `/tmp`, `cp`'d beside the suite and used with `--list` — and it
+ * came back HELD, `status: not_run`, with a ~4 KB `suiteNote` telling it to send the same
+ * command with `--max-failures=15` ("uncapped it walks every test … 8–13 minutes"), beside an
+ * environment block saying the run "ran on their defaults" and an import note about a path the
+ * `cp` had already fixed. Nothing ran. The model gave up on the approach, wrote a second
+ * config, and its next command was held again (flash-m74's "same command three times" shape):
+ * two holds, zero tests, and the config check it asked for never answered.
+ *
+ * So the classifiers live here, in one place, and callers ask them instead of their own
+ * regexes: {@link commandRunsNoTests} answers for a whole command, and the runner-specific
+ * sites (molecule-dev's suite checks, `streamingBackgroundCommand`, `isSuiteRunCommand`) route
+ * through it. A command that runs no test is never held, never noted, and never rewritten
+ * (`--retries`, `--reporter`) as if it were a run.
+ *
+ * What counts as an invocation is COMMAND POSITION, read by `@molecule/api-ai-tools`'
+ * `commandSegments`: `npx playwright test --list`, `hurl --help` and `bash run.sh` invoke the
+ * runner, while a runner named as an argument (`grep -n playwright e2e/README.md`,
+ * `head -30 run-api-tests-hurl.sh`) invokes nothing at all. X1 xr-molecule-flash-m81 (+20:03)
+ * read a runner script with `head -30` and the suite-overlap hold answered "a Playwright suite is
+ * already running … wait for it", for a command that runs nothing.
+ *
+ * @module
+ */
+/**
+ * Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
+ * command runs no test at all.
+ *
+ * A runner counts only where a shell would RUN it ({@link commandSegments}): the word in command
+ * position of a segment, after its wrapper prefixes. A runner named in an argument is not an
+ * invocation — `head -30 run-api-tests-hurl.sh` and `grep -n playwright e2e/README.md` name a
+ * file to read, and a `--list` written inside a file the command writes is not a flag anyone runs
+ * with (flash-m81).
+ *
+ * A command that invokes no runner is NOT one of these (false): "the command runs no test" is
+ * then true for `ls`, which is not the question any caller is asking. The question is whether
+ * the runner invocation each caller read as a run is one.
+ *
+ * A command that also runs tests is false however it is spelled: `npx playwright install &&
+ * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
+ * reading a real run.
+ *
+ * @param command - The shell command as the executor sent it.
+ * @returns True when the command invokes a runner only to print.
+ */
+export declare function commandRunsNoTests(command: string): boolean;
+//# sourceMappingURL=no-test-run.d.ts.map

package/dist/no-test-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-test-run.d.ts","sourceRoot":"","sources":["../src/no-test-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA0EH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAU3D"}

package/dist/no-test-run.js

@@ -0,0 +1,134 @@
+/**
+ * The runner invocations that print information and run no test — the one classifier every
+ * site asks before it treats a command as a test run.
+ *
+ * A Playwright CLI has subcommands and flags that never start a test: `playwright test --list`
+ * prints the tests it would run and exits, `show-report`/`show-trace` open a saved report,
+ * `codegen` records one, `install` fetches browsers, `merge-reports` joins blobs, and
+ * `--help`/`--version` print and exit. Vitest lists with `vitest list` / `--list` and hurl
+ * prints with `--help`/`--version`, the same way.
+ *
+ * Every check in the platform read such a command as a whole-suite run, because each one
+ * matched the runner's NAME. X1 xr-molecule-flash-m79's first Playwright command was a config
+ * check — a config written to `/tmp`, `cp`'d beside the suite and used with `--list` — and it
+ * came back HELD, `status: not_run`, with a ~4 KB `suiteNote` telling it to send the same
+ * command with `--max-failures=15` ("uncapped it walks every test … 8–13 minutes"), beside an
+ * environment block saying the run "ran on their defaults" and an import note about a path the
+ * `cp` had already fixed. Nothing ran. The model gave up on the approach, wrote a second
+ * config, and its next command was held again (flash-m74's "same command three times" shape):
+ * two holds, zero tests, and the config check it asked for never answered.
+ *
+ * So the classifiers live here, in one place, and callers ask them instead of their own
+ * regexes: {@link commandRunsNoTests} answers for a whole command, and the runner-specific
+ * sites (molecule-dev's suite checks, `streamingBackgroundCommand`, `isSuiteRunCommand`) route
+ * through it. A command that runs no test is never held, never noted, and never rewritten
+ * (`--retries`, `--reporter`) as if it were a run.
+ *
+ * What counts as an invocation is COMMAND POSITION, read by `@molecule/api-ai-tools`'
+ * `commandSegments`: `npx playwright test --list`, `hurl --help` and `bash run.sh` invoke the
+ * runner, while a runner named as an argument (`grep -n playwright e2e/README.md`,
+ * `head -30 run-api-tests-hurl.sh`) invokes nothing at all. X1 xr-molecule-flash-m81 (+20:03)
+ * read a runner script with `head -30` and the suite-overlap hold answered "a Playwright suite is
+ * already running … wait for it", for a command that runs nothing.
+ *
+ * @module
+ */
+import { commandSegments } from './command-position.js';
+/**
+ * The runners by the word in command position. A runner spelled as a FILE's name is not one:
+ * `-c playwright.local.config.ts` names a config, and `node playwright.js` runs node.
+ */
+const RUNNERS = {
+    playwright: 'playwright',
+    vitest: 'vitest',
+    hurl: 'hurl',
+};
+/** Playwright's subcommands that start no test. */
+const PLAYWRIGHT_INFO_SUBCOMMANDS = [
+    'show-report',
+    'show-trace',
+    'codegen',
+    'install',
+    'merge-reports',
+];
+/** Vitest's subcommand that prints what a run would collect. */
+const VITEST_LIST_SUBCOMMAND = 'list';
+/**
+ * The flags that put a runner in an information mode: it prints and exits. `-h` is `--help`
+ * for all three (hurl's manual documents `-h, --help`; Playwright's and Vitest's CLIs follow
+ * the same convention), and the value-taking flags beside them are why each is matched as a
+ * whole token — hurl's `-H` is a header, not help.
+ */
+const NO_RUN_FLAGS = {
+    playwright: [
+        /(?:^|\s)--list(?=\s|$)/,
+        /(?:^|\s)--dry-run(?=\s|$)/,
+        /(?:^|\s)--help(?=\s|$)/,
+        /(?:^|\s)-h(?=\s|$)/,
+        /(?:^|\s)--version(?=\s|$)/,
+    ],
+    vitest: [
+        /(?:^|\s)--list(?=\s|$)/,
+        /(?:^|\s)--help(?=\s|$)/,
+        /(?:^|\s)-h(?=\s|$)/,
+        /(?:^|\s)--version(?=\s|$)/,
+    ],
+    hurl: [/(?:^|\s)--help(?=\s|$)/, /(?:^|\s)-h(?=\s|$)/, /(?:^|\s)--version(?=\s|$)/],
+};
+/**
+ * A heredoc body is data a command writes, not what it runs: a `playwright test --list` inside
+ * the config a command writes is not a run of this command either way. The pattern consumes the
+ * writer's own line prefix, the same shape `outputRedirectTarget` reads.
+ */
+const HEREDOC = /[^\n;&|]*<<-?\s*(['"]?)(\w+)\1[\s\S]*?\n\s*\2\b/g;
+/**
+ * Whether this runner's invocation — the text from just after its name to the end of its
+ * segment ({@link commandSegments}) — only prints.
+ *
+ * @param runner - The runner the segment invokes.
+ * @param after - Everything after the runner's name in that segment.
+ * @returns True when the invocation starts no test.
+ */
+function informational(runner, after) {
+    const first = after.trimStart().split(/\s+/)[0] ?? '';
+    if (runner === 'playwright' && PLAYWRIGHT_INFO_SUBCOMMANDS.includes(first))
+        return true;
+    if (runner === 'vitest' && first === VITEST_LIST_SUBCOMMAND)
+        return true;
+    return NO_RUN_FLAGS[runner].some((re) => re.test(after));
+}
+/**
+ * Whether a shell command invokes a test runner and EVERY such invocation only prints — so the
+ * command runs no test at all.
+ *
+ * A runner counts only where a shell would RUN it ({@link commandSegments}): the word in command
+ * position of a segment, after its wrapper prefixes. A runner named in an argument is not an
+ * invocation — `head -30 run-api-tests-hurl.sh` and `grep -n playwright e2e/README.md` name a
+ * file to read, and a `--list` written inside a file the command writes is not a flag anyone runs
+ * with (flash-m81).
+ *
+ * A command that invokes no runner is NOT one of these (false): "the command runs no test" is
+ * then true for `ls`, which is not the question any caller is asking. The question is whether
+ * the runner invocation each caller read as a run is one.
+ *
+ * A command that also runs tests is false however it is spelled: `npx playwright install &&
+ * npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
+ * reading a real run.
+ *
+ * @param command - The shell command as the executor sent it.
+ * @returns True when the command invokes a runner only to print.
+ */
+export function commandRunsNoTests(command) {
+    if (typeof command !== 'string' || !command.trim())
+        return false;
+    let invocations = 0;
+    for (const segment of commandSegments(command.replace(HEREDOC, ' '))) {
+        const runner = RUNNERS[segment.program];
+        if (!runner)
+            continue;
+        invocations += 1;
+        if (!informational(runner, segment.args.join(' ')))
+            return false;
+    }
+    return invocations > 0;
+}

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAmU1C,CAAA"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAyU1C,CAAA"}

package/dist/schemas.js

@@ -29,7 +29,8 @@ export const TOOL_SCHEMAS = {
             'gathering the files behind one feature — pass them all as `paths` in ONE call rather ' +
             'than calling this tool once per file: same content, a fraction of the time. ' +
             'For a @molecule package\u2019s docs call read_molecule_doc instead — one call, the whole ' +
-            'document. A file under 80 KB comes back whole; do not page through it with offset/limit.',
+            'document. A file that fits one read result comes back whole; do not page through it with ' +
+            'offset/limit.',
         parameters: {
             type: 'object',
             properties: {
@@ -42,7 +43,9 @@ export const TOOL_SCHEMAS = {
                     items: { type: 'string' },
                     description: 'Paths to SEVERAL files to read in one call — preferred whenever you want more ' +
                         'than one file. Returns `files`, one entry per path in the order given, each ' +
-                        "with that file's content or its own error.",
+                        "with that file's content or its own error. Whole files are returned up to what one " +
+                        'read result carries; every path past that comes back in the same list marked ' +
+                        '`not returned` — read those next, in their own calls. No file is ever returned in part.',
                 },
                 offset: {
                     type: 'number',
@@ -248,8 +251,11 @@ export const TOOL_SCHEMAS = {
             'no polling. Use it the moment you need that result to continue; never `sleep` and ' +
             'read the log by hand. If it is still running when the budget ends, the result says so ' +
             'and you can call it again. A suite whose failures keep repeating one cause comes back ' +
-            'EARLY with that cause named, the tests it hit and the command that stops the run — act ' +
-            'on it instead of waiting for the rest.',
+            'EARLY with that cause named and the tests it hit — start fixing it, and still LET THE RUN ' +
+            'FINISH, because the run is what names its other causes; the note says so, and names the ' +
+            'command that stops the run only when that one cause is failing every test. A finished ' +
+            'run with failures comes back with a note grouping them by cause, so one round of fixes ' +
+            'covers every cause it found.',
         parameters: {
             type: 'object',
             properties: {

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;AAkL9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoDnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAuzDxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkL9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA0DnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk4DxF"}