@molecule/api-ai-tools 1.12.0 → 1.13.1

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-21T20:10:49.315Z
+Generated: 2026-10-22T07:11:20.054Z
 -->
 
 # @molecule/api-ai-tools
@@ -360,6 +360,101 @@ interface RunnerOutputFilter {
 }
 ```
 
+#### `PlaywrightReportAttachment`
+
+One artifact the runner saved for one test, as the report records it.
+
+```typescript
+interface PlaywrightReportAttachment {
+  /** The attachment's name (`trace`, `screenshot`, …). */
+  name: string
+  /** Its media type, when the runner recorded one. */
+  contentType: string | null
+  /** Where the runner saved it, as the report wrote the path. */
+  path: string
+}
+```
+
+#### `PlaywrightReportTest`
+
+One failing (or flaky) test's identity and evidence, as the runner recorded them.
+
+The identity fields are Playwright's own — never reconstructed from printed headings — so a
+reader can tell exactly which test an attachment belongs to.
+
+```typescript
+interface PlaywrightReportTest {
+  /** The spec's stable id, when the report carries one. */
+  id: string | null
+  /** The Playwright project the test ran in. */
+  project: string | null
+  /** The spec file, relative to the config's root directory as the report writes it. */
+  file: string
+  /** The test's declaration line. */
+  line: number
+  /** The test's declaration column. */
+  column: number
+  /** The full title path (`['describe', …, 'test title']`), empty when none is readable. */
+  titlePath: string[]
+  /** The test's own title (the last entry of {@link titlePath}). */
+  title: string
+  /** Playwright's outcome for the test: `unexpected`, `flaky`, `skipped` or `expected`. */
+  status: string
+  /** How many attempts the runner made (1 when it was not retried). */
+  attempts: number
+  /** The retry index of the attempt whose evidence is reported (0 when not retried). */
+  retry: number
+  /** That attempt's own duration, in milliseconds. */
+  durationMs: number
+  /** That attempt's error message, bounded and redacted, or null. */
+  error: string | null
+  /** The artifacts the runner saved for THAT attempt — `trace` first. */
+  attachments: PlaywrightReportAttachment[]
+}
+```
+
+#### `PlaywrightReportStats`
+
+The runner's own tally, read straight from the report. Never a verdict this module derives.
+
+```typescript
+interface PlaywrightReportStats {
+  /** Tests that ended as expected. */
+  expected: number
+  /** Tests the runner skipped. */
+  skipped: number
+  /** Tests that did not end as expected. */
+  unexpected: number
+  /** Tests that failed and then passed on a retry. */
+  flaky: number
+  /** The run's own duration, in milliseconds. */
+  durationMs: number
+}
+```
+
+#### `PlaywrightRunReport`
+
+What one run's standard machine report says, bounded for a tool result.
+
+A reader that needs evidence this record does not carry reads {@link path} in the sandbox.
+
+```typescript
+interface PlaywrightRunReport {
+  /** How much of the report was read — see {@link PlaywrightReportStatus}. */
+  status: PlaywrightReportStatus
+  /** Where the report file is, for the full evidence. Always the runner's own file. */
+  path: string
+  /** One short phrase saying why a record is not `complete`, when it is not. */
+  reason?: string
+  /** The runner's tally, or null when the report did not carry one. */
+  stats: PlaywrightReportStats | null
+  /** The failing and flaky tests, in report order, bounded by {@link MAX_REPORTED_FAILURES}. */
+  failures: PlaywrightReportTest[]
+  /** How many failing tests did not fit the bound above. */
+  omittedFailures: number
+}
+```
+
 #### `ToolSchema`
 
 JSON-schema-backed definition for a single agent tool.
@@ -943,6 +1038,18 @@ interface TraceArtifact {
    * Absent when no group reached the threshold, and on traces read before this field existed.
    */
   repeated?: TraceRequestRepeat[]
+  /**
+   * The directory the trace was read from, relative to the root the reader was given.
+   *
+   * Playwright saves one directory per test attempt under the run's `outputDir`, and every artifact
+   * of that attempt — `trace.zip` included — sits in it. The run's own machine report records each
+   * test that wrote a trace with its attachment path, so this relative directory is the exact mark
+   * binding THIS artifact to the test that wrote it, with no join by spec line needed
+   * ({@link ./playwright-report.js}).
+   *
+   * Absent on traces read before this field existed.
+   */
+  dir?: string
 }
 ```
 
