@orkestrel/scaffold 0.0.133 → 0.0.135

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 (92) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +275 -33
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/AGENTS.md +1 -1
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  35. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  36. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  37. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  38. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  42. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  43. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  45. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
  46. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  47. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
  53. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  54. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  55. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  56. package/dist/host/claude/agents/orkestrel.md +16 -16
  57. package/dist/host/claude/rules/architecture.md +1 -1
  58. package/dist/host/claude/rules/documentation.md +1 -1
  59. package/dist/host/claude/rules/patterns.md +7 -4
  60. package/dist/host/claude/rules/styles.md +1 -1
  61. package/dist/host/claude/rules/tests.md +3 -3
  62. package/dist/host/claude/rules/workspace.md +50 -37
  63. package/dist/host/configs/helpers.ts +117 -71
  64. package/dist/host/dotfiles/oxlintrc.json +6 -0
  65. package/dist/host/guides/agent.md +989 -395
  66. package/dist/host/guides/database.md +357 -342
  67. package/dist/host/guides/form.md +79 -4
  68. package/dist/host/guides/middleware.md +5 -5
  69. package/dist/host/guides/ollama.md +41 -42
  70. package/dist/host/guides/scaffold.md +170 -70
  71. package/dist/host/guides/study.md +12 -12
  72. package/dist/host/guides/table.md +20 -6
  73. package/dist/host/guides/test.md +166 -52
  74. package/dist/host/guides/toolbox.md +127 -81
  75. package/dist/host/guides/workspace.md +21 -14
  76. package/dist/host/manifest.json +54 -54
  77. package/dist/host/tests/config.test.ts +251 -7
  78. package/dist/host/tests/policy.test.ts +14 -21
  79. package/dist/host/tests/setupPolicy.ts +43 -36
  80. package/dist/src/core/index.cjs +533 -139
  81. package/dist/src/core/index.cjs.map +1 -1
  82. package/dist/src/core/index.d.cts +223 -16
  83. package/dist/src/core/index.d.ts +223 -16
  84. package/dist/src/core/index.js +524 -139
  85. package/dist/src/core/index.js.map +1 -1
  86. package/dist/src/server/index.cjs +23 -14
  87. package/dist/src/server/index.cjs.map +1 -1
  88. package/dist/src/server/index.d.cts +3 -2
  89. package/dist/src/server/index.d.ts +3 -2
  90. package/dist/src/server/index.js +24 -15
  91. package/dist/src/server/index.js.map +1 -1
  92. package/package.json +2 -2
@@ -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,12 @@ 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.
67
73
 
68
74
  The browser face ships ES only. It is built on `vitest/browser`, which is an ES-only module, so no
69
75
  CommonJS consumer can reach it and no `.d.cts` is emitted for it.
@@ -1012,59 +1018,104 @@ collision refusal before writing.
1012
1018
  Imported from `@orkestrel/test/server`.
1013
1019
 
1014
1020
  The provider command consumes the browser journey's resolved selector inside Vitest's tester frame.
