@orkestrel/scaffold 0.0.62 → 0.0.64
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/README.md +18 -103
- package/dist/bin/main.js +95 -27
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +2 -2
- package/dist/host/CLAUDE.md +6 -0
- package/dist/host/agents/orchestration.md +23 -15
- package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md +16 -16
- package/dist/host/agents/skills/enterprise-bootstrap/references/frontend-design.md +6 -6
- package/dist/host/agents/skills/enterprise-bootstrap/references/utilities.md +4 -4
- package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +5 -5
- package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +1 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +15 -15
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +43 -17
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +41 -16
- package/dist/host/claude/agents/orkestrel.md +56 -56
- package/dist/host/claude/agents/reviewer.md +13 -0
- package/dist/host/claude/rules/architecture.md +51 -45
- package/dist/host/claude/rules/documentation.md +18 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +1 -1
- package/dist/host/claude/rules/tests.md +12 -11
- package/dist/host/claude/rules/typescript.md +5 -0
- package/dist/host/claude/rules/workspace.md +23 -18
- package/dist/host/claude/rules/writing.md +4 -0
- package/dist/host/codex/agents/orkestrel.toml +3 -3
- package/dist/host/codex/agents/reviewer.toml +4 -2
- package/dist/host/configs/helpers.ts +311 -2
- package/dist/host/configs/policy.ts +1100 -51
- package/dist/host/dotfiles/oxlintrc.json +72 -1
- package/dist/host/guides/guide.md +749 -222
- package/dist/host/guides/scaffold.md +472 -378
- package/dist/host/manifest.json +34 -33
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +1200 -16
- package/dist/host/tests/policy.test.ts +157 -173
- package/dist/host/tests/setupPolicy.ts +522 -1007
- package/dist/src/core/index.cjs +373 -279
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +130 -120
- package/dist/src/core/index.d.ts +130 -120
- package/dist/src/core/index.js +373 -278
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +28 -21
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +38 -33
- package/dist/src/server/index.d.ts +38 -33
- package/dist/src/server/index.js +28 -21
- package/dist/src/server/index.js.map +1 -1
- package/package.json +17 -18
|
@@ -1,10 +1,7 @@
|
|
|
1
1
|
# Scaffold
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
> real directory, and writes the difference.
|
|
5
|
-
> entry points: `@orkestrel/scaffold` is the pure compiler and its data contracts, and
|
|
6
|
-
> `@orkestrel/scaffold/server` is the filesystem writer and the network reader. Source:
|
|
7
|
-
> [`src/core/index.ts`](../src/core/index.ts) and [`src/server/index.ts`](../src/server/index.ts).
|
|
3
|
+
> A compiler that turns a workspace specification into an ordered list of files, compares that list
|
|
4
|
+
> to a real directory, and writes the difference.
|
|
8
5
|
|
|
9
6
|
The package exists because every `@orkestrel` repository shares the same toolchain, the same agent
|
|
10
7
|
instructions, and the same root dotfiles. Keeping every copy of those files in agreement by hand
|
|
@@ -14,10 +11,10 @@ write the difference back.
|
|
|
14
11
|
|
|
15
12
|
That root stages the vendored set and the instruction canon, and a target meets them differently.
|
|
16
13
|
`HOST_PATHS` names the vendored set — the licence, the harness permission file, the
|
|
17
|
-
session-start hooks, the shared policy register, the shared policy
|
|
18
|
-
the shared configuration leaf and its proof, the byte-identical
|
|
19
|
-
a generated workspace starts from, never its own guide — and
|
|
20
|
-
the paths it selects, which the verbs write and compare.
|
|
14
|
+
session-start hooks, the shared policy register, the shared policy
|
|
15
|
+
proof, the shared policy plugin, the shared configuration leaf and its proof, the byte-identical
|
|
16
|
+
root dotfiles, and the guide mirrors a generated workspace starts from, never its own guide — and
|
|
17
|
+
each target carries its own copy of the paths it selects, which the verbs write and compare.
|
|
21
18
|
`CANON_PATHS` names the instruction canon — the coding and orchestration contracts, the rules, the
|
|
22
19
|
skills, the templates, the transport contracts, the agent roles, the bench configuration, and the
|
|
23
20
|
MCP registrations — which stays in one place and is published for reading. A target carries the
|
|
@@ -51,241 +48,240 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
51
48
|
|
|
52
49
|
#### Types
|
|
53
50
|
|
|
54
|
-
| Name | Kind | Summary
|
|
55
|
-
| ------------------- | ---- |
|
|
56
|
-
| `Artifact` | type |
|
|
57
|
-
| `BuildFormat` | type |
|
|
58
|
-
| `CatalogEntry` | type |
|
|
59
|
-
| `CompileStage` | type |
|
|
60
|
-
| `CompilerEventMap` | type |
|
|
61
|
-
| `HostFile` | type |
|
|
62
|
-
| `Drift` | type |
|
|
63
|
-
| `Environment` | type |
|
|
64
|
-
| `Finding` | type |
|
|
65
|
-
| `Group` | type |
|
|
66
|
-
| `Lookup` | type |
|
|
67
|
-
| `Mirror` | type |
|
|
68
|
-
| `Origin` | type |
|
|
69
|
-
| `Ownership` | type |
|
|
70
|
-
| `Release` | type |
|
|
71
|
-
| `ScaffoldErrorCode` | type |
|
|
72
|
-
| `Snapshot` | type |
|
|
51
|
+
| Name | Kind | Summary |
|
|
52
|
+
| ------------------- | ---- | ----------------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `Artifact` | type | Represents one file in a plan, discriminated by how its content is produced and what scaffold claims of it. |
|
|
54
|
+
| `BuildFormat` | type | Names one module format a published library environment builds. |
|
|
55
|
+
| `CatalogEntry` | type | Represents one package row of the fleet catalog. |
|
|
56
|
+
| `CompileStage` | type | Names the compile phases, in the order they run. |
|
|
57
|
+
| `CompilerEventMap` | type | Represents the compiler's observation channel. |
|
|
58
|
+
| `HostFile` | type | Represents one vendored file read from the repository, beside the target bytes it answers for. |
|
|
59
|
+
| `Drift` | type | Names how one target path compares to the artifact planned for it. |
|
|
60
|
+
| `Environment` | type | Names one environment a generated workspace selects on its `src` or `app` axis. |
|
|
61
|
+
| `Finding` | type | Represents one drift verdict against a target path. |
|
|
62
|
+
| `Group` | type | Names the artifact group a plan selects over. |
|
|
63
|
+
| `Lookup` | type | Names how an upstream lookup resolved: found, missing, unmatched, or failed. |
|
|
64
|
+
| `Mirror` | type | Represents one dependency guide fetched from upstream, beside the local mirror it answers for. |
|
|
65
|
+
| `Origin` | type | Names how an artifact's content is produced. |
|
|
66
|
+
| `Ownership` | type | Names what scaffold claims at an artifact's path. |
|
|
67
|
+
| `Release` | type | Represents one declared dependency range measured against a registry release. |
|
|
68
|
+
| `ScaffoldErrorCode` | type | Names the coded reasons a scaffold error is raised. |
|
|
69
|
+
| `Snapshot` | type | Holds exact lowercase hexadecimal target bytes keyed by artifact-relative path. |
|
|
73
70
|
|
|
74
71
|
#### Interfaces
|
|
75
72
|
|
|
76
|
-
| Name | Kind | Summary
|
|
77
|
-
| ----------------------- | --------- |
|
|
78
|
-
| `AppDefinition` | interface |
|
|
79
|
-
| `ArtifactBase` | interface |
|
|
80
|
-
| `Audit` | interface |
|
|
81
|
-
| `Blueprint` | interface |
|
|
82
|
-
| `CompileFailure` | interface |
|
|
83
|
-
| `CompileRecord` | interface |
|
|
84
|
-
| `CompilerInterface` | interface |
|
|
85
|
-
| `CompilerOptions` | interface |
|
|
86
|
-
| `ContentArtifact` | interface |
|
|
87
|
-
| `Dependency` | interface |
|
|
88
|
-
| `DependencyPinSet` | interface |
|
|
89
|
-
| `HostArtifact` | interface |
|
|
90
|
-
| `HydratedArtifact` | interface |
|
|
91
|
-
| `ManifestDependencySet` | interface |
|
|
92
|
-
| `ManifestRegionSet` | interface |
|
|
93
|
-
| `ManifestScript` | interface |
|
|
94
|
-
| `Override` | interface |
|
|
95
|
-
| `Plan` | interface |
|
|
96
|
-
| `PlanSummary` | interface |
|
|
97
|
-
| `Question` | interface |
|
|
98
|
-
| `Scaffolding` | interface |
|
|
99
|
-
| `SrcDefinition` | interface |
|
|
100
|
-
| `ViteMachinery` | interface |
|
|
73
|
+
| Name | Kind | Summary |
|
|
74
|
+
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `AppDefinition` | interface | Describes the configuration and runtime-entry settings one private `app` environment contributes. |
|
|
76
|
+
| `ArtifactBase` | interface | Describes the fields every planned file carries. |
|
|
77
|
+
| `Audit` | interface | Represents the whole comparison of a plan against a target's current content. |
|
|
78
|
+
| `Blueprint` | interface | Represents the closed, JSON-serializable workspace specification. |
|
|
79
|
+
| `CompileFailure` | interface | Represents the coded reason one compile stage failed. |
|
|
80
|
+
| `CompileRecord` | interface | Holds the input and output snapshot of one compile stage. |
|
|
81
|
+
| `CompilerInterface` | interface | Describes the compilation contract: pure, synchronous, and host-independent. |
|
|
82
|
+
| `CompilerOptions` | interface | Represents the options for the compiler. |
|
|
83
|
+
| `ContentArtifact` | interface | Represents a text file produced by the template or computed compilation path. |
|
|
84
|
+
| `Dependency` | interface | Represents one runtime `@orkestrel/*` dependency of a generated workspace. |
|
|
85
|
+
| `DependencyPinSet` | interface | Describes the runtime and development sections a range-writing operation may change. |
|
|
86
|
+
| `HostArtifact` | interface | Represents a file byte-copied from the vendored data root, planned before its bytes are read. |
|
|
87
|
+
| `HydratedArtifact` | interface | Represents a vendored file whose exact bytes have been read, so its content can be compared. |
|
|
88
|
+
| `ManifestDependencySet` | interface | Describes the runtime, development, and peer sections read from an existing package manifest. |
|
|
89
|
+
| `ManifestRegionSet` | interface | Describes the manifest regions a writing operation may change. |
|
|
90
|
+
| `ManifestScript` | interface | Represents one manifest script a region-writing operation may replace. |
|
|
91
|
+
| `Override` | interface | Represents one artifact override. |
|
|
92
|
+
| `Plan` | interface | Holds the compiled, ordered artifact list and the selection it covers. |
|
|
93
|
+
| `PlanSummary` | interface | Represents the tally of one plan by artifact origin. |
|
|
94
|
+
| `Question` | interface | Represents one validation issue raised against a blueprint or a plan. |
|
|
95
|
+
| `Scaffolding` | interface | Represents the replayable outcome of one compile. |
|
|
96
|
+
| `SrcDefinition` | interface | Describes the build and export settings one published `src` environment contributes. |
|
|
97
|
+
| `ViteMachinery` | interface | Names which host-specific pipelines a generated root Vite configuration carries. |
|
|
101
98
|
|
|
102
99
|
#### Constants
|
|
103
100
|
|
|
104
|
-
| Name | Kind | Summary
|
|
105
|
-
| --------------------------------- | ----- |
|
|
106
|
-
| `APP_BROWSER_DEV_DEPENDENCIES` | const |
|
|
107
|
-
| `APP_DEV_DEPENDENCIES` | const |
|
|
108
|
-
| `APP_MATRIX` | const |
|
|
109
|
-
| `APP_SERVER_DEV_DEPENDENCIES` | const |
|
|
110
|
-
| `ARTIFACT_TEMPLATES` | const |
|
|
111
|
-
| `BASE_DEV_DEPENDENCIES` | const |
|
|
112
|
-
| `BIN_CONFIGS` | const |
|
|
113
|
-
| `BIN_ENTRY_PATH` | const |
|
|
114
|
-
| `CANON_PATHS` | const |
|
|
115
|
-
| `CATALOG_AGENT_PATH` | const |
|
|
116
|
-
| `CATALOG_CLOSING_MARKER` | const |
|
|
117
|
-
| `CATALOG_OPENING_MARKER` | const |
|
|
118
|
-
| `CONFIG_TEMPLATES` | const |
|
|
119
|
-
| `CONFORMANCE_TEST_PATH` | const |
|
|
120
|
-
| `CONTROL_CHARACTER_PATTERN` | const | Unicode controls, formatting controls, and line and paragraph separators rejected in text.
|
|
121
|
-
| `DECLARATION_DEV_DEPENDENCIES` | const |
|
|
122
|
-
| `DEFAULT_ENGINES` | const |
|
|
123
|
-
| `DEFAULT_VERSION` | const |
|
|
124
|
-
| `DEPENDENCY_NAME_PATTERN` | const |
|
|
125
|
-
| `DISTRIBUTION_TEST_PATH` | const |
|
|
126
|
-
| `ENGINES_PATTERN` | const |
|
|
127
|
-
| `ENVIRONMENTS` | const |
|
|
128
|
-
| `EXECUTABLE_PATHS` | const |
|
|
129
|
-
| `EXTRA_RANGE_PATTERN` | const |
|
|
130
|
-
| `FLOOR_RANGE_PATTERN` | const |
|
|
131
|
-
| `FOREIGN_NAME_PATTERN` | const |
|
|
132
|
-
| `GLOBAL_SETUP_PATH` | const |
|
|
133
|
-
| `GROUPS` | const |
|
|
134
|
-
| `GUIDES_TEST_PATH` | const |
|
|
135
|
-
| `HEX_PATTERN` | const |
|
|
136
|
-
| `HOST_PATHS` | const |
|
|
137
|
-
| `HOST_INVENTORY_PATH` | const |
|
|
138
|
-
| `INTEGRATION_TEST_PATH` | const |
|
|
139
|
-
| `INVALID_PATH_CHARACTER_PATTERN` | const |
|
|
140
|
-
| `MANIFEST_PATH` | const |
|
|
141
|
-
| `MAX_ARTIFACT_BYTES` | const |
|
|
142
|
-
| `MAX_ARTIFACT_HEX_LENGTH` | const |
|
|
143
|
-
| `MAX_AUDIT_FINDINGS` | const |
|
|
144
|
-
| `MAX_COLLECTION_ITEMS` | const |
|
|
145
|
-
| `MAX_DEPENDENCY_NAME_LENGTH` | const |
|
|
146
|
-
| `MAX_MANIFEST_BYTES` | const |
|
|
147
|
-
| `MAX_NAME_LENGTH` | const |
|
|
148
|
-
| `MAX_PATH_LENGTH` | const |
|
|
149
|
-
| `MAX_RANGE_LENGTH` | const |
|
|
150
|
-
| `MAX_REGISTRY_BYTES` | const |
|
|
151
|
-
| `MAX_SCRIPT_LENGTH` | const |
|
|
152
|
-
| `MAX_TOTAL_ARTIFACT_BYTES` | const |
|
|
153
|
-
| `MAX_TOTAL_REGISTRY_BYTES` | const |
|
|
154
|
-
| `MINIMUM_NODE_VERSION` | const |
|
|
155
|
-
| `NAME_PATTERN` | const |
|
|
156
|
-
| `ORCHESTRATION_PATH_NAMES` | const |
|
|
157
|
-
| `ORCHESTRATION_PATH_PREFIXES` | const |
|
|
158
|
-
| `ORKESTREL_RANGE_PATTERN` | const |
|
|
159
|
-
| `PRINT_WIDTH` | const |
|
|
160
|
-
| `RELEASE_PROOF_COMMAND` | const |
|
|
161
|
-
| `SERVICE_SCRIPT_PATH` | const |
|
|
162
|
-
| `SERVICE_SETUP_PATH` | const |
|
|
163
|
-
| `SERVICE_TEST_INCLUDE` | const |
|
|
164
|
-
| `SHOWCASE_CONFIG_PATH` | const |
|
|
165
|
-
| `SHOWCASE_DEV_DEPENDENCIES` | const |
|
|
166
|
-
| `SOURCE_BROWSER_DEV_DEPENDENCIES` | const |
|
|
167
|
-
| `SRC_MATRIX` | const |
|
|
168
|
-
| `TAB_WIDTH` | const |
|
|
169
|
-
| `VERSION_PATTERN` | const |
|
|
170
|
-
| `WORKSPACE_OWNED_PATHS` | const |
|
|
101
|
+
| Name | Kind | Summary |
|
|
102
|
+
| --------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ |
|
|
103
|
+
| `APP_BROWSER_DEV_DEPENDENCIES` | const | Lists the development dependencies a private Vue browser application adds. |
|
|
104
|
+
| `APP_DEV_DEPENDENCIES` | const | Names the development dependency every private `app` environment adds. |
|
|
105
|
+
| `APP_MATRIX` | const | Holds the configuration and runtime-entry settings each private `app` environment contributes, frozen. |
|
|
106
|
+
| `APP_SERVER_DEV_DEPENDENCIES` | const | Lists the development dependencies a private server application adds. |
|
|
107
|
+
| `ARTIFACT_TEMPLATES` | const | Holds formatter-stable template text for source, test, document, guide, and service artifacts. |
|
|
108
|
+
| `BASE_DEV_DEPENDENCIES` | const | Holds the tooling versions scaffold and every generated workspace share. |
|
|
109
|
+
| `BIN_CONFIGS` | const | Lists the configuration files a workspace that ships its own executable adds, frozen. |
|
|
110
|
+
| `BIN_ENTRY_PATH` | const | Names the executable entry whose presence makes a workspace `bin`. |
|
|
111
|
+
| `CANON_PATHS` | const | Lists the instruction-canon paths staged for reading rather than for a target, frozen. |
|
|
112
|
+
| `CATALOG_AGENT_PATH` | const | Names the agent file whose marker-bounded package table the catalog verb alone owns. |
|
|
113
|
+
| `CATALOG_CLOSING_MARKER` | const | Names the marker closing the package table inside `CATALOG_AGENT_PATH`. |
|
|
114
|
+
| `CATALOG_OPENING_MARKER` | const | Names the marker opening the package table inside `CATALOG_AGENT_PATH`. |
|
|
115
|
+
| `CONFIG_TEMPLATES` | const | Holds formatter-stable template text for every configuration artifact. |
|
|
116
|
+
| `CONFORMANCE_TEST_PATH` | const | Names the official-tooling drift proof whose presence makes a workspace `conformance`. |
|
|
117
|
+
| `CONTROL_CHARACTER_PATTERN` | const | Matches the Unicode controls, formatting controls, and line and paragraph separators rejected in text. |
|
|
118
|
+
| `DECLARATION_DEV_DEPENDENCIES` | const | Lists the development dependencies that roll declarations up for published source. |
|
|
119
|
+
| `DEFAULT_ENGINES` | const | Names the `engines.node` range a workspace starts with. |
|
|
120
|
+
| `DEFAULT_VERSION` | const | Names the version a workspace starts at. |
|
|
121
|
+
| `DEPENDENCY_NAME_PATTERN` | const | Matches the runtime dependency name syntax: the `@orkestrel` scope and a bare name. |
|
|
122
|
+
| `DISTRIBUTION_TEST_PATH` | const | Names the generated packed-package proof every publishing workspace is planned at. |
|
|
123
|
+
| `ENGINES_PATTERN` | const | Matches the minimum-Node engine syntax a blueprint declares. |
|
|
124
|
+
| `ENVIRONMENTS` | const | Lists the `Environment` values, frozen. |
|
|
125
|
+
| `EXECUTABLE_PATHS` | const | Lists the vendored paths a target receives with its executable bit set, frozen. |
|
|
126
|
+
| `EXTRA_RANGE_PATTERN` | const | Matches the registry-only semver subset accepted for a development extra's range. |
|
|
127
|
+
| `FLOOR_RANGE_PATTERN` | const | Matches the exact `major.minor.patch` floor accepted for a foreign peer's range. |
|
|
128
|
+
| `FOREIGN_NAME_PATTERN` | const | Matches the package name syntax for a dependency this package does not publish. |
|
|
129
|
+
| `GLOBAL_SETUP_PATH` | const | Names the shared Vitest global-setup module whose presence makes a workspace `global`. |
|
|
130
|
+
| `GROUPS` | const | Lists the `Group` values in plan order, frozen. |
|
|
131
|
+
| `GUIDES_TEST_PATH` | const | Names the package-owned guide-parity entry used by `test:guides` and to select the `guides` project. |
|
|
132
|
+
| `HEX_PATTERN` | const | Matches exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. |
|
|
133
|
+
| `HOST_PATHS` | const | Lists the paths a target receives from the vendored data root, frozen. |
|
|
134
|
+
| `HOST_INVENTORY_PATH` | const | Names the repository-relative path where the committed vendored-file inventory is served. |
|
|
135
|
+
| `INTEGRATION_TEST_PATH` | const | Names the cross-environment composition proof whose presence makes a workspace `integration`. |
|
|
136
|
+
| `INVALID_PATH_CHARACTER_PATTERN` | const | Matches the visible characters a target-relative path and a Markdown path cell both forbid. |
|
|
137
|
+
| `MANIFEST_PATH` | const | Names the manifest path every compiler plan emits with birth ownership. |
|
|
138
|
+
| `MAX_ARTIFACT_BYTES` | const | Caps the bytes accepted for one artifact. |
|
|
139
|
+
| `MAX_ARTIFACT_HEX_LENGTH` | const | Caps the length of the hexadecimal string carrying one artifact's bytes. |
|
|
140
|
+
| `MAX_AUDIT_FINDINGS` | const | Caps the findings one audit can produce from a bounded plan and snapshot. |
|
|
141
|
+
| `MAX_COLLECTION_ITEMS` | const | Caps the items accepted in one public collection. |
|
|
142
|
+
| `MAX_DEPENDENCY_NAME_LENGTH` | const | Sets the maximum dependency package name length, scope included, as the registry caps it. |
|
|
143
|
+
| `MAX_MANIFEST_BYTES` | const | Caps the bytes accepted for one package or vendored-host manifest. |
|
|
144
|
+
| `MAX_NAME_LENGTH` | const | Caps the bare workspace name length. |
|
|
145
|
+
| `MAX_PATH_LENGTH` | const | Caps the length of one path, matching the longest a supported filesystem accepts. |
|
|
146
|
+
| `MAX_RANGE_LENGTH` | const | Caps the length of one declared package range. |
|
|
147
|
+
| `MAX_REGISTRY_BYTES` | const | Caps the decoded bytes accepted from one registry response. |
|
|
148
|
+
| `MAX_SCRIPT_LENGTH` | const | Caps the length of one manifest script name or command. |
|
|
149
|
+
| `MAX_TOTAL_ARTIFACT_BYTES` | const | Caps the bytes retained across one whole plan or audit. |
|
|
150
|
+
| `MAX_TOTAL_REGISTRY_BYTES` | const | Caps the decoded bytes accepted across one registry-reading call. |
|
|
151
|
+
| `MINIMUM_NODE_VERSION` | const | Names the oldest Node version the generated toolchain supports. |
|
|
152
|
+
| `NAME_PATTERN` | const | Matches the bare workspace name syntax: lowercase alphanumeric with hyphens, letter first. |
|
|
153
|
+
| `ORCHESTRATION_PATH_NAMES` | const | Lists the exact root paths that wire an agent bench or own an orchestration directory, frozen. |
|
|
154
|
+
| `ORCHESTRATION_PATH_PREFIXES` | const | Lists the path prefixes whose contents instruct or wire an agent, frozen. |
|
|
155
|
+
| `ORKESTREL_RANGE_PATTERN` | const | Matches the exact caret-pinned pre-1.0 range accepted for an `@orkestrel/*` runtime dependency. |
|
|
156
|
+
| `PRINT_WIDTH` | const | Caps the columns one emitted line may occupy, matching `printWidth` in `.oxfmtrc.json`. |
|
|
157
|
+
| `RELEASE_PROOF_COMMAND` | const | Names the `prepublishOnly` row that runs the packed-package proof against a real registry. |
|
|
158
|
+
| `SERVICE_SCRIPT_PATH` | const | Names the provisioner skeleton a workspace with declared service vendors is given once. |
|
|
159
|
+
| `SERVICE_SETUP_PATH` | const | Names the live-service readiness module whose presence makes a workspace `service`. |
|
|
160
|
+
| `SERVICE_TEST_INCLUDE` | const | Names the include the live-service project covers, which is a directory rather than one proof. |
|
|
161
|
+
| `SHOWCASE_CONFIG_PATH` | const | Names the Vite wrapper whose presence makes a workspace `showcase`. |
|
|
162
|
+
| `SHOWCASE_DEV_DEPENDENCIES` | const | Names the development dependency used only by the optional single-file showcase build. |
|
|
163
|
+
| `SOURCE_BROWSER_DEV_DEPENDENCIES` | const | Lists the development dependencies a published browser `src` environment adds. |
|
|
164
|
+
| `SRC_MATRIX` | const | Holds the build and export settings each published `src` environment contributes, frozen. |
|
|
165
|
+
| `TAB_WIDTH` | const | Sets the columns one tab occupies when the formatter measures a line, matching `tabWidth`. |
|
|
166
|
+
| `VERSION_PATTERN` | const | Matches the exact `major.minor.patch` version syntax a blueprint declares. |
|
|
167
|
+
| `WORKSPACE_OWNED_PATHS` | const | Lists the vendored paths whose present bytes belong to each workspace, frozen. |
|
|
171
168
|
|
|
172
169
|
#### Guards
|
|
173
170
|
|
|
174
|
-
| Name | Kind | Summary
|
|
175
|
-
| ------------------- | -------- |
|
|
176
|
-
| `isArtifact` | const |
|
|
177
|
-
| `isAudit` | const |
|
|
178
|
-
| `isBlueprint` | const |
|
|
179
|
-
| `isCatalogEntry` | const |
|
|
180
|
-
| `isCollection` | function |
|
|
181
|
-
| `isCompilerHooks` | const |
|
|
182
|
-
| `isCompilerOptions` | const |
|
|
183
|
-
| `isContent` | const |
|
|
184
|
-
| `isDependency` | const |
|
|
185
|
-
| `isDependencyName` | const |
|
|
186
|
-
| `isEnvironment` | const |
|
|
187
|
-
| `isFinding` | const |
|
|
188
|
-
| `isGroup` | const |
|
|
189
|
-
| `isGroups` | const |
|
|
190
|
-
| `isHex` | const |
|
|
191
|
-
| `isManifestScript` | const |
|
|
192
|
-
| `isMirror` | const |
|
|
193
|
-
| `isOverride` | const |
|
|
194
|
-
| `isPath` | function |
|
|
195
|
-
| `isPlan` | const |
|
|
196
|
-
| `isQuestion` | const |
|
|
197
|
-
| `isScaffoldError` | function |
|
|
198
|
-
| `isSnapshot` | function |
|
|
171
|
+
| Name | Kind | Summary |
|
|
172
|
+
| ------------------- | -------- | --------------------------------------------------------------------------------- |
|
|
173
|
+
| `isArtifact` | const | Narrows a value to an `Artifact`. |
|
|
174
|
+
| `isAudit` | const | Narrows a value to an `Audit`. |
|
|
175
|
+
| `isBlueprint` | const | Narrows a value to a `Blueprint`. |
|
|
176
|
+
| `isCatalogEntry` | const | Narrows a value to a `CatalogEntry`. |
|
|
177
|
+
| `isCollection` | function | Narrows a value to an array within the limit one public collection accepts. |
|
|
178
|
+
| `isCompilerHooks` | const | Narrows a value to the compiler's initial listener record. |
|
|
179
|
+
| `isCompilerOptions` | const | Narrows a value to `CompilerOptions`. |
|
|
180
|
+
| `isContent` | const | Narrows a value to text this package will accept as one artifact's content. |
|
|
181
|
+
| `isDependency` | const | Narrows a value to a `Dependency`. |
|
|
182
|
+
| `isDependencyName` | const | Narrows a value to the scoped package name a runtime dependency carries. |
|
|
183
|
+
| `isEnvironment` | const | Narrows a value to one `Environment` a workspace may select. |
|
|
184
|
+
| `isFinding` | const | Narrows a value to a `Finding`. |
|
|
185
|
+
| `isGroup` | const | Narrows a value to one `Group` a plan selects over. |
|
|
186
|
+
| `isGroups` | const | Narrows a value to a bounded group selection. |
|
|
187
|
+
| `isHex` | const | Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit. |
|
|
188
|
+
| `isManifestScript` | const | Narrows a value to a `ManifestScript`. |
|
|
189
|
+
| `isMirror` | const | Narrows a value to a `Mirror`. |
|
|
190
|
+
| `isOverride` | const | Narrows a value to an `Override`. |
|
|
191
|
+
| `isPath` | function | Narrows a value to a logical target-relative path. |
|
|
192
|
+
| `isPlan` | const | Narrows a value to a `Plan`. |
|
|
193
|
+
| `isQuestion` | const | Narrows a value to a `Question`. |
|
|
194
|
+
| `isScaffoldError` | function | Narrows a caught value to a `ScaffoldError`. |
|
|
195
|
+
| `isSnapshot` | function | Narrows a value to a `Snapshot`. |
|
|
199
196
|
|
|
200
197
|
#### Parsers
|
|
201
198
|
|
|
202
|
-
| Name | Kind | Summary
|
|
203
|
-
| ---------------------- | -------- |
|
|
204
|
-
| `parseBlueprint` | function |
|
|
205
|
-
| `parseCompilerOptions` | function |
|
|
206
|
-
| `parseGroups` | function |
|
|
207
|
-
| `parseSnapshot` | function |
|
|
199
|
+
| Name | Kind | Summary |
|
|
200
|
+
| ---------------------- | -------- | ------------------------------------------------ |
|
|
201
|
+
| `parseBlueprint` | function | Coerces an untrusted value to a `Blueprint`. |
|
|
202
|
+
| `parseCompilerOptions` | function | Coerces an untrusted value to `CompilerOptions`. |
|
|
203
|
+
| `parseGroups` | function | Coerces an untrusted value to a group selection. |
|
|
204
|
+
| `parseSnapshot` | function | Coerces an untrusted value to a `Snapshot`. |
|
|
208
205
|
|
|
209
206
|
#### Helpers
|
|
210
207
|
|
|
211
|
-
| Name | Kind | Summary
|
|
212
|
-
| --------------------------- | -------- |
|
|
213
|
-
| `artifactToFinding` | function |
|
|
214
|
-
| `artifactToHex` | function |
|
|
215
|
-
| `bytesToHex` | function |
|
|
216
|
-
| `catalogToLayers` | function |
|
|
217
|
-
| `cloneValue` | function |
|
|
218
|
-
| `compareVersions` | function |
|
|
219
|
-
| `computeBytes` | function |
|
|
220
|
-
| `computeHash` | function |
|
|
221
|
-
| `contentToHex` | function |
|
|
222
|
-
| `extractRangeMajor` | function |
|
|
223
|
-
| `extractVersion` | function |
|
|
224
|
-
| `inferDrift` | function |
|
|
225
|
-
| `inferGroup` | function |
|
|
226
|
-
| `isCanonPath` | function |
|
|
227
|
-
| `isDeferredPath` | function |
|
|
228
|
-
| `isFloorPath` | function |
|
|
229
|
-
| `isRetainedPath` | function |
|
|
230
|
-
| `manifestToDependencies` | function |
|
|
231
|
-
| `manifestToName` | function |
|
|
232
|
-
| `matchesDriftReachability` | function |
|
|
233
|
-
| `matchesEngines` | function |
|
|
234
|
-
| `matchesOrchestrationPath` | function |
|
|
235
|
-
| `matchesPrintWidth` | function |
|
|
236
|
-
| `matchesRange` | function |
|
|
237
|
-
| `nameToGuide` | function |
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
| `
|
|
241
|
-
| `
|
|
242
|
-
| `
|
|
243
|
-
| `srcToRoot` | function | Select the single published environment a package root points at. |
|
|
208
|
+
| Name | Kind | Summary |
|
|
209
|
+
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
210
|
+
| `artifactToFinding` | function | Projects one planned artifact and the bytes found at its path into a verdict. |
|
|
211
|
+
| `artifactToHex` | function | Projects an artifact to the exact bytes it claims, as hexadecimal. |
|
|
212
|
+
| `bytesToHex` | function | Encodes bytes as exact lowercase hexadecimal text. |
|
|
213
|
+
| `catalogToLayers` | function | Projects a catalog into the layers it publishes in. |
|
|
214
|
+
| `cloneValue` | function | Snapshots an untrusted value into exact JSON data the caller owns. |
|
|
215
|
+
| `compareVersions` | function | Compares two versions by their numeric components. |
|
|
216
|
+
| `computeBytes` | function | Counts the UTF-8 bytes text encodes to. |
|
|
217
|
+
| `computeHash` | function | Computes the deterministic content identity of text. |
|
|
218
|
+
| `contentToHex` | function | Encodes text as the exact lowercase hexadecimal form of its UTF-8 bytes. |
|
|
219
|
+
| `extractRangeMajor` | function | Extracts the major component of an admitted dependency range. |
|
|
220
|
+
| `extractVersion` | function | Extracts the major, minor, and patch components of an exact version. |
|
|
221
|
+
| `inferDrift` | function | Infers how one target path compares to the artifact planned for it. |
|
|
222
|
+
| `inferGroup` | function | Infers the `Group` a path belongs to. |
|
|
223
|
+
| `isCanonPath` | function | Checks whether a path belongs to the instruction canon a target reads rather than holds. |
|
|
224
|
+
| `isDeferredPath` | function | Checks whether another surface owns the vendored bytes at a path. |
|
|
225
|
+
| `isFloorPath` | function | Checks whether a destination's floor bytes survive a live overlay. |
|
|
226
|
+
| `isRetainedPath` | function | Checks whether another surface owns a target's present bytes at a path. |
|
|
227
|
+
| `manifestToDependencies` | function | Projects a package manifest's text to the `@orkestrel/*` packages each dependency section declares. |
|
|
228
|
+
| `manifestToName` | function | Projects a package manifest's text to its own name. |
|
|
229
|
+
| `matchesDriftReachability` | function | Tests whether `inferDrift` could have produced a finding for an ownership. |
|
|
230
|
+
| `matchesEngines` | function | Tests whether a declared engines floor is at or above the supported minimum. |
|
|
231
|
+
| `matchesOrchestrationPath` | function | Tests whether a path instructs or wires an agent rather than the toolchain. |
|
|
232
|
+
| `matchesPrintWidth` | function | Tests whether one emitted line fits the vendored formatter width. |
|
|
233
|
+
| `matchesRange` | function | Tests whether a declared range already admits a published version. |
|
|
234
|
+
| `nameToGuide` | function | Derives the guide mirror path a package name answers for. |
|
|
235
|
+
| `planToSummary` | function | Projects a plan into its tally by artifact origin. |
|
|
236
|
+
| `selectGroups` | function | Selects the groups a compile covers, in plan order. |
|
|
237
|
+
| `selectHostPaths` | function | Selects the host paths a named workspace vendors. |
|
|
238
|
+
| `serializeTypeScriptString` | function | Serializes one string as a single-quoted TypeScript literal. |
|
|
239
|
+
| `srcToRoot` | function | Selects the single published environment a package root points at. |
|
|
244
240
|
|
|
245
241
|
#### Compilers
|
|
246
242
|
|
|
247
|
-
| Name | Kind | Summary
|
|
248
|
-
| ----------------------------------- | -------- |
|
|
249
|
-
| `applyOverrides` | function |
|
|
250
|
-
| `artifactsToQuestions` | function |
|
|
251
|
-
| `blueprintToConfigArtifacts` | function |
|
|
252
|
-
| `blueprintToDevDependencies` | function |
|
|
253
|
-
| `blueprintToDocumentArtifacts` | function |
|
|
254
|
-
| `blueprintToGuideArtifacts` | function |
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `overridesToQuestions` | function |
|
|
268
|
-
| `pathToCondition` | function |
|
|
269
|
-
| `planToFindings` | function |
|
|
270
|
-
| `planToHash` | function |
|
|
271
|
-
| `replaceManifestRanges` | function |
|
|
272
|
-
| `replaceManifestScripts` | function |
|
|
273
|
-
| `replacePlanRanges` | function |
|
|
274
|
-
| `srcToEntry` | function |
|
|
275
|
-
| `srcToExports` | function |
|
|
243
|
+
| Name | Kind | Summary |
|
|
244
|
+
| ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
|
|
245
|
+
| `applyOverrides` | function | Replaces the content of every drafted artifact an override names. |
|
|
246
|
+
| `artifactsToQuestions` | function | Measures a drafted artifact list against the laws a whole plan decides. |
|
|
247
|
+
| `blueprintToConfigArtifacts` | function | Compiles every artifact in the `configs` group. |
|
|
248
|
+
| `blueprintToDevDependencies` | function | Projects a blueprint into the development dependencies its manifest declares. |
|
|
249
|
+
| `blueprintToDocumentArtifacts` | function | Compiles the generated workspace's root documentation. |
|
|
250
|
+
| `blueprintToGuideArtifacts` | function | Compiles the generated workspace's guide index. |
|
|
251
|
+
| `blueprintToHostArtifacts` | function | Compiles the vendored host artifacts a workspace plans. |
|
|
252
|
+
| `blueprintToMachinery` | function | Derives the host-specific machinery a generated root Vite configuration carries. |
|
|
253
|
+
| `blueprintToManifest` | function | Compiles a blueprint into its `package.json` content. |
|
|
254
|
+
| `blueprintToOrchestrationArtifacts` | function | Compiles the blueprint-dependent orchestration artifacts. |
|
|
255
|
+
| `blueprintToQuestions` | function | Measures a blueprint against every law its own fields decide. |
|
|
256
|
+
| `blueprintToRootTsconfig` | function | Compiles the root TypeScript configuration for a blueprint. |
|
|
257
|
+
| `blueprintToRootVite` | function | Compiles the root Vite and Vitest configuration for a blueprint. |
|
|
258
|
+
| `blueprintToScripts` | function | Projects a blueprint into the scripts its manifest declares. |
|
|
259
|
+
| `blueprintToSourceArtifacts` | function | Compiles every artifact in the `source` group. |
|
|
260
|
+
| `blueprintToTestArtifacts` | function | Compiles every artifact in the `tests` group that is not vendored from the host. |
|
|
261
|
+
| `blueprintToWritableScripts` | function | Projects a blueprint into the manifest scripts a region write may replace. |
|
|
262
|
+
| `dependenciesToQuestions` | function | Measures one declared package list against the name and range syntax it accepts. |
|
|
263
|
+
| `overridesToQuestions` | function | Measures a blueprint's overrides against the artifacts drafted for it. |
|
|
264
|
+
| `pathToCondition` | function | Builds one `exports` condition block for a built environment. |
|
|
265
|
+
| `planToFindings` | function | Compares a plan against a target's current content. |
|
|
266
|
+
| `planToHash` | function | Computes a plan's content identity. |
|
|
267
|
+
| `replaceManifestRanges` | function | Replaces the runtime and development dependency ranges in package manifest text, and never a peer range. |
|
|
268
|
+
| `replaceManifestScripts` | function | Replaces named script values in package manifest text. |
|
|
269
|
+
| `replacePlanRanges` | function | Replaces dependency ranges in a plan's manifest and recomputes its identity. |
|
|
270
|
+
| `srcToEntry` | function | Projects a published selection into the manifest's entry fields. |
|
|
271
|
+
| `srcToExports` | function | Projects a published selection into the manifest's `exports` map. |
|
|
276
272
|
|
|
277
273
|
#### Factories
|
|
278
274
|
|
|
279
|
-
| Name | Kind | Summary
|
|
280
|
-
| ----------------- | -------- |
|
|
281
|
-
| `createBlueprint` | function |
|
|
275
|
+
| Name | Kind | Summary |
|
|
276
|
+
| ----------------- | -------- | ---------------------------------------------------------------------------------- |
|
|
277
|
+
| `createBlueprint` | function | Constructs a `Blueprint` from a name and the fields that differ from the defaults. |
|
|
282
278
|
|
|
283
279
|
#### Classes
|
|
284
280
|
|
|
285
|
-
| Name | Kind | Summary
|
|
286
|
-
| --------------- | ----- |
|
|
287
|
-
| `Compiler` | class |
|
|
288
|
-
| `ScaffoldError` | class |
|
|
281
|
+
| Name | Kind | Summary |
|
|
282
|
+
| --------------- | ----- | -------------------------------------------------------------------------------------- |
|
|
283
|
+
| `Compiler` | class | Represents the compile spine: draft, gate, pin, run in that order over a blueprint. |
|
|
284
|
+
| `ScaffoldError` | class | Represents the one error this package throws, carrying the coded reason it was raised. |
|
|
289
285
|
|
|
290
286
|
### Server
|
|
291
287
|
|
|
@@ -294,134 +290,134 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
294
290
|
|
|
295
291
|
#### Types
|
|
296
292
|
|
|
297
|
-
| Name | Kind | Summary
|
|
298
|
-
| ---------------------- | ---- |
|
|
299
|
-
| `MaterializerEventMap` | type |
|
|
300
|
-
| `UpstreamEventMap` | type |
|
|
293
|
+
| Name | Kind | Summary |
|
|
294
|
+
| ---------------------- | ---- | ----------------------------------------------------- |
|
|
295
|
+
| `MaterializerEventMap` | type | Represents the materializer's observation channel. |
|
|
296
|
+
| `UpstreamEventMap` | type | Represents the upstream reader's observation channel. |
|
|
301
297
|
|
|
302
298
|
#### Interfaces
|
|
303
299
|
|
|
304
|
-
| Name | Kind | Summary
|
|
305
|
-
| ----------------------- | --------- |
|
|
306
|
-
| `BytesReadResult` | interface |
|
|
307
|
-
| `Host` | interface |
|
|
308
|
-
| `HostInventory` | interface |
|
|
309
|
-
| `HostManifest` | interface |
|
|
310
|
-
| `ManifestEntry` | interface |
|
|
311
|
-
| `MaterializeResult` | interface |
|
|
312
|
-
| `MaterializerInterface` | interface |
|
|
313
|
-
| `MaterializerOptions` | interface |
|
|
314
|
-
| `ReadAllowance` | interface |
|
|
315
|
-
| `TextReadResult` | interface |
|
|
316
|
-
| `Worktree` | interface |
|
|
317
|
-
| `UpstreamInterface` | interface |
|
|
318
|
-
| `UpstreamOptions` | interface |
|
|
319
|
-
| `WriteAnchor` | interface |
|
|
320
|
-
| `WriteDirectoryResult` | interface |
|
|
321
|
-
| `WriteExpectation` | interface |
|
|
322
|
-
| `WritePrecondition` | interface |
|
|
300
|
+
| Name | Kind | Summary |
|
|
301
|
+
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------- |
|
|
302
|
+
| `BytesReadResult` | interface | Reports the outcome of one bounded read whose body is taken as exact bytes. |
|
|
303
|
+
| `Host` | interface | Represents a whole vendored host supplied as a value: the membership beside the bytes filling it. |
|
|
304
|
+
| `HostInventory` | interface | Represents the committed vendored-file inventory as one call's reads are decided against. |
|
|
305
|
+
| `HostManifest` | interface | Represents the complete vendored-host inventory. |
|
|
306
|
+
| `ManifestEntry` | interface | Represents one file record of the vendored host's manifest. |
|
|
307
|
+
| `MaterializeResult` | interface | Reports the outcome of one mutation of a target. |
|
|
308
|
+
| `MaterializerInterface` | interface | Describes the mutation contract: the package's only filesystem writer. |
|
|
309
|
+
| `MaterializerOptions` | interface | Represents the options for the materializer. |
|
|
310
|
+
| `ReadAllowance` | interface | Represents the byte allowance one whole upstream call spends across every read it makes. |
|
|
311
|
+
| `TextReadResult` | interface | Reports the outcome of one bounded read whose body is taken as text. |
|
|
312
|
+
| `Worktree` | interface | Describes what git reports about a target's working tree. |
|
|
313
|
+
| `UpstreamInterface` | interface | Describes the upstream contract: the package's only network reader, and it never writes. |
|
|
314
|
+
| `UpstreamOptions` | interface | Represents the options for the upstream reader. |
|
|
315
|
+
| `WriteAnchor` | interface | Represents one physical directory identity captured across a write transaction. |
|
|
316
|
+
| `WriteDirectoryResult` | interface | Reports the final directory anchor of a write transaction and the subset one call created. |
|
|
317
|
+
| `WriteExpectation` | interface | Represents one destination snapshot captured before a write and required to survive it. |
|
|
318
|
+
| `WritePrecondition` | interface | Describes the narrower caller-observed destination state a write transaction must still match. |
|
|
323
319
|
|
|
324
320
|
#### Constants
|
|
325
321
|
|
|
326
|
-
| Name | Kind | Summary
|
|
327
|
-
| ----------------------------------- | ----- |
|
|
328
|
-
| `BRANCH_PATTERN` | const |
|
|
329
|
-
| `DEFAULT_BRANCH` | const |
|
|
330
|
-
| `DEFAULT_REGISTRY_BASE` | const |
|
|
331
|
-
| `DEFAULT_REPOSITORY_BASE` | const |
|
|
332
|
-
| `DEFAULT_UPSTREAM_CONCURRENCY` | const |
|
|
333
|
-
| `DEFAULT_UPSTREAM_RETRIES` | const |
|
|
334
|
-
| `DEFAULT_UPSTREAM_TIMEOUT` | const |
|
|
335
|
-
| `DIGEST_PATTERN` | const |
|
|
336
|
-
| `DRIVE_PATTERN` | const |
|
|
337
|
-
| `INVALID_SEGMENT_CHARACTER_PATTERN` | const |
|
|
338
|
-
| `MANIFEST_NAME` | const |
|
|
339
|
-
| `MAX_BRANCH_LENGTH` | const |
|
|
340
|
-
| `MAX_ENDPOINT_LENGTH` | const |
|
|
341
|
-
| `MAX_INVENTORY_PATHS` | const |
|
|
342
|
-
| `MAX_PATH_DEPTH` | const |
|
|
343
|
-
| `MAX_PATH_SEGMENT_BYTES` | const |
|
|
344
|
-
| `MAX_UPSTREAM_CONCURRENCY` | const |
|
|
345
|
-
| `MAX_UPSTREAM_RETRIES` | const |
|
|
346
|
-
| `MAX_UPSTREAM_TIMEOUT` | const |
|
|
347
|
-
| `ORKESTREL_SCOPE` | const |
|
|
348
|
-
| `PACKUMENT_MEDIA_TYPE` | const |
|
|
349
|
-
| `RESERVED_SEGMENT_PATTERN` | const |
|
|
350
|
-
| `SCAFFOLD_REPOSITORY` | const |
|
|
351
|
-
| `UNREADABLE_VERSION_NOTE` | const |
|
|
322
|
+
| Name | Kind | Summary |
|
|
323
|
+
| ----------------------------------- | ----- | ------------------------------------------------------------------------------------------------ |
|
|
324
|
+
| `BRANCH_PATTERN` | const | Matches the Git branch syntax the repository endpoint accepts. |
|
|
325
|
+
| `DEFAULT_BRANCH` | const | Holds the repository branch a raw content read addresses when a caller names none. |
|
|
326
|
+
| `DEFAULT_REGISTRY_BASE` | const | Holds the registry a version read addresses when a caller names none. |
|
|
327
|
+
| `DEFAULT_REPOSITORY_BASE` | const | Holds the raw content host a repository read addresses when a caller names none. |
|
|
328
|
+
| `DEFAULT_UPSTREAM_CONCURRENCY` | const | Sets the simultaneous upstream requests a reader opens with, under `MAX_UPSTREAM_CONCURRENCY`. |
|
|
329
|
+
| `DEFAULT_UPSTREAM_RETRIES` | const | Sets the retries one upstream request is given when a caller names none. |
|
|
330
|
+
| `DEFAULT_UPSTREAM_TIMEOUT` | const | Sets the timeout one upstream request is given when a caller names none, in milliseconds. |
|
|
331
|
+
| `DIGEST_PATTERN` | const | Matches the exact SHA-256 syntax a digest is stated in: sixty-four lowercase hexadecimal digits. |
|
|
332
|
+
| `DRIVE_PATTERN` | const | Matches the drive prefix a Windows host path may open with. |
|
|
333
|
+
| `INVALID_SEGMENT_CHARACTER_PATTERN` | const | Matches the visible characters no host path segment may carry. |
|
|
334
|
+
| `MANIFEST_NAME` | const | Reserves the metadata name a staged vendored host writes at its own root. |
|
|
335
|
+
| `MAX_BRANCH_LENGTH` | const | Caps the characters one repository branch may carry. |
|
|
336
|
+
| `MAX_ENDPOINT_LENGTH` | const | Caps the characters one caller-supplied upstream endpoint may carry. |
|
|
337
|
+
| `MAX_INVENTORY_PATHS` | const | Caps the paths one target's working-tree inventory may report. |
|
|
338
|
+
| `MAX_PATH_DEPTH` | const | Caps the segments one host path may carry. |
|
|
339
|
+
| `MAX_PATH_SEGMENT_BYTES` | const | Caps the UTF-8 bytes one host path segment may encode to. |
|
|
340
|
+
| `MAX_UPSTREAM_CONCURRENCY` | const | Caps the simultaneous upstream requests. |
|
|
341
|
+
| `MAX_UPSTREAM_RETRIES` | const | Caps the retries one upstream request may be given after a transport fault. |
|
|
342
|
+
| `MAX_UPSTREAM_TIMEOUT` | const | Caps the timeout one upstream request may be given, in milliseconds. |
|
|
343
|
+
| `ORKESTREL_SCOPE` | const | Names the npm scope and repository owner the fleet's packages and sources are published under. |
|
|
344
|
+
| `PACKUMENT_MEDIA_TYPE` | const | Names the media type that selects the registry's abbreviated packument. |
|
|
345
|
+
| `RESERVED_SEGMENT_PATTERN` | const | Matches the Windows device names that stay reserved even when an extension follows. |
|
|
346
|
+
| `SCAFFOLD_REPOSITORY` | const | Names the repository this package's own vendored files are served from. |
|
|
347
|
+
| `UNREADABLE_VERSION_NOTE` | const | Holds the note a release carries when its packument names no readable latest version. |
|
|
352
348
|
|
|
353
349
|
#### Guards
|
|
354
350
|
|
|
355
|
-
| Name | Kind | Summary
|
|
356
|
-
| ----------------------- | -------- |
|
|
357
|
-
| `isBranch` | const |
|
|
358
|
-
| `isCatalogEntries` | const |
|
|
359
|
-
| `isDependencies` | const |
|
|
360
|
-
| `isDependencyNames` | const |
|
|
361
|
-
| `isDigest` | const |
|
|
362
|
-
| `isEndpoint` | const |
|
|
363
|
-
| `isFilesystemPath` | function |
|
|
364
|
-
| `isHost` | const |
|
|
365
|
-
| `isHostManifest` | const |
|
|
366
|
-
| `isInventory` | function |
|
|
367
|
-
| `isManifestEntry` | const |
|
|
368
|
-
| `isManifestRegionSet` | const |
|
|
369
|
-
| `isMaterializerHooks` | const |
|
|
370
|
-
| `isMaterializerOptions` | const |
|
|
371
|
-
| `isMirrors` | const |
|
|
372
|
-
| `isPaths` | const |
|
|
373
|
-
| `isWorktree` | const |
|
|
374
|
-
| `isTimeout` | const |
|
|
375
|
-
| `isUpstreamHooks` | const |
|
|
376
|
-
| `isUpstreamOptions` | const |
|
|
351
|
+
| Name | Kind | Summary |
|
|
352
|
+
| ----------------------- | -------- | ----------------------------------------------------------------------------------- |
|
|
353
|
+
| `isBranch` | const | Narrows a value to a Git branch the repository endpoint accepts. |
|
|
354
|
+
| `isCatalogEntries` | const | Narrows a value to a bounded list of fleet catalog rows. |
|
|
355
|
+
| `isDependencies` | const | Narrows a value to a bounded list of declared runtime dependencies. |
|
|
356
|
+
| `isDependencyNames` | const | Narrows a value to a bounded list of `@orkestrel` package names. |
|
|
357
|
+
| `isDigest` | const | Narrows a value to one exact SHA-256 digest. |
|
|
358
|
+
| `isEndpoint` | const | Narrows a value to a bounded upstream endpoint. |
|
|
359
|
+
| `isFilesystemPath` | function | Narrows a value to a path naming a location on this host. |
|
|
360
|
+
| `isHost` | const | Narrows a value to one `Host`. |
|
|
361
|
+
| `isHostManifest` | const | Narrows a value to one `HostManifest`. |
|
|
362
|
+
| `isInventory` | function | Narrows a value to a working-tree inventory within the limit one target may report. |
|
|
363
|
+
| `isManifestEntry` | const | Narrows a value to one `ManifestEntry`. |
|
|
364
|
+
| `isManifestRegionSet` | const | Narrows a value to one `ManifestRegionSet`. |
|
|
365
|
+
| `isMaterializerHooks` | const | Narrows a value to the materializer's initial listener record. |
|
|
366
|
+
| `isMaterializerOptions` | const | Narrows a value to `MaterializerOptions`. |
|
|
367
|
+
| `isMirrors` | const | Narrows a value to a bounded list of fetched guide mirrors. |
|
|
368
|
+
| `isPaths` | const | Narrows a value to a bounded list of target-relative paths. |
|
|
369
|
+
| `isWorktree` | const | Narrows a value to a `Worktree`. |
|
|
370
|
+
| `isTimeout` | const | Narrows a value to a per-request timeout in milliseconds. |
|
|
371
|
+
| `isUpstreamHooks` | const | Narrows a value to the upstream reader's initial listener record. |
|
|
372
|
+
| `isUpstreamOptions` | const | Narrows a value to `UpstreamOptions`. |
|
|
377
373
|
|
|
378
374
|
#### Helpers
|
|
379
375
|
|
|
380
|
-
| Name | Kind | Summary
|
|
381
|
-
| ------------------------- | -------- |
|
|
382
|
-
| `computeDigest` | function |
|
|
383
|
-
| `computeFileDigest` | function |
|
|
384
|
-
| `computeManifestDigest` | function |
|
|
385
|
-
| `filesToHost` | function |
|
|
386
|
-
| `hexToDigest` | function |
|
|
387
|
-
| `isExactCaseFile` | function |
|
|
388
|
-
| `isPhysicalDirectory` | function |
|
|
389
|
-
| `isPhysicalFile` | function |
|
|
390
|
-
| `isVacant` | function |
|
|
391
|
-
| `listCanonPaths` | function |
|
|
392
|
-
| `listDirectories` | function |
|
|
393
|
-
| `listFiles` | function |
|
|
394
|
-
| `matchesAnchor` | function |
|
|
395
|
-
| `matchesExecutablePath` | function |
|
|
396
|
-
| `matchesExpectation` | function |
|
|
397
|
-
| `matchesGitPath` | function |
|
|
398
|
-
| `matchesMissingPath` | function |
|
|
399
|
-
| `matchesPrecondition` | function |
|
|
400
|
-
| `matchesProtectedPath` | function |
|
|
401
|
-
| `matchesSensitivePath` | function |
|
|
402
|
-
| `pathToStorage` | function |
|
|
403
|
-
| `pruneEmptiedDirectories` | function |
|
|
404
|
-
| `readAnchor` | function |
|
|
405
|
-
| `readExpectation` | function |
|
|
406
|
-
| `readFileHex` | function |
|
|
407
|
-
| `readFileText` | function |
|
|
408
|
-
| `readHostFloor` | function |
|
|
409
|
-
| `readHostManifest` | function |
|
|
410
|
-
| `readManifestEntry` | function |
|
|
411
|
-
| `readSnapshot` | function |
|
|
412
|
-
| `resolveContainedPath` | function |
|
|
413
|
-
| `resolveRealPath` | function |
|
|
414
|
-
| `stageBytes` | function |
|
|
415
|
-
| `stageHost` | function |
|
|
416
|
-
| `stageInventory` | function |
|
|
376
|
+
| Name | Kind | Summary |
|
|
377
|
+
| ------------------------- | -------- | -------------------------------------------------------------------------------------- |
|
|
378
|
+
| `computeDigest` | function | Computes the SHA-256 digest of text. |
|
|
379
|
+
| `computeFileDigest` | function | Computes the SHA-256 digest of one file's exact bytes. |
|
|
380
|
+
| `computeManifestDigest` | function | Computes the digest of a vendored host's declared membership. |
|
|
381
|
+
| `filesToHost` | function | Assembles a whole vendored host from live files and the installed floor. |
|
|
382
|
+
| `hexToDigest` | function | Projects exact bytes stated in hexadecimal to their SHA-256 digest. |
|
|
383
|
+
| `isExactCaseFile` | function | Tests whether a path is a physical file with exact on-disk casing. |
|
|
384
|
+
| `isPhysicalDirectory` | function | Tests whether a path is a physical directory this package will read or write into. |
|
|
385
|
+
| `isPhysicalFile` | function | Tests whether a path is a physical file this package will read or replace. |
|
|
386
|
+
| `isVacant` | function | Tests whether a target is safe to write a fresh workspace into. |
|
|
387
|
+
| `listCanonPaths` | function | Lists the canon paths a target holds, filtered to a plan's groups. |
|
|
388
|
+
| `listDirectories` | function | Lists a directory's descendant directories as sorted root-relative paths. |
|
|
389
|
+
| `listFiles` | function | Lists a directory's files as sorted root-relative paths. |
|
|
390
|
+
| `matchesAnchor` | function | Tests whether a captured directory is still the same directory. |
|
|
391
|
+
| `matchesExecutablePath` | function | Tests whether a vendored path is one a target receives executable. |
|
|
392
|
+
| `matchesExpectation` | function | Tests whether a destination still holds what was captured of it. |
|
|
393
|
+
| `matchesGitPath` | function | Tests whether a path addresses a target's own repository metadata. |
|
|
394
|
+
| `matchesMissingPath` | function | Tests whether a caught filesystem error reports an absent path. |
|
|
395
|
+
| `matchesPrecondition` | function | Tests whether a destination still matches the narrower state a caller observed. |
|
|
396
|
+
| `matchesProtectedPath` | function | Tests whether a target-relative path is one no verb may delete. |
|
|
397
|
+
| `matchesSensitivePath` | function | Tests whether a path names local configuration or a credential. |
|
|
398
|
+
| `pathToStorage` | function | Projects a target-relative path to the storage name a vendored host holds it under. |
|
|
399
|
+
| `pruneEmptiedDirectories` | function | Removes every directory one set of deletions emptied. |
|
|
400
|
+
| `readAnchor` | function | Captures one directory's physical identity. |
|
|
401
|
+
| `readExpectation` | function | Captures what one destination holds before a write. |
|
|
402
|
+
| `readFileHex` | function | Reads one contained file as its exact bytes in lowercase hexadecimal. |
|
|
403
|
+
| `readFileText` | function | Reads one contained file as bounded UTF-8 text. |
|
|
404
|
+
| `readHostFloor` | function | Reads the installed vendored host floor as a value. |
|
|
405
|
+
| `readHostManifest` | function | Reads a vendored host's manifest, when it carries one. |
|
|
406
|
+
| `readManifestEntry` | function | Derives one vendored-host manifest entry from a file in a checkout. |
|
|
407
|
+
| `readSnapshot` | function | Reads a target's current bytes at the paths a plan claims. |
|
|
408
|
+
| `resolveContainedPath` | function | Resolves a root-relative path and refuses one that leaves its root. |
|
|
409
|
+
| `resolveRealPath` | function | Resolves a path through the real filesystem, keeping the part that does not exist yet. |
|
|
410
|
+
| `stageBytes` | function | Stages the named destinations of a value host into a private root. |
|
|
411
|
+
| `stageHost` | function | Stages a vendored host root from a real checkout. |
|
|
412
|
+
| `stageInventory` | function | Stages the committed inventory of the files a vendored host carries. |
|
|
417
413
|
|
|
418
414
|
#### Classes
|
|
419
415
|
|
|
420
|
-
| Name | Kind | Summary
|
|
421
|
-
| ------------------ | ----- |
|
|
422
|
-
| `Materializer` | class |
|
|
423
|
-
| `Upstream` | class |
|
|
424
|
-
| `WriteTransaction` | class |
|
|
416
|
+
| Name | Kind | Summary |
|
|
417
|
+
| ------------------ | ----- | --------------------------------------------------------------------------------------------- |
|
|
418
|
+
| `Materializer` | class | Represents the mutation spine: read the vendored host, re-derive the target, stage, swap. |
|
|
419
|
+
| `Upstream` | class | Represents the reading spine: one bounded, unauthenticated, redirect-free request per answer. |
|
|
420
|
+
| `WriteTransaction` | class | Represents one staged, reversible mutation of one target directory. |
|
|
425
421
|
|
|
426
422
|
## Methods
|
|
427
423
|
|
|
@@ -432,45 +428,45 @@ publishes no interface and is documented directly.
|
|
|
432
428
|
|
|
433
429
|
#### `CompilerInterface`
|
|
434
430
|
|
|
435
|
-
| Method | Summary
|
|
436
|
-
| --------- |
|
|
437
|
-
| `compile` |
|
|
438
|
-
| `audit` |
|
|
439
|
-
| `destroy` |
|
|
431
|
+
| Method | Summary |
|
|
432
|
+
| --------- | ----------------------------------------------------------------------------- |
|
|
433
|
+
| `compile` | Compiles a blueprint into a plan through the draft, gate, and pin stages. |
|
|
434
|
+
| `audit` | Compiles a blueprint and compares its plan to a target's current content. |
|
|
435
|
+
| `destroy` | Tears the compiler down. Every later call throws, and teardown is idempotent. |
|
|
440
436
|
|
|
441
437
|
#### `MaterializerInterface`
|
|
442
438
|
|
|
443
|
-
| Method | Summary
|
|
444
|
-
| ------------- |
|
|
445
|
-
| `audit` |
|
|
446
|
-
| `materialize` |
|
|
447
|
-
| `repair` |
|
|
448
|
-
| `mirror` |
|
|
449
|
-
| `catalog` |
|
|
450
|
-
| `declare` |
|
|
451
|
-
| `remove` | Re-
|
|
452
|
-
| `destroy` |
|
|
439
|
+
| Method | Summary |
|
|
440
|
+
| ------------- | --------------------------------------------------------------------------------- |
|
|
441
|
+
| `audit` | Compares a plan with a target through the vendored host that will repair it. |
|
|
442
|
+
| `materialize` | Writes a plan into a vacant target. |
|
|
443
|
+
| `repair` | Writes a plan into an existing target, guided by an audit of it. |
|
|
444
|
+
| `mirror` | Writes fetched dependency guides to their local mirrors. |
|
|
445
|
+
| `catalog` | Rewrites the marker-bounded package table in the target's catalog agent file. |
|
|
446
|
+
| `declare` | Rewrites the manifest regions the caller names in the target's manifest. |
|
|
447
|
+
| `remove` | Re-derives and deletes the tracked files the plan does not own. |
|
|
448
|
+
| `destroy` | Tears the materializer down. Every later call throws, and teardown is idempotent. |
|
|
453
449
|
|
|
454
450
|
#### `UpstreamInterface`
|
|
455
451
|
|
|
456
|
-
| Method | Summary
|
|
457
|
-
| --------- |
|
|
458
|
-
| `lookup` |
|
|
459
|
-
| `fetch` |
|
|
460
|
-
| `read` |
|
|
461
|
-
| `catalog` |
|
|
462
|
-
| `destroy` |
|
|
452
|
+
| Method | Summary |
|
|
453
|
+
| --------- | ------------------------------------------------------------------------------------------- |
|
|
454
|
+
| `lookup` | Looks up the newest release each declared range admits. |
|
|
455
|
+
| `fetch` | Fetches each named package's guide, beside the local mirror it answers for. |
|
|
456
|
+
| `read` | Reads each named vendored file from the repository, beside the target bytes it answers for. |
|
|
457
|
+
| `catalog` | Catalogs the published fleet from the registry's organization package list. |
|
|
458
|
+
| `destroy` | Tears the reader down, aborting every request in flight. Teardown is idempotent. |
|
|
463
459
|
|
|
464
460
|
#### `WriteTransaction`
|
|
465
461
|
|
|
466
|
-
| Method | Summary
|
|
467
|
-
| ----------- |
|
|
468
|
-
| `write` |
|
|
469
|
-
| `copy` |
|
|
470
|
-
| `establish` |
|
|
471
|
-
| `remove` |
|
|
472
|
-
| `commit` |
|
|
473
|
-
| `discard` |
|
|
462
|
+
| Method | Summary |
|
|
463
|
+
| ----------- | ------------------------------------------------------------------------------------- |
|
|
464
|
+
| `write` | Stages one text file. |
|
|
465
|
+
| `copy` | Stages one byte-for-byte copy of a file that already exists on this host. |
|
|
466
|
+
| `establish` | Establishes one directory inside the target, one segment at a time. |
|
|
467
|
+
| `remove` | Marks one file for deletion at commit. |
|
|
468
|
+
| `commit` | Promotes every staged file and takes every marked file, or rolls the whole call back. |
|
|
469
|
+
| `discard` | Abandons the transaction and removes everything it created. |
|
|
474
470
|
|
|
475
471
|
## Command line
|
|
476
472
|
|
|
@@ -605,8 +601,9 @@ The root Vite configuration defines and registers the fixed `guides` project onl
|
|
|
605
601
|
blueprint carries `guides`. Reading verbs set that fact only when `tests/guides.test.ts` is a
|
|
606
602
|
physical file with that exact path case. A directory or a case-folded spelling does not select it. A
|
|
607
603
|
fresh workspace therefore carries no guides project or script. When a developer adds the proof,
|
|
608
|
-
`audit` reports the exact `test:guides` script
|
|
609
|
-
|
|
604
|
+
`audit` reports the exact `test:guides` script until `repair` or `overwrite` appends it through the
|
|
605
|
+
writable script region. That region accepts the prior generated Vitest-only value and preserves a
|
|
606
|
+
customized command. The rest of the manifest remains birth-owned.
|
|
610
607
|
|
|
611
608
|
The plan-reading verbs compare the Vitest project set named by the target manifest with the
|
|
612
609
|
project set the planned root configuration registers. Every planned proof project must also be
|
|
@@ -736,6 +733,13 @@ Limits states what that costs a target that keeps one at a canon path. The sweep
|
|
|
736
733
|
directories its deletions emptied, so a swept target does not keep the shape of the set it no longer
|
|
737
734
|
holds, and git records no directory to report that shape with.
|
|
738
735
|
|
|
736
|
+
Each git query streams raw NUL-delimited output and retains only complete non-empty records. The
|
|
737
|
+
reader applies `MAX_INVENTORY_PATHS` while it collects them and bounds an unfinished record by
|
|
738
|
+
`MAX_PATH_LENGTH` plus git's porcelain prefix. The worktree guard validates every complete path
|
|
739
|
+
after that prefix is removed. A spawn fault, failed exit, signal, stream or listener fault, drain
|
|
740
|
+
cutoff, or incomplete final record refuses the target under `TARGET`; no partial inventory reaches
|
|
741
|
+
deletion.
|
|
742
|
+
|
|
739
743
|
### Machine-readable output
|
|
740
744
|
|
|
741
745
|
`--json` replaces the report with one JSON value on standard output. Warnings and refusals go to
|
|
@@ -1011,6 +1015,53 @@ each of which selects its project by being written. Scaffold content-owns `tests
|
|
|
1011
1015
|
`tests/policy.test.ts`, and `tests/config.test.ts`; `repair` and `overwrite` restore those files when
|
|
1012
1016
|
their bytes drift or the files are missing.
|
|
1013
1017
|
|
|
1018
|
+
`tests/policy.test.ts` proves the path- and text-shaped laws, and the vendored oxlint plugin
|
|
1019
|
+
`configs/policy.ts` carries the syntax-shaped ones: `policy/no-malformed-summary` reads the doc
|
|
1020
|
+
block preceding each export, and `policy/no-banned-term` reads every comment for a term
|
|
1021
|
+
`.claude/rules/writing.md` § Substitutions bans unconditionally. The prose sweep in
|
|
1022
|
+
`tests/setupPolicy.ts` reads every authored Markdown file for the same terms through the
|
|
1023
|
+
`POLICY_BANNED_TERMS` denylist the rule and the sweep share, and `tests/policy.test.ts` proves that
|
|
1024
|
+
denylist against the table wherever the workspace authors it. The sweep skips a top-level guide the
|
|
1025
|
+
package catalog in `.claude/agents/orkestrel.md` registers to another package, because a mirror is
|
|
1026
|
+
fetched bytes rather than prose this workspace wrote, and it reports a top-level guide that is
|
|
1027
|
+
neither this package's own, nor `guides/README.md`, nor a catalog row, so an exclusion always
|
|
1028
|
+
carries its evidence.
|
|
1029
|
+
|
|
1030
|
+
`tests/guides.test.ts` invokes the public `GuideCommand` class with this package's inventory policy,
|
|
1031
|
+
the Guide reader, and the real Vitest runner. Its anonymous worker callback owns the package
|
|
1032
|
+
assertions: a guide's `Summary` cell against its export's description paragraph, a titled guide
|
|
1033
|
+
fence against the `@example` block of that title, and the README pitch against the guide tagline.
|
|
1034
|
+
With no arguments, the command launches only the real `guides` Vitest project. Its assertions report
|
|
1035
|
+
parity failures. With an explicit direction, `GuideCommand` reads the source, tests, guides, and
|
|
1036
|
+
root Markdown; indexes `guides/README.md`; rewrites the selected side; and reports each remaining
|
|
1037
|
+
disagreement with its guide, compared key, side text or `absent`, and reason. It also reports the
|
|
1038
|
+
pitch pair when those values differ: the `README.md` blockquote against the tagline of the guide the
|
|
1039
|
+
manifest's own bare name selects,
|
|
1040
|
+
`guides/<name>.md`. A workspace whose manifest declares no name, whose index carries no row for that
|
|
1041
|
+
guide, or which carries no `README.md` reports no pitch line. It exits `1` when explicit-write drift
|
|
1042
|
+
remains, the project fails, the project collects no module, Vitest reports an unhandled error, or a
|
|
1043
|
+
module state is not `passed`. Default parity failures come from the guides project. An invalid
|
|
1044
|
+
option exits `2` before Vitest starts. On an explicit-direction run, a missing `guides/README.md` or
|
|
1045
|
+
an indexed spec the workspace does not carry also exits `2` before startup.
|
|
1046
|
+
|
|
1047
|
+
The test file is package-owned and stays outside `HOST_PATHS`. The `test:guides` script and
|
|
1048
|
+
`guides` project are emitted only with `guides`. The generated command requires that authored file
|
|
1049
|
+
to invoke `GuideCommand` directly and register the package assertions. Scaffold neither synthesizes
|
|
1050
|
+
nor overwrites the authored proof.
|
|
1051
|
+
|
|
1052
|
+
`npm run test:guides -- --to guide` rewrites reachable `Summary` cells and titled fences from
|
|
1053
|
+
source text. `npm run test:guides -- --to source` rewrites reachable description paragraphs and
|
|
1054
|
+
titled `@example` bodies from guide text. The README pitch remains authored by hand. A shared
|
|
1055
|
+
source file accumulates each selected edit before it is written. After writing changed paths,
|
|
1056
|
+
the entry rereads the inventory and reports remaining drift with the reason its requested rewrite
|
|
1057
|
+
could not resolve it. The guides project starts from those fresh bytes. The entry never formats;
|
|
1058
|
+
after a write it prints `next: npm run format`.
|
|
1059
|
+
|
|
1060
|
+
Scaffold owns the `scripts` directory. An audit for the orchestration group reports every unplanned
|
|
1061
|
+
member as foreign. `overwrite` deletes an unplanned tracked member only when the tree is clean, its
|
|
1062
|
+
observed bytes still match, and the path is not protected. A planned birth-owned
|
|
1063
|
+
`scripts/service.sh` survives that deletion pass.
|
|
1064
|
+
|
|
1014
1065
|
`tests/distribution.test.ts` is the one proof scaffold generates, and the one test artifact it
|
|
1015
1066
|
claims by presence. Generation is the line, not writing: scaffold writes the vendored
|
|
1016
1067
|
`tests/policy.test.ts` and `tests/config.test.ts` proofs too, and restores them, but those are the
|
|
@@ -1083,11 +1134,14 @@ The region holds a table with these columns:
|
|
|
1083
1134
|
| `Version` | The registry's `dist-tags.latest`, or the cause when the lookup found none |
|
|
1084
1135
|
| `Layer` | The publish round the edges place the package in, as `L0`, `L1`, … |
|
|
1085
1136
|
| `Runtime dependencies` | Each declared runtime edge, as name and range |
|
|
1137
|
+
| `Peer dependencies` | Each declared peer edge, as name and range |
|
|
1086
1138
|
|
|
1087
1139
|
The edge-bearing columns come from the same abbreviated packument the version came from, so a
|
|
1088
|
-
catalog costs one request per package and no more.
|
|
1089
|
-
reaches no consumer of the published package, so it constrains nothing about
|
|
1090
|
-
reading it would place packages in rounds that do not exist.
|
|
1140
|
+
catalog costs one request per package and no more. `dependencies` and `peerDependencies` are read.
|
|
1141
|
+
`devDependencies` reaches no consumer of the published package, so it constrains nothing about
|
|
1142
|
+
publish order, and reading it would place packages in rounds that do not exist. A peer edge orders
|
|
1143
|
+
a dependent the same way a runtime edge does, because a caret peer range at `0.0.x` pins one exact
|
|
1144
|
+
release.
|
|
1091
1145
|
|
|
1092
1146
|
The layer is not stored on a row. `catalogToLayers` derives it from the rows' own edges, in the same
|
|
1093
1147
|
call that writes them, so the layer and the rows cannot disagree:
|
|
@@ -1194,10 +1248,14 @@ The vendored data root is the shared file set, staged into the published package
|
|
|
1194
1248
|
Staging walks `HOST_PATHS` and `CANON_PATHS`, and a release ships what both name.
|
|
1195
1249
|
|
|
1196
1250
|
`HOST_PATHS` is the vendored set, and a target receives a copy of each path it selects: the
|
|
1197
|
-
licence, the harness permission file, the
|
|
1198
|
-
shared policy
|
|
1199
|
-
byte-identical root dotfiles, and the guide mirrors a generated workspace
|
|
1200
|
-
candidate list rather than a plan, because a workspace never mirrors its own
|
|
1251
|
+
licence, the harness permission file, the scaffold-owned `scripts` directory, the
|
|
1252
|
+
shared policy register, the shared policy proof, the shared policy plugin, the shared configuration
|
|
1253
|
+
leaf and its proof, the byte-identical root dotfiles, and the guide mirrors a generated workspace
|
|
1254
|
+
starts from. It is a candidate list rather than a plan, because a workspace never mirrors its own
|
|
1255
|
+
guide. The session-start hooks inside `scripts` split by job:
|
|
1256
|
+
the bench probe reports whether a bench CLI resolves, and the dependency hook installs the
|
|
1257
|
+
lockfile's closure in a remote session. What wires a bench stays in the canon, and a session reads
|
|
1258
|
+
it at its primary root.
|
|
1201
1259
|
|
|
1202
1260
|
`CANON_PATHS` is the instruction canon, staged for reading instead: the `AGENTS.md` coding contract,
|
|
1203
1261
|
the `CLAUDE.md` harness bridge, the `.agents/orchestration.md` agent-operation contract, the rules
|
|
@@ -1218,9 +1276,10 @@ sits beneath a member of the other. Staging depends on that, because the walk co
|
|
|
1218
1276
|
path it discovers twice claims one storage name twice, which refuses the stage. `isCanonPath` is the
|
|
1219
1277
|
one reading of canon membership, matching a member and anything beneath a member that is a directory,
|
|
1220
1278
|
so staging, the live overlay, and the executable's fetch list never disagree about what a path is.
|
|
1221
|
-
Membership says where a path's bytes are staged, not whether a plan claims it:
|
|
1222
|
-
appends `CATALOG_AGENT_PATH` to what `HOST_PATHS` selects rather than
|
|
1223
|
-
keeps the file planned without putting a canon path in the vendored
|
|
1279
|
+
Membership says where a path's bytes are staged, not whether a plan claims it:
|
|
1280
|
+
`blueprintToHostArtifacts` appends `CATALOG_AGENT_PATH` to what `HOST_PATHS` selects rather than
|
|
1281
|
+
listing it there, which is what keeps the file planned without putting a canon path in the vendored
|
|
1282
|
+
list.
|
|
1224
1283
|
|
|
1225
1284
|
The `host.json` file at the repository root is the committed live inventory. Each entry carries the
|
|
1226
1285
|
SHA-256 digest of its file content, and the inventory carries a membership digest over its declared
|
|
@@ -1324,7 +1383,14 @@ except the manifest.
|
|
|
1324
1383
|
`--ignore-scripts` to `npm pack` so a suite never re-runs the build it already gates.
|
|
1325
1384
|
- One template artifact per configuration file the selection needs: the root `tsconfig.json` and
|
|
1326
1385
|
`vite.config.ts`, plus a Vite config and a scoped TypeScript config per selected environment and
|
|
1327
|
-
for `bin` when it is set.
|
|
1386
|
+
for `bin` when it is set. The root `tsconfig.json` maps the `@src` and `@app` aliases the selection
|
|
1387
|
+
reaches, and beside them the workspace's own published specifiers — `@orkestrel/<name>` and one
|
|
1388
|
+
`@orkestrel/<name>/<environment>` entry per subpath the `exports` map publishes — each to its
|
|
1389
|
+
source entry. Without them the workspace's own name resolves through that `exports` map to
|
|
1390
|
+
`dist/`, and `npm run check` would wait on `npm run build`. Every subpath is written before the
|
|
1391
|
+
bare specifier, because `vite.config.ts` derives its `alias` record from these entries in order and
|
|
1392
|
+
a bare specifier also matches its own subpaths. An `app` environment publishes nothing and maps no
|
|
1393
|
+
such entry.
|
|
1328
1394
|
- One template artifact, `configs/browsers.ts`, for a workspace selecting `browser` on either axis.
|
|
1329
1395
|
It resolves the Chromium the Playwright provider launches, and the root `vite.config.ts` calls it
|
|
1330
1396
|
once into `browserOptions` and passes that to every `playwright()` provider it configures. The
|
|
@@ -1358,6 +1424,19 @@ except the manifest.
|
|
|
1358
1424
|
- One host artifact per vendored path the workspace selects. A vendored directory is one planned
|
|
1359
1425
|
path that expands into the files the data root stores beneath it.
|
|
1360
1426
|
|
|
1427
|
+
A workspace publishing a `src` environment rolls each published face's declarations up from that
|
|
1428
|
+
face's own Vite config. The seeded config calls `declarationRollup` from the vendored
|
|
1429
|
+
`configs/helpers.ts`, which runs the workspace's own compiler as a command —
|
|
1430
|
+
`--declaration --emitDeclarationOnly` into a scratch directory outside the tree — and hands the
|
|
1431
|
+
emitted entry declaration to API Extractor, which rolls the face into the one `index.d.ts` beside
|
|
1432
|
+
its bundle. The extractor analyses with the compiler engine it bundles rather than the one the
|
|
1433
|
+
workspace installs, so a publishing workspace declares `@microsoft/api-extractor` and imports no
|
|
1434
|
+
compiler API of its own. The browser and server faces pass `rewriteCoreSpecifier`: the compiler
|
|
1435
|
+
emits the `@src/core` specifier unrewritten and the extractor keeps it external, so the rewrite
|
|
1436
|
+
replaces it with the workspace's own published name and a consumer of the packed face reaches core
|
|
1437
|
+
through the root export the tarball declares. The seeded `bin` config calls no roll-up, because an
|
|
1438
|
+
executable ships no declarations.
|
|
1439
|
+
|
|
1361
1440
|
`planToSummary` reports the tally rather than a number written down here:
|
|
1362
1441
|
|
|
1363
1442
|
```ts
|
|
@@ -1665,6 +1744,16 @@ one answered first. That is what drives a `require`-only subpath declaring its t
|
|
|
1665
1744
|
`require`, and what admits a conventional subpath that publishes no `types` condition but ships the
|
|
1666
1745
|
adjacent declaration TypeScript substitutes from its runtime target.
|
|
1667
1746
|
|
|
1747
|
+
An entry's published names are checked against its own declarations by the type system rather than
|
|
1748
|
+
by a walk the proof carries. Each drive writes the runtime's own key list into a generated consumer
|
|
1749
|
+
module as a literal and lets the workspace's compiler judge that module under the driver's own
|
|
1750
|
+
resolution, in both directions. `Record<keyof typeof entry, true>` takes the literal, so a name the
|
|
1751
|
+
declarations carry and the runtime does not lands there. `Record<keyof typeof published, true>`
|
|
1752
|
+
takes that record back, so a name the runtime carries and the declarations do not, and a name the
|
|
1753
|
+
declarations publish as a type alone, land there instead. One direction alone passes on a runtime
|
|
1754
|
+
key the declarations lack, which is why the consumer carries both, and each diagnostic names the
|
|
1755
|
+
member that moved.
|
|
1756
|
+
|
|
1668
1757
|
A subpath is undeclared when it resolves no declaration and names a runtime target, which is a
|
|
1669
1758
|
defect, because a consumer importing it compiles against nothing under `node16`. A target is a
|
|
1670
1759
|
runtime target when its own file name carries no extension at all, or carries `.js`, `.mjs`,
|
|
@@ -1784,8 +1873,13 @@ port, so the run drives nothing external and stays in `test`.
|
|
|
1784
1873
|
- [`tests/src/bin/helpers.test.ts`](../tests/src/bin/helpers.test.ts) — command-line reading, usage
|
|
1785
1874
|
rendering, and the failure envelope.
|
|
1786
1875
|
- [`tests/src/bin/main.test.ts`](../tests/src/bin/main.test.ts) — the process entry point.
|
|
1787
|
-
- [`tests/policy.test.ts`](../tests/policy.test.ts) — the
|
|
1788
|
-
|
|
1876
|
+
- [`tests/policy.test.ts`](../tests/policy.test.ts) — the path- and text-shaped policy laws:
|
|
1877
|
+
mirrors, suppressions, the rule map, filenames, manifest scripts, skills, bridges, and the prose
|
|
1878
|
+
sweep over every authored Markdown file. The syntax-shaped laws are the rules of the vendored
|
|
1879
|
+
oxlint plugin `configs/policy.ts`, proven in `tests/config.test.ts`.
|
|
1880
|
+
- [`tests/config.test.ts`](../tests/config.test.ts) — the root configuration's aliases, projects,
|
|
1881
|
+
and outputs, every plugin rule against a case pair drawn from inside and outside its membership
|
|
1882
|
+
boundary, and the declaration roll-up over a real face.
|
|
1789
1883
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — this guide's bijection with the barrels.
|
|
1790
1884
|
|
|
1791
1885
|
## See also
|