@@ -1562,6 +1669,23 @@ What the transport did when a request never got an answer.
 type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty'
 ```
 
+#### `PlaywrightReportStatus`
+
+How much of a report this module could account for.
+
+- `complete` — the runner's stats and its suite tree both parsed: every test entry is present.
+- `partial` — a report was written but is not a whole run (Playwright's own `errors` are present,
+  the suite tree is missing, or the file is past {@link MAX_REPORT_PARSE_CHARS}). What is listed
+  is real; what is missing must be read at {@link PlaywrightRunReport.path}.
+- `malformed` — the file exists but is not a Playwright JSON report (truncated, wrong shape).
+  Nothing in it may be treated as runner data.
+- `missing` — the run left no report (killed before `onEnd`, not a run this wrapper rewrote, or
+  the file was removed). Nothing may be inferred from its absence.
+
+```typescript
+type PlaywrightReportStatus = 'complete' | 'partial' | 'malformed' | 'missing'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -1792,6 +1916,43 @@ function statementArgumentEnd(
 
 **Returns:** The offset to write the option at, or null when the statement cannot be placed here.
 
+#### `statementBoundary(command, start, end)`
+
+Where a statement's own text ends, and whether it leaves a group open.
+
+A statement can be written inside a subshell or a brace group, and the tokenizer attaches an
+adjacent closer to its last word because no separator comes between them: `( … | tail -25)`
+parses its last stage as `tail` with the argument `-25)`. {@link LocatedCommandSegment.end}
+therefore says one past the `)`, and a caller cutting that stage out of the command takes the
+group's closer with it — the rewritten command is then `( … 2>&1`, which no shell parses
+(xr-molecule-flash-m418 +23:31: a heredoc config plus a parenthesized Playwright pipeline came
+back as `end of file unexpected` from the background runner).
+
+The parse's own group depths answer which closers belong to an enclosing group: the depth a
+statement was written at is its first character's depth (an opener is recorded at the depth
+BEFORE it opens), and every character of that statement's own words is at that depth or deeper.
+A closer at a LOWER depth closes a group opened before the statement, so it is not the
+statement's text. A character inside a quote (`-1`) is literal text and stops the walk: `grep
+'a)b'` ends on its own quote, not on a closer.
+
+The same depths answer the other dangerous cut: a stage that OPENS a group it does not close
+(`| { cat` when the `}` follows a `;`) has its closer outside the stage, so dropping the stage
+alone leaves that closer dangling.
+
+```typescript
+function statementBoundary(
+  command: string,
+  start: number | null,
+  end: number | null,
+): { textEnd: number; leavesGroupOpen: boolean } | null
+```
+
+- `command` — The shell command.
+- `start` — The statement's first character ({@link LocatedCommandSegment.start}).
+- `end` — One past the statement's last character ({@link LocatedCommandSegment.end}).
+
+**Returns:** The offset of the first character that is not the statement's own text, and whether the statement leaves a group it opened still open; null when it cannot be placed in this command.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -2255,6 +2416,105 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 
 **Returns:** One sentence naming the stage the code came from, or null.
 
+#### `reportCarriesIdentities(status)`
+
+The report statuses for which the report's own per-test identities and attachments may be used.
+
+`partial` is included because a partial report's suite tree, where it parsed, is still the
+runner's own record of which test owns which attachment; `malformed` and `missing` are not,
+because nothing about them is runner data.
+
+```typescript
+function reportCarriesIdentities(status: PlaywrightReportStatus): boolean
+```
+
+- `status` — One record's {@link PlaywrightReportStatus}.
+
+**Returns:** True when the record's tests and attachments are the runner's own.
+
+#### `reportTestAttachmentPaths(test)`
+
+The attachment paths a stored test record carries, `trace` first.
+
+```typescript
+function reportTestAttachmentPaths(test: PlaywrightReportTest): string[]
+```
+
+- `test` — One entry of {@link PlaywrightRunReport.failures}, as stored.
+
+**Returns:** Every saved path the record can prove, in its own order.
+
+#### `reportTestArtifactDir(test)`
+
+The directory a test result's own artifacts were saved in, or null when the report names none.
+
+Playwright writes one directory per test attempt under the run's `outputDir`, and every artifact
+of that attempt — `trace.zip` included — sits in it. The directory is therefore the exact
+ownership mark for a trace: two tests' traces are never in one another's directory. A damaged
+record whose attachment entries carry no path answers null, so nothing is claimed from it.
+
+```typescript
+function reportTestArtifactDir(test: PlaywrightReportTest): string | null
+```
+
+- `test` — One entry of {@link PlaywrightRunReport.failures}, as stored.
+
+**Returns:** The posix-normalized directory, or null.
+
+#### `summarizePlaywrightReport(text, options)`
+
+Summarize one Playwright `json` report into the bounded record a tool result carries.
+
+Pure text in, record out: the caller reads the file (and decides whether it may), so this is
+testable against genuine reports and against malformed controls alike.
+
+```typescript
+function summarizePlaywrightReport(
+  text: string,
+  options: { path: string; sanitize?: (text: string) => string },
+): PlaywrightRunReport
+```
+
+- `text` — The report file's text, exactly as written.
+- `options` — Where the file is, and the consumer's redactor for error text.
+- `options.path` — The report file's path, carried on the record for full evidence.
+- `options.sanitize` — Redactor applied to error text (defaults to the identity).
+
+**Returns:** The bounded record; never a verdict.
+
+#### `commandWritesReportTo(command, expectedPath)`
+
+The report path a command was launched with, when it is the one this platform sets.
+
+Read back from the launched script (and from a completed task's own command) so a record written
+before an API restart is still found: the path is the task's own id derived by
+{@link playwrightReportPathFor}, never a path parsed out of the executor's command.
+
+```typescript
+function commandWritesReportTo(command: string, expectedPath: string): boolean
+```
+
+- `command` — The command as it was launched.
+- `expectedPath` — The one path this task's report may be at.
+
+**Returns:** True when the command sets {@link PLAYWRIGHT_REPORT_ENV} to that exact path.
+
+#### `playwrightReportPathFor(taskId)`
+
+The report file a background task's own scratch files live beside.
+
+Derived from the task id, never from the command: the id is unique per launch, so two runs can
+never read one another's report, and the path survives a process restart the same way the task's
+log and exit file do.
+
+```typescript
+function playwrightReportPathFor(taskId: string): string
+```
+
+- `taskId` — The `mol-bg-…` handle the launch returned.
+
+**Returns:** The report file's absolute path.
+
 #### `startsServerProgram(command)`
 
 Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
@@ -2423,13 +2683,15 @@ function withSuiteConfig(command: string, config: string | null | undefined): st
 #### `scopedRerunCommand(command, locations, excluded, config, cwd, env)`
 
 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
-suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+invocation — same launcher, same settings — with the named `file:line`s in place of every
+positional selection the run carried (a spec file, a suite directory or a regex filter),
+`--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
 The re-run keeps the run's `> <file>` redirect only in the sense of keeping its OUTPUT there:
