@orkestrel/scaffold 0.0.134 → 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.
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
- package/dist/bin/main.js +253 -35
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
- package/dist/host/claude/agents/orkestrel.md +14 -14
- package/dist/host/claude/rules/architecture.md +1 -1
- package/dist/host/claude/rules/patterns.md +2 -0
- package/dist/host/claude/rules/workspace.md +64 -63
- package/dist/host/configs/helpers.ts +88 -67
- package/dist/host/dotfiles/oxlintrc.json +1 -57
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/database.md +357 -342
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/scaffold.md +177 -105
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/test.md +158 -46
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +23 -23
- package/dist/host/tests/config.test.ts +166 -112
- package/dist/src/core/index.cjs +491 -195
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +217 -24
- package/dist/src/core/index.d.ts +217 -24
- package/dist/src/core/index.js +482 -193
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +18 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +4 -3
- package/dist/src/server/index.d.ts +4 -3
- package/dist/src/server/index.js +19 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -129,7 +129,7 @@ The `triage` role sends System One requests to `/v1/systemone`. Its `StudySystem
|
|
|
129
129
|
|
|
130
130
|
A provider declares `triage` and `digest.triage` together. Both metadata passes verify the pin through tags and show, configuration identity retains it, and a declared daemon includes it in its verified maintenance population. A transport fault on this leg fails the trial even if the consumer catches it; it cannot produce successful recording completion. A well-transported answer the consumer semantically refuses remains the consumer's decision to refer onward. Study chooses no model name or probability cutoff.
|
|
131
131
|
|
|
132
|
-
Recording reads
|
|
132
|
+
Recording reads the optional procedure from the exchange sink's opening declaration. The transport refuses metadata or model pins that differ from that row. Preflight and postflight each fetch the serving version, then verify tags and show for each distinct pinned model. The version is an observation for debugging: each pass appends a `version` evidence row to its goal, `{ version }` with the reply's nonempty string or `null` when the reply names none, and Study compares it with nothing, so no recording, replay, or continuation refuses because of a version. The sidecar retains each version reply's exact bytes. Ordered exact steps compare UTF-8 bytes and verify their declared SHA-256 receipt; capture steps require their declared positive safe byte length and forbid body or input members. Goal, role, route, policy, and order are checked before sending. A second request and verification during request admission refuse. The sink supplies each HTTP ordinal, which joins dispatch and wire evidence even without passive observation. An attempt retains request bytes before sending. A validated response retains native status, selected headers, exact bytes, and chunk lengths; a failure retains bounded partial bytes and cannot produce completion. Successful postflight appends completion after the admitted execution sequence; a declared procedure also requires every step to finish. The parent composes the declaration, and the worker retains that row after verifying any maintenance prefix.
|
|
133
133
|
|
|
134
134
|
The transport owns its configuration before validation and snapshots each outbound URL, settings, headers, and request correlation before awaiting admission. Later caller mutation cannot change the admitted request. Cancellation signals, the timing callback, and the optional fetch collaborator retain their live identity.
|
|
135
135
|
|
|
@@ -216,9 +216,9 @@ The Ollama transport appends a `stop` evidence row after its `wire` row when com
|
|
|
216
216
|
|
|
217
217
|
## Native command
|
|
218
218
|
|
|
219
|
-
Recording declares positive safe `record.bytes`, `record.calls`, and `record.duration` allowances on the profile. The manifest retains the same declaration, and the parent reserves that complete allowance separately for each trial before starting workers. The allowance covers every serialized sidecar byte, including base64 expansion, opening and terminal rows, and LF framing. It consumes series custody without consuming goal evidence or model quota. Recording profiles explicitly supply `settings.
|
|
219
|
+
Recording declares positive safe `record.bytes`, `record.calls`, and `record.duration` allowances on the profile. The manifest retains the same declaration, and the parent reserves that complete allowance separately for each trial before starting workers. The allowance covers every serialized sidecar byte, including base64 expansion, opening and terminal rows, and LF framing. It consumes series custody without consuming goal evidence or model quota. Recording profiles explicitly supply `settings.metadata`, and name no serving version. Omitting `settings.procedure` selects open recording; supplying it keeps ordered exact or capture admission. The parent calls `buildStudyExchangeDeclaration` with the profile, trial, scenario, and whether it owns a daemon session. Each destination carries that declaration, and the driver, session, and worker check its members against the profile and trial they hold before constructing the adapter driver. The transport takes the procedure from the sink, with no duplicate options.
|
|
220
220
|
|
|
221
|
-
The declaration retains `record`, the ordered `goals`, and a `configuration` digest alongside
|
|
221
|
+
The declaration retains `record`, the ordered `goals`, and a `configuration` digest alongside pinned models, metadata bounds, maintenance, and optional procedure. It holds no version, and a declaration that carries one refuses. Configuration hashes canonical room, settings, and daemon configuration with the daemon executable path omitted; the daemon declaration holds no executable digest, so an updated executable leaves configuration unchanged. Profile record and elapsed bounds stay outside that digest. Maintenance lists the daemon's declared models when the parent owns a daemon session for this execution, and is empty otherwise.
|
|
222
222
|
|
|
223
223
|
The `record.calls` allowance counts execution attempts retained by the sidecar, including replayed exchanges. A request past the cap refuses before append or send with CAPACITY and the scope stop Recording calls. The `record.duration` allowance sums execution send-to-settlement milliseconds; metadata retains its independent budget. When the remaining model time binds a request, its recording deadline starts immediately before send and expires with DEADLINE and the scope stop Recording duration. An exhausted allowance refuses before append or send. A refusal keeps prior charges and prevents completion; an admitted attempt retains its failure terminal, including any bounded partial reply. Such a result stays interrupted.
|
|
224
224
|
|
|
@@ -238,11 +238,11 @@ The `StudyIdentity` interface retains location-independent runtime and content d
|
|
|
238
238
|
|
|
239
239
|
The replay manifest's ancestor retains the source result id, seal, and complete source identity. The replay sidecar's ancestor also retains its source file identity and exchange prefix. The manifest's own identity describes the executing build, so both contents remain available. The worker rechecks the ancestor and recorded goal prefix. The `scanStudyDivergence` function accepts a strictly read history and strictly read replay rows, aligns non-maintenance attempts by position, and returns the first differing or unmatched request. It performs no second validation. An extra request pairs with the recorded attempt at its position; after the last recorded execution, that is the first postflight request; an early end has no actual attempt. An attempt past the complete recording has no expected attempt and uses the recording's completion count plus one as its ordinal.
|
|
240
240
|
|
|
241
|
-
Continuation selects `--extend <result>` on check or execute and refuses a simultaneous replay selection. The ancestor must be sealed, recorded in open form, and complete without operational failures or partial products. The executing profile must declare open recording and a dedicated daemon. The definition, driver, ordered trials, runtime, content,
|
|
241
|
+
Continuation selects `--extend <result>` on check or execute and refuses a simultaneous replay selection. The ancestor must be sealed, recorded in open form, and complete without operational failures or partial products. The executing profile must declare open recording, and it can declare a dedicated daemon or none, with empty maintenance. The definition, driver, ordered trials, runtime, content, models, and configuration must match; the serving version and the daemon executable can differ, so a recording continues under a later Ollama. Every scenario keeps its id and strictly extends its ancestor's goals, including their canonical input values. Fixture identity changes with the grown scenario. Recording and elapsed bounds may rise because they stay outside configuration; no bound rises automatically.
|
|
242
242
|
|
|
243
|
-
The parent derives a live replay prefix ending immediately before each ancestor's postflight.
|
|
243
|
+
The parent derives a live replay prefix ending immediately before each ancestor's postflight. With a declared daemon, it starts and verifies the daemon, then records live unloads before opening the worker; without one, it records no maintenance and live requests go to the external daemon at the provider URL. The worker reconstructs state through the real adapter with exact recorded preflight and execution responses, sending no prefix request to the daemon. It checks the consumed prefix at the ancestor's last goal. An extra request in that goal refuses before forwarding and retains its attempt and failure. The first request in a later goal goes live; postflight verifies the live daemon at the extended horizon's last goal. With a declared daemon, each segment's first live goal starts cold, so its timing and cache state can differ from a continuous execution; an external daemon keeps whatever models it holds.
|
|
244
244
|
|
|
245
|
-
The descendant retains a complete flat sidecar: its extended declaration and ancestor prefix, live maintenance, replayed request and response bytes with recorded chunk lengths, live execution, live postflight, and completion. Its manifest links the immediate ancestor, so a later segment needs only that complete descendant. Replayed goals emit their evidence again and count against recording calls; their send-to-settlement time follows the executing recording duration allowance.
|
|
245
|
+
The descendant retains a complete flat sidecar: its extended declaration and ancestor prefix, any live maintenance, replayed request and response bytes with recorded chunk lengths, live execution, live postflight, and completion. Its manifest links the immediate ancestor, so a later segment needs only that complete descendant. Replayed goals emit their evidence again and count against recording calls; their send-to-settlement time follows the executing recording duration allowance.
|
|
246
246
|
|
|
247
247
|
Triage participates in open recording and in exact or capture procedures using its System One route and policy. Strict sidecar reading checks the same identity, ordering, receipts, and completion as for other roles. Prefix and keyed replay retain original response bytes and chunk lengths. An offline replay sends nothing, and a keyed triage miss cannot borrow another role's recorded answer. Replayed triage usage still charges admission budgets, while progress and reports attribute it to `triage`, count it as replayed, and exclude it from live spending. Continuation requires open recording, replays the ancestor goals, and sends only the grown horizon's suffix live. Keyed replay remains exclusive with `--extend`, and every keyed execution still requires recording.
|
|
248
248
|
|
|
@@ -300,9 +300,9 @@ isStudyExchangeAncestor(reference)
|
|
|
300
300
|
|
|
301
301
|
The process driver accepts `StudyProcessDriverOptions`. Its optional `prepare` callback runs in the parent before session construction, preserves the reserved destination and allowance, and never crosses structured cloning or IPC. Offline replay refuses a preparation callback. A worker verifies any retained maintenance prefix before resuming the sidecar and projects those ordinals into its first goal's evidence.
|
|
302
302
|
|
|
303
|
-
A provider's optional `daemon` declaration makes live execution own a dedicated Ollama session at the provider URL. The declaration
|
|
303
|
+
A provider's optional `daemon` declaration makes live execution own a dedicated Ollama session at the provider URL. The declaration names a canonical absolute executable, explicit environment overrides, and distinct model names and inventory digests equal to the provider's model, judge, and triage pins. It names no executable digest and no version, and a declaration that carries either refuses. Shared pins require one entry. A maintenance-only model, a relative executable, port 11434, a missing model digest, or conflicting environment-name casing refuses at profile load. The daemon owns the effective OLLAMA_HOST value. Without this declaration, the provider URL selects an external daemon.
|
|
304
304
|
|
|
305
|
-
The `StudyDaemonSession` class starts and verifies the daemon before trial execution. The manifest's `host.daemon` string retains the verified startup identity
|
|
305
|
+
The `StudyDaemonSession` class starts and verifies the daemon before trial execution. Each start reads the executable's SHA-256 and hands it to the daemon as the identity to start. The manifest's `host.daemon` string retains the verified startup identity, including that digest and the version the daemon reported. Study compares neither with an earlier reading, so an updated executable or version never refuses a run. Startup version and inventory probes belong to no trial sidecar. Before each trial worker opens, preparation unloads the declared models in order. The `StudyDaemonTrial` class synchronizes each maintenance attempt before sending, retains status, allowed headers, original sender chunk lengths, and exact body bytes, and closes the prefix after daemon validation. A failed exchange retains a failure row. The worker joins the maintenance ordinals to the scenario's first declared goal. Every execution ending awaits daemon stop and process-tree join; an unconfirmed tree stop refuses completion, and an executable that changed or became unreadable while the daemon ran refuses nothing. Offline replay constructs no daemon or preparation callback and sends no maintenance request.
|
|
306
306
|
|
|
307
307
|
Install the package in the consumer workspace, then run the study executable from that workspace. The selected declaration lives at studies/<name>/study.json, and its declared rubric path resolves inside that same directory. Its driver field selects a bundle at studies/<driver>/ containing scenarios/<scenario>.json, profiles/<profile>.json, and the adapter module index.ts. Several declarations can share one driver bundle while each keeps its own rubric. The profile defaults to local. JSON declarations use the public definition, scenario, profile, and rubric contracts.
|
|
308
308
|
|
|
@@ -405,7 +405,7 @@ The following declarations describe this concept.
|
|
|
405
405
|
| `STUDY_CHECKPOINT_EVENT` | const | `"checkpoint"` | Names the evidence event whose row a seeded execution hands its trial at open. |
|
|
406
406
|
| `STUDY_COMMAND_DURATION` | const | `86400000` | Caps declared execution duration at the native supervisor's host ceiling. |
|
|
407
407
|
| `STUDY_COMMAND_GRADER` | const | `"consumer-adapter"` | Names the trusted command's independent offline predicate. |
|
|
408
|
-
| `STUDY_COMMAND_HELP` | const | `"study check <study> [--profile <name>] [--closure <directory>] [--extend <result>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy freeze <study> --profile <name> --to <directory>\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] [--closure <directory>] [--extend <result> \| --replay <result> --prefix <JSON trial counts> --offline <true\|false> \| --replay <result> --roles <JSON roles> --offline <true\|false>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy grade <result> --rubric <path>\nstudy label <result> --assessment <sha256> --labels <path>\nstudy report <result> --assessment <sha256>\nstudy progress <result> [--from <goal>]\nstudy --help\nstudy --version\n\nProfiles default to local; freeze requires --profile. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --assessment selects an exact assessment.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\n--closure selects retained artifacts. Replay requires explicit prefix counts or roles, and offline behavior.\n--roles serves a listed role's request whose path, method, and body bytes equal a recorded attempt's.\n--extend continues a sealed open recording with further goals
|
|
408
|
+
| `STUDY_COMMAND_HELP` | const | `"study check <study> [--profile <name>] [--closure <directory>] [--extend <result>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy freeze <study> --profile <name> --to <directory>\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] [--closure <directory>] [--extend <result> \| --replay <result> --prefix <JSON trial counts> --offline <true\|false> \| --replay <result> --roles <JSON roles> --offline <true\|false>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy grade <result> --rubric <path>\nstudy label <result> --assessment <sha256> --labels <path>\nstudy report <result> --assessment <sha256>\nstudy progress <result> [--from <goal>]\nstudy --help\nstudy --version\n\nProfiles default to local; freeze requires --profile. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --assessment selects an exact assessment.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\n--closure selects retained artifacts. Replay requires explicit prefix counts or roles, and offline behavior.\n--roles serves a listed role's request whose path, method, and body bytes equal a recorded attempt's.\n--extend continues a sealed open recording with further goals; the profile can omit a daemon.\ncheck carries --extend into next and binds the ancestor seal into its fingerprint.\ncheck binds --trial, --goals, and --seed into its fingerprint and carries them into next.\nSuccess writes one JSON document; next contains suggested argv, never executed automatically.\ncheck, freeze, grade, label, report and progress have a fixed allowance of 60 seconds.\nexecute checks first, then uses the declared series duration plus 15 seconds for cleanup.\nExit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 operational failure.\n"` | Defines the complete public CLI reference shared by help and grammar diagnostics. |
|
|
409
409
|
| `STUDY_COMMAND_OPERATION` | const | `"study-command"` | Names the command route beneath the native supervisor. |
|
|
410
410
|
| `STUDY_CUSTODY_BYTES` | const | `number` | Limits untrusted metadata before JSON parsing or file allocation. |
|
|
411
411
|
| `STUDY_DRAIN_DURATION` | const | `1000` | Bounds how long inherited output handles stay open after native exit, in milliseconds. |
|
|
@@ -749,7 +749,7 @@ The following declarations describe this concept.
|
|
|
749
749
|
| `readStudyDeclarationBytes` | function | `(root: string, path: string) => Promise<Uint8Array>` | Reads one declaration file and refuses a missing or linked path with its root-relative path. |
|
|
750
750
|
| `readStudyVersion` | function | `(entry: string) => string` | Reads the version of the study package that owns an executable entry. |
|
|
751
751
|
| `matchesSystemError` | function | `(value: unknown, code: string) => boolean` | Reports whether a caught value is a Node error carrying the given system code. |
|
|
752
|
-
| `StudyDaemon` | interface | `{ executable,
|
|
752
|
+
| `StudyDaemon` | interface | `{ executable, environment?, models }` | Pins an executable and the model population an execution owns until cleanup. |
|
|
753
753
|
| `StudyDaemonModel` | interface | `{ name, digest }` | Pins one model the declared daemon verifies and unloads before each trial. |
|
|
754
754
|
| `StudyRecord` | interface | `{ bytes, calls, duration }` | Bounds serialized exchange bytes, execution calls and summed model time for each trial. |
|
|
755
755
|
| `ArtifactErrorCode` | type | `'ARTIFACT' \| 'TRAVERSAL' \| 'REDIRECT' \| 'ALIAS' \| 'NAME' \| 'DUPLICATE' \| 'OCCUPIED' \| 'OVERLAP' \| 'PARENT' \| 'STALE' \| 'VOLUME' \| 'DRIFT' \| 'LIMIT'` | Names the refused boundary of a captured or materialized artifact graph. |
|
|
@@ -782,7 +782,7 @@ The following declarations describe this concept.
|
|
|
782
782
|
| `StudyExchangeDestination` | interface | `{ path, declaration, retained? }` | Holds the parent-reserved destination of one trial's exchange sidecar. |
|
|
783
783
|
| `StudyExchangeBytes` | interface | `{ body, digest, size }` | Retains an application HTTP body's exact bytes independently of text decoding. |
|
|
784
784
|
| `StudyExchangeIdentity` | interface | `{ ordinal, goal, role, path, method, stage, step? }` | Binds one HTTP exchange to its trial-local position and declared execution stage. |
|
|
785
|
-
| `StudyExchangeDeclaration` | interface | `{ phase, trial,
|
|
785
|
+
| `StudyExchangeDeclaration` | interface | `{ phase, trial, models, metadata, record, goals, configuration, procedure?, maintenance, ancestor?, keyed? }` | Declares a bounded trial horizon and serving identities before any exchange attempt. |
|
|
786
786
|
| `StudyExchangeAttempt` | interface | `{ phase }` | Retains admitted request bytes durably before the corresponding send begins. |
|
|
787
787
|
| `StudyExchangeReply` | interface | `{ status, headers, chunks }` | Retains response status, headers, and original application-body chunk lengths. |
|
|
788
788
|
| `StudyExchangeResponse` | interface | `{ phase }` | Retains a fully consumed response only after status and terminal validation succeed. |
|
|
@@ -3346,7 +3346,7 @@ try {
|
|
|
3346
3346
|
|
|
3347
3347
|
## Tests
|
|
3348
3348
|
|
|
3349
|
-
The staging proofs drive the real command and worker over a Node protocol daemon on an ephemeral loopback port. The daemon records whether each unload's attempt was already readable on disk. The source suite proves repeated maintenance prefixes, exact ordinal joins, offline replay without a daemon or request,
|
|
3349
|
+
The staging proofs drive the real command and worker over a Node protocol daemon on an ephemeral loopback port. The daemon records whether each unload's attempt was already readable on disk. The source suite proves repeated maintenance prefixes, exact ordinal joins, offline replay without a daemon or request, startup, trial, unload, and cancellation cleanup while an unrelated sentinel survives, and a stop that completes after the executable changed under the running daemon. Setup proofs validate fixture declarations without starting a child.
|
|
3350
3350
|
|
|
3351
3351
|
### Call exchange and replay helpers
|
|
3352
3352
|
|
package/dist/host/guides/test.md
CHANGED
|
@@ -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,
|
|
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
|
|
1017
|
-
|
|
|
1018
|
-
| `chooseFiles`
|
|
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
|
|
1023
|
-
|
|
|
1024
|
-
| `ScratchInterface`
|
|
1025
|
-
| `ScratchIdentity`
|
|
1026
|
-
| `ScratchOptions`
|
|
1027
|
-
| `LoopbackInterface`
|
|
1028
|
-
| `CookieJarInterface`
|
|
1029
|
-
| `InventoryOptions`
|
|
1030
|
-
| `UpgradeOptions`
|
|
1031
|
-
| `UpgradeResult`
|
|
1032
|
-
| `ChooserContext`
|
|
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
|
|
1037
|
-
| ----------------------------- | ----- |
|
|
1038
|
-
| `REMOVE_TREE_MAX_ATTEMPTS` | const | `10`
|
|
1039
|
-
| `REMOVE_TREE_RETRY_DELAY_MS` | const | `100`
|
|
1040
|
-
| `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]`
|
|
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
|
|
1045
|
-
| ------------------------ | -------- |
|
|
1046
|
-
| `readLoopClock` | function | `() => number`
|
|
1047
|
-
| `alignLoopClock` | function | `(offset?: number) => void`
|
|
1048
|
-
| `readCapture` | function | `(path: string) => Promise<string>`
|
|
1049
|
-
| `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>`
|
|
1050
|
-
| `resolveContained` | function | `(root: string, target: string) => string \| undefined`
|
|
1051
|
-
| `requireContained` | function | `(root: string, target: string) => string`
|
|
1052
|
-
| `hasScratchPath` | function | `(root: string, target: string) => boolean`
|
|
1053
|
-
| `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean`
|
|
1054
|
-
| `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity`
|
|
1055
|
-
| `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean`
|
|
1056
|
-
| `readErrorCode` | function | `(error: unknown) => string \| undefined`
|
|
1057
|
-
| `createLink` | function | `(path: string, source: string) => void`
|
|
1058
|
-
| `removeTree` | function | `(path: string) => void`
|
|
1059
|
-
| `isRunning` | function | `(pid: number) => boolean`
|
|
1060
|
-
| `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>`
|
|
1061
|
-
| `
|
|
1062
|
-
| `
|
|
1063
|
-
| `
|
|
1064
|
-
| `
|
|
1065
|
-
| `
|
|
1066
|
-
| `
|
|
1067
|
-
| `
|
|
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
|
|
@@ -2997,7 +3048,7 @@ Object.keys(
|
|
|
2997
3048
|
readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
|
|
2998
3049
|
)
|
|
2999
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',
|
|
3000
|
-
// 'src/core/types.ts', 'src/core/validators.ts']
|
|
3051
|
+
// 'src/core/types.ts', 'src/core/validators.ts', 'src/reporter/main.ts']
|
|
3001
3052
|
|
|
3002
3053
|
// An exclusion also applies to a target you name, so naming one file below an excluded directory
|
|
3003
3054
|
// does not reinstate it.
|
|
@@ -3204,6 +3255,67 @@ rejects with the client's own `ECONNREFUSED` rather than reporting a refusal, an
|
|
|
3204
3255
|
accepts the connection and answers nothing rejects on the budget, which defaults to `1000`
|
|
3205
3256
|
milliseconds and names the port and path it was waiting on.
|
|
3206
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
|
+
|
|
3207
3319
|
### Probe what the host supports
|
|
3208
3320
|
|
|
3209
3321
|
Gate a proof on the mechanism it needs rather than on the platform name. Each probe allocates its own
|