@molecule/api-ai-tools 1.7.0 → 1.8.2

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-10-17T00:30:38.264Z
+Generated: 2026-10-17T02:50:55.123Z
 -->
 
 # @molecule/api-ai-tools
@@ -81,6 +81,72 @@ interface CommandSegment {
 }
 ```
 
+#### `LocatedCommandSegment`
+
+One statement of a shell command, with where it sits and the variables it sets for itself.
+
+`commandSegments` answers WHAT runs; this answers where, and what the shell binds to it — the
+two things a caller that WRITES into a command needs. The platform composes a run from the
+executor's own command in more than one place, and a value written for the runner belongs in
+the runner's own statement: `APP_BASE=https://… cd app && npx playwright test` sets the variable
+for `cd` alone, so the Playwright config falls back to the local app while the command line
+still names the deployed host (xr-molecule-flash-m103 +28:08).
+
+```typescript
+interface LocatedCommandSegment {
+  /**
+   * What the statement runs, or null when it only sets variables (`BASE=http://…` on its own):
+   * that shape persists in the shell, so a caller following assignments across `;`/`&&` has to
+   * see it.
+   */
+  segment: CommandSegment | null
+  /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
+  assignments: readonly string[]
+  /**
+   * The offset in the command of the statement's first word, or null for a segment inside a
+   * nested `sh -c '<command>'` string — its positions are offsets in THAT string, not in this
+   * command, so nothing may be spliced at them.
+   */
+  start: number | null
+  /**
+   * The offset in the command just before the word the statement runs — after its own leading
+   * `NAME=value` words and their whitespace. A `NAME=value` written here is in the environment of
+   * the program the statement runs (`… TEST_MODE=fullstack <here>npx playwright test`). Null
+   * inside a nested `sh -c` string, for the same reason as {@link start}.
+   */
+  assignmentOffset: number | null
+}
+```
+
+#### `SuiteSummary`
+
+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.
+
+```typescript
+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
+}
+```
+
 #### `CutRun`
 
 A run a budget stopped, as its result reports it.
@@ -96,9 +162,15 @@ 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'
@@ -376,6 +448,20 @@ interface ToolBuildConfig {
    */
   outlineLargeHtml?: () => boolean
 
+  /**
+   * The test titles the person's request EXCLUDES by name (molecule-dev's `excludedTestTitles`),
+   * asked when a finished suite run's cause note is built. Their failures are not causes to fix:
+   * the note drops them, says so at the end, and inverts them out of the narrowed re-run it hands
+   * over — a result must never name a test beside "it does not count" (xr-molecule-flash-m101
+   * +12:00, where the executor spent a turn and an edit on the excluded test).
+   *
+   * A getter, not an array, because the request is read per turn while the tool set is built
+   * once. Unset means no test is excluded.
+   *
+   * @returns The quoted titles the request carves out.
+   */
+  excludedTestTitles?: () => readonly string[]
+
   /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
   onAfterWrite?: (path: string) => Promise<void>
 
@@ -454,6 +540,19 @@ interface PromptContext {
 }
 ```
 
+#### `SuiteFilterStrip`
+
+A command with the output filters after its suite runner removed.
+
+```typescript
+interface SuiteFilterStrip {
+  /** The command to run. */
+  command: string
+  /** The pipeline stages dropped, as written (`| grep … | tail -20`), or '' when none were. */
+  dropped: string
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -514,6 +613,12 @@ interface FailureCause {
   seconds: number | null
   /** The distinct tests it hit, in the order the log named them. */
   tests: FailedTest[]
+  /**
+   * The FIRST failure's two most useful body lines — the values that differ, or the locator from
+   * its `Call log` ({@link failureEvidence}) — so a fix round needs no re-read of the log. Empty
+   * for a duration group, whose blocks carried no bodies.
+   */
+  evidence: string[]
 }
 ```
 
