@orkestrel/scaffold 0.0.137 → 0.0.139
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 +489 -23
- package/dist/bin/main.js +6 -6
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +33 -27
- package/dist/host/agents/skills/orkestrel-journey/references/captures.md +37 -16
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
- package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +5 -0
- package/dist/host/claude/agents/orkestrel.md +54 -54
- package/dist/host/claude/rules/typescript.md +4 -1
- package/dist/host/claude/rules/workspace.md +6 -4
- package/dist/host/guides/capture.md +442 -313
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/middleware.md +489 -259
- package/dist/host/guides/process.md +139 -53
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +35 -23
- package/dist/host/guides/server.md +417 -181
- package/dist/host/guides/test.md +353 -232
- package/dist/host/manifest.json +18 -18
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +19 -27
- package/dist/src/core/index.cjs +139 -60
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +139 -60
- package/dist/src/core/index.js.map +1 -1
- package/package.json +6 -6
|
@@ -72,13 +72,17 @@ choose the capture destination, the matrix row, and the statechart run together.
|
|
|
72
72
|
|
|
73
73
|
- Read `inject('variant')` for this run's variant name, `inject('variants')` for the declared list,
|
|
74
74
|
and `inject('capture')` for whether this run writes frames.
|
|
75
|
-
-
|
|
76
|
-
|
|
75
|
+
- Keep the provided types the workspace's browser test setup module declares once: `scaffold new`
|
|
76
|
+
seeds it to extend Vitest's own `ProvidedContext` with `CaptureProvided` and `TaskMeta` with
|
|
77
|
+
`CaptureMeta` from `@orkestrel/capture`, so `inject` is typed rather than narrowed at each call.
|
|
77
78
|
- Declare the variant list in `configs/app/vite.journey.config.ts`, the birth-owned wrapper a
|
|
78
79
|
browser application is born with. Its presence is the journey axis. Rename and extend the seeded
|
|
79
80
|
viewports for this application.
|
|
80
|
-
- Activate the axis in a workspace born before it: write `configs/app/vite.journey.config.ts
|
|
81
|
-
`
|
|
81
|
+
- Activate the axis in a workspace born before it: write `configs/app/vite.journey.config.ts` as
|
|
82
|
+
one `buildCaptureWrapper` call whose `project` option returns `appJourney(variant, mode,
|
|
83
|
+
override)`, run `scaffold audit`, and add any missing planned dependencies it names before
|
|
84
|
+
`scaffold repair`. Rewrite a wrapper that still calls `appJourney(variant, VARIANTS, mode)` the
|
|
85
|
+
same way.
|
|
82
86
|
Check that the repair defines `appJourney` in the root configuration, emits `test:journey`,
|
|
83
87
|
`journey`, and `capture`, and excludes the journey suite from the ordinary `app:browser` project.
|
|
84
88
|
Place each script by `.claude/rules/workspace.md` § Test project matrix. When the repair preserves
|
|
@@ -86,9 +90,11 @@ choose the capture destination, the matrix row, and the statechart run together.
|
|
|
86
90
|
- Name each variant per [captures.md](references/captures.md) → Variants.
|
|
87
91
|
- Keep the provided variants as serializable `JourneyVariant` data: `name`, `width`, and `height`.
|
|
88
92
|
Compose no callback merely to pass that data to a capture.
|
|
89
|
-
-
|
|
90
|
-
|
|
91
|
-
`
|
|
93
|
+
- Close the journey gate with `npx capture registry`, which runs the whole suite, ownerless cases
|
|
94
|
+
included, and then `npm run capture -- all`. Accept in place of that frames run a portfolio
|
|
95
|
+
whose `npx capture stale all` reads every frame current and exits 0. Run no
|
|
96
|
+
`npm run test:journey` for the gate. Use the scoped commands under Choosing what to run for
|
|
97
|
+
iteration and stamped frames.
|
|
92
98
|
- Keep the journeys in `tests/app/browser/integration.test.ts`, and the journeys of the `vue`
|
|
93
99
|
extension's application in `tests/app/vue/integration.test.ts`, which `npm run test:journey:vue`
|
|
94
100
|
runs. Each variant project of a mode collects that file alone, and the application's ordinary
|
|
@@ -116,10 +122,12 @@ For an absent-configuration question, inspect
|
|
|
116
122
|
`npm run journey -- <selector>` (`capture journey`) for owner-selected behavior with capture
|
|
117
123
|
off, and `npm run capture -- <selector>` (`capture frames`) for capture-bearing journeys with
|
|
118
124
|
`CAPTURE=1`. Keep the commands separate; never append capture work to a behavior run.
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
125
|
+
- Build the journey wrapper with the `buildCaptureWrapper` factory from
|
|
126
|
+
`@orkestrel/capture/server`, as the `@orkestrel/capture` guide's Runner selection and process
|
|
127
|
+
protocol section shows under Wrapper; never wire discovery, the selection request, or the tags
|
|
128
|
+
by hand. Write each run record in the wrapper's final case through capture's core record
|
|
129
|
+
helpers, as the arrival journey `scaffold new` seeds does. Declare in the wrapper every owner
|
|
130
|
+
path the journey cases carry.
|
|
123
131
|
- Select `all` or a colon-delimited owner path from the wrapper's tags: `<scope>`,
|
|
124
132
|
`<scope>:<owner>`, or further declared descendants. Use the wrapper's names, never infer them
|
|
125
133
|
from filenames. Keep behavior on the positive `owner:` filter and frames on its intersection
|
|
@@ -171,25 +179,13 @@ judging their freshness or completeness.
|
|
|
171
179
|
invokes the hook without awaiting a returned promise.
|
|
172
180
|
- Keep `applyTheme` as the workspace's own browser setup helper. Make it drive the theme control
|
|
173
181
|
through the published journey verbs and await the announced theme state and settled paint.
|
|
174
|
-
-
|
|
182
|
+
- Keep the provided-context declaration in the browser test setup module, and consume the injected
|
|
175
183
|
data in `tests/app/browser/integration.test.ts` through the following portfolio configuration.
|
|
176
184
|
Mount the shipped application entry with its real provisions before the acceptance journey runs.
|
|
177
185
|
- From `tests/app/browser/integration.test.ts`, pass `../../../tmp/captures/states` as the capture
|
|
178
186
|
directory to write into the workspace's `tmp/captures/states` directory. The browser provider
|
|
179
187
|
resolves a custom screenshot path relative to the test file's directory.
|
|
180
188
|
|
|
181
|
-
```ts
|
|
182
|
-
import type { JourneyVariant } from '@orkestrel/test'
|
|
183
|
-
|
|
184
|
-
declare module 'vitest' {
|
|
185
|
-
interface ProvidedContext {
|
|
186
|
-
readonly variant: string
|
|
187
|
-
readonly variants: readonly JourneyVariant[]
|
|
188
|
-
readonly capture: boolean
|
|
189
|
-
}
|
|
190
|
-
}
|
|
191
|
-
```
|
|
192
|
-
|
|
193
189
|
```ts
|
|
194
190
|
import { createPortfolio } from '@orkestrel/test/browser'
|
|
195
191
|
import { inject } from 'vitest'
|
|
@@ -281,9 +277,18 @@ and no title scheme.
|
|
|
281
277
|
([layer.md](references/layer.md) → Role vocabulary).
|
|
282
278
|
- Every census phase states the screen state it starts from, measures the pointer route at arrival
|
|
283
279
|
before any key, and proves a focus-presented state (a skip link, a focus tooltip) by its own case.
|
|
280
|
+
- Take a reachability row's stop set once, through one `collectTabStops` call or one `walkFocus`
|
|
281
|
+
call. Assert both the pointer route and the reached set against that one walk, never walking the
|
|
282
|
+
Tab cycle once per assertion. Keep the census set as the row's proof.
|
|
284
283
|
- The reachability walk asserts that focusing each control leaves fixed chrome's geometry
|
|
285
284
|
unchanged.
|
|
286
285
|
|
|
286
|
+
Take the row's walk from the journey layer:
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
import { collectTabStops, walkFocus } from '@orkestrel/test/browser'
|
|
290
|
+
```
|
|
291
|
+
|
|
287
292
|
## Declare the transport family
|
|
288
293
|
|
|
289
294
|
- Name the block for what it proves — persistence, restart, storage failure.
|
|
@@ -317,8 +322,9 @@ transition, the runner, the mounted harness, and the gate that reads its tally.
|
|
|
317
322
|
## Generate the portfolio
|
|
318
323
|
|
|
319
324
|
Follow [captures.md](references/captures.md) for the state registry and its placement rules, the
|
|
320
|
-
variant matrix, the always-on filename proof, the capture-run membership proof,
|
|
321
|
-
exists only during an activation is captured
|
|
325
|
+
variant matrix, the always-on filename proof, the capture-run membership proof, how a state that
|
|
326
|
+
exists only during an activation is captured, and when a capture-bearing journey navigates under
|
|
327
|
+
reduced motion.
|
|
322
328
|
|
|
323
329
|
Where a capture and a green suite disagree, take the capture as the evidence and the fixture as the
|
|
324
330
|
defect.
|
|
@@ -354,7 +360,7 @@ Completion requires all of:
|
|
|
354
360
|
- the declared families each proven, the declaration asserted, and the transport family driven through real implementations;
|
|
355
361
|
- the matrix family read once per declared variant, each style reading carrying its published control from [styles.md](references/styles.md) → The published controls, and the authored-class census and the `extractStyles` reading each reporting the population it walked;
|
|
356
362
|
- the statechart table driven to a terminal status with no failed row, and the harness tally read from the object and from its markup;
|
|
357
|
-
- the registry-times-variants filename proof and the state-placement proof green in an ordinary run,
|
|
363
|
+
- the registry-times-variants filename proof and the state-placement proof green in an ordinary run, the journey gate under § Read the variant once green, every registered file written by its frames run or read current by `capture stale all`, and the written artifact produced for every variant, named by that variant;
|
|
358
364
|
- the browser test setup module proven by `tests/setupBrowser.test.ts` in the `setup:browser` project `scaffold repair` registers;
|
|
359
365
|
- each assertion class mutated, with the red reading and the green reading recorded;
|
|
360
366
|
- the repository gates green, per `.agents/orchestration.md` § Acceptance.
|
|
@@ -15,7 +15,14 @@ import type {
|
|
|
15
15
|
PortfolioInterface,
|
|
16
16
|
PortfolioOptions,
|
|
17
17
|
} from '@orkestrel/test/browser'
|
|
18
|
-
import {
|
|
18
|
+
import {
|
|
19
|
+
captureFrame,
|
|
20
|
+
createPortfolio,
|
|
21
|
+
expandCaptures,
|
|
22
|
+
readFrame,
|
|
23
|
+
settleCapture,
|
|
24
|
+
stageMedia,
|
|
25
|
+
} from '@orkestrel/test/browser'
|
|
19
26
|
import { inject } from 'vitest'
|
|
20
27
|
```
|
|
21
28
|
|
|
@@ -28,12 +35,13 @@ file is written to, and the flag as `enabled`.
|
|
|
28
35
|
|
|
29
36
|
- Place a state with `place(state)` for the whole page, and `place(state, element)` where the
|
|
30
37
|
picture is one element.
|
|
31
|
-
- Take `enabled` from `inject('capture')`, which the
|
|
32
|
-
`CAPTURE` environment variable set to `1` in the shell that runs the axis. An
|
|
33
|
-
it false, so `place` returns `undefined`, resizes nothing, writes nothing,
|
|
34
|
-
and still refuses an unregistered state and a second placement of one state.
|
|
35
|
-
- Read `files` for the registry expanded across every variant, `
|
|
36
|
-
and `paths` for what it wrote. Each
|
|
38
|
+
- Take `enabled` from `inject('capture')`, which the wrapper's `buildCaptureWrapper` factory
|
|
39
|
+
provides from the `CAPTURE` environment variable set to `1` in the shell that runs the axis. An
|
|
40
|
+
ordinary run leaves it false, so `place` returns `undefined`, resizes nothing, writes nothing,
|
|
41
|
+
records no placement, and still refuses an unregistered state and a second placement of one state.
|
|
42
|
+
- Read `files` for the registry expanded across every variant, `observed` for every state this run
|
|
43
|
+
placed, written or not, `placements` for the states it wrote, and `paths` for what it wrote. Each
|
|
44
|
+
hands back a snapshot.
|
|
37
45
|
- Reach for `readFrame` where the written image itself is the subject — its decoded size, or its
|
|
38
46
|
pixels. `captureFrame` already reads each file back and compares its bytes against the frame it
|
|
39
47
|
shot.
|
|
@@ -59,8 +67,9 @@ Declare the state names once in the journey file, and build the portfolio from t
|
|
|
59
67
|
that ran declare.
|
|
60
68
|
- Place a capture state from inside the journey that reaches it, immediately after the assertion
|
|
61
69
|
that proves the screen is in the condition that state names.
|
|
62
|
-
-
|
|
63
|
-
`
|
|
70
|
+
- Read the portfolio's `observed` list in the always-on placement proof: it lists every state
|
|
71
|
+
`place` and `view` accepted, written or not, in placement order, where `placements` lists only
|
|
72
|
+
the states a capture run wrote.
|
|
64
73
|
- Give each owner-bearing case registry-derived `owner:` tags. Declare a placing case's states in
|
|
65
74
|
`meta.states`, derive its capture scope and part tags from those states, and place only states
|
|
66
75
|
of that owner. Give behavior-only cases no capture tag.
|
|
@@ -74,8 +83,8 @@ Declare the state names once in the journey file, and build the portfolio from t
|
|
|
74
83
|
- Run `npm run journey -- <selector>` for behavior and `npm run capture -- <selector>` for frames.
|
|
75
84
|
Take both commands from `node_modules/@orkestrel/capture`; follow
|
|
76
85
|
[SKILL.md](../SKILL.md#choosing-what-to-run) for selector grammar, flags, refusals, and the
|
|
77
|
-
case, changed-set, section or page, group, and `all` ladder.
|
|
78
|
-
|
|
86
|
+
case, changed-set, section or page, group, and `all` ladder. Run the whole-suite gate
|
|
87
|
+
[SKILL.md](../SKILL.md#read-the-variant-once) names.
|
|
79
88
|
- Inspect the changed set with `--changed <ref> --plan` before executing it. Keep a shared-input
|
|
80
89
|
refusal explicit, and follow its next command without silently capturing the complement.
|
|
81
90
|
- Use the authenticated selection request to refuse a case whose declared states cross the
|
|
@@ -104,8 +113,7 @@ these.
|
|
|
104
113
|
`createPortfolio` refuses a `variant` no declared variant carries, and `files` expands the
|
|
105
114
|
registry across the whole list rather than across the one being rendered.
|
|
106
115
|
- Produce the complete stamped portfolio with `npm run capture -- all`, which runs the declared
|
|
107
|
-
variant projects through the capture runner
|
|
108
|
-
behavioral gate; a bare capture-flag run supplies no manifest stamp.
|
|
116
|
+
variant projects through the capture runner; a bare capture-flag run supplies no manifest stamp.
|
|
109
117
|
|
|
110
118
|
## The proofs the suite owes
|
|
111
119
|
|
|
@@ -115,7 +123,7 @@ Write each of the following proofs into the suite. The package asserts none of t
|
|
|
115
123
|
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
|
|
116
124
|
| Filename expansion | Always | `expandCaptures(states, variants)` has one entry per state and variant, all unique |
|
|
117
125
|
| Declaration coverage | Always | The case declarations cover the registry, are disjoint, and match the owner and capture tag definitions |
|
|
118
|
-
| Placement membership | Always | The
|
|
126
|
+
| Placement membership | Always | The portfolio's `observed` list equals the states declared by the cases that ran, as sets |
|
|
119
127
|
| Disk membership | Under the flag | The written filenames equal the selected expansion for this run's variant, with no orphan on disk |
|
|
120
128
|
|
|
121
129
|
- Keep the filename proof always-on, so a registry edit that introduces a duplicate or a collision
|
|
@@ -126,8 +134,8 @@ Write each of the following proofs into the suite. The package asserts none of t
|
|
|
126
134
|
- Assert placement as set equality against the union of the states the cases that ran declare.
|
|
127
135
|
When every case ran, require that union to equal the registry. Derive completeness from the
|
|
128
136
|
recorded cases that ran and passed, never from the selector or a task's mode alone.
|
|
129
|
-
- Read the placement proof from
|
|
130
|
-
|
|
137
|
+
- Read the placement proof from `observed` rather than from `placements`, which stays empty in an
|
|
138
|
+
ordinary run. `place` refuses an unregistered name and a second placement of one state in
|
|
131
139
|
every run, but a registered state that no journey placed reaches no refusal; the always-on
|
|
132
140
|
placement proof catches it.
|
|
133
141
|
- Under the flag, assert the written filenames equal the ran cases' declared states expanded for
|
|
@@ -148,6 +156,19 @@ after the click returns.
|
|
|
148
156
|
through the normal verb and await the promise the listener recorded.
|
|
149
157
|
- Fail the step when the listener never ran.
|
|
150
158
|
|
|
159
|
+
## Navigate under reduced motion
|
|
160
|
+
|
|
161
|
+
Apply this section to a capture-bearing journey whose navigation runs transitions, smooth scrolls,
|
|
162
|
+
or entrance animations. Leave every other journey under default motion.
|
|
163
|
+
|
|
164
|
+
- Stage reduced motion with a `stageMedia({ motion: false })` call before the journey navigates,
|
|
165
|
+
then restore motion with a `stageMedia({ motion: true })` call before each `settleCapture()`
|
|
166
|
+
call.
|
|
167
|
+
- Keep one declared journey per transition kind under default motion end to end.
|
|
168
|
+
- Keep a journey on the default-motion path when its stage reads the `prefers-reduced-motion`
|
|
169
|
+
media feature once at mount: that stage keeps the reduced reading after the restore. The
|
|
170
|
+
`@orkestrel/test` guide's Place a capture portfolio section states this limit.
|
|
171
|
+
|
|
151
172
|
## Hygiene
|
|
152
173
|
|
|
153
174
|
- Keep the portfolio out of version control.
|
|
@@ -21,7 +21,7 @@ description: >-
|
|
|
21
21
|
Run from the checkout root. The script's opening comment owns its behavior.
|
|
22
22
|
|
|
23
23
|
- `scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]` reads a Vitest `--reporter=json` report and requires every case a `--passed` name matches to have passed and every case a `--failed` name matches to have failed. A name matches a case's full name or its own title exactly; both flags repeat. A name that matches no case is missing, and a failed case no name matches is refused, as is a test file that failed with no failed case (it did not collect, or a hook threw) and a report whose `success` is false while nothing in it failed. It prints one summary line, each difference, and `ok` or `differences=N`. Exit 0 when the report matches, 3 when it does not, 2 when the report cannot be read as a Vitest report, 64 usage.
|
|
24
|
-
- `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]` runs process-running commands on this host in one heavy lane and several light lanes, each in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. A ticket runs light only while `limits.json` exists under the lane root and the command's kind or its own run records read it light; every other ticket runs heavy, one at a time. `npx` and `npm exec` read as the tool they run, and a `mutate` run of the falsify skill reads as the command it wraps, keyed without its edits file, and a `mutate --restore` run reads heavy; each waits on the earlier tickets of its working directory, and every later ticket of that directory waits on it. A run's record counts a command shorter than the sample interval when the command outlives one process query; a shorter command can record zero, per the opening comment's Sampling limit. A record that opens a history key prunes the history to the age and count bounds the opening comment names. `--solo` runs heavy with no light run beside it. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its lane, and whether it holds, and names the heavy holder and every light holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 69 when a light run passed its threshold and the lane ended it, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads like the lane's own code. The opening comment owns the lane rules, the limits, and the migration stop.
|
|
24
|
+
- `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]` runs process-running commands on this host in one heavy lane and several light lanes, each in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. A ticket runs light only on Windows or Linux, while `limits.json` exists under the lane root and the command's kind or its own run records read it light; every other ticket runs heavy, one at a time. `npx` and `npm exec` read as the tool they run, and a `mutate` run of the falsify skill reads as the command it wraps, keyed without its edits file, and a `mutate --restore` run reads heavy; each waits on the earlier tickets of its working directory, and every later ticket of that directory waits on it. A run's record counts a command shorter than the sample interval when the command outlives one process query; a shorter command can record zero, per the opening comment's Sampling limit. A record that opens a history key prunes the history to the age and count bounds the opening comment names. `--solo` runs heavy with no light run beside it. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its lane, and whether it holds, and names the heavy holder and every light holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 69 when a light run passed its threshold and the lane ended it, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads like the lane's own code. The opening comment owns the lane rules, the limits, and the migration stop.
|
|
25
25
|
|
|
26
26
|
## Bound the host
|
|
27
27
|
|