1021
+ The progress reporter is a Vitest reporter a run lists beside its others.
1015
1022
 
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. |
1023
+ | Name | Kind | Signature | Summary |
1024
+ | ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1025
+ | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1026
+ | `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
1027
 
1020
1028
  #### Types
1021
1029
 
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. |
1030
+ | Name | Kind | Signature | Summary |
1031
+ | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1032
+ | `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. |
1033
+ | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1034
+ | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1035
+ | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1036
+ | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1037
+ | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1038
+ | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1039
+ | `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. |
1040
+ | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1041
+ | `ProgressError` | interface | `{ message, location? }` | Represents one error a progress line carries: its first message line and where it was thrown. |
1042
+ | `ProgressSpecification` | interface | `{ project, module }` | Names one module a run starts, under the project that runs it, as one Vitest specification. |
1043
+ | `ProgressStamp` | interface | `{ time, pid }` | Represents the stamp every progress line carries. |
1044
+ | `ProgressInitEvent` | interface | `{ event, version, wall, bail }` | Represents the line a reporter writes when Vitest initializes it. |
1045
+ | `ProgressStartEvent` | interface | `{ event, specifications }` | Represents the line a reporter writes when a run starts, listing the modules it runs. |
1046
+ | `ProgressCollectedEvent` | interface | `{ event, project, module, planned, errors }` | Represents the line a reporter writes when Vitest collects one module's cases. |
1047
+ | `ProgressReadyEvent` | interface | `{ event, project, id, name }` | Represents the line a reporter writes when a planned case starts. |
1048
+ | `ProgressCaseState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending'` | Names the state a case result reports, mirroring Vitest's `TestState`. |
1049
+ | `ProgressCaseEvent` | interface | `{ event, project, module, id, name, state, duration?, start?, errors? }` | Represents the line a reporter writes once for each planned case's result. |
1050
+ | `ProgressCancelEvent` | interface | `{ event, reason, wall }` | Represents the line a reporter writes each time Vitest cancels the run. |
1051
+ | `ProgressModuleState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending' \| 'queued'` | Names the state a finished module reports, mirroring Vitest's `TestModuleState`. |
1052
+ | `ProgressModuleEvent` | interface | `{ event, project, module, state, duration }` | Represents the line a reporter writes when a module finishes. |
1053
+ | `ProgressEndReason` | type | `'passed' \| 'interrupted' \| 'failed'` | Names why a run ended, mirroring Vitest's `TestRunEndReason`. |
1054
+ | `ProgressEndEvent` | interface | `{ event, reason, overhead, unhandled }` | Represents the line a reporter writes when a run ends. |
1055
+ | `ProgressEvent` | type | `ProgressInitEvent \| ProgressStartEvent \| ProgressCollectedEvent \| ProgressReadyEvent \| ProgressCaseEvent \| ProgressCancelEvent \| ProgressModuleEvent \| ProgressEndEvent` | Represents one line of a progress file, discriminated by `event`. |
1056
+ | `ProgressState` | type | `'live' \| ProgressEndReason` | Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. |
1057
+ | `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. |
1058
+ | `ProgressProject` | interface | `{ name, planned, done, passed, failed, skipped, modules, collected }` | Represents one project's tallies in a progress reading. |
1059
+ | `ProgressCase` | interface | `{ project, name, duration }` | Represents a case that started and has not reported a result. |
1060
+ | `ProgressFailure` | interface | `{ project, module, name, time, relation, error }` | Represents one failed case, or one module that failed to collect, in a progress reading. |
1061
+ | `ProgressCancel` | interface | `{ reason, time }` | Represents the first cancel a run recorded. |
1062
+ | `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
1063
 
1034
1064
  #### Constants
1035
1065
 
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. |
1066
+ | Name | Kind | Signature | Summary |
1067
+ | ----------------------------- | ----- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
1068
+ | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1069
+ | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1070
+ | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1071
+ | `PROGRESS_VERSION` | const | `1` | Names the format version a progress file's `init` line carries; a reader refuses any other. |
1072
+ | `PROGRESS_MESSAGE_LIMIT` | const | `300` | Caps the characters a progress error message keeps. |
1073
+ | `PROGRESS_LABELS` | const | `Readonly<Record<ProgressRelation, string>>` | Names the label a rendered progress reading prints for each failure relation. |
1074
+
1075
+ #### Validators
1076
+
1077
+ | Name | Kind | Signature | Summary |
1078
+ | ----------------- | ----- | ---------------------- | ------------------------------------------------------------ |
1079
+ | `isProgressError` | const | `Guard<ProgressError>` | Checks whether a value is one error a progress line carries. |
1080
+ | `isProgressEvent` | const | `Guard<ProgressEvent>` | Checks whether a value is one line of a progress file. |
1041
1081
 
1042
1082
  #### Helpers
1043
1083
 
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: Stats) => 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. |
1084
+ | Name | Kind | Signature | Summary |
1085
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
1086
+ | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1087
+ | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1088
+ | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1089
+ | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1090
+ | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1091
+ | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1092
+ | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1093
+ | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1094
+ | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1095
+ | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1096
+ | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1097
+ | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1098
+ | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1099
+ | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1100
+ | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1101
+ | `normalizeProgressPath` | function | `(file: string, root: string) => string` | Normalizes a module or stack-frame path to the form a progress line carries. |
1102
+ | `extractProgressError` | function | `(error: SerializedError, root: string) => ProgressError` | Extracts the message line and location a progress line keeps from one Vitest error. |
1103
+ | `matchesPlannedCase` | function | `(test: { readonly options: { readonly mode: string; }; }) => boolean` | Reports whether a collected case is one the run plans to report. |
1104
+ | `readFileSnapshot` | function | `(path: string) => Buffer` | Reads the bytes a file holds when it is opened, leaving out every byte appended during the read. |
1105
+ | `filterProgressEvents` | function | `<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName) => ReadonlyArray<Extract<ProgressEvent, { readonly event: TName; }>>` | Filters the progress lines of one event. |
1106
+ | `extractProgressEvents` | function | `(text: string) => readonly ProgressEvent[]` | Extracts the progress lines a text holds, skipping a partial last line. |
1107
+ | `computeProgressRun` | function | `(events: readonly ProgressEvent[], now: number) => ProgressRun \| undefined` | Computes where the run one process wrote stands, from its last `init` line on. |
1108
+ | `computeProgress` | function | `(events: readonly ProgressEvent[], now: number) => readonly ProgressRun[]` | Computes where every run a progress file holds stands, one run per writing process. |
1109
+ | `readProgress` | function | `(path: string, now?: number) => readonly ProgressRun[]` | Reads where every run a progress file holds stands, live or finished. |
1110
+ | `renderDuration` | function | `(milliseconds: number) => string` | Renders a duration as whole minutes and seconds. |
1111
+ | `renderProgress` | function | `(runs: readonly ProgressRun[]) => string` | Renders progress runs as the text a person reads mid-run. |
1112
+ | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1113
+ | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1114
+ | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1115
+ | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1116
+ | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1117
+ | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1118
+ | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1068
1119
 
