@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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
- package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
- package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
- package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
- package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
- package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
- package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
- package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
- package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
- package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
- package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
- package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1018 -194
- package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
- package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +95 -108
- package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
- package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
- package/dist/bin/main.js +27 -3
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
- package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
- package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
- package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
- package/dist/host/claude/agents/orkestrel.md +4 -4
- package/dist/host/claude/rules/documentation.md +1 -1
- package/dist/host/claude/rules/patterns.md +5 -4
- package/dist/host/claude/rules/styles.md +1 -1
- package/dist/host/claude/rules/tests.md +3 -3
- package/dist/host/claude/rules/workspace.md +47 -35
- package/dist/host/configs/helpers.ts +40 -15
- package/dist/host/dotfiles/oxlintrc.json +62 -0
- package/dist/host/guides/form.md +79 -4
- package/dist/host/guides/scaffold.md +93 -65
- package/dist/host/guides/table.md +20 -6
- package/dist/host/guides/test.md +9 -7
- package/dist/host/manifest.json +44 -44
- package/dist/host/tests/config.test.ts +201 -11
- package/dist/host/tests/policy.test.ts +14 -21
- package/dist/host/tests/setupPolicy.ts +43 -36
- package/dist/src/core/index.cjs +191 -93
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +27 -13
- package/dist/src/core/index.d.ts +27 -13
- package/dist/src/core/index.js +189 -93
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +8 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +1 -1
- package/dist/src/server/index.d.ts +1 -1
- package/dist/src/server/index.js +8 -9
- package/dist/src/server/index.js.map +1 -1
- 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
|
|
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.
|
|
17
|
-
2.
|
|
18
|
-
3.
|
|
19
|
-
4.
|
|
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,
|
|
213
|
-
in its browser variant also `playwright`, `@vitest/browser-playwright`,
|
|
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
|
|
20
|
-
|
|
|
21
|
-
| `src/core/`
|
|
22
|
-
| `src/browser/`
|
|
23
|
-
| `src/server/`
|
|
24
|
-
| `src/styles/`
|
|
25
|
-
| `src/<name>/`
|
|
26
|
-
| `src/vue/`
|
|
27
|
-
| `src/bin/`
|
|
28
|
-
| `
|
|
29
|
-
| `app/
|
|
30
|
-
| `app/
|
|
31
|
-
| `app/
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
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`,
|
|
69
|
-
relative path to `src/core`, to `src/browser` from `src/vue`, or to `src/server` from
|
|
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
|
|
152
|
-
|
|
|
153
|
-
| `src:core`
|
|
154
|
-
| `src:browser`
|
|
155
|
-
| `src:vue`
|
|
156
|
-
| `src:server`
|
|
157
|
-
| `src:styles`
|
|
158
|
-
| `src:<name>`
|
|
159
|
-
| `src:bin`
|
|
160
|
-
| `
|
|
161
|
-
| `app:
|
|
162
|
-
| `app:
|
|
163
|
-
| `app:
|
|
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`
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
887
|
-
*
|
|
888
|
-
*
|
|
889
|
-
*
|
|
890
|
-
*
|
|
891
|
-
*
|
|
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,
|
|
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}",
|
package/dist/host/guides/form.md
CHANGED
|
@@ -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? }`
|
|
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
|
|
1672
|
-
sequence free of blur feedback that moves the
|
|
1673
|
-
|
|
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
|