@orkestrel/scaffold 0.0.134 → 0.0.136

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +777 -83
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +327 -21
  3. package/dist/bin/main.js +254 -36
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +2 -2
  6. package/dist/host/agents/orchestration.md +2 -2
  7. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +983 -123
  9. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  11. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +403 -32
  12. package/dist/host/claude/agents/orkestrel.md +17 -17
  13. package/dist/host/claude/agents/reviewer.md +1 -1
  14. package/dist/host/claude/rules/architecture.md +1 -1
  15. package/dist/host/claude/rules/documentation.md +1 -1
  16. package/dist/host/claude/rules/patterns.md +4 -2
  17. package/dist/host/claude/rules/workspace.md +73 -67
  18. package/dist/host/configs/helpers.ts +109 -73
  19. package/dist/host/dotfiles/oxlintrc.json +1 -57
  20. package/dist/host/guides/agent.md +989 -395
  21. package/dist/host/guides/contract.md +198 -163
  22. package/dist/host/guides/database.md +978 -503
  23. package/dist/host/guides/indexeddb.md +80 -66
  24. package/dist/host/guides/middleware.md +5 -5
  25. package/dist/host/guides/ollama.md +41 -42
  26. package/dist/host/guides/relation.md +56 -32
  27. package/dist/host/guides/scaffold.md +185 -107
  28. package/dist/host/guides/sqlite.md +44 -23
  29. package/dist/host/guides/study.md +12 -12
  30. package/dist/host/guides/test.md +163 -47
  31. package/dist/host/guides/toolbox.md +127 -81
  32. package/dist/host/guides/workspace.md +21 -14
  33. package/dist/host/manifest.json +30 -30
  34. package/dist/host/scripts/browsers.sh +0 -0
  35. package/dist/host/scripts/codex.sh +0 -0
  36. package/dist/host/scripts/cursor.sh +0 -0
  37. package/dist/host/scripts/deps.sh +0 -0
  38. package/dist/host/scripts/npm.sh +0 -0
  39. package/dist/host/scripts/ollama.sh +0 -0
  40. package/dist/host/tests/config.test.ts +237 -115
  41. package/dist/src/core/index.cjs +591 -218
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.d.cts +248 -29
  44. package/dist/src/core/index.d.ts +248 -29
  45. package/dist/src/core/index.js +581 -216
  46. package/dist/src/core/index.js.map +1 -1
  47. package/dist/src/server/index.cjs +18 -8
  48. package/dist/src/server/index.cjs.map +1 -1
  49. package/dist/src/server/index.d.cts +4 -3
  50. package/dist/src/server/index.d.ts +4 -3
  51. package/dist/src/server/index.js +19 -9
  52. package/dist/src/server/index.js.map +1 -1
  53. package/package.json +3 -3
@@ -30,6 +30,10 @@ at the type boundary, where a value nothing declares meets a claim its caller ow
30
30
  `flattenHeaders` is outside them on the comparison side, turning any header initializer into one
31
31
  frozen record.
32
32
 
33
+ `ProgressReporter` and `readProgress` sit outside them on the runner side: the reporter appends
34
+ one JSON line per Vitest run event to a file while the run is live, and the reader summarizes that
35
+ file at any moment, so a long run's progress and its first failure are readable before it ends.
36
+
33
37
  The journey layer drives a real interface by role and accessible name through the installed Vitest
34
38
  provider, measures what a reader can see of the result, records the scenario and the page's own
35
39
  output as it goes, and generates the capture portfolio from the same journeys. Around it sit the
@@ -60,10 +64,16 @@ npm install --save-dev @orkestrel/test
60
64
  ```
61
65
 
62
66
  `@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face — the
63
- filesystem helpers, the process and socket readings, the cookie jar, and the pure leaves they are
64
- built from. `@orkestrel/test/browser` is the
67
+ filesystem helpers, the process and socket readings, the cookie jar, the Vitest progress reporter
68
+ and its reader, and the pure leaves they are built from. `@orkestrel/test/browser` is the
65
69
  journey layer, which drives a real browser through the installed Vitest provider. Core touches
66
70
  neither `node:*` nor the DOM, so a browser test project imports it unchanged.
71
+ `@orkestrel/test/reporter` is the runner entry Vitest's `--reporter` flag loads: its default
72
+ export is `ProgressReporter`, and it ships ES only. The entry lives at `src/bin/reporter.ts` and
73
+ builds to `dist/bin/reporter.js`; the specifier does not name that path. Use it for a run started
74
+ from the command line with a configuration you cannot edit, as `@orkestrel/capture` starts a
75
+ package's Vitest. In a package's own configuration, list `new ProgressReporter()` instead, as
76
+ § Read a long run while it runs shows.
67
77
 
