@molecule/api-ai-tools 1.7.0 → 1.8.1

package/dist/command-position.js

@@ -64,6 +64,122 @@ const PACKAGE_RUNNER_HEADS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
  * a script of the project's, and nothing is stripped from them.
  */
 const PACKAGE_RUNNER_SUBCOMMANDS = new Set(['dlx', 'exec', 'x']);
+/**
+ * npm's value-taking options: `npm exec`'s own (`-p/--package`, `-c/--call`, `-w/--workspace`,
+ * `--prefix`) and the string-valued configs `npm config ls -l` lists in the sandbox image, which
+ * npm accepts on the command line of any invocation.
+ */
+const NPM_VALUE_FLAGS = [
+    '-c',
+    '--call',
+    '-p',
+    '--package',
+    '-w',
+    '--workspace',
+    '--prefix',
+    '--registry',
+    '--cache',
+    '--userconfig',
+    '--globalconfig',
+    '--loglevel',
+    '--logs-dir',
+    '--script-shell',
+    '--shell',
+    '--tag',
+    '--otp',
+    '--scope',
+    '--location',
+    '--user-agent',
+    '--which',
+    '--viewer',
+    '--proxy',
+    '--https-proxy',
+    '--cert',
+    '--key',
+    '--ca',
+    '--cafile',
+    '--editor',
+    '--message',
+    '--node-options',
+    '--save-prefix',
+    '--preid',
+    '--access',
+    '--also',
+    '--audit-level',
+    '--auth-type',
+    '--before',
+    '--browser',
+    '--cidr',
+    '--cpu',
+    '--depth',
+    '--expect-result-count',
+    '--expect-results',
+    '--install-strategy',
+    '--libc',
+    '--local-address',
+    '--lockfile-version',
+    '--only',
+    '--os',
+    '--pack-destination',
+    '--provenance-file',
+    '--replace-registry-host',
+    '--sbom-format',
+    '--sbom-type',
+    '--searchexclude',
+    '--searchopts',
+    '--tag-version-prefix',
+];
+/** pnpm dlx's value-taking options (`pnpm dlx --help`); its `-c` is the boolean shell-mode. */
+const PNPM_DLX_VALUE_FLAGS = ['--allow-build', '--package', '--reporter'];
+/**
+ * The package manager's OWN options that take their value from the next word — read from the
+ * versions the sandbox image (`node:22-trixie-slim`) ships: npm 10.9.9 (`npm exec --help`, and
+ * every string-valued key of `npm config ls -l`), pnpm 10.34.7 (`pnpm help exec`,
+ * `pnpm dlx --help`) and Yarn 4.18.1 (`yarn dlx --help`). A flag absent here is skipped as a
+ * boolean, which is what every documented switch is.
+ *
+ * The table is keyed per manager because the same short flag means different things in two of
+ * them: `-c` is npm's `--call <command>` (a value, and a command of its own —
+ * {@link PACKAGE_RUNNER_CALL_FLAGS}) but pnpm's `--shell-mode` (a switch), and `-w` is npm's
+ * `--workspace <name>` (a value) but pnpm's `--workspace-root` (a switch).
+ */
+const PACKAGE_RUNNER_VALUE_FLAGS = {
+    // npm exec's documented options, plus the config flags npm accepts on any invocation.
+    npx: NPM_VALUE_FLAGS,
+    'npm exec': NPM_VALUE_FLAGS,
+    'npm x': NPM_VALUE_FLAGS,
+    // `npx --prefix /app playwright test` is how flash-m101's run reached the app's own Playwright.
+    bunx: ['-p', '--package'],
+    'bun x': ['-p', '--package'],
+    pnpx: PNPM_DLX_VALUE_FLAGS,
+    'pnpm dlx': PNPM_DLX_VALUE_FLAGS,
+    'pnpm x': PNPM_DLX_VALUE_FLAGS,
+    'pnpm exec': [
+        '-C',
+        '--dir',
+        '--loglevel',
+        '--resume-from',
+        '--reporter',
+        '--filter',
+        '--filter-prod',
+        '--changed-files-ignore-pattern',
+        '--workspace-concurrency',
+        '--prefix',
+    ],
+    'yarn dlx': ['-p', '--package'],
+    'yarn exec': [],
+    'yarn x': [],
+};
+/**
+ * The package-runner options whose VALUE is itself a command (`npm exec -c '<command>'`), so it is
+ * parsed as one: `npx -c 'playwright test'` runs Playwright, and its program is not the word after
+ * the flag.
+ */
+const PACKAGE_RUNNER_CALL_FLAGS = {
+    npx: ['-c', '--call'],
+    'npm exec': ['-c', '--call'],
+    'npm x': ['-c', '--call'],
+};
 /** 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'],
@@ -149,6 +265,44 @@ function flagWords(words, from, wrapper) {
     }
     return count;
 }
+/**
+ * How many words a package runner (`npx`, `npm exec`, `pnpm dlx`, `yarn dlx`) owns before the
+ * program it runs — its own options, and each value flag's value — plus the command string of a
+ * `-c '<command>'`, which is a command of its own rather than the program word.
+ *
+ * A `--` ends the options: `npm exec --prefix x -- playwright test` runs `playwright` with `test`,
+ * so the terminator is consumed and the walk stops there.
+ *
+ * @param words - The segment's words.
+ * @param from - The index just after the runner (or after `npm exec`).
+ * @param key - The runner's table key (`npm`, `npx`, `pnpm exec`, `yarn dlx`, …).
+ * @returns The count of words the runner owns, and the `-c` command string when it carries one.
+ */
+function packageRunnerOptions(words, from, key) {
+    const withValue = PACKAGE_RUNNER_VALUE_FLAGS[key] ?? [];
+    const callFlags = PACKAGE_RUNNER_CALL_FLAGS[key] ?? [];
+    let count = 0;
+    while (from + count < words.length) {
+        const word = words[from + count] ?? '';
+        if (!word.startsWith('-'))
+            break;
+        // `--` ends the runner's options; the program is the next word.
+        if (word === '--')
+            return { count: count + 1, nested: null };
+        const flag = unquoted(word);
+        // `--flag=value` carries its value inside the same word.
+        if (word.includes('=')) {
+            count += 1;
+            continue;
+        }
+        if (callFlags.includes(flag)) {
+            const value = words[from + count + 1];
+            return { count: count + 2, nested: value === undefined ? null : unquoted(value) };
+        }
+        count += withValue.includes(flag) ? 2 : 1;
+    }
+    return { count, nested: null };
+}
 /**
  * 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.
@@ -201,12 +355,19 @@ function commandStart(words) {
             continue;
         }
         if (PACKAGE_RUNNERS.has(name)) {
-            at += 1 + flagWords(words, at + 1, name);
+            const runner = packageRunnerOptions(words, at + 1, name);
+            if (runner.nested !== null)
+                return { at, nested: runner.nested, timeoutSeconds };
+            at += 1 + runner.count;
             continue;
         }
         if (PACKAGE_RUNNER_HEADS.has(name) &&
             PACKAGE_RUNNER_SUBCOMMANDS.has(unquoted(words[at + 1] ?? ''))) {
-            at += 2 + flagWords(words, at + 2, name);
+            const subcommand = unquoted(words[at + 1] ?? '');
+            const runner = packageRunnerOptions(words, at + 2, `${name} ${subcommand}`);
+            if (runner.nested !== null)
+                return { at, nested: runner.nested, timeoutSeconds };
+            at += 2 + runner.count;
             continue;
         }
         if (!LAUNCHERS.has(name))

package/dist/cut-run.d.ts

@@ -24,6 +24,12 @@
  *    `backends/sandbox.ts`), which reports 124 whatever the pipeline did, and returns everything
  *    printed until then. The budget is the tool's own, so its number belongs to the tool.
  *
+ * A runner's closing summary is what separates "used the bound and finished" from "stopped at the
+ * bound", but it is only half the evidence: Playwright prints one when its process is stopped too,
+ * listing just the tests it reached. So a summary is a finish only when it accounts for the total
+ * the runner announced before it started ({@link suiteSummary}) — a summary that does not
+ * reconcile is a stopped run like any other, and the result says so.
+ *
  * @module
  */
 /**
@@ -46,14 +52,82 @@ export type CommandRunState = 'ran' | typeof CUT_AT_BUDGET;
  */
 export declare function commandRunState(result: unknown): CommandRunState;
 /**
- * Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+ * What a runner's own closing summary reports, and whether it accounts for the whole run.
+ *
+ * A summary is not by itself proof that the run finished. Playwright prints one when its process
+ * is stopped too (SIGTERM/SIGINT), listing only the tests it reached — so a run killed at 36 of
+ * 139 tests ends with the same `36 passed (2.5m)` line as a run that walked all 139. The only
+ * thing that separates them is the total the runner announced before it started
+ * (`Running 139 tests using 1 worker`), which {@link suiteSummary} reconciles the summary against.
+ */
+export interface SuiteSummary {
+    /**
+     * The total the runner announced before its first test, or null when it announced none (Hurl
+     * announces nothing; Vitest's own summary line carries its total in parentheses).
+     */
+    announced: number | null;
+    /**
+     * Every test the summary accounts for — the ones it passed, failed, marked flaky, timed out,
+     * interrupted, skipped or left "did not run". This is how far the walk got, which is what a
+     * stopped run's sentence says; a summary that accounts for fewer than {@link announced} was
+     * printed by a process that stopped early.
+     */
+    accounted: number;
+    /** Whether the summary accounts for every test the runner announced. */
+    finished: boolean;
+}
+/**
+ * What the runner's closing summary accounts for, or null when it printed none.
+ *
+ * Three runners' summaries are read, each by its own wording: Playwright's per-status lines
+ * (reconciled against its `Running N tests` announcement), Vitest's single `Tests …` line (its own
+ * parenthesised total), and Hurl's `Executed files:` block (which it prints only at the end, and
+ * which announces no total — so it is a finish by construction).
+ *
+ * @param text - The run's stdout and stderr, RAW (a truncated copy can lose the announcement).
+ * @returns The summary, or null when the text carries none.
+ */
+export declare function suiteSummary(text: string): SuiteSummary | null;
+/**
+ * Whether text carries a runner's closing summary.
+ *
+ * A summary is NOT a finish on its own — a stopped Playwright run prints one too. Use
+ * {@link suiteSummary} and its `finished` for that.
  *
  * @param text - The run's stdout and stderr.
  * @returns True when the runner's own end-of-run summary is there.
  */
 export declare function suiteTally(text: string): boolean;
