@orkestrel/scaffold 0.0.134 → 0.0.135
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
- package/dist/bin/main.js +253 -35
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
- package/dist/host/claude/agents/orkestrel.md +14 -14
- package/dist/host/claude/rules/architecture.md +1 -1
- package/dist/host/claude/rules/patterns.md +2 -0
- package/dist/host/claude/rules/workspace.md +64 -63
- package/dist/host/configs/helpers.ts +88 -67
- package/dist/host/dotfiles/oxlintrc.json +1 -57
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/database.md +357 -342
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/scaffold.md +177 -105
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/test.md +158 -46
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +23 -23
- package/dist/host/tests/config.test.ts +166 -112
- package/dist/src/core/index.cjs +491 -195
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +217 -24
- package/dist/src/core/index.d.ts +217 -24
- package/dist/src/core/index.js +482 -193
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +18 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +4 -3
- package/dist/src/server/index.d.ts +4 -3
- package/dist/src/server/index.js +19 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -44,7 +44,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
44
44
|
| Package | Version | Layer | Runtime dependencies | Peer dependencies |
|
|
45
45
|
| ----------------------- | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
46
46
|
| `@orkestrel/abort` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
47
|
-
| `@orkestrel/agent` | `0.0.
|
|
47
|
+
| `@orkestrel/agent` | `0.0.44` | L5 | `@orkestrel/tool` `^0.0.23`, `@orkestrel/abort` `^0.0.17`, `@orkestrel/queue` `^0.0.23`, `@orkestrel/budget` `^0.0.18`, `@orkestrel/ndjson` `^0.0.17`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24`, `@orkestrel/workflow` `^0.0.29`, `@orkestrel/workspace` `^0.0.19` | |
|
|
48
48
|
| `@orkestrel/brief` | `0.0.18` | L4 | `@orkestrel/reason` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/interpret` `^0.0.23` | |
|
|
49
49
|
| `@orkestrel/browser` | `0.0.33` | L5 | `@orkestrel/mcp` `^0.0.43`, `@orkestrel/html` `^0.0.16`, `@orkestrel/pool` `^0.0.21`, `@orkestrel/tool` `^0.0.23`, `@orkestrel/codec` `^0.0.10`, `@orkestrel/router` `^0.0.21`, `@orkestrel/server` `^0.0.27`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/markdown` `^0.0.21`, `@orkestrel/websocket` `^0.0.19` | |
|
|
50
50
|
| `@orkestrel/budget` | `0.0.18` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
@@ -53,7 +53,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
53
53
|
| `@orkestrel/console` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
54
54
|
| `@orkestrel/contract` | `0.0.23` | L0 | | |
|
|
55
55
|
| `@orkestrel/csv` | `0.0.14` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
|
|
56
|
-
| `@orkestrel/database` | `0.0.
|
|
56
|
+
| `@orkestrel/database` | `0.0.24` | L2 | `@orkestrel/sqlite` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/indexeddb` `^0.0.18` | |
|
|
57
57
|
| `@orkestrel/emitter` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
58
58
|
| `@orkestrel/form` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
59
59
|
| `@orkestrel/guide` | `0.0.31` | L3 | `@orkestrel/contract` `^0.0.23`, `@orkestrel/markdown` `^0.0.21` | |
|
|
@@ -64,37 +64,37 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
64
64
|
| `@orkestrel/lsp` | `0.0.15` | L3 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/jsonrpc` `^0.0.3`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23` | |
|
|
65
65
|
| `@orkestrel/markdown` | `0.0.21` | L2 | `@orkestrel/html` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
66
66
|
| `@orkestrel/mcp` | `0.0.43` | L4 | `@orkestrel/sse` `^0.0.14`, `@orkestrel/tool` `^0.0.23`, `@orkestrel/codec` `^0.0.10`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/jsonrpc` `^0.0.3`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/websocket` `^0.0.19` | `@orkestrel/router` `^0.0.21`, `@orkestrel/server` `^0.0.27` |
|
|
67
|
-
| `@orkestrel/middleware` | `0.0.
|
|
67
|
+
| `@orkestrel/middleware` | `0.0.32` | L4 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/budget` `^0.0.18`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23` | `@orkestrel/server` `^0.0.27`, `@orkestrel/database` `^0.0.24` |
|
|
68
68
|
| `@orkestrel/msg` | `0.0.17` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
|
|
69
69
|
| `@orkestrel/ndjson` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
70
|
-
| `@orkestrel/ollama` | `0.0.
|
|
70
|
+
| `@orkestrel/ollama` | `0.0.38` | L6 | `@orkestrel/tool` `^0.0.23`, `@orkestrel/agent` `^0.0.44`, `@orkestrel/budget` `^0.0.18`, `@orkestrel/ndjson` `^0.0.17`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23` | |
|
|
71
71
|
| `@orkestrel/pool` | `0.0.21` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
72
72
|
| `@orkestrel/probe` | `0.0.30` | L5 | `@orkestrel/lsp` `^0.0.15`, `@orkestrel/mcp` `^0.0.43`, `@orkestrel/pool` `^0.0.21`, `@orkestrel/tool` `^0.0.23`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/process` `^0.0.19`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23` | `vitest` `^4.1.12 \|\| ^5.1.0`, `typescript` `^6.0.3 \|\| ^7.0.2` |
|
|
73
73
|
| `@orkestrel/process` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
74
74
|
| `@orkestrel/program` | `0.0.21` | L4 | `@orkestrel/rater` `^0.0.22`, `@orkestrel/reason` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/qualifier` `^0.0.22` | |
|
|
75
75
|
| `@orkestrel/qualifier` | `0.0.22` | L3 | `@orkestrel/reason` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
76
|
-
| `@orkestrel/queue` | `0.0.
|
|
76
|
+
| `@orkestrel/queue` | `0.0.23` | L3 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
77
77
|
| `@orkestrel/rater` | `0.0.22` | L3 | `@orkestrel/reason` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
78
78
|
| `@orkestrel/reason` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
79
|
-
| `@orkestrel/relation` | `0.0.
|
|
79
|
+
| `@orkestrel/relation` | `0.0.22` | L3 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
80
80
|
| `@orkestrel/router` | `0.0.21` | L2 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
81
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
81
|
+
| `@orkestrel/scaffold` | `0.0.134` | L3 | `@orkestrel/console` `^0.0.20`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/markdown` `^0.0.21`, `@orkestrel/template` `^0.0.14` | |
|
|
82
82
|
| `@orkestrel/sea` | `0.0.23` | L3 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/process` `^0.0.19`, `@orkestrel/contract` `^0.0.23` | |
|
|
83
83
|
| `@orkestrel/server` | `0.0.27` | L3 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/codec` `^0.0.10`, `@orkestrel/router` `^0.0.21`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23` | |
|
|
84
84
|
| `@orkestrel/sqlite` | `0.0.18` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
85
85
|
| `@orkestrel/sse` | `0.0.14` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
|
|
86
|
-
| `@orkestrel/study` | `0.0.
|
|
86
|
+
| `@orkestrel/study` | `0.0.20` | L7 | `@orkestrel/tool` `^0.0.23`, `@orkestrel/abort` `^0.0.17`, `@orkestrel/agent` `^0.0.44`, `@orkestrel/budget` `^0.0.18`, `@orkestrel/ollama` `^0.0.38`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23` | |
|
|
87
87
|
| `@orkestrel/table` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
88
88
|
| `@orkestrel/template` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
89
|
-
| `@orkestrel/terminal` | `0.0.
|
|
90
|
-
| `@orkestrel/test` | `0.0.
|
|
89
|
+
| `@orkestrel/terminal` | `0.0.26` | L3 | `@orkestrel/sse` `^0.0.14`, `@orkestrel/form` `^0.0.18`, `@orkestrel/console` `^0.0.20`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
90
|
+
| `@orkestrel/test` | `0.0.38` | L1 | `@orkestrel/contract` `^0.0.23` | `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.65.0` |
|
|
91
91
|
| `@orkestrel/timeout` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
|
|
92
92
|
| `@orkestrel/tool` | `0.0.23` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
93
|
-
| `@orkestrel/toolbox` | `0.0.
|
|
93
|
+
| `@orkestrel/toolbox` | `0.0.33` | L6 | `@orkestrel/form` `^0.0.18`, `@orkestrel/tool` `^0.0.23`, `@orkestrel/agent` `^0.0.44`, `@orkestrel/server` `^0.0.27`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24`, `@orkestrel/relation` `^0.0.22`, `@orkestrel/terminal` `^0.0.26`, `@orkestrel/workflow` `^0.0.29`, `@orkestrel/workspace` `^0.0.19` | |
|
|
94
94
|
| `@orkestrel/websocket` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
|
|
95
|
-
| `@orkestrel/worker` | `0.0.
|
|
96
|
-
| `@orkestrel/workflow` | `0.0.
|
|
97
|
-
| `@orkestrel/workspace` | `0.0.
|
|
95
|
+
| `@orkestrel/worker` | `0.0.23` | L4 | `@orkestrel/pool` `^0.0.21`, `@orkestrel/queue` `^0.0.23`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
96
|
+
| `@orkestrel/workflow` | `0.0.29` | L4 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/queue` `^0.0.23`, `@orkestrel/budget` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/timeout` `^0.0.17`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
97
|
+
| `@orkestrel/workspace` | `0.0.19` | L3 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/database` `^0.0.24` | |
|
|
98
98
|
|
|
99
99
|
<!-- /orkestrel:catalog -->
|
|
100
100
|
|
|
@@ -304,7 +304,7 @@ export * from './greeters/Greeter.js'
|
|
|
304
304
|
|
|
305
305
|
`AGENTS.md` § Design laws owns the minimal-API, shim, polling, and product-policy laws. This section adds:
|
|
306
306
|
|
|
307
|
-
- For multiple backends,
|
|
307
|
+
- For multiple backends, have each backend answer every part of an operation its engine performs natively, such as filtering, ordering, paging, counting, aggregating, and transactions. Implement one shared engine over the smallest primitives, and run it only over the part a backend's engine cannot answer, for that backend alone. Never run the shared engine where a native path exists.
|
|
308
308
|
- Centralize any pattern repeated twice.
|
|
309
309
|
- Keep everything generic/reusable and free of unrelated-project logic.
|
|
310
310
|
- Mechanism in a framework or server utility means HMAC, CORS, parsing, sessions, cookies, CSRF, and static serving; product policy means user models, login flow, and authorization.
|
|
@@ -145,6 +145,8 @@ Use these orthogonal contract mechanisms:
|
|
|
145
145
|
- Declare a parser's whole admitted language and its adjacent refusals, and prove them with a table of the class; never tune the parser example by example. On a parser change, run a seeded differential against its parent build, and read a passing suite as no evidence of what the change moved.
|
|
146
146
|
- Derive a decision from validated inputs; an editable prior result never substitutes for them.
|
|
147
147
|
- Project a value outward by its authorship and trust origin, and accept no authority channel from a client.
|
|
148
|
+
- When a handler acts on a resource a run selects, take the resource from the execution context that run supplies, accept it only as the instance the handler's own registry holds, and never read a pointer other runs share.
|
|
149
|
+
- When a list bounds what a run reads from a resource, hold every handler that reaches that resource to the same list at the call: refuse a member outside it with one text whether or not it exists, and pass the list into any operation that walks the resource.
|
|
148
150
|
|
|
149
151
|
### Foreign contracts
|
|
150
152
|
|
|
@@ -16,37 +16,40 @@ 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
|
-
| `
|
|
34
|
-
| `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` and host-tool modules; never a 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 |
|
|
35
34
|
|
|
36
35
|
- 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.
|
|
37
36
|
- Typical browser-app domains: `components/`, `pages/`, `composables/`, `controllers/`, `services/`, `stores/`.
|
|
38
37
|
- Typical server-app domains: `handlers.ts`, `middlewares.ts`, `routes.ts`.
|
|
39
38
|
- 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.
|
|
40
|
-
- Name a styles extension with a name the `NAME_PATTERN` constant admits, and never `core`, `browser`, `server`, `bin`, `
|
|
41
|
-
- `src/bin/main.ts` is the executable entry, built to `dist/bin/main.js
|
|
42
|
-
is for `app/browser/main.ts` and
|
|
43
|
-
found at the same name.
|
|
44
|
-
- `src/
|
|
45
|
-
`
|
|
46
|
-
|
|
39
|
+
- Name a styles extension with a name the `NAME_PATTERN` constant admits, and never `core`, `browser`, `server`, `bin`, `styles`, `themes`, or `vue`.
|
|
40
|
+
- `src/bin/main.ts` is the executable entry, built to `dist/bin/main.js` and published through the
|
|
41
|
+
manifest's `bin` field. The name is fixed, as it is for `app/browser/main.ts` and
|
|
42
|
+
`app/server/main.ts`, so every runtime entry in a workspace is found at the same name.
|
|
43
|
+
- Every other direct `src/bin/<name>.ts` whose stem `BIN_MODULE_PATTERN` admits and
|
|
44
|
+
`CENTRAL_FILE_NAMES` does not name is a module for a host tool that loads it by specifier and
|
|
45
|
+
reads its default export, as Vitest reads a reporter. It builds through the same bin build to the
|
|
46
|
+
ES-only `dist/bin/<name>.js` and its `dist/bin/<name>.d.ts`, and publishes as
|
|
47
|
+
`exports["./<name>"]`. Its body is two statements: an import of the value it publishes from a
|
|
48
|
+
library environment through that environment's alias, then `export default` of that value. That
|
|
47
49
|
body is the one exception to `.claude/rules/architecture.md` § Barrel exports, and the vendored
|
|
48
|
-
`.oxlintrc.json`
|
|
49
|
-
|
|
50
|
+
`.oxlintrc.json` admits a default export in `src/bin/*.ts`. Keep the value in its environment,
|
|
51
|
+
exported by name through that environment's barrel. Never name a module for a subpath another
|
|
52
|
+
face publishes; the blueprint gate refuses it and names both.
|
|
50
53
|
- `package.json`'s `bin` key is the installed command name. The entry path is the value and does
|
|
51
54
|
not carry that name.
|
|
52
55
|
- Keep every ignored output at the workspace root or under `tmp/`, and write no `.gitignore`
|
|
@@ -72,9 +75,9 @@ Use only the environments a project needs, and keep the root dependency model in
|
|
|
72
75
|
|
|
73
76
|
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.
|
|
74
77
|
|
|
75
|
-
Import a sibling environment through its alias. In `src/browser`, `src/server`, `src/vue`, `src/bin`,
|
|
76
|
-
|
|
77
|
-
|
|
78
|
+
Import a sibling environment through its alias. In `src/browser`, `src/server`, `src/vue`, and `src/bin`,
|
|
79
|
+
a relative path to `src/core`, to `src/browser` from `src/vue`, or to `src/server` from `src/bin`
|
|
80
|
+
bundles a private copy of that environment into the face, so the vendored `.oxlintrc.json` refuses it with a message naming the alias.
|
|
78
81
|
|
|
79
82
|
## Configuration authority
|
|
80
83
|
|
|
@@ -83,7 +86,7 @@ Import a sibling environment through its alias. In `src/browser`, `src/server`,
|
|
|
83
86
|
- `*/types.ts`: public API contracts.
|
|
84
87
|
- `configs/agents/tsconfig.skills.json`: the scoped typecheck of the skill scripts; its presence selects the `skills` blueprint fact.
|
|
85
88
|
- `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
|
|
86
|
-
`configs/src/*bin*`
|
|
89
|
+
`configs/src/*bin*` files. Shared logic remains in root configs.
|
|
87
90
|
- `configs/helpers.ts`, `configs/browsers.ts`, `configs/commands.ts`, and `configs/policy.ts`: the
|
|
88
91
|
only permitted leaves under `configs/`. Each imports nothing from the workspace, which is what
|
|
89
92
|
keeps it a leaf, so no `configs/types.ts` exists for one to import: each keeps its own types,
|
|
@@ -126,26 +129,26 @@ Environment rules:
|
|
|
126
129
|
|
|
127
130
|
## Build outputs
|
|
128
131
|
|
|
129
|
-
| Output | Content
|
|
130
|
-
| ----------------------------- |
|
|
131
|
-
| `dist/src/core` | Core library + declarations
|
|
132
|
-
| `dist/src/browser` | Browser library + declarations
|
|
133
|
-
| `dist/src/server` | Server library + declarations
|
|
134
|
-
| `dist/src/vue` | Vue face + declarations
|
|
135
|
-
| `dist/src/styles` | Compiled `index.css`
|
|
136
|
-
| `dist/src/styles/themes` | Compiled themes `index.css`
|
|
137
|
-
| `dist/src/<name>` | Compiled `index.css`
|
|
138
|
-
| `dist/bin` |
|
|
139
|
-
| `dist/
|
|
140
|
-
| `dist/app/
|
|
141
|
-
| `dist/app/
|
|
142
|
-
| `
|
|
143
|
-
| `showcase/<application>.html` | Single-file page per application | self-contained, committed |
|
|
132
|
+
| Output | Content | Format |
|
|
133
|
+
| ----------------------------- | ------------------------------------------------ | ------------------------------------------------------- |
|
|
134
|
+
| `dist/src/core` | Core library + declarations | ES and CJS |
|
|
135
|
+
| `dist/src/browser` | Browser library + declarations | ES |
|
|
136
|
+
| `dist/src/server` | Server library + declarations | ES and CJS |
|
|
137
|
+
| `dist/src/vue` | Vue face + declarations | ES |
|
|
138
|
+
| `dist/src/styles` | Compiled `index.css` | CSS |
|
|
139
|
+
| `dist/src/styles/themes` | Compiled themes `index.css` | CSS |
|
|
140
|
+
| `dist/src/<name>` | Compiled `index.css` | CSS |
|
|
141
|
+
| `dist/bin` | Executable `main.js`; each module + declarations | ES; shebang on `main.js` alone |
|
|
142
|
+
| `dist/app/browser` | Browser application | target-defined |
|
|
143
|
+
| `dist/app/vue` | Vue application | target-defined |
|
|
144
|
+
| `dist/app/server` | Server application | CJS runtime entry; ES barrel when `studies` is selected |
|
|
145
|
+
| `showcase/<application>.html` | Single-file page per application | self-contained, committed |
|
|
144
146
|
|
|
145
147
|
- 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
|
|
147
|
-
`../src/<environment>/index.js
|
|
148
|
-
`
|
|
148
|
+
- Build every `src/bin` module ES only with `@src/*` external, rewritten through `output.paths` to
|
|
149
|
+
`../src/<environment>/index.js`. Give `main.js` alone the `#!/usr/bin/env node` banner, and roll
|
|
150
|
+
up `dist/bin/<name>.d.ts` for every other module with `rewriteSourceSpecifier` rewriting each
|
|
151
|
+
`@src/<environment>` to `../src/<environment>/index.js`.
|
|
149
152
|
- A sheet face ships CSS, not declarations, and its JavaScript build stub stays out of `files`.
|
|
150
153
|
- Build each sheet face with `cssMinify: false`, bounded to its own output directory.
|
|
151
154
|
- Build `dist/src/styles/themes` after `dist/src/styles`; the themes build empties only its own directory.
|
|
@@ -159,20 +162,19 @@ Environment rules:
|
|
|
159
162
|
`vite.config.ts` defines Vitest projects on an environment axis and a workspace-proof axis. The
|
|
160
163
|
environment axis is one project per src/app axis × environment, plus one per extension face:
|
|
161
164
|
|
|
162
|
-
| Project
|
|
163
|
-
|
|
|
164
|
-
| `src:core`
|
|
165
|
-
| `src:browser`
|
|
166
|
-
| `src:vue`
|
|
167
|
-
| `src:server`
|
|
168
|
-
| `src:styles`
|
|
169
|
-
| `src:<name>`
|
|
170
|
-
| `src:bin`
|
|
171
|
-
| `
|
|
172
|
-
| `app:
|
|
173
|
-
| `app:
|
|
174
|
-
| `app:
|
|
175
|
-
| `app:server` | `tests/app/server/**` | Node | `setup.ts`, `setupServer.ts` |
|
|
165
|
+
| Project | Files | Environment | Setup |
|
|
166
|
+
| ------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------ |
|
|
167
|
+
| `src:core` | `tests/src/core/**` | Node | `setup.ts` |
|
|
168
|
+
| `src:browser` | `tests/src/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
|
|
169
|
+
| `src:vue` | `tests/src/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
|
|
170
|
+
| `src:server` | `tests/src/server/**` | Node | `setup.ts`, `setupServer.ts` |
|
|
171
|
+
| `src:styles` | `tests/src/styles/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
|
|
172
|
+
| `src:<name>` | `tests/src/<name>/**` | Playwright Chromium, `isolate: false` | `setup.ts`, `setupBrowser.ts`, `setupStyles.ts` when present |
|
|
173
|
+
| `src:bin` | `tests/src/bin/**` | Node | `setup.ts`, `setupServer.ts` |
|
|
174
|
+
| `app:core` | `tests/app/core/**` | Node | `setup.ts` |
|
|
175
|
+
| `app:browser` | `tests/app/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
|
|
176
|
+
| `app:vue` | `tests/app/vue/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts` |
|
|
177
|
+
| `app:server` | `tests/app/server/**` | Node | `setup.ts`, `setupServer.ts` |
|
|
176
178
|
|
|
177
179
|
- Compose every sheet-face project (`src:styles` and each `src:<name>`) in its own wrapper through
|
|
178
180
|
the one root `sheetProject` factory, and run it through its `test:src:<face>` script, which builds
|
|
@@ -285,8 +287,7 @@ then runs the configured scoped checks that prove environment isolation.
|
|
|
285
287
|
|
|
286
288
|
- Use plain `tsc` for a TypeScript-only tree.
|
|
287
289
|
- Use `vue-tsc` only for a scope containing `.vue` internals.
|
|
288
|
-
- `check:src` mirrors configured `src:*` test projects; optional `src:bin`
|
|
289
|
-
are each their own scope.
|
|
290
|
+
- `check:src` mirrors configured `src:*` test projects; optional `src:bin` is its own scope.
|
|
290
291
|
- `check:app` mirrors configured `app:*` projects.
|
|
291
292
|
- `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.
|
|
292
293
|
- 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.
|
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
import {
|
|
23
23
|
basename,
|
|
24
24
|
dirname,
|
|
25
|
+
extname,
|
|
25
26
|
isAbsolute,
|
|
26
27
|
join,
|
|
27
28
|
relative,
|
|
@@ -522,7 +523,7 @@ export class BuildState {
|
|
|
522
523
|
#building = false
|
|
523
524
|
#output: string
|
|
524
525
|
#root = WORKSPACE_ROOT
|
|
525
|
-
#
|
|
526
|
+
#entries: Readonly<Record<string, string>> = {}
|
|
526
527
|
readonly #trusted = new Set<string>()
|
|
527
528
|
|
|
528
529
|
constructor(output = WORKSPACE_ROOT) {
|
|
@@ -544,9 +545,9 @@ export class BuildState {
|
|
|
544
545
|
return this.#root
|
|
545
546
|
}
|
|
546
547
|
|
|
547
|
-
/** The library entry
|
|
548
|
-
get
|
|
549
|
-
return this.#
|
|
548
|
+
/** The library entry paths by entry name, empty when the build has none. */
|
|
549
|
+
get entries(): Readonly<Record<string, string>> {
|
|
550
|
+
return this.#entries
|
|
550
551
|
}
|
|
551
552
|
|
|
552
553
|
/**
|
|
@@ -571,7 +572,10 @@ export class BuildState {
|
|
|
571
572
|
}
|
|
572
573
|
|
|
573
574
|
/**
|
|
574
|
-
* Reads the command, output directory, project root, and library
|
|
575
|
+
* Reads the command, output directory, project root, and library entries from a resolved config.
|
|
576
|
+
*
|
|
577
|
+
* @remarks
|
|
578
|
+
* A single-path entry and each member of an entry list take their file's stem as their name.
|
|
575
579
|
*
|
|
576
580
|
* @param config - The resolved Vite configuration.
|
|
577
581
|
*/
|
|
@@ -579,10 +583,11 @@ export class BuildState {
|
|
|
579
583
|
this.#building = config.command === 'build'
|
|
580
584
|
this.#output = resolvePath(config.root, config.build.outDir)
|
|
581
585
|
this.#root = physicalPath(config.root)
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
+
const entry = config.build.lib === false ? {} : config.build.lib.entry
|
|
587
|
+
this.#entries =
|
|
588
|
+
typeof entry === 'string' || Array.isArray(entry)
|
|
589
|
+
? Object.fromEntries([entry].flat().map((path) => [basename(path, extname(path)), path]))
|
|
590
|
+
: { ...entry }
|
|
586
591
|
}
|
|
587
592
|
}
|
|
588
593
|
|
|
@@ -696,13 +701,15 @@ export interface ExtractorModule {
|
|
|
696
701
|
*
|
|
697
702
|
* @remarks
|
|
698
703
|
* `project` is the absolute path of that face's TypeScript project file. `types` overrides the
|
|
699
|
-
* `types` the extractor's own program reads, and defaults to the face's resolved `types`. `
|
|
700
|
-
*
|
|
701
|
-
*
|
|
704
|
+
* `types` the extractor's own program reads, and defaults to the face's resolved `types`. `entries`
|
|
705
|
+
* names the library entries that roll up, and defaults to every entry the build declares; a
|
|
706
|
+
* single-path entry takes its file's stem as its name. `rewrite` receives each finished roll-up and
|
|
707
|
+
* returns what the face ships; a face that omits it ships the roll-up as the extractor wrote it.
|
|
702
708
|
*/
|
|
703
709
|
export interface DeclarationRollupOptions {
|
|
704
710
|
readonly project: string
|
|
705
711
|
readonly types?: readonly string[]
|
|
712
|
+
readonly entries?: readonly string[]
|
|
706
713
|
readonly rewrite?: (content: string) => string
|
|
707
714
|
}
|
|
708
715
|
|
|
@@ -878,27 +885,28 @@ export function rewriteBrowserSpecifier(content: string): string {
|
|
|
878
885
|
}
|
|
879
886
|
|
|
880
887
|
/**
|
|
881
|
-
* Rewrites every
|
|
888
|
+
* Rewrites every source environment alias in a roll-up to the built environment beside `dist/bin`.
|
|
882
889
|
*
|
|
883
890
|
* @param content - The finished roll-up.
|
|
884
|
-
* @returns That roll-up with each `@src
|
|
891
|
+
* @returns That roll-up with each `@src/<environment>` specifier replaced by
|
|
892
|
+
* `../src/<environment>/index.js`.
|
|
885
893
|
*
|
|
886
894
|
* @remarks
|
|
887
|
-
*
|
|
888
|
-
* keeps
|
|
889
|
-
* declarations at the
|
|
895
|
+
* A `src/bin` module reaches a library environment through its `@src/*` alias, and the extractor
|
|
896
|
+
* keeps the alias external and writes it through unchanged. `dist/bin/<name>.d.ts` resolves the
|
|
897
|
+
* environment's declarations at the relative path its `<name>.js` imports through `output.paths`.
|
|
890
898
|
*
|
|
891
899
|
* @example
|
|
892
900
|
* ```ts
|
|
893
|
-
*
|
|
901
|
+
* rewriteSourceSpecifier("from '@src/server'") // "from '../src/server/index.js'"
|
|
894
902
|
* ```
|
|
895
903
|
*/
|
|
896
|
-
export function
|
|
897
|
-
return content.replaceAll('
|
|
904
|
+
export function rewriteSourceSpecifier(content: string): string {
|
|
905
|
+
return content.replaceAll(/@src\/([a-z][a-z0-9-]*)(?=['"])/gu, '../src/$1/index.js')
|
|
898
906
|
}
|
|
899
907
|
|
|
900
908
|
/**
|
|
901
|
-
* Rolls
|
|
909
|
+
* Rolls each named library entry's declarations into the single file that entry ships.
|
|
902
910
|
*
|
|
903
911
|
* @param options - The face's roll-up options.
|
|
904
912
|
* @returns The Vite plugin that performs that roll-up.
|
|
@@ -906,9 +914,10 @@ export function rewriteServerSpecifier(content: string): string {
|
|
|
906
914
|
* @remarks
|
|
907
915
|
* At `closeBundle`, after Vite has written every format of the face, the plugin emits the face's
|
|
908
916
|
* declarations with the workspace compiler run as a process into a scratch directory made fresh
|
|
909
|
-
* under the host temporary directory, hands
|
|
910
|
-
* applies `rewrite`, and removes the scratch directory.
|
|
911
|
-
* an `index.ts` face ships `index.d.ts` and a `
|
|
917
|
+
* under the host temporary directory, hands each named entry to the extractor's own engine,
|
|
918
|
+
* applies `rewrite`, and removes the scratch directory. Each roll-up takes its entry's name, so
|
|
919
|
+
* an `index.ts` face ships `index.d.ts` and a `reporter` entry ships `reporter.d.ts`. An empty
|
|
920
|
+
* `entries` list rolls up nothing. Keeping the
|
|
912
921
|
* scratch outside the face's own output means its unconditional removal can never take a sibling
|
|
913
922
|
* the face already published, such as its own `declarations` folder. The extractor is a publishing
|
|
914
923
|
* workspace's development dependency, so this vendored leaf defers loading it to that hook: a
|
|
@@ -924,12 +933,20 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
|
|
|
924
933
|
},
|
|
925
934
|
closeBundle() {
|
|
926
935
|
if (!state.building) return
|
|
927
|
-
const
|
|
928
|
-
|
|
936
|
+
const named = options.entries ?? Object.keys(state.entries)
|
|
937
|
+
const declarations = named.map((name) => {
|
|
938
|
+
const source = state.entries[name] ?? ''
|
|
939
|
+
return { name, source, declaration: source.replace(/\.tsx?$/, '.d.ts') }
|
|
940
|
+
})
|
|
941
|
+
if (
|
|
942
|
+
(options.entries === undefined && declarations.length === 0) ||
|
|
943
|
+
declarations.some(({ source, declaration }) => declaration === source)
|
|
944
|
+
) {
|
|
929
945
|
throw new Error(
|
|
930
|
-
'[orkestrel-declaration-rollup] The face must build
|
|
946
|
+
'[orkestrel-declaration-rollup] The face must build each named TypeScript library entry',
|
|
931
947
|
)
|
|
932
948
|
}
|
|
949
|
+
if (declarations.length === 0) return
|
|
933
950
|
const load = createRequire(import.meta.url)
|
|
934
951
|
const compiler = resolveCompiler(import.meta.url)
|
|
935
952
|
const scope = parseProjectScope(
|
|
@@ -942,7 +959,6 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
|
|
|
942
959
|
)
|
|
943
960
|
}
|
|
944
961
|
const scratch = mkdtempSync(join(tmpdir(), 'orkestrel-declarations-'))
|
|
945
|
-
const rollup = resolvePath(state.output, basename(declaration))
|
|
946
962
|
try {
|
|
947
963
|
readCompilerOutput(compiler, [
|
|
948
964
|
'-p',
|
|
@@ -954,7 +970,6 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
|
|
|
954
970
|
'--outDir',
|
|
955
971
|
scratch,
|
|
956
972
|
])
|
|
957
|
-
const entry = resolvePath(scratch, relative(scope.root, declaration))
|
|
958
973
|
// A literal `import()` of the extractor reddens `tsc` in a workspace that does not
|
|
959
974
|
// install it, so the literal `createRequire` call is the form that clears the
|
|
960
975
|
// typecheck in an app-only workspace.
|
|
@@ -964,45 +979,51 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
|
|
|
964
979
|
'[orkestrel-declaration-rollup] The declaration extractor exposes no entry point',
|
|
965
980
|
)
|
|
966
981
|
}
|
|
967
|
-
const
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
982
|
+
for (const { name, declaration } of declarations) {
|
|
983
|
+
const entry = resolvePath(scratch, relative(scope.root, declaration))
|
|
984
|
+
const rollup = resolvePath(state.output, `${name}.d.ts`)
|
|
985
|
+
const prepared: unknown = loaded.ExtractorConfig.prepare({
|
|
986
|
+
configObject: {
|
|
987
|
+
projectFolder: WORKSPACE_ROOT,
|
|
988
|
+
mainEntryPointFilePath: entry,
|
|
989
|
+
bundledPackages: [],
|
|
990
|
+
compiler: {
|
|
991
|
+
overrideTsconfig: buildExtractorOverride(
|
|
992
|
+
entry,
|
|
993
|
+
scope.lib,
|
|
994
|
+
options.types ?? scope.types,
|
|
995
|
+
),
|
|
996
|
+
},
|
|
997
|
+
apiReport: { enabled: false },
|
|
998
|
+
docModel: { enabled: false },
|
|
999
|
+
tsdocMetadata: { enabled: false },
|
|
1000
|
+
dtsRollup: { enabled: true, untrimmedFilePath: rollup },
|
|
1001
|
+
messages: {
|
|
1002
|
+
compilerMessageReporting: { default: { logLevel: 'none' } },
|
|
1003
|
+
extractorMessageReporting: { default: { logLevel: 'none' } },
|
|
1004
|
+
tsdocMessageReporting: { default: { logLevel: 'none' } },
|
|
1005
|
+
},
|
|
978
1006
|
},
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
? Reflect.get(outcome, 'succeeded')
|
|
1000
|
-
: undefined
|
|
1001
|
-
if (succeeded !== true) {
|
|
1002
|
-
throw new Error('[orkestrel-declaration-rollup] The declaration roll-up failed')
|
|
1003
|
-
}
|
|
1004
|
-
if (options.rewrite !== undefined) {
|
|
1005
|
-
writeFileSync(rollup, options.rewrite(readFileSync(rollup, 'utf8')), 'utf8')
|
|
1007
|
+
configObjectFullPath: resolvePath(WORKSPACE_ROOT, 'api-extractor.json'),
|
|
1008
|
+
packageJsonFullPath: resolvePath(WORKSPACE_ROOT, 'package.json'),
|
|
1009
|
+
})
|
|
1010
|
+
const outcome: unknown = loaded.Extractor.invoke(prepared, {
|
|
1011
|
+
localBuild: true,
|
|
1012
|
+
showVerboseMessages: false,
|
|
1013
|
+
showDiagnostics: false,
|
|
1014
|
+
})
|
|
1015
|
+
const succeeded: unknown =
|
|
1016
|
+
typeof outcome === 'object' && outcome !== null
|
|
1017
|
+
? Reflect.get(outcome, 'succeeded')
|
|
1018
|
+
: undefined
|
|
1019
|
+
if (succeeded !== true) {
|
|
1020
|
+
throw new Error(
|
|
1021
|
+
`[orkestrel-declaration-rollup] The declaration roll-up of ${name} failed`,
|
|
1022
|
+
)
|
|
1023
|
+
}
|
|
1024
|
+
if (options.rewrite !== undefined) {
|
|
1025
|
+
writeFileSync(rollup, options.rewrite(readFileSync(rollup, 'utf8')), 'utf8')
|
|
1026
|
+
}
|
|
1006
1027
|
}
|
|
1007
1028
|
} finally {
|
|
1008
1029
|
rmSync(scratch, { recursive: true, force: true })
|