68
78
  The browser face ships ES only. It is built on `vitest/browser`, which is an ES-only module, so no
69
79
  CommonJS consumer can reach it and no `.d.cts` is emitted for it.
@@ -1012,59 +1022,104 @@ collision refusal before writing.
1012
1022
  Imported from `@orkestrel/test/server`.
1013
1023
 
1014
1024
  The provider command consumes the browser journey's resolved selector inside Vitest's tester frame.
1025
+ The progress reporter is a Vitest reporter a run lists beside its others.
1015
1026
 
1016
- | Name | Kind | Signature | Summary |
1017
- | ------------- | -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
1018
- | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1027
+ | Name | Kind | Signature | Summary |
1028
+ | ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1029
+ | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1030
+ | `ProgressReporter` | class | `new () => Reporter` | Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live run's progress and each failure's first error can be read before the run ends. |
1019
1031
 
1020
1032
  #### Types
1021
1033
 
1022
- | Name | Kind | Signature | Summary |
1023
- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
1024
- | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1025
- | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1026
- | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1027
- | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1028
- | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1029
- | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1030
- | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1031
- | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1032
- | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1034
+ | Name | Kind | Signature | Summary |
1035
+ | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1036
+ | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1037
+ | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1038
+ | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1039
+ | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1040
+ | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1041
+ | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1042
+ | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1043
+ | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1044
+ | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1045
+ | `ProgressError` | interface | `{ message, location? }` | Represents one error a progress line carries: its first message line and where it was thrown. |
1046
+ | `ProgressSpecification` | interface | `{ project, module }` | Names one module a run starts, under the project that runs it, as one Vitest specification. |
1047
+ | `ProgressStamp` | interface | `{ time, pid }` | Represents the stamp every progress line carries. |
1048
+ | `ProgressInitEvent` | interface | `{ event, version, wall, bail }` | Represents the line a reporter writes when Vitest initializes it. |
1049
+ | `ProgressStartEvent` | interface | `{ event, specifications }` | Represents the line a reporter writes when a run starts, listing the modules it runs. |
1050
+ | `ProgressCollectedEvent` | interface | `{ event, project, module, planned, errors }` | Represents the line a reporter writes when Vitest collects one module's cases. |
1051
+ | `ProgressReadyEvent` | interface | `{ event, project, id, name }` | Represents the line a reporter writes when a planned case starts. |
1052
+ | `ProgressCaseState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending'` | Names the state a case result reports, mirroring Vitest's `TestState`. |
1053
+ | `ProgressCaseEvent` | interface | `{ event, project, module, id, name, state, duration?, start?, errors? }` | Represents the line a reporter writes once for each planned case's result. |
1054
+ | `ProgressCancelEvent` | interface | `{ event, reason, wall }` | Represents the line a reporter writes each time Vitest cancels the run. |
1055
+ | `ProgressModuleState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending' \| 'queued'` | Names the state a finished module reports, mirroring Vitest's `TestModuleState`. |
1056
+ | `ProgressModuleEvent` | interface | `{ event, project, module, state, duration }` | Represents the line a reporter writes when a module finishes. |
1057
+ | `ProgressEndReason` | type | `'passed' \| 'interrupted' \| 'failed'` | Names why a run ended, mirroring Vitest's `TestRunEndReason`. |
1058
+ | `ProgressEndEvent` | interface | `{ event, reason, overhead, unhandled }` | Represents the line a reporter writes when a run ends. |
1059
+ | `ProgressEvent` | type | `ProgressInitEvent \| ProgressStartEvent \| ProgressCollectedEvent \| ProgressReadyEvent \| ProgressCaseEvent \| ProgressCancelEvent \| ProgressModuleEvent \| ProgressEndEvent` | Represents one line of a progress file, discriminated by `event`. |
1060
+ | `ProgressState` | type | `'live' \| ProgressEndReason` | Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. |
1061
+ | `ProgressRelation` | type | `'first' \| 'bail' \| 'later'` | Names how a failure relates to the run's bail: `first` is the earliest failure, `bail` is a failure past the bail setting whose result arrived or whose case ended after the first cancel, and `later` is any other failure. |
1062
+ | `ProgressProject` | interface | `{ name, planned, done, passed, failed, skipped, modules, collected }` | Represents one project's tallies in a progress reading. |
1063
+ | `ProgressCase` | interface | `{ project, name, duration }` | Represents a case that started and has not reported a result. |
1064
+ | `ProgressFailure` | interface | `{ project, module, name, time, relation, error }` | Represents one failed case, or one module that failed to collect, in a progress reading. |
1065
+ | `ProgressCancel` | interface | `{ reason, time }` | Represents the first cancel a run recorded. |
1066
+ | `ProgressRun` | interface | `{ pid, wall, state, bail, elapsed, done, planned, exact, rate, remaining, projects, running, cancel, failures, overhead, unhandled }` | Represents where one run stands, read from its progress lines. |
1033
1067
 