+/**
+ * The exit code a finished suite run may report.
+ *
+ * The code in a background result is the code of the command's LAST pipeline stage. When a stage
+ * after the suite runner still consumes its output (`| tee run.log`, or a filter the platform could
+ * not prove output-only), that stage produced the code, not the run — and `… | grep … | tail -20`
+ * exited 0 for a run with a failure in it (xr-molecule-flash-m101 +25:54). No code is reported
+ * then: the log's own tally decides.
+ *
+ * The same reading covers a code of 0 beside a tally that names a failure: whatever ended the
+ * pipeline, a run whose log counts a failure did not pass.
+ *
+ * @param exitCode - The code the pipeline reported (null when it has none).
+ * @param output - The run's full log.
+ * @param piped - Whether a pipeline stage after the suite runner still consumes its output.
+ * @returns The code the run may report, or null when the code is the filter's or contradicts the tally.
+ */
+export declare function suiteRunExitCode(exitCode: number | null, output: string, piped: boolean): number | null;
 /** What stopped a run. */
-export type CutBy = 'tool-budget' | 'command-timeout';
+export type CutBy = 
+/** This tool's own budget (the backend's `timeout`, just past it). */
+'tool-budget'
+/** The `timeout <N>` the command itself carried. */
+ | 'command-timeout'
+/**
+ * Something outside the run: the runner's summary does not account for the total it announced,
+ * and neither of the two bounds above had fired — the process was killed by something this
+ * platform does not own (the sandbox's own process supervisor, the box going away, a signal).
+ */
+ | 'process-stop';
 /** A run a budget stopped, as its result reports it. */
 export interface CutRun {
     /** The bound the run was allowed, in seconds. */
@@ -65,9 +139,15 @@ export interface CutRun {
      * the pipeline's filter (`… | tail`) rather than to the run — the case that read as success.
      */
     exitCode: number | null;
-    /** How many files or tests the runner's own output shows finishing, or null when it shows none. */
+    /**
+     * How far the run got, as its own output counts it — the files that finished, or the tests its
+     * summary accounts for — or null when the output says nothing.
+     */
     ran: number | null;
-    /** How many the run was walking, when the runner printed it (Playwright's `[n/K]`), or null. */
+    /**
+     * How many the run was walking: the total its runner announced (`Running 139 tests`), or
+     * Playwright's `[n/K]`, whichever the output carries; null when neither does.
+     */
     total: number | null;
     /** The noun the runner counts in. */
     noun: 'files' | 'tests';
@@ -80,6 +160,9 @@ export interface CutRun {
  *
  * Evidence, in order — never a guess:
  *
+ * - the runner's own summary, when it printed one: it is a finish only if it accounts for the total
+ *   the runner announced. A summary that accounts for fewer is a walk a process stopped early, and
+ *   falls through to the branches below with its own counts ({@link suiteSummary}).
  * - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
  *   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
  *   ran out first and less than the budget, that bound instead.
@@ -88,14 +171,19 @@ export interface CutRun {
  *   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
  * - the run used this tool's whole budget behind a filter that withheld its output, and printed no
  *   closing summary: the budget stopped it, and no code in the result is the run's.
+ * - a summary that does not account for its announced total, with neither bound fired: something
+ *   outside this platform stopped the process ({@link CutBy} `process-stop`).
  *
  * @param command - The command the executor sent.
  * @param result - Its result.
  * @param elapsedMs - How long the command ran, in ms.
  * @param budgetSeconds - This tool's foreground budget, in seconds (0 when it has none).
+ * @param rawOutput - The run's output BEFORE truncation, when the caller has it: the announcement
+ *   a summary is reconciled against is the first line a long run prints, which is exactly what a
+ *   size cap drops. Detection reads this; the sentence's last line still comes from `result`.
  * @returns The stopped run, or null.
  */
-export declare function commandCutRun(command: string, result: unknown, elapsedMs: number, budgetSeconds?: number): CutRun | null;
+export declare function commandCutRun(command: string, result: unknown, elapsedMs: number, budgetSeconds?: number, rawOutput?: string): CutRun | null;
 /**
  * The facts a result records about the run a budget stopped it in — what a reader needs to say
  * how far the run got WITHOUT re-reading its log or re-deriving the counts.
@@ -110,12 +198,14 @@ export declare function commandCutRun(command: string, result: unknown, elapsedM
  */
 export declare function cutRunFacts(result: unknown): CutRun | null;
 /**
- * The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
- * got, and the last thing it printed.
+ * The first line of a stopped run's result: how far it got, what stopped it, the last thing it
+ * printed, and what the reader must do next.
  *
  * Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
  * the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
- * read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+ * read elsewhere (the suite's own file count) fills in the "of N" it can then state. The sentence
+ * says how many tests the stop left unrun — a number a reader cannot round up to "the suite
+ * passed" — and hands over the one move that survives a long run: run it in the background.
  *
  * @param run - The stopped run.
  * @returns The sentence.

package/dist/cut-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AA0BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAErD,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,mGAAmG;IACnG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AA2CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,GAChB,MAAM,GAAG,IAAI,CA2Df;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBlD"}
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAgFf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuBlD"}