@orkestrel/scaffold 0.0.133 → 0.0.134

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 (82) 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 +1018 -194
  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 +95 -108
  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 +27 -3
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  35. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  36. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  37. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  38. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  42. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  43. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  45. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  46. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  52. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  53. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  54. package/dist/host/claude/agents/orkestrel.md +4 -4
  55. package/dist/host/claude/rules/documentation.md +1 -1
  56. package/dist/host/claude/rules/patterns.md +5 -4
  57. package/dist/host/claude/rules/styles.md +1 -1
  58. package/dist/host/claude/rules/tests.md +3 -3
  59. package/dist/host/claude/rules/workspace.md +47 -35
  60. package/dist/host/configs/helpers.ts +40 -15
  61. package/dist/host/dotfiles/oxlintrc.json +62 -0
  62. package/dist/host/guides/form.md +79 -4
  63. package/dist/host/guides/scaffold.md +93 -65
  64. package/dist/host/guides/table.md +20 -6
  65. package/dist/host/guides/test.md +9 -7
  66. package/dist/host/manifest.json +44 -44
  67. package/dist/host/tests/config.test.ts +201 -11
  68. package/dist/host/tests/policy.test.ts +14 -21
  69. package/dist/host/tests/setupPolicy.ts +43 -36
  70. package/dist/src/core/index.cjs +191 -93
  71. package/dist/src/core/index.cjs.map +1 -1
  72. package/dist/src/core/index.d.cts +27 -13
  73. package/dist/src/core/index.d.ts +27 -13
  74. package/dist/src/core/index.js +189 -93
  75. package/dist/src/core/index.js.map +1 -1
  76. package/dist/src/server/index.cjs +8 -9
  77. package/dist/src/server/index.cjs.map +1 -1
  78. package/dist/src/server/index.d.cts +1 -1
  79. package/dist/src/server/index.d.ts +1 -1
  80. package/dist/src/server/index.js +8 -9
  81. package/dist/src/server/index.js.map +1 -1
  82. package/package.json +2 -2
@@ -113,7 +113,7 @@ A skill, a tool description, and a refusal message each teach an agent mid-task.
113
113
 
114
114
  - Run a script in a target through its built twin, `node node_modules/@orkestrel/scaffold/dist/agents/skills/<skill>/scripts/<name>.js`, because Node refuses to strip types for a file under `node_modules`; `.claude/rules/workspace.md` names the `build:skills` script that emits the twins. When a script spawns a sibling script, take the extension from the running file (`extname(fileURLToPath(import.meta.url))`), so the twin spawns `.js` and the checkout spawns `.ts`. When a script resolves a file under `.agents/templates/`, add that file to the copy in `build:skills`.
115
115
  - Resolve a sibling canon file (a template, another script) from the script's own location with `import.meta.url`, and the manifest, `tmp/`, and the test tree from the working directory, because a target runs the script from `node_modules/@orkestrel/scaffold/dist/agents/` against its own checkout.
116
- - Read arguments as `--flag value` pairs: the first occurrence of a flag wins, a value that opens with `--` is a missing value, and `--flag=value` is not read. Refuse every argument before a bare `--` that opens with `--` and names no flag the script reads, the `--flag=value` form included, so a mistyped flag never runs the default; a bare `--` opens a command the script passes on. Where flags select different work (`--visit` or `--plan`), the script names one operation mode per run and refuses two; where each flag adds a section to one report (`--tree` with `--headings`), the script combines them and its usage line says so. Read every value of a flag that repeats (`--range`) and say in the usage line that it repeats. Exit 64 on every usage refusal and say on stderr what was refused: the usage line when no mode or two modes were given, and the flag with the value it takes when a flag was unknown, malformed, or given with no value.
116
+ - Read arguments with `parseArgs` from `node:util`, with `strict: true` and every flag the script reads declared in its `options`: it refuses an unknown flag, a value-taking flag with no value, and a value that opens with `-` and is longer than `-`, outside the `--flag=value` form, and it reads `--flag value` and `--flag=value` alike. Never wrap `parseArgs` to change what it reads. Declare a flag that repeats (`--range`) with `multiple: true` and say in the usage line that it repeats. Where a script passes a command on, parse only the arguments before the first bare `--` and take the arguments after it as the command. Where flags select different work (`--visit` or `--plan`), the script names one operation mode per run and refuses two; where each flag adds a section to one report (`--tree` with `--headings`), the script combines them and its usage line says so. Exit 64 on every usage refusal and say on stderr what was refused: the `parseArgs` error message followed by the usage line, the usage line when no mode or two modes were given, and the flag with the value it takes when a value fails the script's own check.
117
117
  - Print to the terminal by default. Offer `--json` for a reader that parses, and `--out FILE` (`.txt` for a list, `.json` for a structure) where a lane reads the result later or the output would crowd a context; a written file saves the tokens a terminal dump spends. Choose per script; state each form in its usage line.