1034
1068
  #### Constants
1035
1069
 
1036
- | Name | Kind | Signature | Summary |
1037
- | ----------------------------- | ----- | ------------------- | ---------------------------------------------------------------------------------- |
1038
- | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1039
- | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1040
- | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1070
+ | Name | Kind | Signature | Summary |
1071
+ | ----------------------------- | ----- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
1072
+ | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1073
+ | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1074
+ | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1075
+ | `PROGRESS_VERSION` | const | `1` | Names the format version a progress file's `init` line carries; a reader refuses any other. |
1076
+ | `PROGRESS_MESSAGE_LIMIT` | const | `300` | Caps the characters a progress error message keeps. |
1077
+ | `PROGRESS_LABELS` | const | `Readonly<Record<ProgressRelation, string>>` | Names the label a rendered progress reading prints for each failure relation. |
1078
+
1079
+ #### Validators
1080
+
1081
+ | Name | Kind | Signature | Summary |
1082
+ | ----------------- | ----- | ---------------------- | ------------------------------------------------------------ |
1083
+ | `isProgressError` | const | `Guard<ProgressError>` | Checks whether a value is one error a progress line carries. |
1084
+ | `isProgressEvent` | const | `Guard<ProgressEvent>` | Checks whether a value is one line of a progress file. |
1041
1085
 
1042
1086
  #### Helpers
1043
1087
 
1044
- | Name | Kind | Signature | Summary |
1045
- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
1046
- | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1047
- | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1048
- | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1049
- | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1050
- | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1051
- | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1052
- | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1053
- | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1054
- | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1055
- | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1056
- | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1057
- | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1058
- | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1059
- | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1060
- | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1061
- | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1062
- | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1063
- | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1064
- | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1065
- | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1066
- | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1067
- | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1088
+ | Name | Kind | Signature | Summary |
1089
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
1090
+ | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1091
+ | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1092
+ | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1093
+ | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1094
+ | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1095
+ | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1096
+ | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1097
+ | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1098
+ | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1099
+ | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1100
+ | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1101
+ | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1102
+ | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1103
+ | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1104
+ | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1105
+ | `normalizeProgressPath` | function | `(file: string, root: string) => string` | Normalizes a module or stack-frame path to the form a progress line carries. |
1106
+ | `extractProgressError` | function | `(error: SerializedError, root: string) => ProgressError` | Extracts the message line and location a progress line keeps from one Vitest error. |
1107
+ | `matchesPlannedCase` | function | `(test: { readonly options: { readonly mode: string; }; }) => boolean` | Reports whether a collected case is one the run plans to report. |
1108
+ | `readFileSnapshot` | function | `(path: string) => Buffer` | Reads the bytes a file holds when it is opened, leaving out every byte appended during the read. |
1109
+ | `filterProgressEvents` | function | `<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName) => ReadonlyArray<Extract<ProgressEvent, { readonly event: TName; }>>` | Filters the progress lines of one event. |
1110
+ | `extractProgressEvents` | function | `(text: string) => readonly ProgressEvent[]` | Extracts the progress lines a text holds, skipping a partial last line. |
1111
+ | `computeProgressRun` | function | `(events: readonly ProgressEvent[], now: number) => ProgressRun \| undefined` | Computes where the run one process wrote stands, from its last `init` line on. |
1112
+ | `computeProgress` | function | `(events: readonly ProgressEvent[], now: number) => readonly ProgressRun[]` | Computes where every run a progress file holds stands, one run per writing process. |
1113
+ | `readProgress` | function | `(path: string, now?: number) => readonly ProgressRun[]` | Reads where every run a progress file holds stands, live or finished. |
1114
+ | `renderDuration` | function | `(milliseconds: number) => string` | Renders a duration as whole minutes and seconds. |
1115
+ | `renderProgress` | function | `(runs: readonly ProgressRun[]) => string` | Renders progress runs as the text a person reads mid-run. |
1116
+ | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1117
+ | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1118
+ | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1119
+ | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1120
+ | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1121
+ | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1122
+ | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1068
1123
 
1069
1124
  `hasScratchPath` takes a scratch's absolute path and a relative or absolute target. It checks