1069
1120
  `hasScratchPath` takes a scratch's absolute path and a relative or absolute target. It checks
1070
1121
  containment before inspecting the root, returns `false` for a missing root or entry, and refuses a
@@ -1106,7 +1157,9 @@ All three fields are compared because none of them alone identifies an allocatio
1106
1157
  shared by every directory on one filesystem, an index node is reused after its directory is removed,
1107
1158
  and a creation time repeats within the host's timestamp resolution. It is exported so a fixture that
1108
1159
  manages its own directory can make the same check rather than trusting a path. `readIdentity` reads
1109
- that triple off a `node:fs` `Stats`, and it is the one reading `createScratch` takes at allocation,
1160
+ that triple off a `node:fs` `BigIntStats` taken with `{ bigint: true }`, with the creation time in
1161
+ nanoseconds as `birthtimeNs`. A number `Stats` rounds a file identifier past 2^53, and two distinct
1162
+ entries then compare equal. `readIdentity` is the one reading `createScratch` takes at allocation,
1110
1163
  before a `remove`, and before a `destroy`, so the three sites cannot drift on which fields name an
1111
1164
  allocation.
1112
1165
 
@@ -1678,8 +1731,8 @@ These hold across `src/core`, `src/browser`, `src/server`, and this guide.
1678
1731
  reads the entry and then removes the path as separate steps, so an allocation swapped between
1679
1732
  them is removed anyway; whoever swaps it runs as the same uid, which is the population the threat
1680
1733
  model already declines to defend against. And birth time is the host's to supply. This host
1681
- supplies a real one — the allocation's `birthtimeMs` does not move when files are written into
1682
- it, while its `ctimeMs` does — so `destroy()` is sound here. Where a host has none, libuv reports
1734
+ supplies a real one — the allocation's `birthtimeNs` does not move when files are written into
1735
+ it, while its `ctimeNs` does — so `destroy()` is sound here. Where a host has none, libuv reports
1683
1736
  `ctime` in its place, the first seeded write moves it, and `destroy()` takes its early return. It
1684
1737
  returns `void`, so that refusal is indistinguishable from success and the allocation leaks
1685
1738
  silently.
@@ -2995,7 +3048,7 @@ Object.keys(
2995
3048
  readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
2996
3049
  )
2997
3050
  // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
2998
- // 'src/core/types.ts', 'src/core/validators.ts']
3051
+ // 'src/core/types.ts', 'src/core/validators.ts', 'src/reporter/main.ts']
2999
3052
 
3000
3053
  // An exclusion also applies to a target you name, so naming one file below an excluded directory
3001
3054
  // does not reinstate it.
@@ -3202,6 +3255,67 @@ rejects with the client's own `ECONNREFUSED` rather than reporting a refusal, an
3202
3255
  accepts the connection and answers nothing rejects on the budget, which defaults to `1000`
3203
3256
  milliseconds and names the port and path it was waiting on.
3204
3257
 