118
118
  - Verify each API a skill instructs an executor to call against the installed package's public entry before landing the instruction, and name the entry you read. A skill that names a symbol its package does not export teaches an executor to write a dangling import.
119
119
  - Put every symbol a skill teaches in a named import inside a Markdown fence in `SKILL.md` or a named reference. The policy sweep reads fenced value and type imports from `@orkestrel/*` declaration entries; it does not read identifiers in prose or table cells, or validate call signatures and runtime behavior.
@@ -13,10 +13,11 @@ These rules govern the shape of options, managers, emitters, and contracts, and
13
13
 
14
14
  `AGENTS.md` § Non-negotiable rules owns the reuse law. Before writing a guard, parser, combinator, outcome, safe exception boundary, contract shape/compiler, schema utility, error narrower, emitter helper, or other general primitive:
15
15
 
16
- 1. Inspect `package.json`, the lockfile, vendored dependency guides, and exact installed declarations/exports.
17
- 2. Build a semantic overlap map between the proposed/local behavior and declared `@orkestrel/*` capabilities.
18
- 3. Keep local behavior only when it adds a real domain invariant, composition, projection, translation, or intentionally different contract.
19
- 4. Test the difference. Similar names are not proof of equivalent semantics.
16
+ 1. Check the stable `node:` modules and ECMAScript built-ins at the declared `engines.node` floor, and use the one whose semantics match, such as `parseArgs` from `node:util` for command-line flags.
17
+ 2. Inspect `package.json`, the lockfile, vendored dependency guides, and exact installed declarations/exports.
18
+ 3. Build a semantic overlap map between the proposed/local behavior and declared `@orkestrel/*` capabilities.
19
+ 4. Keep local behavior only when it adds a real domain invariant, composition, projection, translation, or intentionally different contract.
20
+ 5. Test the difference. Similar names are not proof of equivalent semantics.
20
21
 
21
22
  ## Options
22
23
 
@@ -109,4 +109,4 @@ State classes are bare adjectives such as `.active` and `.disabled`, chosen cons
109
109
 
110
110
  When a class sets one component's tokens for one key of a shared Sass map, such as a recreated `$theme-colors`, write it as a variant class, as Bootstrap writes `.btn-success`: generate one class per key with `@each` over the map's keys, take each value from the family map with an `@error` on a missing key, and set only the component's own custom properties. Keep the bare modifier form for a class that any component reads.
111
111
 
112
- The composable owns interaction state, class application, `aria-*`, and timing. The partial owns visual presentation. Their contracts are stable class names and transition tokens. A native browser module's partial keys its chrome on the module's `data-*` state attribute, scoped under the module's host attribute, and its proof sets the attribute directly; the stable-class-name contract covers the classes a composable writes, not a module's attributes.
112
+ The composable owns interaction state, class application, `aria-*`, and timing. The partial owns visual presentation. Their contracts are stable class names and transition tokens. A native browser module's partial keys its chrome on the module's `data-*` state attribute, scoped under the module's host attribute, and its proof sets the attribute directly; the stable-class-name contract covers the classes a composable writes, not a module's attributes. When descent from the host cannot select every element the module marks, because the module declares no host attribute or reaches the element through an association such as `commandfor` or `form`, key the state attribute on the marked element instead: compound it with the class whose paint the state changes, and only when no other module of the package writes that attribute. The proof of such a rule sets the attribute directly in a fixture that carries no host attribute, and proves that an element carrying the attribute without the class paints unchanged.
@@ -209,9 +209,9 @@ Test helpers are shared infrastructure, not local test-file clutter.
209
209
  - For the test modules scaffold owns, keep shared helpers within them instead of importing them
210
210
  from `@orkestrel/test`. In the vendored set (`tests/setupPolicy.ts`, `tests/policy.test.ts`, and
211
211
  `tests/config.test.ts`), follow the vendored-file import law in `.claude/rules/workspace.md`. In
212
- the `tests/setupDistribution.ts` harness, import only `node:` modules, `vitest`, and `vite`, and
213
- in its browser variant also `playwright`, `@vitest/browser-playwright`, and
214
- `../configs/browsers.js`.
212
+ the `tests/setupDistribution.ts` harness, import only `node:` modules, `@orkestrel/contract`,
213
+ `vitest`, and `vite`, and in its browser variant also `playwright`, `@vitest/browser-playwright`,
214
+ and `../configs/browsers.js`.
215
215
 
216
216
  - Extract a fixture, recorder, event factory, async wait, renderer, scenario/data builder, protocol fixture, or DOM builder as soon as it could serve another test.
217
217
  - Any duplicate or near-duplicate helper is a defect; consolidate it into one general form.
@@ -16,30 +16,37 @@ Use only the environments a project needs, and keep the root dependency model in
16
16
 
17
17
  ## Environments
18
18
 