@@ -532,7 +637,17 @@ type CommandRunState = 'ran' | typeof CUT_AT_BUDGET
 What stopped a run.
 
 ```typescript
-type CutBy = 'tool-budget' | 'command-timeout'
+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'
 ```
 
 #### `DiscoveredSkill` _(deprecated)_
@@ -608,6 +723,20 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `locatedCommandSegments(command)`
+
+Every statement of a command, with its own assignments and where it sits — assignment-only
+statements included, because the variables those persist are exactly what a later statement of
+the same command reads.
+
+```typescript
+function locatedCommandSegments(command: string): LocatedCommandSegment[]
+```
+
+- `command` — The shell command.
+
+**Returns:** One entry per statement or pipeline stage, in order.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -662,9 +791,29 @@ function commandRunState(result: unknown): CommandRunState
 
 **Returns:** The state the result records.
 
+#### `suiteSummary(text)`
+
+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).
+
+```typescript
+function suiteSummary(text: string): SuiteSummary | null
+```
+
+- `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.
+
 #### `suiteTally(text)`
 
-Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+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.
 
 ```typescript
 function suiteTally(text: string): boolean
@@ -674,13 +823,39 @@ function suiteTally(text: string): boolean
 
 **Returns:** True when the runner's own end-of-run summary is there.
 
-#### `commandCutRun(command, result, elapsedMs, budgetSeconds)`
+#### `suiteRunExitCode(exitCode, output, piped)`
+
+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.
+
+```typescript
+function suiteRunExitCode(exitCode: number | null, output: string, piped: boolean): number | null
+```
+
+- `exitCode` — The code the pipeline reported (null when it has none).
+- `output` — The run's full log.
+- `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.
+
+#### `commandCutRun(command, result, elapsedMs, budgetSeconds, rawOutput)`
 
 The run a command's result records as stopped by a budget, or null when the result is a run that
 ended (or says nothing about a run).
 
 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.
@@ -689,6 +864,8 @@ Evidence, in order — never a guess:
   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`).
 
 ```typescript
 function commandCutRun(
@@ -696,6 +873,7 @@ function commandCutRun(
   result: unknown,
   elapsedMs: number,
   budgetSeconds?: number,
+  rawOutput?: string,
 ): CutRun | null
 ```
 
