@orkestrel/scaffold 0.0.72 → 0.0.74
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/bin/main.js +75 -34
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-prove-journey/SKILL.md +175 -29
- package/dist/host/agents/skills/orkestrel-prove-journey/references/captures.md +42 -15
- package/dist/host/agents/skills/orkestrel-prove-journey/references/decide.md +34 -15
- package/dist/host/agents/skills/orkestrel-prove-journey/references/layer.md +248 -52
- package/dist/host/agents/skills/orkestrel-prove-journey/references/statechart.md +255 -49
- package/dist/host/agents/skills/orkestrel-prove-journey/references/styles.md +111 -23
- package/dist/host/agents/transports/codex.md +7 -0
- package/dist/host/claude/agents/orkestrel.md +46 -46
- package/dist/host/claude/rules/documentation.md +2 -0
- package/dist/host/claude/rules/tests.md +5 -3
- package/dist/host/claude/rules/workspace.md +26 -15
- package/dist/host/dotfiles/gitignore +3 -0
- package/dist/host/guides/README.md +5 -0
- package/dist/host/guides/scaffold.md +97 -13
- package/dist/host/guides/test.md +788 -206
- package/dist/host/manifest.json +22 -32
- package/dist/host/tests/config.test.ts +272 -121
- package/dist/host/tests/policy.test.ts +11 -1
- package/dist/host/tests/setupPolicy.ts +571 -7
- package/dist/src/core/index.cjs +109 -18
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +19 -6
- package/dist/src/core/index.d.ts +19 -6
- package/dist/src/core/index.js +109 -19
- package/dist/src/core/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -45,56 +45,56 @@ so network-controlled descriptions never enter agent instruction context.
|
|
|
45
45
|
|
|
46
46
|
| Package | Version | Layer | Runtime dependencies | Peer dependencies |
|
|
47
47
|
| ----------------------- | -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
48
|
-
| `@orkestrel/abort` | `0.0.
|
|
49
|
-
| `@orkestrel/agent` | `0.0.
|
|
50
|
-
| `@orkestrel/brief` | `0.0.
|
|
51
|
-
| `@orkestrel/browser` | `0.0.
|
|
52
|
-
| `@orkestrel/budget` | `0.0.
|
|
53
|
-
| `@orkestrel/codec` | `0.0.
|
|
54
|
-
| `@orkestrel/console` | `0.0.
|
|
48
|
+
| `@orkestrel/abort` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
49
|
+
| `@orkestrel/agent` | `0.0.24` | L5 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/budget` `^0.0.11`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/queue` `^0.0.14`, `@orkestrel/timeout` `^0.0.11`, `@orkestrel/tool` `^0.0.16`, `@orkestrel/workflow` `^0.0.19`, `@orkestrel/workspace` `^0.0.9` | |
|
|
50
|
+
| `@orkestrel/brief` | `0.0.9` | L4 | `@orkestrel/reason` `^0.0.11`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/interpret` `^0.0.14` | |
|
|
51
|
+
| `@orkestrel/browser` | `0.0.17` | L3 | `@orkestrel/html` `^0.0.10`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/websocket` `^0.0.13` | |
|
|
52
|
+
| `@orkestrel/budget` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
53
|
+
| `@orkestrel/codec` | `0.0.4` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
54
|
+
| `@orkestrel/console` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
55
55
|
| `@orkestrel/contract` | `0.0.17` | L0 | | |
|
|
56
|
-
| `@orkestrel/csv` | `0.0.
|
|
57
|
-
| `@orkestrel/database` | `0.0.
|
|
56
|
+
| `@orkestrel/csv` | `0.0.8` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
57
|
+
| `@orkestrel/database` | `0.0.15` | L2 | `@orkestrel/sqlite` `^0.0.12`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/indexeddb` `^0.0.12` | |
|
|
58
58
|
| `@orkestrel/emitter` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
59
|
-
| `@orkestrel/form` | `0.0.
|
|
60
|
-
| `@orkestrel/guide` | `0.0.
|
|
61
|
-
| `@orkestrel/html` | `0.0.
|
|
62
|
-
| `@orkestrel/indexeddb` | `0.0.
|
|
63
|
-
| `@orkestrel/interpret` | `0.0.
|
|
64
|
-
| `@orkestrel/lsp` | `0.0.
|
|
65
|
-
| `@orkestrel/markdown` | `0.0.
|
|
66
|
-
| `@orkestrel/mcp` | `0.0.
|
|
67
|
-
| `@orkestrel/middleware` | `0.0.
|
|
68
|
-
| `@orkestrel/msg` | `0.0.
|
|
59
|
+
| `@orkestrel/form` | `0.0.7` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
60
|
+
| `@orkestrel/guide` | `0.0.20` | L3 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/markdown` `^0.0.15` | |
|
|
61
|
+
| `@orkestrel/html` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
62
|
+
| `@orkestrel/indexeddb` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
63
|
+
| `@orkestrel/interpret` | `0.0.14` | L3 | `@orkestrel/reason` `^0.0.11`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/template` `^0.0.8` | |
|
|
64
|
+
| `@orkestrel/lsp` | `0.0.9` | L3 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.13`, `@orkestrel/contract` `^0.0.17` | |
|
|
65
|
+
| `@orkestrel/markdown` | `0.0.15` | L2 | `@orkestrel/html` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
66
|
+
| `@orkestrel/mcp` | `0.0.32` | L4 | `@orkestrel/sse` `^0.0.8`, `@orkestrel/tool` `^0.0.16`, `@orkestrel/codec` `^0.0.4`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.13`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/websocket` `^0.0.13` | `@orkestrel/router` `^0.0.15`, `@orkestrel/server` `^0.0.20` |
|
|
67
|
+
| `@orkestrel/middleware` | `0.0.21` | L4 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/budget` `^0.0.11`, `@orkestrel/timeout` `^0.0.11`, `@orkestrel/contract` `^0.0.17` | `@orkestrel/server` `^0.0.20`, `@orkestrel/database` `^0.0.15` |
|
|
68
|
+
| `@orkestrel/msg` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
69
69
|
| `@orkestrel/ndjson` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
70
|
-
| `@orkestrel/ollama` | `0.0.
|
|
71
|
-
| `@orkestrel/pool` | `0.0.
|
|
72
|
-
| `@orkestrel/probe` | `0.0.
|
|
73
|
-
| `@orkestrel/process` | `0.0.
|
|
74
|
-
| `@orkestrel/program` | `0.0.
|
|
75
|
-
| `@orkestrel/qualifier` | `0.0.
|
|
76
|
-
| `@orkestrel/queue` | `0.0.
|
|
77
|
-
| `@orkestrel/rater` | `0.0.
|
|
78
|
-
| `@orkestrel/reason` | `0.0.
|
|
79
|
-
| `@orkestrel/relation` | `0.0.
|
|
80
|
-
| `@orkestrel/router` | `0.0.
|
|
81
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
82
|
-
| `@orkestrel/sea` | `0.0.
|
|
83
|
-
| `@orkestrel/server` | `0.0.
|
|
84
|
-
| `@orkestrel/sqlite` | `0.0.
|
|
85
|
-
| `@orkestrel/sse` | `0.0.
|
|
70
|
+
| `@orkestrel/ollama` | `0.0.18` | L6 | `@orkestrel/tool` `^0.0.16`, `@orkestrel/agent` `^0.0.24`, `@orkestrel/budget` `^0.0.11`, `@orkestrel/ndjson` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
71
|
+
| `@orkestrel/pool` | `0.0.12` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
72
|
+
| `@orkestrel/probe` | `0.0.16` | L5 | `@orkestrel/lsp` `^0.0.9`, `@orkestrel/mcp` `^0.0.32`, `@orkestrel/tool` `^0.0.16`, `@orkestrel/queue` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/timeout` `^0.0.11`, `@orkestrel/contract` `^0.0.17` | `oxlint` `^1.82.0`, `vitest` `^4.1.11`, `typescript` `^6.0.3` |
|
|
73
|
+
| `@orkestrel/process` | `0.0.13` | L2 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10` | |
|
|
74
|
+
| `@orkestrel/program` | `0.0.14` | L4 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/qualifier` `^0.0.15`, `@orkestrel/rater` `^0.0.15`, `@orkestrel/reason` `^0.0.11` | |
|
|
75
|
+
| `@orkestrel/qualifier` | `0.0.15` | L3 | `@orkestrel/reason` `^0.0.11`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
76
|
+
| `@orkestrel/queue` | `0.0.14` | L3 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/timeout` `^0.0.11` | |
|
|
77
|
+
| `@orkestrel/rater` | `0.0.15` | L3 | `@orkestrel/reason` `^0.0.11`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
78
|
+
| `@orkestrel/reason` | `0.0.11` | L2 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10` | |
|
|
79
|
+
| `@orkestrel/relation` | `0.0.13` | L3 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15` | |
|
|
80
|
+
| `@orkestrel/router` | `0.0.15` | L2 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
81
|
+
| `@orkestrel/scaffold` | `0.0.73` | L3 | `@orkestrel/console` `^0.0.14`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/markdown` `^0.0.15`, `@orkestrel/process` `^0.0.13`, `@orkestrel/template` `^0.0.8` | |
|
|
82
|
+
| `@orkestrel/sea` | `0.0.17` | L3 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/process` `^0.0.13` | |
|
|
83
|
+
| `@orkestrel/server` | `0.0.20` | L3 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/codec` `^0.0.4`, `@orkestrel/router` `^0.0.15`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/timeout` `^0.0.11`, `@orkestrel/contract` `^0.0.17` | |
|
|
84
|
+
| `@orkestrel/sqlite` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
85
|
+
| `@orkestrel/sse` | `0.0.8` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
86
86
|
| `@orkestrel/supervisor` | `0.0.1` | L5 | `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.9`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/workflow` `^0.0.12` | |
|
|
87
|
-
| `@orkestrel/table` | `0.0.
|
|
88
|
-
| `@orkestrel/template` | `0.0.
|
|
89
|
-
| `@orkestrel/terminal` | `0.0.
|
|
90
|
-
| `@orkestrel/test` | `0.0.
|
|
91
|
-
| `@orkestrel/timeout` | `0.0.
|
|
92
|
-
| `@orkestrel/tool` | `0.0.
|
|
93
|
-
| `@orkestrel/toolbox` | `0.0.
|
|
94
|
-
| `@orkestrel/websocket` | `0.0.
|
|
95
|
-
| `@orkestrel/worker` | `0.0.
|
|
96
|
-
| `@orkestrel/workflow` | `0.0.
|
|
97
|
-
| `@orkestrel/workspace` | `0.0.
|
|
87
|
+
| `@orkestrel/table` | `0.0.6` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
88
|
+
| `@orkestrel/template` | `0.0.8` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
89
|
+
| `@orkestrel/terminal` | `0.0.16` | L3 | `@orkestrel/sse` `^0.0.8`, `@orkestrel/form` `^0.0.7`, `@orkestrel/console` `^0.0.14`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15` | |
|
|
90
|
+
| `@orkestrel/test` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.17` | `vitest` `^4.1.11` |
|
|
91
|
+
| `@orkestrel/timeout` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.17` | |
|
|
92
|
+
| `@orkestrel/tool` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
93
|
+
| `@orkestrel/toolbox` | `0.0.15` | L6 | `@orkestrel/form` `^0.0.7`, `@orkestrel/tool` `^0.0.16`, `@orkestrel/agent` `^0.0.24`, `@orkestrel/server` `^0.0.20`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15`, `@orkestrel/relation` `^0.0.13`, `@orkestrel/terminal` `^0.0.16`, `@orkestrel/workflow` `^0.0.19`, `@orkestrel/workspace` `^0.0.9` | |
|
|
94
|
+
| `@orkestrel/websocket` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17` | |
|
|
95
|
+
| `@orkestrel/worker` | `0.0.13` | L4 | `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/pool` `^0.0.12`, `@orkestrel/queue` `^0.0.14` | |
|
|
96
|
+
| `@orkestrel/workflow` | `0.0.19` | L4 | `@orkestrel/abort` `^0.0.11`, `@orkestrel/budget` `^0.0.11`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15`, `@orkestrel/emitter` `^0.0.10`, `@orkestrel/queue` `^0.0.14`, `@orkestrel/timeout` `^0.0.11` | |
|
|
97
|
+
| `@orkestrel/workspace` | `0.0.9` | L3 | `@orkestrel/emitter` `^0.0.10`, `@orkestrel/contract` `^0.0.17`, `@orkestrel/database` `^0.0.15` | |
|
|
98
98
|
|
|
99
99
|
<!-- /orkestrel:catalog -->
|
|
100
100
|
|
|
@@ -91,6 +91,8 @@ Never use in-repository `@src/*` aliases in public guide examples; reserve them
|
|
|
91
91
|
- Do not put model routing or package version catalogs in a skill.
|
|
92
92
|
- Validate every referenced resource, leave no template TODOs, and limit each skill directory to `SKILL.md`, `agents/openai.yaml`, and the `references/*.md` files its `SKILL.md` names; add no other file or directory.
|
|
93
93
|
- 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.
|
|
94
|
+
- 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.
|
|
95
|
+
- Import only packages in `BASE_DEV_DEPENDENCIES` in those fences. The sweep refuses a package outside that set because a generated workspace need not install it.
|
|
94
96
|
- Write `agents/openai.yaml` as one root `interface:` mapping over exactly `display_name`, `short_description`, and `default_prompt`, in that order, each on its own two-space-indented line.
|
|
95
97
|
- Research the external schema only when a consumer needs a key outside `display_name`, `short_description`, and `default_prompt`, and add no key before then.
|
|
96
98
|
- Give every one of those keys a non-empty single-quoted scalar, and write an apostrophe inside it as `''`.
|
|
@@ -59,9 +59,11 @@ its own:
|
|
|
59
59
|
| `tests/setup*.test.ts` | Reusable behavior exported from sibling `tests/setup*.ts` modules works as the workspace's suites require |
|
|
60
60
|
| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real |
|
|
61
61
|
|
|
62
|
-
- Put
|
|
63
|
-
|
|
64
|
-
|
|
62
|
+
- Put `tests/setupBrowser.test.ts` in the browser-enabled `setup:browser` project. Put every
|
|
63
|
+
other root `tests/setup*.test.ts` proof in the Node `setup` project, and exclude the browser
|
|
64
|
+
proof from that project. Keep each proof's assertions on exported test-infrastructure behavior:
|
|
65
|
+
do not duplicate production behavior there, and do not move setup-helper assertions into another
|
|
66
|
+
cross-cutting proof.
|
|
65
67
|
- `.claude/rules/workspace.md` names the Vitest project each location belongs to.
|
|
66
68
|
- The `guides` project runs in Node with the browser disabled. Its subject is what the guide
|
|
67
69
|
claims: that every documented name resolves, and that every fence asserting a value returns
|
|
@@ -128,20 +128,30 @@ environment axis is one project per src/app axis × environment:
|
|
|
128
128
|
The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
|
|
129
129
|
one environment, so each is its own project:
|
|
130
130
|
|
|
131
|
-
| Project
|
|
132
|
-
|
|
|
133
|
-
| `policy`
|
|
134
|
-
| `config`
|
|
135
|
-
| `setup`
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
131
|
+
| Project | Files | Proves | Gate |
|
|
132
|
+
| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
133
|
+
| `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges | `test` |
|
|
134
|
+
| `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs | `test` |
|
|
135
|
+
| `setup` | `tests/setup*.test.ts`, excluding `tests/setupBrowser.test.ts` | Prove root setup behavior in Node with `setup.ts`. | `test` |
|
|
136
|
+
| `setup:browser` | `tests/setupBrowser.test.ts` | Prove browser setup behavior in Playwright Chromium with `setup.ts` and `setupBrowser.ts`. | `test` |
|
|
137
|
+
| `journey:<variant>` | `tests/app/browser/integration.test.ts` | Drive the browser application at the declared variant viewport in Playwright Chromium with `setup.ts` and `setupBrowser.ts`. | `test` through `test:journey` |
|
|
138
|
+
| `guides` | `tests/guides.test.ts` | Every documented API exists, every public API is documented, every compared summary, example, and pitch equals its source, and every executable fence returns what the guide says it returns | `test` |
|
|
139
|
+
| `conformance` | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks | `test` |
|
|
140
|
+
| `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports | `prepublishOnly`; absent when private |
|
|
141
|
+
| `integration` | `tests/integration.test.ts` | The package's features work together end to end across environments | `test` |
|
|
142
|
+
| `service` | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real | `prepublishOnly`; `test` when private |
|
|
143
|
+
|
|
144
|
+
- Define the Node `setup` project only when a root file matches `tests/setup*.test.ts`,
|
|
145
|
+
exact-case, other than `tests/setupBrowser.test.ts`. Include those matching files and exclude
|
|
146
|
+
`tests/setupBrowser.test.ts`. Define `setup:browser` only when that exact-case browser proof
|
|
147
|
+
exists, and collect that path alone. For each registered project, emit its `test:setup` or
|
|
148
|
+
`test:setup:browser` script and run it from `test`; otherwise emit neither its project nor its
|
|
149
|
+
script.
|
|
150
|
+
- When a browser application selects the journey axis, register `journey:<variant>` projects
|
|
151
|
+
through the birth-owned `configs/app/vite.journey.config.ts` wrapper. Keep the adopter's variant
|
|
152
|
+
list there and compose each project through the root `appJourney` factory. Exclude
|
|
153
|
+
`tests/app/browser/integration.test.ts` from `app:browser`, collect it in each variant project,
|
|
154
|
+
and run the wrapper through `test:journey` after the application projects in `test`.
|
|
145
155
|
|
|
146
156
|
`conformance`, `integration`, `distribution`, and `service` are separate subjects, not names for
|
|
147
157
|
one.
|
|
@@ -180,7 +190,8 @@ Setup assets:
|
|
|
180
190
|
- Styles setup loads `setup.css` and the compiled cascade.
|
|
181
191
|
|
|
182
192
|
Scope with `test:src`, `test:src:core`, `test:app`, `test:app:server`, and equivalent scripts. Each
|
|
183
|
-
cross-cutting project has its own script too: `test:policy`, `test:config`, `test:setup`,
|
|
193
|
+
cross-cutting project has its own script too: `test:policy`, `test:config`, `test:setup`,
|
|
194
|
+
`test:setup:browser`, `test:journey`, `test:guides`,
|
|
184
195
|
`test:conformance`, `test:distribution`, `test:integration`, `test:service`.
|
|
185
196
|
|
|
186
197
|
## Typechecking and environment isolation
|
|
@@ -16,6 +16,11 @@ guide mirrors, and the `WriteTransaction` those writes stage through. The `scaff
|
|
|
16
16
|
([`src/bin`](../src/bin)) publishes no barrel, so it is documented in prose and sits outside the
|
|
17
17
|
surface bijection.
|
|
18
18
|
|
|
19
|
+
The [Blueprint reference](scaffold.md#blueprint) describes the journey axis and its adopter-edited
|
|
20
|
+
`configs/app/vite.journey.config.ts` wrapper, the `SetupRuntime` list, and the `setup:browser`
|
|
21
|
+
project. The generated workspace runs journey variants and browser setup proofs through its
|
|
22
|
+
`test` chain.
|
|
23
|
+
|
|
19
24
|
That bijection is the row's contract, and [`tests/guides.test.ts`](../tests/guides.test.ts)
|
|
20
25
|
enforces it: every symbol the guide documents exists in the core barrel or the server barrel, and
|
|
21
26
|
every symbol either barrel exports is documented.
|
|
@@ -70,6 +70,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
70
70
|
| `Ownership` | type | Names what scaffold claims at an artifact's path. |
|
|
71
71
|
| `Release` | type | Represents one declared dependency range measured against a registry release. |
|
|
72
72
|
| `ScaffoldErrorCode` | type | Names the coded reasons a scaffold error is raised. |
|
|
73
|
+
| `SetupRuntime` | type | Names the runtime a root setup proof requires. |
|
|
73
74
|
| `Snapshot` | type | Holds exact lowercase hexadecimal target bytes keyed by artifact-relative path. |
|
|
74
75
|
|
|
75
76
|
#### Interfaces
|
|
@@ -138,6 +139,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
138
139
|
| `HOST_PATHS` | const | Lists the paths a target receives from the vendored data root, frozen. |
|
|
139
140
|
| `INTEGRATION_TEST_PATH` | const | Names the cross-environment composition proof whose presence makes a workspace `integration`. |
|
|
140
141
|
| `INVALID_PATH_CHARACTER_PATTERN` | const | Matches the visible characters a target-relative path and a Markdown path cell both forbid. |
|
|
142
|
+
| `JOURNEY_CONFIG_PATH` | const | Names the Vite wrapper whose presence makes a workspace `journey`. |
|
|
141
143
|
| `MANIFEST_PATH` | const | Names the manifest path every compiler plan emits with birth ownership. |
|
|
142
144
|
| `MAX_ARTIFACT_BYTES` | const | Caps the bytes accepted for one artifact. |
|
|
143
145
|
| `MAX_ARTIFACT_HEX_LENGTH` | const | Caps the length of the hexadecimal string carrying one artifact's bytes. |
|
|
@@ -588,10 +590,15 @@ files on `main`, the scaffold repository's `host.json` file, and changed vendore
|
|
|
588
590
|
answers a read and grant no verb write authority that it did not already have.
|
|
589
591
|
|
|
590
592
|
`new --bin` creates the executable entry, its test, and its scoped Vite and TypeScript wrappers. The
|
|
591
|
-
|
|
593
|
+
`new --app browser` command selects the journey axis, creates its birth-owned wrapper, defines
|
|
594
|
+
`appJourney` in the root configuration, and excludes the browser integration suite from
|
|
595
|
+
`app:browser`. Its manifest declares `test:journey` and invokes it after `npm run test:app` in
|
|
596
|
+
`test`. A selection without a browser application emits no journey axis. Creation leaves `setup`
|
|
597
|
+
empty. The other structural facts do not need creation flags. Add a root `tests/setup*.test.ts` proof for
|
|
592
598
|
`setup`, `tests/guides.test.ts` for `guides`, `tests/integration.test.ts` for `integration`,
|
|
593
599
|
`tests/conformance.test.ts` for `conformance`, `tests/setupService.ts` for `service`,
|
|
594
|
-
`tests/setupGlobal.ts` for `global`,
|
|
600
|
+
`tests/setupGlobal.ts` for `global`, `configs/app/vite.showcase.config.ts` for `showcase`, and
|
|
601
|
+
`configs/app/vite.journey.config.ts` for `journey`;
|
|
595
602
|
reading verbs detect each exact-case file and register its fixed machinery. An explicitly supplied
|
|
596
603
|
plan with `vendors` owns and protects the birth-owned `scripts/service.sh` inventory skeleton.
|
|
597
604
|
Reading verbs do not infer its vendor list from edited text and cannot preserve an arbitrary present
|
|
@@ -610,7 +617,8 @@ beside it could disagree. The remaining facts come from exact-case files: `src/b
|
|
|
610
617
|
`bin`, each root `tests/setup*.test.ts` match selects `setup`, `tests/guides.test.ts` selects
|
|
611
618
|
`guides`, `tests/integration.test.ts` selects `integration`, `tests/conformance.test.ts` selects
|
|
612
619
|
`conformance`, `tests/setupService.ts` selects `service`, `tests/setupGlobal.ts` selects `global`,
|
|
613
|
-
|
|
620
|
+
`configs/app/vite.showcase.config.ts` selects `showcase`, and
|
|
621
|
+
`configs/app/vite.journey.config.ts` selects `journey`. A containing directory does not select
|
|
614
622
|
the fact by itself. `tests/distribution.test.ts` selects nothing: the published `src` axis the
|
|
615
623
|
target ships already decides the `distribution` project, and the file is planned from that.
|
|
616
624
|
|
|
@@ -641,12 +649,33 @@ package before a publish lifecycle script runs, so crediting it would report a d
|
|
|
641
649
|
one. Generated integration runs from `test`. One shell-token pass reads quoted and unquoted
|
|
642
650
|
`--project value` and `--project=value` forms and follows literal `npm run` calls. A shell expansion
|
|
643
651
|
or malformed quote that prevents a project or script name from being resolved statically produces a
|
|
644
|
-
question instead of licensing a write. The
|
|
645
|
-
text that names `vitest`;
|
|
646
|
-
static Vitest fact
|
|
652
|
+
question instead of licensing a write. The absent-project and absent-configuration checks read
|
|
653
|
+
only manifest script text that names `vitest`; the configuration check also requires a `test:*`
|
|
654
|
+
script name. An external wrapper whose text does not name `vitest` supplies no static Vitest fact
|
|
655
|
+
to infer for these checks.
|
|
656
|
+
|
|
657
|
+
The invocation reader also reads literal `-c <path>`, `--config <path>`, and `--config=<path>` values
|
|
658
|
+
in command order. A configuration value containing an unresolved shell expansion makes the whole reading
|
|
659
|
+
`undefined`. The executable keeps this contract in its own modules:
|
|
660
|
+
|
|
661
|
+
| Declaration | Summary |
|
|
662
|
+
| --------------------- | -------------------------------------------------------------------------------------------------- |
|
|
663
|
+
| `ScriptInvocations` | Lists the literal Vitest projects, configuration paths, and npm run scripts a shell command names. |
|
|
664
|
+
| `scriptToInvocations` | Reads the literal Vitest projects, configuration paths, and npm run scripts a shell command names. |
|
|
665
|
+
|
|
666
|
+
When a `test:*` script whose text names `vitest` names a configuration that the plan does not emit
|
|
667
|
+
and the target does not hold, the non-blocking `projects` question names the script and configuration
|
|
668
|
+
path. Its remedy asks you to add the configuration, or remove the script that names it and its
|
|
669
|
+
invocation from the `test` chain. When the plan emits `test:journey` and no chain from `test` reaches
|
|
670
|
+
`npm run test:journey` through literal `npm run` calls, that question asks you to insert the invocation
|
|
671
|
+
after `npm run test:app`. These advisories belong to `configs`
|
|
672
|
+
and remain report-only during `repair`: the command preserves the `test` chain and an unplanned
|
|
673
|
+
script. A configuration emitted by the plan or present in the target does not raise the absent
|
|
674
|
+
configuration advisory.
|
|
647
675
|
|
|
648
676
|
`audit` still completes the comparison and reports one non-blocking `projects` question when its
|
|
649
|
-
selection includes `configs`.
|
|
677
|
+
selection includes `configs`. It reports the earliest of the facts it finds; settling that fact and
|
|
678
|
+
re-running surfaces the next. A scoped audit that excludes `configs` omits that question. For a
|
|
650
679
|
literal absent project, its advisory tells the developer to register the project or remove the
|
|
651
680
|
script. For a planned project absent from the gate chains, the advisory reads the manifest after a
|
|
652
681
|
writable script projection. The `scripts` question owns an absent direct `test:<project>` line. The
|
|
@@ -876,14 +905,21 @@ because the shape is chosen once and read afterwards: `new` refuses the advisory
|
|
|
876
905
|
`repair` need the plan to describe and restore a target that already has that shape. A library
|
|
877
906
|
caller creating a workspace holds the same refusal, and the Compile section states it.
|
|
878
907
|
|
|
879
|
-
`bin`, `setup`, `guides`, `integration`, `conformance`, `service`, `vendors`, `global`,
|
|
880
|
-
`
|
|
908
|
+
`bin`, `setup`, `guides`, `integration`, `conformance`, `service`, `vendors`, `global`, `showcase`,
|
|
909
|
+
and `journey` are structural facts. Reading verbs set each only when the workspace physically ships the directory
|
|
881
910
|
or exact-case file that defines it, never because of the workspace's name and never because a
|
|
882
911
|
sibling fact is set.
|
|
883
912
|
|
|
884
|
-
`setup`
|
|
885
|
-
`
|
|
886
|
-
`test
|
|
913
|
+
The `setup` member is a `readonly SetupRuntime[]`, empty by default. Target inference adds
|
|
914
|
+
`browser` for the exact-case `tests/setupBrowser.test.ts` proof and `node` for every other root
|
|
915
|
+
`tests/setup*.test.ts` match, including `tests/setup.test.ts` and `tests/setupServer.test.ts`.
|
|
916
|
+
A nested or wrong-case match adds no runtime.
|
|
917
|
+
|
|
918
|
+
The `node` runtime registers the Node `setup` project, which loads `tests/setup.ts` and excludes
|
|
919
|
+
`tests/setupBrowser.test.ts`. The `browser` runtime registers `setup:browser`, which collects
|
|
920
|
+
only that browser proof and loads `tests/setup.ts` and `tests/setupBrowser.ts` through Playwright
|
|
921
|
+
Chromium. The generated manifest emits the selected `test:setup` and `test:setup:browser` scripts
|
|
922
|
+
and invokes them from `test`. Scaffold generates no setup proof for an empty setup seed.
|
|
887
923
|
|
|
888
924
|
A structural fact is read when a verb runs, not when the file appears. Writing
|
|
889
925
|
`tests/integration.test.ts` into a workspace sets the fact, but the root configuration on disk was
|
|
@@ -927,6 +963,30 @@ rather than withholding it.
|
|
|
927
963
|
no artifact, configuration, script, or dependency, and the gate reports a non-blocking question on
|
|
928
964
|
that field so the caller who set it learns it emitted nothing.
|
|
929
965
|
|
|
966
|
+
The library's `journey` flag defaults to `false`; `new` sets it when its `app` selection includes
|
|
967
|
+
`browser`. Reading verbs infer it from the wrapper's presence. The flag requires a browser application. Without that
|
|
968
|
+
application, it emits no journey configuration or script and raises a non-blocking `journey`
|
|
969
|
+
question. With that application, the content-owned root configuration defines
|
|
970
|
+
`appJourney(variant, variants)` and excludes `tests/app/browser/integration.test.ts` from the
|
|
971
|
+
ordinary `app:browser` project.
|
|
972
|
+
|
|
973
|
+
Edit the variant list in `configs/app/vite.journey.config.ts`. This wrapper is birth-owned:
|
|
974
|
+
scaffold creates it when absent and preserves your edits during `repair`. It imports
|
|
975
|
+
`JourneyVariant` from `@orkestrel/test`, declares `readonly JourneyVariant[]`, and seeds `desktop`
|
|
976
|
+
at 1280 × 800 and `compact` at 390 × 844 without a theme. Rename and extend those variants for
|
|
977
|
+
your application; apply themes through the application's interface in your tests.
|
|
978
|
+
|
|
979
|
+
The wrapper registers `journey:<name>` for each variant through the root factory. Each project
|
|
980
|
+
collects the browser integration suite alone, sets the variant viewport, and provides `variant`
|
|
981
|
+
as its name, `variants` as the declared list, and `capture` as a boolean. The root configuration
|
|
982
|
+
reads `process.env.CAPTURE === '1'` for that boolean. The generated `test:journey` script runs
|
|
983
|
+
`vitest run --config configs/app/vite.journey.config.ts --no-cache --reporter=dot`, and the generated
|
|
984
|
+
`test` chain runs it after the application projects. With the journey axis off, the ordinary
|
|
985
|
+
browser project retains its integration suite.
|
|
986
|
+
|
|
987
|
+
The generated browser resolver and gate cover Chromium alone. The emitted `configs/browsers.ts` doc
|
|
988
|
+
block states the condition that reopens engine selection, and is that condition's one home.
|
|
989
|
+
|
|
930
990
|
`createBlueprint` enforces shape only. Whether the name is a name, the version a version, and the
|
|
931
991
|
axis combination one this package can generate are the gate's laws, and the gate answers them with
|
|
932
992
|
questions. A blueprint the gate will refuse is still constructible, so one law lives in one place.
|
|
@@ -1089,6 +1149,29 @@ fetched bytes rather than prose this workspace wrote, and it reports a top-level
|
|
|
1089
1149
|
neither this package's own, nor `guides/README.md`, nor a catalog row, so an exclusion always
|
|
1090
1150
|
carries its evidence.
|
|
1091
1151
|
|
|
1152
|
+
The skill sweep reads named value and type imports from `@orkestrel/*` in every Markdown fence
|
|
1153
|
+
in `SKILL.md` and its named references, including fences inside lists and blockquotes. It resolves
|
|
1154
|
+
each entry through that package's exports map — the workspace's own manifest for the package the
|
|
1155
|
+
workspace publishes, and `node_modules` for every other package — and reads the declaration
|
|
1156
|
+
exports with Vite's Oxc parser without loading the runtime entry. A missing binding reports the
|
|
1157
|
+
skill file, the specifier, and the exported name. A fence the parser refuses reports a violation
|
|
1158
|
+
when its text names an `@orkestrel/` specifier, because error recovery drops the statements after
|
|
1159
|
+
the failure; a refused fence naming no such specifier stays outside the sweep. A package outside
|
|
1160
|
+
`BASE_DEV_DEPENDENCIES` reports a violation of its own.
|
|
1161
|
+
The sweep doesn't read identifiers in prose or table cells, indented code, default imports,
|
|
1162
|
+
namespace imports, or imports from other scopes. This proof checks exported names; it doesn't
|
|
1163
|
+
check call signatures or runtime behavior.
|
|
1164
|
+
The declaration reader follows exact exports-map keys and relative star and named re-exports.
|
|
1165
|
+
It reads exported functions, variables, classes, enums, interfaces, types, and local export lists.
|
|
1166
|
+
Each refused reading reports its own cause: an entry specifier outside the supported grammar, an
|
|
1167
|
+
absent package, an exports key the map lacks or maps through a wildcard, an array, a source alias,
|
|
1168
|
+
or a runtime path, a declaration file the package doesn't hold, a syntax error the parser raised, a
|
|
1169
|
+
re-exported name the target doesn't declare, and a refused declaration form — a default export, an
|
|
1170
|
+
export assignment, an ambient module, a namespace export, a star export alias, or a non-relative
|
|
1171
|
+
re-export. A file the branch already visited contributes the names it declares itself, so a named
|
|
1172
|
+
re-export through a cycle resolves against those declarations. Local export lists aren't
|
|
1173
|
+
typechecked, and ambiguous star exports aren't resolved semantically.
|
|
1174
|
+
|
|
1092
1175
|
The `surface` rule in `inspectPolicyWorkspace` compares live barrel exports and target-owned root
|
|
1093
1176
|
`tests/setup*.ts` exports with the hosted guides. It matches bare names case-sensitively across
|
|
1094
1177
|
environments and declaration kinds. Source names claimed by the target's own hosted guide are
|
|
@@ -1587,7 +1670,8 @@ except the manifest.
|
|
|
1587
1670
|
bare specifier, because `vite.config.ts` derives its `alias` record from these entries in order and
|
|
1588
1671
|
a bare specifier also matches its own subpaths. An `app` environment publishes nothing and maps no
|
|
1589
1672
|
such entry.
|
|
1590
|
-
- One template artifact, `configs/browsers.ts`, for a workspace selecting `browser` on either
|
|
1673
|
+
- One template artifact, `configs/browsers.ts`, for a workspace selecting `browser` on either
|
|
1674
|
+
environment axis or in its setup runtime list.
|
|
1591
1675
|
It resolves the Chromium the Playwright provider launches, and the root `vite.config.ts` calls it
|
|
1592
1676
|
once into `browserOptions` and passes that to every `playwright()` provider it configures. The
|
|
1593
1677
|
precedence is `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`, `PLAYWRIGHT_CHANNEL`, the
|