19
- | Path | Purpose |
20
- | -------------- | ------------------------------------------------------------------ |
21
- | `src/core/` | Published host-independent library |
22
- | `src/browser/` | Published browser-only library |
23
- | `src/server/` | Published Node-only library |
24
- | `src/styles/` | Optional styles surface: the base sheet face producing `index.css` |
25
- | `src/<name>/` | Styles extension: a named sheet face beside `src/styles/` |
26
- | `src/vue/` | Browser extension: the published `vue` face over `src/browser/` |
27
- | `src/bin/` | Optional executable; `main.ts` entry, never a public barrel |
28
- | `app/core/` | Shared application logic with an `index.ts` barrel |
29
- | `app/browser/` | Browser app; `main.ts` entry, not a barrel |
30
- | `app/vue/` | Browser extension: the Vue app beside `app/browser/`; `main.ts` |
31
- | `app/server/` | Node server app; `main.ts` entry |
32
- | `tests/` | Mirrors src/app environments; root holds cross-cutting proofs |
33
- | `configs/` | Thin target wrappers around root configs |
19
+ | Path | Purpose |
20
+ | --------------- | ------------------------------------------------------------------ |
21
+ | `src/core/` | Published host-independent library |
22
+ | `src/browser/` | Published browser-only library |
23
+ | `src/server/` | Published Node-only library |
24
+ | `src/styles/` | Optional styles surface: the base sheet face producing `index.css` |
25
+ | `src/<name>/` | Styles extension: a named sheet face beside `src/styles/` |
26
+ | `src/vue/` | Browser extension: the published `vue` face over `src/browser/` |
27
+ | `src/bin/` | Optional executable; `main.ts` entry, never a public barrel |
28
+ | `src/reporter/` | Optional Vitest reporter; `main.ts` entry, never a barrel |
29
+ | `app/core/` | Shared application logic with an `index.ts` barrel |
30
+ | `app/browser/` | Browser app; `main.ts` entry, not a barrel |
31
+ | `app/vue/` | Browser extension: the Vue app beside `app/browser/`; `main.ts` |
32
+ | `app/server/` | Node server app; `main.ts` entry |
33
+ | `tests/` | Mirrors src/app environments; root holds cross-cutting proofs |
34
+ | `configs/` | Thin target wrappers around root configs |
34
35
 
35
36
  - Dependency direction is the root project model in `AGENTS.md` and is not restated here; this file governs where the environments live and how they are configured.
36
37
  - Typical browser-app domains: `components/`, `pages/`, `composables/`, `controllers/`, `services/`, `stores/`.
37
38
  - Typical server-app domains: `handlers.ts`, `middlewares.ts`, `routes.ts`.
38
39
  - A sheet face (`src/styles/` and each `src/<name>/` styles extension) builds from `sheet.ts`, which imports `./index.scss` alone; its `index.ts` star-exports `./sheet.js`. The themes target builds from `src/styles/themes/sheet.ts` the same way.
39
- - Name a styles extension with a name the `NAME_PATTERN` constant admits, and never `core`, `browser`, `server`, `bin`, `styles`, `themes`, or `vue`.
40
+ - Name a styles extension with a name the `NAME_PATTERN` constant admits, and never `core`, `browser`, `server`, `bin`, `reporter`, `styles`, `themes`, or `vue`.
40
41
  - `src/bin/main.ts` is the executable entry, built to `dist/bin/main.js`. The name is fixed, as it
41
42
  is for `app/browser/main.ts` and `app/server/main.ts`, so every runtime entry in a workspace is
42
43
  found at the same name.
44
+ - `src/reporter/main.ts` is the Vitest reporter entry, one per package, built to
45
+ `dist/reporter/main.js` and published as the `./reporter` export. Its body is two statements:
46
+ an import of the reporter class from `@src/server`, then `export default` of that class. That
47
+ body is the one exception to `.claude/rules/architecture.md` § Barrel exports, and the vendored
48
+ `.oxlintrc.json` exempts that one path from `import/no-default-export`. Keep the class in
49
+ `src/server`, exported by name through the server barrel.
43
50
  - `package.json`'s `bin` key is the installed command name. The entry path is the value and does
44
51
  not carry that name.
45
52
  - Keep every ignored output at the workspace root or under `tmp/`, and write no `.gitignore`
@@ -65,9 +72,9 @@ Use only the environments a project needs, and keep the root dependency model in
65
72
 