-the target is rewritten to a fresh sibling ({@link redirectToFreshFile}), so a re-run never
-overwrites the log the run itself is the evidence for (xr-molecule-flash-m173).
+the target is rewritten to a fresh sibling ({@link redirectRunnerOutputsToFreshFiles}), so a
+re-run never overwrites the log the run itself is the evidence for (xr-molecule-flash-m173) —
+and the setup around the run keeps its own file writes untouched (xr-molecule-flash-m429).
 
 `config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
 carries it whenever the command itself does not, so a run that dropped `--config` cannot be
@@ -3184,7 +3446,7 @@ function outputRedirectTarget(command: string): string | null
 
 **Returns:** The target, or null (`/dev/null` and `&1`/`&2` are not files).
 
-#### `streamingBackgroundCommand(command, context)`
+#### `streamingBackgroundCommand(command, context, reportPath)`
 
 Rewrite a command about to run in the background so its log grows while it
 runs. Two shapes left the log empty until exit, and an empty log is what
@@ -3213,13 +3475,44 @@ _(description truncated — read the full text in `node_modules/@molecule/api-ai
 function streamingBackgroundCommand(
   command: string,
   context?: DiagnosisRunContext,
-): { command: string; changes: string[]; error?: string }
+  reportPath?: string,
+): { command: string; changes: string[]; reportPath?: string; error?: string }
 ```
 
 - `command` — The command as the executor sent it.
 - `context` — What the caller knows beyond the command: the tests the person's request 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).
+- `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.
 
-**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.
+#### `withPlaywrightRunReport(command, reportPath)`
+
+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.
+
+```typescript
+function withPlaywrightRunReport(
+  command: string,
+  reportPath: string,
+): { command: string; reportPath: string | null }
+```
+
+- `command` — The command the executor sent, after every other rewrite.
+- `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.
 
 #### `suiteRunStatements(command)`
 
@@ -3388,6 +3681,10 @@ run writes still holds every failure (xr-molecule-flash-m121 — a `| tail -5; e
 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.