@@ -703,6 +881,7 @@ function commandCutRun(
 - `result` — Its result.
 - `elapsedMs` — How long the command ran, in ms.
 - `budgetSeconds` — This tool's foreground budget, in seconds (0 when it has none).
+- `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.
 
@@ -726,12 +905,14 @@ function cutRunFacts(result: unknown): CutRun | null
 
 #### `cutRunSentence(run)`
 
-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.
 
 ```typescript
 function cutRunSentence(run: CutRun): string
@@ -880,7 +1061,7 @@ function suiteCommandTarget(command: string): string
 
 **Returns:** The target key.
 
-#### `scopedRerunCommand(command, locations)`
+#### `scopedRerunCommand(command, locations, excluded)`
 
 The whole-suite command made scoped to the tests it should re-run instead: the same
 invocation — same directory, same settings — with the named `file:line`s in place of the whole
@@ -888,11 +1069,16 @@ suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flas
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
 ```typescript
-function scopedRerunCommand(command: string, locations: readonly string[]): string
+function scopedRerunCommand(
+  command: string,
+  locations: readonly string[],
+  excluded?: readonly string[],
+): string
 ```
 
 - `command` — The whole-suite run's command.
 - `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
+- `excluded` — The test titles the request carves out. They are inverted out (`--grep-invert`) so a re-run of the failing locations cannot report one of them again — xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about a test the request had already said does not count.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1331,19 +1517,19 @@ killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
 
 - a trailing `| tail -N`, which holds everything back until the command ends.
   It is dropped: `wait_for_task` already returns the end of the log.
+- any output-only filter piped after a SUITE runner (`| grep … | tail -20`), which hides the
+  failing test's own error and leaves the pipeline's exit status — the filter's — as the run's.
+  Every such stage is dropped ({@link stripTrailingSuiteFilters}); `wait_for_task` already
+  returns the end of the full log, and a run whose tally shows a failure must never report 0
+  (xr-molecule-flash-m101 +25:54).
 - `playwright test` with no `--reporter`, which runs the config's reporter —
   often `html`, which prints nothing per test. `--reporter=list` is added
-  when the playwright run is the command's last step and nothing is piped or
-  redirected from it: it writes each result as it finishes, and it is the
-  shape the platform reads a background suite back in.
+  when the playwright run is the command's last step, piped or not: it writes each result as
+  it finishes, and it is the shape the platform reads a background suite back in.
 
 The run ends up with exactly ONE reporter that prints each failure — `list`. A run that names
 any other printing reporter has it REPLACED, never joined: two of them write every test result
 into the log twice, which on X1 flash-m83 (2026-10-16) made a `--reporter=list,line` run (its
-`line` added by this function one run earlier) report two distinct failures as "4 of this run's
-tests have already failed the same way", and the executor stopped a 139-test walk at test 21
-with a single cause in hand. `line` alone is no use either: it writes `[n/N] <title>` with no
-✓/✘ mark and no duration, so on X1 flash-m62 an 8.3-minute walk of one suite could never trip
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -1393,6 +1579,47 @@ function isPlaywrightRunCommand(command: string): boolean
 
 **Returns:** True when the command starts a Playwright run.
 
+#### `stripTrailingSuiteFilters(command)`
+
+Drop the output-only filters piped after the command's suite runner.
+
+A filter after the runner is not "the end of the log" the executor asked for: it hides the
+failing test's own error (it usually matches none of `✘|passed|failed`), and the pipeline's exit
+status becomes the FILTER's, so `… 2>&1 | grep -E "✘|passed|failed|skipped" | tail -20` came back
+`exitCode: 0` for a run with a failure in it (xr-molecule-flash-m101 +25:54). The tool returns
+the end of the full log anyway, so the filter only costs diagnosability.
+
+Only a contiguous suffix of the stages after the runner is cut, and only stages the parse proves
+are output-only ({@link isOutputOnlyFilter}): a `| tee` or `| xargs` keeps its place, and a
+caller that reports the run's exit code must then treat it as unknown
+({@link suiteRunPipedAfterRunner}).
+
+```typescript
+function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
+```
+
+- `command` — The shell command.
+
+**Returns:** The rewritten command and the stages dropped.
+
+#### `suiteRunPipedAfterRunner(command)`
+
+Whether the command's last step runs a suite whose output still passes through a stage after
+the runner — one {@link stripTrailingSuiteFilters} could not prove is output-only (`| tee log`,
+`| xargs …`). The pipeline's exit status is that stage's, not the run's.
+
+A command whose stages cannot be placed in the text (irregular whitespace inside the run) is
+reported as piped too: whether a pipe follows the runner is then UNKNOWN, and an unknown exit
+code that gets trusted is a failing run read as a pass — the failure this rule exists to stop.
+
+```typescript
+function suiteRunPipedAfterRunner(command: string): boolean
+```
+
+- `command` — The shell command, after the streaming rewrite when one was applied.
+
+**Returns:** True when a pipe this tool must not drop still follows the suite runner, or when the command runs a suite the parse cannot place.
+
 #### `suiteRunPriorityLaunch(command, launch)`
 
 Start a background suite run at lower CPU and IO priority, so the sandbox it
@@ -1938,7 +2165,32 @@ function earlyReturnCause(
 
 **Returns:** The cause to stop the run over, or null — in which case nothing may be stopped, the wait keeps going, and the finding rides the run's result as a note.
 
-#### `failuresByCause(log)`
+#### `matchingExcludedTitles(heading, excluded)`
+
+The titles a request excludes that a test's heading names — the ONE matcher for "is this
+failure one the request does not count?".
+
+The request quotes a test's own title (`… except "should require login to post comment"`,
+extracted by molecule-dev's `excludedTestTitles`) while a run's heading carries more of it
+(`comments.spec.ts › Comments › should require login to post comment`), so containment is the
+comparison. Whitespace is normalised and case is ignored: a brief may wrap the title across a
+line (`xr-molecule-flash-m44`), and the reporter's own casing never has to match the brief's.
+
+Two readers used to answer this separately — the causes note (which therefore asked the
+executor to fix a test the same result said not to) and molecule-dev's exclusion notes — and
+xr-molecule-flash-m101 paid for the gap (+12:00: a turn and an edit spent on the excluded
+test).
+
+```typescript
+function matchingExcludedTitles(heading: string, excluded: readonly string[]): string[]
+```
+
+- `heading` — The text to match against: a test's title, its whole `file › describe › title` path, or (for a note that only has the run's output) the run's text.
+- `excluded` — The titles the request carves out, if the caller knows them.
+
+**Returns:** The excluded titles this heading names, in the request's order.
+
+#### `failuresByCause(log, excluded)`
 
 Every failure a run names, grouped by the cause behind it — one group per cause, with the
 tests it hit.
@@ -1954,15 +2206,22 @@ background `list` run — whose failures print as they fail — or a `line` repo
 they took where it does not, which is why a duration group is labelled as a duration and not as a
 proven cause. A test the log printed twice, or failed twice, is one test.
 
+A test the request EXCLUDES by name is not a cause to fix: its failure does not count for
+this request ({@link matchingExcludedTitles}), so it is dropped here rather than handed to the
+executor as work — a result that names it beside "it does not count" is the contradiction
+xr-molecule-flash-m101 filed (+12:00: the model spent a turn and an edit on the excluded test,
+on a page that was passing).
+
 ```typescript
-function failuresByCause(log: string): FailureCause[]
+function failuresByCause(log: string, excluded?: readonly string[]): FailureCause[]
 ```
 
 - `log` — The log of a finished or running run.
+- `excluded` — The test titles the request carves out, if the caller knows them.
 
 **Returns:** The causes, the one with the most tests first.
 
-#### `failureCausesNote(log)`
+#### `failureCausesNote(log, excluded, run)`
 
 The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
 than two of them.
@@ -1971,15 +2230,26 @@ This is what makes a run worth finishing: every cause the run found, in the resu
 executor reads, so one round of fixes covers all of them rather than the one cause a run
 stopped early happened to reach.
 
+A test the request excludes is not one of the causes — it is dropped and named once, at the
+end, so a result never asks to fix a test it also says to ignore. Where the caller knows how
+the run was started, the note also hands over the narrowed re-run of exactly those tests
+({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the whole suite.
+
 ```typescript
-function failureCausesNote(log: string): string | null
+function failureCausesNote(
+  log: string,
+  excluded?: readonly string[],
+  run?: { command: string; cwd?: string; log?: string },
+): string | null
 ```
 
 - `log` — The finished run's output.
+- `excluded` — The test titles the request carves out, if the caller knows them.
+- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
 
 **Returns:** The note, or null.
 
-#### `rerunOfRunningSuite(run, locations)`
+#### `rerunOfRunningSuite(run, locations, excluded)`
 
 The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
 invocation, in the same directory, narrowed to those tests — or null when the running command
@@ -1996,11 +2266,13 @@ the same app and database, and that is exactly what is refused while the run wal
 function rerunOfRunningSuite(
   run: { command: string; cwd?: string },
   locations: readonly string[],
+  excluded?: readonly string[],
 ): string | null
 ```
 
 - `run` — The run in flight: the command it was started with, as it was run, and the directory that command ran in.
 - `locations` — The failing `file:line`s to re-run, as the run's log printed them.
+- `excluded` — The test titles the request carves out: the re-run inverts them out (`--grep-invert`) so it cannot report them again.
 
 **Returns:** The re-run command, or null when there is no suite to narrow.
 
@@ -2479,12 +2751,39 @@ How many of a repeating cause's failures the note lists before it says "and N mo
 const REPEATING_FAILURE_LISTED: 5
 ```
 
+#### `TOOL_RESULT_CHARS`
+
+The platform's cap on one tool result's text: `MAX_TOOL_OUTPUT_CHARS` in molecule-dev's
+`api/src/ai/chat-handler.ts`, which cuts a longer string field's MIDDLE. A finished run's
+stdout is cut to it, so the cause list must not depend on reading the log back — and must
+itself fit inside it, or the cut lands in the list.
+
+```typescript
+const TOOL_RESULT_CHARS: 8000
+```
+
+#### `FAILURE_CAUSES_CHARS`
+
+The characters a finished run's cause list may use of {@link TOOL_RESULT_CHARS}. The recap
+measured by xr-molecule-flash-m102 (+12:43) was `12 failures, 8 causes`: one cause line is
+~200 chars and ~80 more with its two body lines, so 8 causes is ~2.3 k against the 8 k cap —
+the old 5-cause cap withheld 3 causes that the same result had room for.
+
+The rest of the cap is left to the header, the narrowed re-run command and the exclusion
+line, which ride the same note.
+
+```typescript
+const FAILURE_CAUSES_CHARS: number
+```
+
 #### `FAILURE_CAUSES_LISTED`
 
-How many causes a finished run's summary lists before it says "and N more".
+How many causes a finished run's summary lists at most. The character budget above is the
+bound that must hold (it is what keeps the note on the surviving side of the tool-result
+cut); this is the bound past which a list stops being read at all.
 
 ```typescript
-const FAILURE_CAUSES_LISTED: 5
+const FAILURE_CAUSES_LISTED: 12
 ```
 
 #### `FAILURE_CAUSE_TESTS_LISTED`

package/dist/command-position.d.ts

@@ -58,6 +58,48 @@ export declare function durationSeconds(word: string): number | null;
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * One statement of a shell command, with where it sits and the variables it sets for itself.
+ *
+ * `commandSegments` answers WHAT runs; this answers where, and what the shell binds to it — the
+ * two things a caller that WRITES into a command needs. The platform composes a run from the
+ * executor's own command in more than one place, and a value written for the runner belongs in
+ * the runner's own statement: `APP_BASE=https://… cd app && npx playwright test` sets the variable
+ * for `cd` alone, so the Playwright config falls back to the local app while the command line
+ * still names the deployed host (xr-molecule-flash-m103 +28:08).
+ */
+export interface LocatedCommandSegment {
+    /**
+     * What the statement runs, or null when it only sets variables (`BASE=http://…` on its own):
+     * that shape persists in the shell, so a caller following assignments across `;`/`&&` has to
+     * see it.
+     */
+    segment: CommandSegment | null;
+    /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
+    assignments: readonly string[];
+    /**
+     * The offset in the command of the statement's first word, or null for a segment inside a
+     * nested `sh -c '<command>'` string — its positions are offsets in THAT string, not in this
+     * command, so nothing may be spliced at them.
+     */
+    start: number | null;
+    /**
+     * The offset in the command just before the word the statement runs — after its own leading
+     * `NAME=value` words and their whitespace. A `NAME=value` written here is in the environment of
+     * the program the statement runs (`… TEST_MODE=fullstack <here>npx playwright test`). Null
+     * inside a nested `sh -c` string, for the same reason as {@link start}.
+     */
+    assignmentOffset: number | null;
+}
+/**
+ * Every statement of a command, with its own assignments and where it sits — assignment-only
+ * statements included, because the variables those persist are exactly what a later statement of
+ * the same command reads.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage, in order.
+ */
+export declare function locatedCommandSegments(command: string): LocatedCommandSegment[];
 /**
  * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
  * under (`timeout 280 hurl --test …` → 280), or null when it carries none.

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAmFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAyPD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAkVD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}