66
73
  Give every selected environment and every face an alias: `src/styles`, each `src/<name>` styles extension, and each axis the `vue` extension occupies. Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compilerOptions.paths`; keep both aligned.
67
74
 
68
- Import a sibling environment through its alias. In `src/browser`, `src/server`, `src/vue`, and `src/bin`, a
69
- relative path to `src/core`, to `src/browser` from `src/vue`, or to `src/server` from `src/bin` bundles a
70
- private copy of that environment into the face, so the vendored `.oxlintrc.json` refuses it with a message naming the alias.
75
+ Import a sibling environment through its alias. In `src/browser`, `src/server`, `src/vue`, `src/bin`, and
76
+ `src/reporter`, a relative path to `src/core`, to `src/browser` from `src/vue`, or to `src/server` from
77
+ `src/bin` or `src/reporter` bundles a private copy of that environment into the face, so the vendored `.oxlintrc.json` refuses it with a message naming the alias.
71
78
 
72
79
  ## Configuration authority
73
80
 
@@ -76,7 +83,7 @@ private copy of that environment into the face, so the vendored `.oxlintrc.json`
76
83
  - `*/types.ts`: public API contracts.
77
84
  - `configs/agents/tsconfig.skills.json`: the scoped typecheck of the skill scripts; its presence selects the `skills` blueprint fact.
78
85
  - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
79
- `configs/src/*bin*` files. Shared logic remains in root configs.
86
+ `configs/src/*bin*` and `configs/src/*reporter*` files. Shared logic remains in root configs.
80
87
  - `configs/helpers.ts`, `configs/browsers.ts`, `configs/commands.ts`, and `configs/policy.ts`: the
81
88
  only permitted leaves under `configs/`. Each imports nothing from the workspace, which is what
82
89
  keeps it a leaf, so no `configs/types.ts` exists for one to import: each keeps its own types,
@@ -129,12 +136,16 @@ Environment rules:
129
136
  | `dist/src/styles/themes` | Compiled themes `index.css` | CSS |
130
137
  | `dist/src/<name>` | Compiled `index.css` | CSS |
131
138
  | `dist/bin` | Optional executable `main.js` | ES with shebang |
139
+ | `dist/reporter` | Vitest reporter + `main.d.ts` | ES |
132
140
  | `dist/app/browser` | Browser application | target-defined |
133
141
  | `dist/app/vue` | Vue application | target-defined |
134
142
  | `dist/app/server` | Server application | CJS runtime entry; ES barrel when `studies` is selected |
135
143
  | `showcase/<application>.html` | Single-file page per application | self-contained, committed |
136
144
 
137
145
  - Roll up each published TypeScript face's declarations in its Vite wrapper. A face that imports `@src/core` or `@src/browser` rewrites those specifiers to the published subpaths in its emitted declarations.
146
+ - Build the reporter entry ES only with `@src/*` external, rewritten through `output.paths` to
147
+ `../src/<environment>/index.js`, and roll up `dist/reporter/main.d.ts` with
148
+ `rewriteServerSpecifier` rewriting `@src/server` to `../src/server/index.js`.
138
149
  - A sheet face ships CSS, not declarations, and its JavaScript build stub stays out of `files`.
139
150
  - Build each sheet face with `cssMinify: false`, bounded to its own output directory.
140
151
  - Build `dist/src/styles/themes` after `dist/src/styles`; the themes build empties only its own directory.
@@ -148,19 +159,20 @@ Environment rules:
148
159
  `vite.config.ts` defines Vitest projects on an environment axis and a workspace-proof axis. The
149
160
  environment axis is one project per src/app axis × environment, plus one per extension face:
150
161
 
151
- | Project | Files | Environment | Setup |
152
- | ------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------ |
153
- | `src:core` | `tests/src/core/**` | Node | `setup.ts` |
154
- | `src:browser` | `tests/src/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
155
- | `src:vue` | `tests/src/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
156
- | `src:server` | `tests/src/server/**` | Node | `setup.ts`, `setupServer.ts` |
157
- | `src:styles` | `tests/src/styles/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
158
- | `src:<name>` | `tests/src/<name>/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
159
- | `src:bin` | `tests/src/bin/**` | Node | `setup.ts`, `setupServer.ts` |
160
- | `app:core` | `tests/app/core/**` | Node | `setup.ts` |
161
- | `app:browser` | `tests/app/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
162
- | `app:vue` | `tests/app/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
163
- | `app:server` | `tests/app/server/**` | Node | `setup.ts`, `setupServer.ts` |
162
+ | Project | Files | Environment | Setup |
163
+ | -------------- | ----------------------- | ------------------------------------- | ------------------------------------------------------------ |
164
+ | `src:core` | `tests/src/core/**` | Node | `setup.ts` |
165
+ | `src:browser` | `tests/src/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
166
+ | `src:vue` | `tests/src/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
167
+ | `src:server` | `tests/src/server/**` | Node | `setup.ts`, `setupServer.ts` |
168
+ | `src:styles` | `tests/src/styles/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
169
+ | `src:<name>` | `tests/src/<name>/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
170
+ | `src:bin` | `tests/src/bin/**` | Node | `setup.ts`, `setupServer.ts` |
171
+ | `src:reporter` | `tests/src/reporter/**` | Node | `setup.ts`, `setupServer.ts` |
172
+ | `app:core` | `tests/app/core/**` | Node | `setup.ts` |
173
+ | `app:browser` | `tests/app/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
174
+ | `app:vue` | `tests/app/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
175
+ | `app:server` | `tests/app/server/**` | Node | `setup.ts`, `setupServer.ts` |
164
176
 
165
177
  - Compose every sheet-face project (`src:styles` and each `src:<name>`) in its own wrapper through
166
178
  the one root `sheetProject` factory, and run it through its `test:src:<face>` script, which builds
@@ -273,8 +285,8 @@ then runs the configured scoped checks that prove environment isolation.
273
285
 
274
286
  - Use plain `tsc` for a TypeScript-only tree.
275
287
  - Use `vue-tsc` only for a scope containing `.vue` internals.
276
- - `check:src` mirrors configured `src:*` test projects; optional `src:bin` is its
277
- own scope.
288
+ - `check:src` mirrors configured `src:*` test projects; optional `src:bin` and `src:reporter`
289
+ are each their own scope.
278
290
  - `check:app` mirrors configured `app:*` projects.
279
291
  - `check:skills` typechecks `.agents/skills/*/scripts/*.ts` through `configs/agents/tsconfig.skills.json` wherever that wrapper is present: the root project's wildcard never enters a dot-prefixed directory, so the scripts need their own scope.
280
292
  - The `build:skills` script emits a `.js` twin of every `.agents/skills/*/scripts/*.ts` script into the `dist/agents/skills/` tree through the same wrapper, rewrites each relative import to `.js`, and copies `.agents/templates/brief.md` into the `dist/agents/templates/` directory; the `build` chain runs it after `build:host`, and `dist/agents` ships in the package.
@@ -19,14 +19,18 @@ import {
19
19
  rmSync,
20
20
  writeFileSync,
21
21
  } from 'node:fs'
22
- import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from 'node:path'
22
+ import {
23
+ basename,
24
+ dirname,
25
+ isAbsolute,
26
+ join,
27
+ relative,
28
+ resolve as resolvePath,
29
+ sep,
30
+ } from 'node:path'
23
31
 
24
32
  export function hasASCIIURLControl(value: string): boolean {
25
- for (const character of value) {
26
- const code = character.codePointAt(0)
27
- if (code !== undefined && (code <= 0x1f || code === 0x7f)) return true
28
- }
29
- return false
33
+ return /[\p{Cc}--[\u0080-\u009f]]/v.test(value)
30
34
  }
31
35
 
32
36
  /**
@@ -372,7 +376,7 @@ export function findPackageDirectory(current: string): string | undefined {
372
376
  export function packageRootOf(packageName: string, resolvedPath: string): string | undefined {
373
377
  const physical = physicalPath(resolvedPath)
374
378
  const directory = findPackageDirectory(
375
- existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical),
379
+ lstatSync(physical, { throwIfNoEntry: false })?.isDirectory() ? physical : dirname(physical),
376
380
  )
377
381
  return directory !== undefined && packageManifestName(directory) === packageName
378
382
  ? realpathSync.native(directory)
@@ -382,7 +386,7 @@ export function packageRootOf(packageName: string, resolvedPath: string): string
382
386
  export function packageRootForResolved(resolvedPath: string): string | undefined {
383
387
  const physical = physicalPath(resolvedPath)
384
388
  const directory = findPackageDirectory(
385
- existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical),
389
+ lstatSync(physical, { throwIfNoEntry: false })?.isDirectory() ? physical : dirname(physical),
386
390
  )
387
391
  return directory !== undefined && packageManifestName(directory) !== undefined
388
392
  ? realpathSync.native(directory)
@@ -873,6 +877,26 @@ export function rewriteBrowserSpecifier(content: string): string {
873
877
  .replaceAll('@src/browser', `${name}/browser`)
874
878
  }
875
879
 
880
+ /**
881
+ * Rewrites every server alias in a roll-up to the built server entry beside the reporter output.
882
+ *
883
+ * @param content - The finished roll-up.
884
+ * @returns That roll-up with each `@src/server` specifier replaced by `../src/server/index.js`.
885
+ *
886
+ * @remarks
887
+ * The reporter entry reaches the server class through the `@src/server` alias, and the extractor
888
+ * keeps it external and writes it through unchanged. `dist/reporter/main.d.ts` resolves the server
889
+ * declarations at the same relative path its `main.js` imports through `output.paths`.
890
+ *
891
+ * @example
892
+ * ```ts
893
+ * rewriteServerSpecifier("from '@src/server'") // "from '../src/server/index.js'"
894
+ * ```
895
+ */
896
+ export function rewriteServerSpecifier(content: string): string {
897
+ return content.replaceAll('@src/server', '../src/server/index.js')
898
+ }
899
+
876
900
  /**
877
901
  * Rolls one published face's declarations into the single file that face ships.
878
902
  *
@@ -883,12 +907,13 @@ export function rewriteBrowserSpecifier(content: string): string {
883
907
  * At `closeBundle`, after Vite has written every format of the face, the plugin emits the face's
884
908
  * declarations with the workspace compiler run as a process into a scratch directory made fresh
885
909
  * under the host temporary directory, hands the emitted entry to the extractor's own engine,
886
- * applies `rewrite`, and removes the scratch directory. Keeping the scratch outside the face's own
887
- * output means its unconditional removal can never take a sibling the face already published, such
888
- * as its own `declarations` folder. The extractor is a publishing workspace's development
889
- * dependency, so this vendored leaf defers loading it to that hook: a workspace that publishes no
890
- * library installs no extractor, never reaches the hook, and never resolves the package at build
891
- * or at check.
910
+ * applies `rewrite`, and removes the scratch directory. The roll-up takes the entry's own name, so
911
+ * an `index.ts` face ships `index.d.ts` and a `main.ts` entry ships `main.d.ts`. Keeping the
912
+ * scratch outside the face's own output means its unconditional removal can never take a sibling
913
+ * the face already published, such as its own `declarations` folder. The extractor is a publishing
914
+ * workspace's development dependency, so this vendored leaf defers loading it to that hook: a
915
+ * workspace that publishes no library installs no extractor, never reaches the hook, and never
916
+ * resolves the package at build or at check.
892
917
  */