+
 ```typescript
 function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 ```
@@ -4319,7 +4616,9 @@ function whitespaceTolerantReplace(
 
 The shell command that parses one file and exits non-zero with the error
 when it does not parse: `node --check` for JavaScript, `JSON.parse` for
-JSON, esbuild's transform (present wherever Vite is) for TypeScript.
+ordinary JSON, TypeScript's config parser for `tsconfig`/`jsconfig` files
+(which are JSONC), esbuild's transform (present wherever Vite is) for
+TypeScript.
 
 ```typescript
 function parseCheckCommand(path: string): string | null
@@ -4385,6 +4684,59 @@ is a runaway detector, not a performance budget.
 const INLINE_SCRIPT_BUDGET_MS: 20000
 ```
 
+#### `PLAYWRIGHT_REPORT_ENV`
+
+The environment variable Playwright's built-in `json` reporter takes its output path from
+(`resolveOutputFile("JSON", …)`), resolved against the runner's own working directory. An
+absolute path is used here, so the file lands in the run's scratch area whatever directory the
+suite runs from.
+
+```typescript
+const PLAYWRIGHT_REPORT_ENV: 'PLAYWRIGHT_JSON_OUTPUT_FILE'
+```
+
+#### `PLAYWRIGHT_REPORT_SUFFIX`
+
+The file name a background task's report is written to, beside its own log.
+
+```typescript
+const PLAYWRIGHT_REPORT_SUFFIX: '.playwright.json'
+```
+
+#### `MAX_REPORT_PARSE_CHARS`
+
+How big a report may be before this module refuses to summarize it. The file stays readable at
+its path; the record only says so. A whole 139-test suite's report is well under a megabyte; a
+report past this is not one a tool result should carry.
+
+```typescript
+const MAX_REPORT_PARSE_CHARS: 8000000
+```
+
+#### `MAX_REPORTED_FAILURES`
+
+How many failing tests a record lists before the rest are counted in `omittedFailures`.
+
+```typescript
+const MAX_REPORTED_FAILURES: 12
+```
+
+#### `MAX_REPORTED_ATTACHMENTS`
+
+How many attachments one failing test keeps in the record (`trace` first).
+
+```typescript
+const MAX_REPORTED_ATTACHMENTS: 4
+```
+
+#### `MAX_REPORTED_ERROR_CHARS`
+
+How much of one failure's own error text the record keeps.
+
+```typescript
+const MAX_REPORTED_ERROR_CHARS: 400
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.

package/dist/command-position.d.ts

@@ -205,6 +205,39 @@ export declare function locatedCommandSegments(command: string): LocatedCommandS
  * @returns The offset to write the option at, or null when the statement cannot be placed here.
  */
 export declare function statementArgumentEnd(command: string, start: number | null, end: number | null): number | null;
+/**
+ * Where a statement's own text ends, and whether it leaves a group open.
+ *
+ * A statement can be written inside a subshell or a brace group, and the tokenizer attaches an
+ * adjacent closer to its last word because no separator comes between them: `( … | tail -25)`
+ * parses its last stage as `tail` with the argument `-25)`. {@link LocatedCommandSegment.end}
+ * therefore says one past the `)`, and a caller cutting that stage out of the command takes the
+ * group's closer with it — the rewritten command is then `( … 2>&1`, which no shell parses
+ * (xr-molecule-flash-m418 +23:31: a heredoc config plus a parenthesized Playwright pipeline came
+ * back as `end of file unexpected` from the background runner).
+ *
+ * The parse's own group depths answer which closers belong to an enclosing group: the depth a
+ * statement was written at is its first character's depth (an opener is recorded at the depth
+ * BEFORE it opens), and every character of that statement's own words is at that depth or deeper.
+ * A closer at a LOWER depth closes a group opened before the statement, so it is not the
+ * statement's text. A character inside a quote (`-1`) is literal text and stops the walk: `grep
+ * 'a)b'` ends on its own quote, not on a closer.
+ *
+ * The same depths answer the other dangerous cut: a stage that OPENS a group it does not close
+ * (`| { cat` when the `}` follows a `;`) has its closer outside the stage, so dropping the stage
+ * alone leaves that closer dangling.
+ *
+ * @param command - The shell command.
+ * @param start - The statement's first character ({@link LocatedCommandSegment.start}).
+ * @param end - One past the statement's last character ({@link LocatedCommandSegment.end}).
+ * @returns The offset of the first character that is not the statement's own text, and whether
+ *   the statement leaves a group it opened still open; null when it cannot be placed in this
+ *   command.
+ */
+export declare function statementBoundary(command: string, start: number | null, end: number | null): {
+    textEnd: number;
+    leavesGroupOpen: boolean;
+} | null;
 /**
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAynBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;AAmCD;;;;;;;;;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;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;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":"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"}

package/dist/command-position.js

@@ -1325,6 +1325,72 @@ export function statementArgumentEnd(command, start, end) {
         at -= 1;
     return at;
 }
+/**
+ * Where a statement's own text ends, and whether it leaves a group open.
+ *
+ * A statement can be written inside a subshell or a brace group, and the tokenizer attaches an
+ * adjacent closer to its last word because no separator comes between them: `( … | tail -25)`
+ * parses its last stage as `tail` with the argument `-25)`. {@link LocatedCommandSegment.end}
+ * therefore says one past the `)`, and a caller cutting that stage out of the command takes the
+ * group's closer with it — the rewritten command is then `( … 2>&1`, which no shell parses
+ * (xr-molecule-flash-m418 +23:31: a heredoc config plus a parenthesized Playwright pipeline came
+ * back as `end of file unexpected` from the background runner).
+ *
+ * The parse's own group depths answer which closers belong to an enclosing group: the depth a
+ * statement was written at is its first character's depth (an opener is recorded at the depth
+ * BEFORE it opens), and every character of that statement's own words is at that depth or deeper.
+ * A closer at a LOWER depth closes a group opened before the statement, so it is not the
+ * statement's text. A character inside a quote (`-1`) is literal text and stops the walk: `grep
+ * 'a)b'` ends on its own quote, not on a closer.
+ *
+ * The same depths answer the other dangerous cut: a stage that OPENS a group it does not close
+ * (`| { cat` when the `}` follows a `;`) has its closer outside the stage, so dropping the stage
+ * alone leaves that closer dangling.
+ *
+ * @param command - The shell command.
+ * @param start - The statement's first character ({@link LocatedCommandSegment.start}).
+ * @param end - One past the statement's last character ({@link LocatedCommandSegment.end}).
+ * @returns The offset of the first character that is not the statement's own text, and whether
+ *   the statement leaves a group it opened still open; null when it cannot be placed in this
+ *   command.
+ */
+export function statementBoundary(command, start, end) {
+    if (typeof command !== 'string')
+        return null;
+    if (start === null || end === null)
+        return null;
+    if (!Number.isInteger(start) || !Number.isInteger(end))
+        return null;
+    if (start < 0 || end > command.length || end < start)
+        return null;
+    const part = splitSegments(command).find((candidate) => candidate.start === start && candidate.start + candidate.text.length === end);
+    const enclosing = part?.depths[0];
+    if (part === undefined || enclosing === undefined)
+        return null;
+    let at = part.text.length;
+    while (at > 0) {
+        const depth = part.depths[at - 1];
+        if (depth === undefined || depth < 0 || depth >= enclosing)
+            break;
+        at -= 1;
+    }
+    // Whitespace before the closer is not part of the statement's last word either.
+    while (at > 0 && /\s/.test(part.text[at - 1] ?? ''))
+        at -= 1;
+    // The group state where the statement's own text stops: a group opened here and never closed
+    // puts its closer after the statement, in a later stage or statement.
+    let trailing = enclosing;
+    let deepest = enclosing;
+    for (let i = 0; i < at; i += 1) {
+        const depth = part.depths[i];
+        if (depth === undefined || depth < 0)
+            continue;
+        trailing = depth;
+        if (depth > deepest)
+            deepest = depth;
+    }
+    return { textEnd: start + at, leavesGroupOpen: deepest > enclosing && trailing > enclosing };
+}
 /**
  * {@link locatedCommandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
  * {@link MAX_NESTING} allows. A nested statement's offsets are cleared: they are positions in

package/dist/index.d.ts

@@ -147,6 +147,7 @@ export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
+export * from './playwright-report.js';
 export * from './schemas.js';
 export * from './server-command.js';
 export * from './sleep-peek.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -147,6 +147,7 @@ export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
+export * from './playwright-report.js';
 export * from './schemas.js';
 export * from './server-command.js';
 export * from './sleep-peek.js';