1070
1125
  containment before inspecting the root, returns `false` for a missing root or entry, and refuses a
@@ -2996,8 +3051,8 @@ Object.keys(
2996
3051
  Object.keys(
2997
3052
  readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
2998
3053
  )
2999
- // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
3000
- // 'src/core/types.ts', 'src/core/validators.ts']
3054
+ // ['src/bin/reporter.ts', 'src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
3055
+ // 'src/core/helpers.ts', 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
3001
3056
 
3002
3057
  // An exclusion also applies to a target you name, so naming one file below an excluded directory
3003
3058
  // does not reinstate it.
@@ -3204,6 +3259,67 @@ rejects with the client's own `ECONNREFUSED` rather than reporting a refusal, an
3204
3259
  accepts the connection and answers nothing rejects on the budget, which defaults to `1000`
3205
3260
  milliseconds and names the port and path it was waiting on.
3206
3261
 
3262
+ ### Read a long run while it runs
3263
+
3264
+ This configuration lists the progress reporter beside the dot reporter and names its file the way
3265
+ `--outputFile.json` names the JSON report's file.
3266
+
3267
+ ```ts
3268
+ import { defineConfig } from 'vitest/config'
3269
+ import { ProgressReporter } from '@orkestrel/test/server'
3270
+
3271
+ export default defineConfig({
3272
+ test: {
3273
+ reporters: ['dot', new ProgressReporter()],
3274
+ outputFile: { progress: 'tmp/runs/progress.jsonl' },
3275
+ },
3276
+ })
3277
+ ```
3278
+
3279
+ The reporter refuses to initialize when no `progress` file is named. It appends with one
3280
+ synchronous write per line, so a second process can read the file at any moment. It writes `ready`
3281
+ and `case` lines only for the cases each module plans to run, so a name filter's removed cases
3282
+ never count, and it writes one `case` line per planned case even where a bail makes Vitest report a
3283
+ case twice. It records every `cancel` Vitest delivers, registering its listener once a module
3284
+ queues, because Vitest clears cancel listeners after `onTestRunStart`.
3285
+
3286
+ This read summarizes the file once, from another process or the same one, and renders it.
3287
+
3288
+ ```ts
3289
+ import { readProgress, renderProgress } from '@orkestrel/test/server'
3290
+
3291
+ const runs = readProgress('tmp/runs/progress.jsonl')
3292
+ runs[0]?.state // 'live' until the run writes its end line
3293
+ runs[0]?.failures[0]?.relation // 'first'
3294
+ console.log(renderProgress(runs))
3295
+ ```
3296
+
3297
+ `readProgress` reads up to the file's length at open, decodes complete lines only, holds no timer,
3298
+ and writes nothing. It returns one run per writing process, each read from that process's last
3299
+ `init` line, and each run carries that line's `wall` time. The rendered text gives cases done
3300
+ against planned per project, with `+` on the total until every module is collected, the elapsed
3301
+ time, rate, and estimate, the running cases, the cancel, and each failure under its module and case
3302
+ with its first message line and location. A module that fails to collect, such as one that throws
3303
+ while it is imported, reads as a failure under its module alone, and as `FIRST` when its line comes
3304
+ before every other failure line. The earliest failure line reads `FIRST` even when Vitest wrote the
3305
+ cancel before its result. Only a failed case can trigger a bail, so under a bail the first failed
3306
+ case reads as a cause even after a collection failure. A later failure past the bail setting that
3307
+ arrived or ended after the cancel reads `AFTER-BAIL`, and any other reads `FAILED`. A project's
3308
+ `failed` tally counts its failed cases and its modules that failed to collect.
3309
+
3310
+ The format reads one `vitest run` per process. The reporter appends and never truncates, so delete
3311
+ the file before each run. A file that still holds earlier runs reads as one run per process, each
3312
+ from its last `init` line, and `wall` tells them apart. A run killed before its `end` line reads
3313
+ `live` until its file is deleted. Watch mode initializes the reporter once, so its reruns pile under
3314
+ one `init` line and are outside what the format reads.
3315
+
3316
+ Without a configuration, name the published entry and its file on the command line. Vitest
3317
+ constructs the entry's default export, `ProgressReporter`.
3318
+
3319
+ ```bash
3320
+ npx vitest run --reporter=@orkestrel/test/reporter --outputFile.progress=tmp/runs/progress.jsonl
3321
+ ```
3322
+
3207
3323
  ### Probe what the host supports
3208
3324
 
3209
3325
  Gate a proof on the mechanism it needs rather than on the platform name. Each probe allocates its own