893
918
  export function declarationRollup(options: DeclarationRollupOptions): Plugin {
894
919
  const state = new BuildState()
@@ -917,7 +942,7 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
917
942
  )
918
943
  }
919
944
  const scratch = mkdtempSync(join(tmpdir(), 'orkestrel-declarations-'))
920
- const rollup = resolvePath(state.output, 'index.d.ts')
945
+ const rollup = resolvePath(state.output, basename(declaration))
921
946
  try {
922
947
  readCompilerOutput(compiler, [
923
948
  '-p',
@@ -88,6 +88,12 @@
88
88
  "import/no-default-export": "off"
89
89
  }
90
90
  },
91
+ {
92
+ "files": ["src/reporter/main.ts"],
93
+ "rules": {
94
+ "import/no-default-export": "off"
95
+ }
96
+ },
91
97
  {
92
98
  "files": [".agents/skills/*/scripts/*.ts"],
93
99
  "rules": {
@@ -773,6 +779,62 @@
773
779
  ]
774
780
  }
775
781
  },
782
+ {
783
+ "files": ["src/reporter/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}"],
784
+ "rules": {
785
+ "no-restricted-imports": [
786
+ "error",
787
+ {
788
+ "patterns": [
789
+ {
790
+ "regex": "^(?:/|[A-Za-z]:[\\\\/])",
791
+ "message": "imports must not use machine-specific absolute paths"
792
+ },
793
+ {
794
+ "regex": "^(?:[A-Za-mo-z][A-Za-z0-9+.-]*|n(?:[A-Za-np-z0-9+.-][A-Za-z0-9+.-]*)?|no(?:[A-Za-ce-z0-9+.-][A-Za-z0-9+.-]*)?|nod(?:[A-Za-df-z0-9+.-][A-Za-z0-9+.-]*)?|node[A-Za-z0-9+.-]+):",
795
+ "message": "imports must not use non-Node URL schemes"
796
+ },
797
+ {
798
+ "regex": "(?:^|/)(?:[^/.][^/]*|\\.[^/.][^/]*|\\.\\.[^/]+)/\\.{1,2}(?:/|$)",
799
+ "message": "internal import paths must not contain noncanonical dot segments"
800
+ },
801
+ {
802
+ "regex": "^(?:(?:\\./)+\\.\\.(?:/|$)|(?:\\.\\./)+(?:\\./)+)|//",
803
+ "message": "relative import paths must not contain normalized traversal segments"
804
+ },
805
+ {
806
+ "regex": "\\\\",
807
+ "message": "import paths must use portable forward slashes"
808
+ },
809
+ {
810
+ "regex": "^typescript(?:[/?#]|$)",
811
+ "message": "the in-process compiler API is not a surface the fleet uses"
812
+ },
813
+ {
814
+ "regex": "\\.(?:css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:[?#]|$)",
815
+ "message": "src/reporter must not import browser stylesheets"
816
+ },
817
+ {
818
+ "regex": "^(?:@app(?:[/?#]|$)|(?:\\.\\./)+app(?:[/?#]|$))",
819
+ "message": "src/reporter must not depend on private app modules"
820
+ },
821
+ {
822
+ "regex": "^(?:(?:vue|vite)(?:[/?#]|$)|@(?:vue|vitejs)/|@src/(?:browser|vue)(?:[/?#]|$)|@orkestrel/[^/]+/(?:browser|vue)(?:[/?#]|$)|(?:\\.\\./)+(?:browser|vue|src/(?:browser|vue)|app/browser)(?:[/?#]|$))",
823
+ "message": "src/reporter must not depend on browser-only modules"
824
+ },
825
+ {
826
+ "regex": "^(?:\\.\\./)+(?:src/)?core(?:[/?#]|$)",
827
+ "message": "src/reporter must import src/core through the @src/core alias"
828
+ },
829
+ {
830
+ "regex": "^(?:\\.\\./)+(?:src/)?server(?:[/?#]|$)",
831
+ "message": "src/reporter must import src/server through the @src/server alias"
832
+ }
833
+ ]
834
+ }
835
+ ]
836
+ }
837
+ },
776
838
  {
777
839
  "files": [
778
840
  "tests/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}",
@@ -229,7 +229,7 @@ The browser entry publishes the controlled native form and its host readers.
229
229
  | `FormControl` | type | `HTMLInputElement \| HTMLSelectElement \| HTMLTextAreaElement` | Represents a native answer control admitted by the binding. |
230
230
  | `FormBindingErrorCode` | type | `'CONTROL' \| 'PENDING' \| 'DOM'` | Names a native binding refusal. |
231
231
  | `FormBindingEventMap` | type | `{ readonly render: readonly []; readonly write: readonly [control: FormControl]; readonly submit: readonly [submission: FormSubmission, submitter: HTMLElement \| undefined]; readonly error: readonly [error: unknown]; }` | Lists the native binding's notifications after their associated DOM effects. |
232
- | `FormBindingOptions` | interface | `{ feedback?, summary?, presentations?, defer?, on?, error? }` | Configures neutral feedback destinations and isolated event listeners. |
232
+ | `FormBindingOptions` | interface | `{ feedback?, summary?, presentations?, defer?, reveal?, on?, error? }` | Configures neutral feedback destinations and isolated event listeners. |
233
233
  | `FormBindingInterface` | interface | `{ element, document, destroyed, emitter, read(), refresh(), destroy() }` | Declares a native form's borrowed document and synchronization lifecycle. |
234
234
  | `FormBindingAttribute` | interface | `{ original, value }` | Records an attribute's authored value and the binding's last contribution. |
235
235
  | `FormBindingValidity` | interface | `{ original, value }` | Records the binding's custom-validity contribution beside the authored message. |
@@ -239,6 +239,7 @@ The browser entry publishes the controlled native form and its host readers.
239
239
  | `isFormBindingError` | function | `(value: unknown) => value is FormBindingError` | Checks whether a value is a native binding refusal. |
240
240
  | `isFormControl` | function | `(value: unknown) => value is FormControl` | Checks whether a value is a native answer control. |
241
241
  | `matchesFormControls` | function | `(field: FormField, controls: readonly FormControl[]) => boolean` | Checks a native control population against a field's declared value shape. |
242
+ | `matchesNativeNumber` | function | `(control: FormControl, value: FieldValue \| undefined) => boolean` | Checks whether a numeric control's own text already parses to the document's number. |
242
243
  | `readNativeMessages` | function | `(control: FormControl, errors: readonly FieldError[]) => readonly string[]` | Reads native constraint messages not already reported by document rules. |
243
244
  | `readFormControls` | function | `(field: FormField, controls: readonly FormControl[]) => FieldValue \| undefined` | Reads one compatible native population using the document's blank-to-absence semantics. |
244
245
 
@@ -261,6 +262,18 @@ readFormControls({ control: 'text', name: 'name' }, [input]) // 'Ada'
261
262
  isFormBindingError(new FormBindingError('CONTROL', 'Duplicate controls')) // true
262
263
  ```
263
264
 
265
+ The projection keeps a number input's own text while it parses to the document's number.
266
+
267
+ ```ts
268
+ import { matchesNativeNumber } from '@orkestrel/form/browser'
269
+
270
+ const price = document.createElement('input')
271
+ price.type = 'number'
272
+ price.value = '1.50'
273
+ matchesNativeNumber(price, 1.5) // true — the binding leaves '1.50' in place
274
+ matchesNativeNumber(price, 1.25) // false — the binding writes '1.25'
275
+ ```
276
+
264
277
  ## Controls
265
278
 
266
279
  Each control fixes both the options its field accepts and the `FieldValue` it holds. The `confirm`,
@@ -1254,6 +1267,18 @@ the failure lasts until that field is filled again or the form is cleared.
1254
1267
  captured enabled fields to their submitted values or absence. It is what `dirty` measures against
1255
1268
  and what `clear` returns to. Read `extractChanges(form.values, form.baseline)` for the changed names.
1256
1269
 
1270
+ An empty list and absence are equal in change extraction, in either direction. A list field that
1271
+ opens with no baseline answer and is read back empty therefore stays clean, so `dirty` stays false
1272
+ until an entry arrives. Every other answer, the empty string included, differs from absence.
1273
+
1274
+ ```ts
1275
+ import { extractChanges } from '@orkestrel/form'
1276
+
1277
+ Array.from(extractChanges({ to: [] }, {})) // [] — an empty list matches an absent baseline
1278
+ Array.from(extractChanges({ to: ['ada@example.com'] }, {})) // ['to']
1279
+ Array.from(extractChanges({ subject: '' }, {})) // ['subject']
1280
+ ```
1281
+
1257
1282
  `clear` returns every answer to `baseline`. It also clears `touched`, every external failure, and
1258
1283
  every runtime `disable` or `enable`. Pending acknowledgement is aborted; the disabled state returns
1259
1284
  to the schema's declarations and the answers return to the acknowledged baseline.
@@ -1584,6 +1609,27 @@ without reachable controls remain text. An invalid submission focuses the first
1584
1609
  control. The binding never invokes a native validity popup. A `render` event follows DOM effects,
1585
1610
  including effects triggered by core changes, so a presentation adapter can apply its own classes.
1586
1611
 
1612
+ ### Reveal a refused field
1613
+
1614
+ An invalid submission focuses only a control a person can reach. A field whose control sits on
1615
+ another page, behind a search, or in a hidden pane has none. Supply `reveal` to bring that field
1616
+ into the document. A refused field a person can already reach takes focus first, and the hook does
1617
+ not run. When none is reachable, the binding calls the hook with each refused field's name in order,
1618
+ rediscovers controls after each call, and focuses the first field the hook made reachable. The hook
1619
+ returns nothing and the binding awaits nothing; a host whose reveal finishes later focuses the
1620
+ field itself. A throw reaches the binding's `error` event and focuses nothing.
1621
+
1622
+ ```ts
1623
+ import { createFormBinding } from '@orkestrel/form/browser'
1624
+
1625
+ const binding = createFormBinding(element, model, {
1626
+ reveal: (name) => {
1627
+ search.clear()
1628
+ pager.show(name)
1629
+ },
1630
+ })
1631
+ ```
1632
+
1587
1633
  Native and document validation remain distinct sources. A named rule's message replaces feedback
1588
1634
  for that native constraint. Required, bounds, length, step, pattern, email, and URL failures match
1589
1635
  by rule identity, never localized text. A lone uncovered failure keeps the platform's message.
@@ -1668,9 +1714,16 @@ workaround and the scalar comma-splitting validator for recipient arrays.
1668
1714
 
1669
1715
  Set `defer: true` to hold blur-triggered touch while a primary pointer press on an enabled button
1670
1716
  associated with this form is active. This includes externally associated buttons and presses on
1671
- their descendants. Touch resumes in a task after pointer release or cancellation, leaving the click
1672
- sequence free of blur feedback that moves the button. Keyboard blur remains immediate; input reads
1673
- and submission validation remain immediate. Reset and destruction discard deferred touch.
1717
+ their descendants. Touch resumes in a task after the press's click, after cancellation, or after a
1718
+ release away from the button, leaving the click sequence free of blur feedback that moves the
1719
+ button. Keyboard blur remains immediate; input reads and submission validation remain immediate.
1720
+ Reset and destruction discard deferred touch.
1721
+
1722
+ A release on the button whose click never reaches the binding keeps the touch pending: a click a
1723
+ listener prevented, or one a listener stopped. The touch then waits for a reset, which discards it, or for the next focus change, which applies it.
1724
+ A later press on a form button carries the pending touch and decides it by its own click. A
1725
+ confirmation gate that holds its first press back therefore keeps the field's feedback still while
1726
+ it is armed, and the confirming press resets the form with nothing shown.
1674
1727
 
1675
1728
  Enable deferral where feedback can move an action under the pointer.
1676
1729
 
@@ -1680,6 +1733,25 @@ import { createFormBinding } from '@orkestrel/form/browser'
1680
1733
  const binding = createFormBinding(element, model, { defer: true })
1681
1734
  ```
1682
1735
 
1736
+ For a reset button behind a confirmation gate, let the gate hold the arming click back. The field
1737
+ stays untouched until the confirming click resets the form or focus moves on.
1738
+
1739
+ ```ts
1740
+ import { createFormBinding } from '@orkestrel/form/browser'
1741
+
1742
+ const binding = createFormBinding(element, model, { defer: true })
1743
+ window.addEventListener(
1744
+ 'click',
1745
+ (event) => {
1746
+ if (!event.composedPath().includes(discard) || gate.armed) return
1747
+ event.preventDefault()
1748
+ event.stopImmediatePropagation()
1749
+ gate.arm()
1750
+ },
1751
+ { capture: true },
1752
+ )
1753
+ ```
1754
+
1683
1755
  ### Native capability boundaries
1684
1756
 
1685
1757
  The browser admits text, search, email, URL, telephone, hidden, password, textarea, number, range,
@@ -1687,6 +1759,9 @@ date, time, datetime-local, color, confirm, radio, single select, multiple selec
1687
1759
  and file inputs. Blank strings become absence through the core's answer predicate; false, zero, and
1688
1760
  empty lists remain answers. A password field accepts both `password` and `text` inputs, so a reveal
1689
1761
  toggle retains discovery, validation, and summary links without mirroring the value.
1762
+ A number or range input whose own text parses to the document's number keeps that text, so a typed
1763
+ `1.50` survives every projection of `1.5`, and a different number rewrites it. The comparison reads
1764
+ the input's own locale-independent value with the document's equality, and blank text never matches.
1690
1765
  Numeric bad input remains a native error and never becomes NaN or a
1691
1766
  valid absent answer. Explicit refresh discards that unreadable native text and repaints the document's
1692
1767
  answer; ordinary input, touch, and submit keep the text available for correction. Native constraints