3258
+ ### Read a long run while it runs
3259
+
3260
+ This configuration lists the progress reporter beside the dot reporter and names its file the way
3261
+ `--outputFile.json` names the JSON report's file.
3262
+
3263
+ ```ts
3264
+ import { defineConfig } from 'vitest/config'
3265
+ import { ProgressReporter } from '@orkestrel/test/server'
3266
+
3267
+ export default defineConfig({
3268
+ test: {
3269
+ reporters: ['dot', new ProgressReporter()],
3270
+ outputFile: { progress: 'tmp/runs/progress.jsonl' },
3271
+ },
3272
+ })
3273
+ ```
3274
+
3275
+ The reporter refuses to initialize when no `progress` file is named. It appends with one
3276
+ synchronous write per line, so a second process can read the file at any moment. It writes `ready`
3277
+ and `case` lines only for the cases each module plans to run, so a name filter's removed cases
3278
+ never count, and it writes one `case` line per planned case even where a bail makes Vitest report a
3279
+ case twice. It records every `cancel` Vitest delivers, registering its listener once a module
3280
+ queues, because Vitest clears cancel listeners after `onTestRunStart`.
3281
+
3282
+ This read summarizes the file once, from another process or the same one, and renders it.
3283
+
3284
+ ```ts
3285
+ import { readProgress, renderProgress } from '@orkestrel/test/server'
3286
+
3287
+ const runs = readProgress('tmp/runs/progress.jsonl')
3288
+ runs[0]?.state // 'live' until the run writes its end line
3289
+ runs[0]?.failures[0]?.relation // 'first'
3290
+ console.log(renderProgress(runs))
3291
+ ```
3292
+
3293
+ `readProgress` reads up to the file's length at open, decodes complete lines only, holds no timer,
3294
+ and writes nothing. It returns one run per writing process, each read from that process's last
3295
+ `init` line, and each run carries that line's `wall` time. The rendered text gives cases done
3296
+ against planned per project, with `+` on the total until every module is collected, the elapsed
3297
+ time, rate, and estimate, the running cases, the cancel, and each failure under its module and case
3298
+ with its first message line and location. A module that fails to collect, such as one that throws
3299
+ while it is imported, reads as a failure under its module alone, and as `FIRST` when its line comes
3300
+ before every other failure line. The earliest failure line reads `FIRST` even when Vitest wrote the
3301
+ cancel before its result. Only a failed case can trigger a bail, so under a bail the first failed
3302
+ case reads as a cause even after a collection failure. A later failure past the bail setting that
3303
+ arrived or ended after the cancel reads `AFTER-BAIL`, and any other reads `FAILED`. A project's
3304
+ `failed` tally counts its failed cases and its modules that failed to collect.
3305
+
3306
+ The format reads one `vitest run` per process. The reporter appends and never truncates, so delete
3307
+ the file before each run. A file that still holds earlier runs reads as one run per process, each
3308
+ from its last `init` line, and `wall` tells them apart. A run killed before its `end` line reads
3309
+ `live` until its file is deleted. Watch mode initializes the reporter once, so its reruns pile under
3310
+ one `init` line and are outside what the format reads.
3311
+
3312
+ Without a configuration, name the published entry and its file on the command line. Vitest
3313
+ constructs the entry's default export, `ProgressReporter`.
3314
+
3315
+ ```bash
3316
+ npx vitest run --reporter=@orkestrel/test/reporter --outputFile.progress=tmp/runs/progress.jsonl
3317
+ ```
3318
+
3205
3319
  ### Probe what the host supports
3206
3320
 
3207
3321
  Gate a proof on the mechanism it needs rather than on the platform name. Each probe allocates its own
@@ -4439,11 +4553,11 @@ Each entry names the contracts its file proves. The test names carry the cases.
4439
4553
  contained relative and absolute targets and both spellings of a path outside the root, and `requireContained`
4440
4554
  takes the same contained pair and each path outside the root refused with the message naming the target it was
4441
4555
  given. `readIdentity` takes a real
4442
- allocation's three fields, that allocation matching itself across a `stat` and an `lstat`, and a
4556
+ allocation's three bigint fields, that allocation matching itself across a `stat` and an `lstat`, and a
4443
4557
  second allocation reading as a different identity. `readErrorCode` takes a real `ENOENT` off the
4444
4558
  host, a plain object, an `Error` carrying a non-string `code` and one carrying none, a
4445
4559
  null-prototype record, and the values that are not objects at all. `matchesIdentity` takes a triple
4446
- matching in every field and one differing in each. `isExcluded` takes a key, an ancestor, the root, and a sibling that only
4560
+ matching in every field, one differing in each, and two index nodes that differ only past 2^53. `isExcluded` takes a key, an ancestor, the root, and a sibling that only
4447
4561
  looks like a match. `readInventory` takes key order, extension filtering, exclusion at the named
4448
4562
  door and at the walked one with its spellings normalized to one rule, each of its link refusals
4449
4563
  with a contained intermediate link as the control on the intermediate-link one, a root-level
@@ -4483,7 +4597,7 @@ Each entry names the contracts its file proves. The test names carry the cases.
4483
4597
  `ensure` takes an empty directory, every missing parent, and a repeated call. `link` takes
4484
4598
  traversal through a planted link, the final segment `has` reports rather than follows, and the
4485
4599
  `EEXIST` an occupied final segment throws. `remove` takes a file beside a kept
4486
- sibling, an empty directory, a populated subtree, a missing target, an ancestor link back to the
4600
+ sibling, a file written immediately after allocation, an empty directory, a populated subtree, a missing target, an ancestor link back to the
4487
4601
  allocation with every seeded file read back afterwards, a final link whose destination is read back
4488
4602
  afterwards, a sibling directory reached through that same ancestor link, a target outside the root with
4489
4603
  the file outside left intact, the root refused as `''`, as `'.'`, and as its absolute path, a