@orkestrel/scaffold 0.0.119 → 0.0.120
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 +15 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +27 -26
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +136 -136
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/manifest.json +39 -464
- package/dist/src/core/index.cjs +162 -177
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +151 -166
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +25 -25
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -50
- package/dist/src/server/index.d.ts +50 -50
- package/dist/src/server/index.js +26 -26
- package/dist/src/server/index.js.map +1 -1
- package/package.json +9 -9
|
@@ -55,30 +55,30 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
55
55
|
|
|
56
56
|
#### Types
|
|
57
57
|
|
|
58
|
-
| Name | Kind | Signature
|
|
59
|
-
| ------------------- | ---- |
|
|
60
|
-
| `Artifact` | type | `HostArtifact \| HydratedArtifact \| ContentArtifact`
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `Lookup` | type | `'found' \| 'missing' \| 'unmatched' \| 'failed'`
|
|
74
|
-
| `Mirror` | type | `{ readonly name: string; readonly path: string; readonly lookup: 'found'; readonly content: string; readonly observed?: string; readonly note?: never; } \| { readonly name: string; readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly content?: never; }`
|
|
75
|
-
| `Origin` | type | `'host' \| 'template' \| 'computed'`
|
|
76
|
-
| `Ownership` | type | `'content' \| 'presence' \| 'birth'`
|
|
77
|
-
| `Release` | type | `{ readonly name: string; readonly range: string; readonly lookup: 'found'; readonly latest: string; readonly major?: number; readonly note?: never; } \| { readonly name: string; readonly range: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly major?: number; readonly latest?: never; }`
|
|
78
|
-
| `ScaffoldErrorCode` | type | `'INVALID' \| 'BLOCKED' \| 'DESTROYED' \| 'TARGET' \| 'WRITE' \| 'FETCH'`
|
|
79
|
-
| `SetupRuntime` | type | `'node' \| 'browser'`
|
|
80
|
-
| `Snapshot` | type | `Readonly<Record<string, string>>`
|
|
81
|
-
| `Surface` | type | `'browser' \| 'styles'`
|
|
58
|
+
| Name | Kind | Signature | Summary |
|
|
59
|
+
| ------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `Artifact` | type | `HostArtifact \| HydratedArtifact \| ContentArtifact` | Represents one file in a plan, discriminated by how its content is produced and what scaffold claims of it. |
|
|
61
|
+
| `ArtifactDrift` | type | `'aligned' \| 'stale' \| 'missing' \| 'foreign'` | Names how one target path compares to the artifact planned for it. |
|
|
62
|
+
| `ArtifactFinding` | type | `{ readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'stale'; readonly observed: string; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership?: never; readonly drift: 'foreign'; readonly observed: string; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'missing'; readonly observed?: never; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'aligned'; readonly observed?: string; }` | Represents one drift verdict against a target path. |
|
|
63
|
+
| `ArtifactGroup` | type | `'manifest' \| 'configs' \| 'source' \| 'tests' \| 'guides' \| 'docs' \| 'orchestration'` | Names the artifact group a plan selects over. |
|
|
64
|
+
| `Axis` | type | `'src' \| 'app'` | Names the workspace axis an extension occupies. |
|
|
65
|
+
| `BuildFormat` | type | `'es' \| 'cjs'` | Names one module format a published library environment builds. |
|
|
66
|
+
| `CatalogEntry` | type | `{ readonly name: string; readonly lookup: 'found'; readonly version: string; readonly dependencies: readonly Dependency[]; readonly peers: readonly Dependency[]; readonly note?: never; } \| { readonly name: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly version?: never; readonly dependencies?: never; readonly peers?: never; }` | Represents one package row of the fleet catalog. |
|
|
67
|
+
| `CompileStage` | type | `'draft' \| 'gate' \| 'pin'` | Names the compile phases, in the order they run. |
|
|
68
|
+
| `CompilerEventMap` | type | `{ readonly compile: readonly [result: CompileResult]; readonly audit: readonly [audit: Audit]; readonly block: readonly [questions: readonly Question[]]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the compiler's observation channel. |
|
|
69
|
+
| `HostFile` | type | `{ readonly path: string; readonly lookup: 'found'; readonly hex: string; readonly observed?: string; readonly note?: never; } \| { readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly hex?: never; }` | Represents one vendored file read from the repository, beside the target bytes it answers for. |
|
|
70
|
+
| `Environment` | type | `'core' \| 'browser' \| 'server'` | Names one environment a generated workspace selects on its `src` or `app` axis. |
|
|
71
|
+
| `Extension` | type | `BrowserExtension \| StylesExtension` | Represents an extension discriminated by its surface. |
|
|
72
|
+
| `Framework` | type | `'vue'` | Names a supported browser framework. |
|
|
73
|
+
| `Lookup` | type | `'found' \| 'missing' \| 'unmatched' \| 'failed'` | Names how an upstream lookup resolved: found, missing, unmatched, or failed. |
|
|
74
|
+
| `Mirror` | type | `{ readonly name: string; readonly path: string; readonly lookup: 'found'; readonly content: string; readonly observed?: string; readonly note?: never; } \| { readonly name: string; readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly content?: never; }` | Represents one dependency guide fetched from upstream, beside the local mirror it answers for. |
|
|
75
|
+
| `Origin` | type | `'host' \| 'template' \| 'computed'` | Names how an artifact's content is produced. |
|
|
76
|
+
| `Ownership` | type | `'content' \| 'presence' \| 'birth'` | Names what scaffold claims at an artifact's path. |
|
|
77
|
+
| `Release` | type | `{ readonly name: string; readonly range: string; readonly lookup: 'found'; readonly latest: string; readonly major?: number; readonly note?: never; } \| { readonly name: string; readonly range: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly major?: number; readonly latest?: never; }` | Represents one declared dependency range measured against a registry release. |
|
|
78
|
+
| `ScaffoldErrorCode` | type | `'INVALID' \| 'BLOCKED' \| 'DESTROYED' \| 'TARGET' \| 'WRITE' \| 'FETCH'` | Names the coded reasons a scaffold error is raised. |
|
|
79
|
+
| `SetupRuntime` | type | `'node' \| 'browser'` | Names the runtime a root setup proof requires. |
|
|
80
|
+
| `Snapshot` | type | `Readonly<Record<string, string>>` | Holds exact lowercase hexadecimal target bytes keyed by artifact-relative path. |
|
|
81
|
+
| `Surface` | type | `'browser' \| 'styles'` | Names the surface an extension extends. |
|
|
82
82
|
|
|
83
83
|
#### Interfaces
|
|
84
84
|
|
|
@@ -136,6 +136,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
136
136
|
| `APP_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency every private `app` environment adds. |
|
|
137
137
|
| `APP_MATRIX` | const | `Readonly<Record<Environment, AppDefinition>>` | Holds the configuration and runtime-entry settings each private `app` environment contributes, frozen. |
|
|
138
138
|
| `APP_SERVER_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies a private server application adds. |
|
|
139
|
+
| `ARTIFACT_GROUPS` | const | `readonly ArtifactGroup[]` | Lists the `ArtifactGroup` values in plan order, frozen. |
|
|
139
140
|
| `ARTIFACT_TEMPLATES` | const | `ArtifactTemplateSet` | Holds formatter-stable template text for source, test, document, guide, and service artifacts. |
|
|
140
141
|
| `AXES` | const | `readonly Axis[]` | Lists the axes a browser extension may occupy, frozen. |
|
|
141
142
|
| `BASE_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Holds the baseline tooling versions, before framework holds apply. |
|
|
@@ -168,7 +169,6 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
168
169
|
| `FRAMEWORKS` | const | `readonly Framework[]` | Lists the supported browser frameworks, frozen. |
|
|
169
170
|
| `FRAMEWORK_MATRIX` | const | `Readonly<Record<Framework, FrameworkDefinition>>` | Describes the tooling and package boundaries of each browser framework, frozen. |
|
|
170
171
|
| `GLOBAL_SETUP_PATH` | const | `"tests/setupGlobal.ts"` | Names the shared Vitest global-setup module whose presence makes a workspace `global`. |
|
|
171
|
-
| `GROUPS` | const | `readonly Group[]` | Lists the `Group` values in plan order, frozen. |
|
|
172
172
|
| `GUIDES_TEST_PATH` | const | `"tests/guides.test.ts"` | Names the package-owned guide-parity entry used by `test:guides` and to select the `guides` project. |
|
|
173
173
|
| `HEX_PATTERN` | const | `RegExp` | Matches exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. |
|
|
174
174
|
| `HOST_INVENTORY_PATH` | const | `"host.json"` | Names the repository-relative path where the committed vendored-file inventory is served. |
|
|
@@ -233,6 +233,9 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
233
233
|
| Name | Kind | Signature | Summary |
|
|
234
234
|
| -------------------- | -------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
235
235
|
| `isArtifact` | const | `Guard<Artifact>` | Narrows a value to an `Artifact`. |
|
|
236
|
+
| `isArtifactFinding` | const | `Guard<ArtifactFinding>` | Narrows a value to an `ArtifactFinding`. |
|
|
237
|
+
| `isArtifactGroup` | const | `Guard<ArtifactGroup>` | Narrows a value to one `ArtifactGroup` a plan selects over. |
|
|
238
|
+
| `isArtifactGroups` | const | `Guard<readonly ArtifactGroup[]>` | Narrows a value to a bounded group selection. |
|
|
236
239
|
| `isAudit` | const | `Guard<Audit>` | Narrows a value to an `Audit`. |
|
|
237
240
|
| `isBlueprint` | const | `Guard<Blueprint>` | Narrows a value to a `Blueprint`. |
|
|
238
241
|
| `isBrowserExtension` | const | `Guard<BrowserExtension>` | Narrows a value to a supported browser framework with distinct occupied axes. |
|
|
@@ -245,10 +248,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
245
248
|
| `isDependencyName` | const | `Guard<string>` | Narrows a value to the scoped package name a runtime dependency carries. |
|
|
246
249
|
| `isEnvironment` | const | `Guard<Environment>` | Narrows a value to one `Environment` a workspace may select. |
|
|
247
250
|
| `isExtension` | const | `Guard<Extension>` | Narrows a value to an extension of a supported surface. |
|
|
248
|
-
| `
|
|
249
|
-
| `isGroup` | const | `Guard<Group>` | Narrows a value to one `Group` a plan selects over. |
|
|
250
|
-
| `isGroups` | const | `Guard<readonly Group[]>` | Narrows a value to a bounded group selection. |
|
|
251
|
-
| `isHex` | const | `Guard<string>` | Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit. |
|
|
251
|
+
| `isHexContent` | const | `Guard<string>` | Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit. |
|
|
252
252
|
| `isManifestScript` | const | `Guard<ManifestScript>` | Narrows a value to a `ManifestScript`. |
|
|
253
253
|
| `isMirror` | const | `Guard<Mirror>` | Narrows a value to a `Mirror`. |
|
|
254
254
|
| `isOverride` | const | `Guard<Override>` | Narrows a value to an `Override`. |
|
|
@@ -263,52 +263,52 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
263
263
|
|
|
264
264
|
#### Parsers
|
|
265
265
|
|
|
266
|
-
| Name | Kind | Signature
|
|
267
|
-
| ---------------------- | -------- |
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `parseSnapshot` | function | `(value: unknown) => Snapshot \| undefined`
|
|
266
|
+
| Name | Kind | Signature | Summary |
|
|
267
|
+
| ---------------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
268
|
+
| `parseArtifactGroups` | function | `(value: unknown) => readonly ArtifactGroup[] \| undefined` | Coerces an untrusted value to a group selection. |
|
|
269
|
+
| `parseBlueprint` | function | `(value: unknown) => Blueprint \| undefined` | Coerces an untrusted value to a `Blueprint`. |
|
|
270
|
+
| `parseCompilerOptions` | function | `(value: unknown) => CompilerOptions \| undefined` | Coerces an untrusted value to `CompilerOptions`. |
|
|
271
|
+
| `parseExtension` | function | `(value: unknown) => Extension \| undefined` | Coerces an extension value or a `surface:name` selection into an extension. |
|
|
272
|
+
| `parseSnapshot` | function | `(value: unknown) => Snapshot \| undefined` | Coerces an untrusted value to a `Snapshot`. |
|
|
273
273
|
|
|
274
274
|
#### Helpers
|
|
275
275
|
|
|
276
|
-
| Name
|
|
277
|
-
|
|
|
278
|
-
| `
|
|
279
|
-
| `artifactToHex`
|
|
280
|
-
| `bytesToHex`
|
|
281
|
-
| `catalogToLayers`
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
298
|
-
| `
|
|
299
|
-
| `
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `planToSummary`
|
|
306
|
-
| `renderSkillPointer`
|
|
307
|
-
| `scanManifestTokens`
|
|
308
|
-
| `
|
|
309
|
-
| `selectHostPaths`
|
|
310
|
-
| `serializeTypeScriptString`
|
|
311
|
-
| `srcToRoot`
|
|
276
|
+
| Name | Kind | Signature | Summary |
|
|
277
|
+
| ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
278
|
+
| `artifactToArtifactFinding` | function | `(artifact: Artifact, observed?: string) => ArtifactFinding` | Projects one planned artifact and the bytes found at its path into a verdict. |
|
|
279
|
+
| `artifactToHex` | function | `(artifact: Artifact) => string \| undefined` | Projects an artifact to the exact bytes it claims, as hexadecimal. |
|
|
280
|
+
| `bytesToHex` | function | `(bytes: Uint8Array) => string` | Encodes bytes as exact lowercase hexadecimal text. |
|
|
281
|
+
| `catalogToLayers` | function | `(entries: readonly CatalogEntry[]) => ReadonlyArray<readonly string[]>` | Projects a catalog into the layers it publishes in. |
|
|
282
|
+
| `compareVersions` | function | `(left: string, right: string) => number` | Compares two versions by their numeric components. |
|
|
283
|
+
| `computeBytes` | function | `(content: string) => number` | Counts the UTF-8 bytes text encodes to. |
|
|
284
|
+
| `computeHash` | function | `(text: string) => string` | Computes the deterministic content identity of text. |
|
|
285
|
+
| `computeTotal` | function | `(values: readonly number[]) => number` | Computes the sum of a list of numbers. |
|
|
286
|
+
| `contentToHex` | function | `(content: string) => string` | Encodes text as the exact lowercase hexadecimal form of its UTF-8 bytes. |
|
|
287
|
+
| `extractRangeMajor` | function | `(range: string) => number \| undefined` | Extracts the major component of an admitted dependency range. |
|
|
288
|
+
| `extractVersion` | function | `(version: string) => readonly [major: number, minor: number, patch: number] \| undefined` | Extracts the major, minor, and patch components of an exact version. |
|
|
289
|
+
| `inferArtifactDrift` | function | `(artifact: Artifact, observed?: string) => Exclude<ArtifactDrift, 'foreign'>` | Infers how one target path compares to the artifact planned for it. |
|
|
290
|
+
| `inferArtifactGroup` | function | `(path: string) => ArtifactGroup` | Infers the `ArtifactGroup` a path belongs to. |
|
|
291
|
+
| `isCanonPath` | function | `(path: string) => boolean` | Checks whether a path belongs to the instruction canon a target reads rather than holds. |
|
|
292
|
+
| `isDeferredPath` | function | `(path: string) => boolean` | Checks whether another surface owns the vendored bytes at a path. |
|
|
293
|
+
| `isFloorPath` | function | `(path: string) => boolean` | Checks whether a destination's floor bytes survive a live overlay. |
|
|
294
|
+
| `isRetainedPath` | function | `(path: string) => boolean` | Checks whether another surface owns a target's present bytes at a path. |
|
|
295
|
+
| `iterateAnswers` | function | `<TValue, TAnswer>(source: Iterable<TValue>, answer: (value: TValue) => TAnswer \| undefined) => Generator<TAnswer \| undefined, void, undefined>` | Yields the answer to each value of a source and ends after the first refused answer. |
|
|
296
|
+
| `manifestToDependencies` | function | `(manifest: string) => ManifestDependencySet` | Projects a package manifest's text to the `@orkestrel/*` packages each dependency section declares. |
|
|
297
|
+
| `manifestToName` | function | `(manifest: string) => string \| undefined` | Projects a package manifest's text to its own name. |
|
|
298
|
+
| `matchesArtifactDriftReachability` | function | `(ownership: Ownership, finding: ArtifactFinding) => boolean` | Tests whether `inferArtifactDrift` could have produced a finding for an ownership. |
|
|
299
|
+
| `matchesEngines` | function | `(engines: string) => boolean` | Tests whether a declared engines floor is at or above the supported minimum. |
|
|
300
|
+
| `matchesOrchestrationPath` | function | `(path: string) => boolean` | Tests whether a path instructs or wires an agent rather than the toolchain. |
|
|
301
|
+
| `matchesPrintWidth` | function | `(line: string) => boolean` | Tests whether one emitted line fits the vendored formatter width. |
|
|
302
|
+
| `matchesRange` | function | `(range: string, latest: string) => boolean` | Tests whether a declared range already admits a published version. |
|
|
303
|
+
| `nameToGuide` | function | `(name: string) => string` | Derives the guide mirror path a package name answers for. |
|
|
304
|
+
| `parseOwnedJSONValue` | function | `(value: unknown) => JSONValue \| undefined` | Snapshots an untrusted value into exact JSON data the caller owns. |
|
|
305
|
+
| `planToSummary` | function | `(plan: Plan) => PlanSummary` | Projects a plan into its tally by artifact origin. |
|
|
306
|
+
| `renderSkillPointer` | function | `(canonical: string, name: string) => string \| undefined` | Renders the `SKILL.md` pointer a target carries in place of a canonical skill. |
|
|
307
|
+
| `scanManifestTokens` | function | `(text: string) => readonly ManifestToken[] \| undefined` | Scans manifest text for its strings and object braces, in order. |
|
|
308
|
+
| `selectArtifactGroups` | function | `(groups?: readonly ArtifactGroup[]) => readonly ArtifactGroup[]` | Selects the groups a compile covers, in plan order. |
|
|
309
|
+
| `selectHostPaths` | function | `(paths: readonly string[], name: string) => readonly string[]` | Selects the host paths a named workspace vendors. |
|
|
310
|
+
| `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
|
|
311
|
+
| `srcToRoot` | function | `(src: readonly Environment[]) => Environment \| undefined` | Selects the single published environment a package root points at. |
|
|
312
312
|
|
|
313
313
|
| Name | Kind | Signature | Summary |
|
|
314
314
|
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -353,7 +353,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
353
353
|
| `insertManifestSection` | function | `(manifest: string, section: 'dependencies' \| 'devDependencies', dependencies: readonly Dependency[], present: boolean) => string \| undefined` | Inserts dependencies into one section of package manifest text. |
|
|
354
354
|
| `overridesToQuestions` | function | `(overrides: readonly Override[], artifacts: readonly Artifact[]) => readonly Question[]` | Measures a blueprint's overrides against the artifacts drafted for it. |
|
|
355
355
|
| `pathToCondition` | function | `(path: string, formats: readonly BuildFormat[]) => Readonly<Record<string, unknown>>` | Builds one `exports` condition block for a built environment. |
|
|
356
|
-
| `
|
|
356
|
+
| `planToArtifactFindings` | function | `(plan: Plan, current: Snapshot) => readonly ArtifactFinding[]` | Compares a plan against a target's current content. |
|
|
357
357
|
| `planToHash` | function | `(plan: Plan) => string \| undefined` | Computes a plan's content identity. |
|
|
358
358
|
| `replaceManifestRanges` | function | `(manifest: string, pins: DependencyPinSet) => string \| undefined` | Replaces the runtime and development dependency ranges in package manifest text, and never a peer range. |
|
|
359
359
|
| `replaceManifestOverride` | function | `(manifest: string, path: readonly string[], range: string) => string \| undefined` | Replaces one npm override leaf in manifest text, inserting its absent ancestors. |
|
|
@@ -397,8 +397,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
397
397
|
| `Host` | interface | `{ manifest, bytes }` | Represents a whole vendored host supplied as a value: the membership beside the bytes filling it. |
|
|
398
398
|
| `HostInventory` | interface | `{ lookup, digests, duplicates, note, surface, unreachable? }` | Represents the committed vendored-file inventory as one call's reads are decided against. |
|
|
399
399
|
| `HostManifest` | interface | `{ entries, roots, surface, digest }` | Represents the complete vendored-host inventory. |
|
|
400
|
+
| `HostManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
|
|
400
401
|
| `HostStageOptions` | interface | `{ inventory?, establish?, report? }` | Configures the committed inventory baseline and staging reports. |
|
|
401
|
-
| `ManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
|
|
402
402
|
| `MaterializeResult` | interface | `{ target, written, skipped, removed }` | Reports the outcome of one mutation of a target. |
|
|
403
403
|
| `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
|
|
404
404
|
| `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
|
|
@@ -455,8 +455,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
455
455
|
| `isFilesystemPath` | function | `(value: unknown) => value is string` | Narrows a value to a path naming a location on this host. |
|
|
456
456
|
| `isHost` | const | `Guard<Host>` | Narrows a value to one `Host`. |
|
|
457
457
|
| `isHostManifest` | const | `Guard<HostManifest>` | Narrows a value to one `HostManifest`. |
|
|
458
|
+
| `isHostManifestEntry` | const | `Guard<HostManifestEntry>` | Narrows a value to one `HostManifestEntry`. |
|
|
458
459
|
| `isInventory` | function | `(value: unknown) => value is readonly unknown[]` | Narrows a value to a working-tree inventory within the limit one target may report. |
|
|
459
|
-
| `isManifestEntry` | const | `Guard<ManifestEntry>` | Narrows a value to one `ManifestEntry`. |
|
|
460
460
|
| `isManifestRegionSet` | const | `Guard<ManifestRegionSet>` | Narrows a value to one `ManifestRegionSet`. |
|
|
461
461
|
| `isMaterializerHooks` | const | `Guard<EmitterHooks<MaterializerEventMap>>` | Narrows a value to the materializer's initial listener record. |
|
|
462
462
|
| `isMaterializerOptions` | const | `Guard<MaterializerOptions>` | Narrows a value to `MaterializerOptions`. |
|
|
@@ -470,56 +470,56 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
470
470
|
|
|
471
471
|
#### Helpers
|
|
472
472
|
|
|
473
|
-
| Name | Kind | Signature
|
|
474
|
-
| ------------------------- | -------- |
|
|
475
|
-
| `climbRealPath` | function | `(current: string, pending: readonly string[], depth: number) => string \| undefined`
|
|
476
|
-
| `collectIndexed` | function | `<TResult>(entries: ReadonlyArray<readonly [number, TResult]>) => readonly TResult[]`
|
|
477
|
-
| `computeDigest` | function | `(content: string) => string`
|
|
478
|
-
| `computeFileDigest` | function | `(path: string) => string \| undefined`
|
|
479
|
-
| `computeManifestDigest` | function | `(entries: readonly
|
|
480
|
-
| `decodeHexText` | function | `(hex: string) => string \| undefined`
|
|
481
|
-
| `filesToHost` | function | `(files: readonly HostFile[], floor: Host) => Host \| undefined`
|
|
482
|
-
| `hexToDigest` | function | `(hex: string) => string`
|
|
483
|
-
| `isExactCaseFile` | function | `(path: string) => boolean`
|
|
484
|
-
| `isPhysicalDirectory` | function | `(path: string) => boolean`
|
|
485
|
-
| `isPhysicalFile` | function | `(path: string) => boolean`
|
|
486
|
-
| `isVacant` | function | `(target: string) => boolean`
|
|
487
|
-
| `listAncestors` | function | `(path: string, limit?: number) => readonly string[]`
|
|
488
|
-
| `listCanonPaths` | function | `(target: string, groups: readonly
|
|
489
|
-
| `listDirectories` | function | `(root: string) => readonly string[]`
|
|
490
|
-
| `listFiles` | function | `(root: string) => readonly string[]`
|
|
491
|
-
| `matchesAnchor` | function | `(anchor: WriteAnchor) => boolean`
|
|
492
|
-
| `matchesExecutablePath` | function | `(path: string) => boolean`
|
|
493
|
-
| `matchesExpectation` | function | `(expectation: WriteExpectation) => boolean`
|
|
494
|
-
| `matchesGitPath` | function | `(path: string) => boolean`
|
|
495
|
-
| `matchesMissingPath` | function | `(error: unknown) => boolean`
|
|
496
|
-
| `matchesPrecondition` | function | `(precondition: WritePrecondition) => boolean`
|
|
497
|
-
| `matchesProtectedPath` | function | `(path: string) => boolean`
|
|
498
|
-
| `matchesSensitivePath` | function | `(path: string) => boolean`
|
|
499
|
-
| `pathToStorage` | function | `(path: string) => string`
|
|
500
|
-
| `pruneEmptiedDirectories` | function | `(target: string, removed: readonly string[]) => readonly string[]`
|
|
501
|
-
| `readAnchor` | function | `(path: string) => WriteAnchor \| undefined`
|
|
502
|
-
| `readExpectation` | function | `(path: string) => WriteExpectation \| undefined`
|
|
503
|
-
| `readFileHex` | function | `(root: string, path: string, limit?: number) => string \| undefined`
|
|
504
|
-
| `readFileText` | function | `(root: string, path: string, limit?: number) => string \| undefined`
|
|
505
|
-
| `readHostFloor` | function | `(root?: string) => Host`
|
|
506
|
-
| `readHostManifest` | function | `(host: string, name?: string) => HostManifest \| undefined`
|
|
507
|
-
| `
|
|
508
|
-
| `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot`
|
|
509
|
-
| `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined`
|
|
510
|
-
| `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>`
|
|
511
|
-
| `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]`
|
|
512
|
-
| `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate`
|
|
513
|
-
| `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceContract \| undefined`
|
|
514
|
-
| `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceContract`
|
|
515
|
-
| `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule`
|
|
516
|
-
| `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]`
|
|
517
|
-
| `resolveHostRoot` | function | `() => string`
|
|
518
|
-
| `resolveContainedPath` | function | `(root: string, path: string) => string \| undefined`
|
|
519
|
-
| `resolveRealPath` | function | `(path: string) => string \| undefined`
|
|
520
|
-
| `stageBytes` | function | `(host: Host, root: string, destinations: readonly string[]) => readonly
|
|
521
|
-
| `stageHost` | function | `(checkout: string, host: string, options?: HostStageOptions) => readonly
|
|
522
|
-
| `stageInventory` | function | `(checkout: string, path?: string) => HostManifest`
|
|
473
|
+
| Name | Kind | Signature | Summary |
|
|
474
|
+
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
475
|
+
| `climbRealPath` | function | `(current: string, pending: readonly string[], depth: number) => string \| undefined` | Climbs from an absolute path to its deepest existing ancestor and resolves it through every link. |
|
|
476
|
+
| `collectIndexed` | function | `<TResult>(entries: ReadonlyArray<readonly [number, TResult]>) => readonly TResult[]` | Places each result at the index its entry names, in a fresh array. |
|
|
477
|
+
| `computeDigest` | function | `(content: string) => string` | Computes the SHA-256 digest of text. |
|
|
478
|
+
| `computeFileDigest` | function | `(path: string) => string \| undefined` | Computes the SHA-256 digest of one file's exact bytes. |
|
|
479
|
+
| `computeManifestDigest` | function | `(entries: readonly HostManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]) => string` | Computes the digest of a vendored host's declared membership. |
|
|
480
|
+
| `decodeHexText` | function | `(hex: string) => string \| undefined` | Decodes exact bytes stated in hexadecimal as strict UTF-8 text. |
|
|
481
|
+
| `filesToHost` | function | `(files: readonly HostFile[], floor: Host) => Host \| undefined` | Assembles a whole vendored host from live files and the installed floor. |
|
|
482
|
+
| `hexToDigest` | function | `(hex: string) => string` | Projects exact bytes stated in hexadecimal to their SHA-256 digest. |
|
|
483
|
+
| `isExactCaseFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file with exact on-disk casing. |
|
|
484
|
+
| `isPhysicalDirectory` | function | `(path: string) => boolean` | Tests whether a path is a physical directory this package will read or write into. |
|
|
485
|
+
| `isPhysicalFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file this package will read or replace. |
|
|
486
|
+
| `isVacant` | function | `(target: string) => boolean` | Tests whether a target is safe to write a fresh workspace into. |
|
|
487
|
+
| `listAncestors` | function | `(path: string, limit?: number) => readonly string[]` | Lists a path followed by each directory above it, nearest first. |
|
|
488
|
+
| `listCanonPaths` | function | `(target: string, groups: readonly ArtifactGroup[]) => readonly string[]` | Lists the canon paths a target holds, filtered to a plan's groups. |
|
|
489
|
+
| `listDirectories` | function | `(root: string) => readonly string[]` | Lists a directory's descendant directories as sorted root-relative paths. |
|
|
490
|
+
| `listFiles` | function | `(root: string) => readonly string[]` | Lists a directory's files as sorted root-relative paths. |
|
|
491
|
+
| `matchesAnchor` | function | `(anchor: WriteAnchor) => boolean` | Tests whether a path still holds the captured directory identity. |
|
|
492
|
+
| `matchesExecutablePath` | function | `(path: string) => boolean` | Tests whether a vendored path is one a target receives executable. |
|
|
493
|
+
| `matchesExpectation` | function | `(expectation: WriteExpectation) => boolean` | Tests whether a destination still holds what was captured of it. |
|
|
494
|
+
| `matchesGitPath` | function | `(path: string) => boolean` | Tests whether a path addresses a target's own repository metadata. |
|
|
495
|
+
| `matchesMissingPath` | function | `(error: unknown) => boolean` | Tests whether a caught filesystem error reports an absent path. |
|
|
496
|
+
| `matchesPrecondition` | function | `(precondition: WritePrecondition) => boolean` | Tests whether a destination still matches the narrower state a caller observed. |
|
|
497
|
+
| `matchesProtectedPath` | function | `(path: string) => boolean` | Tests whether a target-relative path is one no verb may delete. |
|
|
498
|
+
| `matchesSensitivePath` | function | `(path: string) => boolean` | Tests whether a path names local configuration or a credential. |
|
|
499
|
+
| `pathToStorage` | function | `(path: string) => string` | Projects a target-relative path to the storage name a vendored host holds it under. |
|
|
500
|
+
| `pruneEmptiedDirectories` | function | `(target: string, removed: readonly string[]) => readonly string[]` | Removes every directory one set of deletions emptied. |
|
|
501
|
+
| `readAnchor` | function | `(path: string) => WriteAnchor \| undefined` | Captures one directory's physical identity. |
|
|
502
|
+
| `readExpectation` | function | `(path: string) => WriteExpectation \| undefined` | Captures what one destination holds before a write. |
|
|
503
|
+
| `readFileHex` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as its exact bytes in lowercase hexadecimal. |
|
|
504
|
+
| `readFileText` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as bounded UTF-8 text. |
|
|
505
|
+
| `readHostFloor` | function | `(root?: string) => Host` | Reads the installed vendored host floor as a value. |
|
|
506
|
+
| `readHostManifest` | function | `(host: string, name?: string) => HostManifest \| undefined` | Reads a vendored host's manifest, when it carries one. |
|
|
507
|
+
| `readHostManifestEntry` | function | `(destination: string, source: string) => HostManifestEntry \| undefined` | Derives one vendored-host manifest entry from a file in a checkout. |
|
|
508
|
+
| `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
|
|
509
|
+
| `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
|
|
510
|
+
| `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
|
|
511
|
+
| `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
|
|
512
|
+
| `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
|
|
513
|
+
| `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceContract \| undefined` | Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim. |
|
|
514
|
+
| `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceContract` | Reads one guide's claims and reports parser refusals with its owner and source. |
|
|
515
|
+
| `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
|
|
516
|
+
| `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
|
|
517
|
+
| `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
|
|
518
|
+
| `resolveContainedPath` | function | `(root: string, path: string) => string \| undefined` | Resolves a root-relative path and refuses one that leaves its root. |
|
|
519
|
+
| `resolveRealPath` | function | `(path: string) => string \| undefined` | Resolves a path through the real filesystem, keeping the part that does not exist yet. |
|
|
520
|
+
| `stageBytes` | function | `(host: Host, root: string, destinations: readonly string[]) => readonly HostManifestEntry[]` | Stages the named destinations of a value host into a private root. |
|
|
521
|
+
| `stageHost` | function | `(checkout: string, host: string, options?: HostStageOptions) => readonly HostManifestEntry[]` | Stages a vendored host root from a real checkout. |
|
|
522
|
+
| `stageInventory` | function | `(checkout: string, path?: string) => HostManifest` | Stages the committed inventory of the files a vendored host carries. |
|
|
523
523
|
|
|
524
524
|
#### Classes
|
|
525
525
|
|
|
@@ -1742,7 +1742,7 @@ than a silent no-op.
|
|
|
1742
1742
|
A plan selects over the following groups, and a compile that names none covers all of them. Their
|
|
1743
1743
|
order is the order a plan lists its artifacts in.
|
|
1744
1744
|
|
|
1745
|
-
|
|
|
1745
|
+
| `ArtifactGroup` | Holds |
|
|
1746
1746
|
| --------------- | ------------------------------------------------------------------------------------------------- |
|
|
1747
1747
|
| `manifest` | `package.json` |
|
|
1748
1748
|
| `configs` | The root and per-target build configuration, and the root dotfiles |
|
|
@@ -1760,7 +1760,7 @@ target that lacks the file. It also carries the skill pointer set, three host-or
|
|
|
1760
1760
|
each name in `TARGET_SKILL_NAMES`, so every harness in a target discovers the package-facing skills
|
|
1761
1761
|
while their bodies, references, and scripts stay in the installed package. Every other canon path is
|
|
1762
1762
|
staged for reading, so no group selection copies a contract into a target, and a copy a target holds
|
|
1763
|
-
at one of them is foreign drift in the group `
|
|
1763
|
+
at one of them is foreign drift in the group `inferArtifactGroup` gives it. A scoped audit reads the canon
|
|
1764
1764
|
through that same selection, so a run excluding a group reports nothing there.
|
|
1765
1765
|
|
|
1766
1766
|
## Ownership and drift
|
|
@@ -2033,7 +2033,7 @@ defining paths, `studies` by an exact-case `*.test.ts` file beneath `tests/studi
|
|
|
2033
2033
|
configuration must keep those edits outside a content-owned file; `repair` restores that file to the
|
|
2034
2034
|
canonical project set.
|
|
2035
2035
|
|
|
2036
|
-
An audit reports one `
|
|
2036
|
+
An audit reports one `ArtifactFinding` per planned path, followed by every foreign path in the groups the
|
|
2037
2037
|
plan covers. That second list draws on a file beneath a vendored directory the plan expands and on a
|
|
2038
2038
|
file the target holds at a canon path the plan does not claim. Every planned finding carries its
|
|
2039
2039
|
artifact's `ownership`. A foreign finding has no ownership because no artifact was planned for its
|
|
@@ -2049,12 +2049,12 @@ aggregate tally.
|
|
|
2049
2049
|
The plan and snapshot are each bounded at `MAX_COLLECTION_ITEMS`. An audit may therefore carry one
|
|
2050
2050
|
finding per planned artifact plus one per unplanned snapshot path, up to `MAX_AUDIT_FINDINGS`.
|
|
2051
2051
|
|
|
2052
|
-
| `
|
|
2053
|
-
|
|
|
2054
|
-
| `aligned`
|
|
2055
|
-
| `stale`
|
|
2056
|
-
| `missing`
|
|
2057
|
-
| `foreign`
|
|
2052
|
+
| `ArtifactDrift` | Means |
|
|
2053
|
+
| --------------- | ------------------------------------- |
|
|
2054
|
+
| `aligned` | The target matches the plan |
|
|
2055
|
+
| `stale` | The target holds different bytes |
|
|
2056
|
+
| `missing` | The target holds no file at that path |
|
|
2057
|
+
| `foreign` | The plan does not own the path at all |
|
|
2058
2058
|
|
|
2059
2059
|
A stale or foreign finding carries the destination's exact bytes in `observed`, and that record is
|
|
2060
2060
|
the precondition the mutation is held to. A write that replaces stale bytes and a deletion that
|
|
@@ -2062,7 +2062,7 @@ removes a foreign file each fail when the destination no longer matches what the
|
|
|
2062
2062
|
The requirement sits in the type rather than in prose, because a deletion that cannot bind to what
|
|
2063
2063
|
the audit showed is the one thing the destructive verb must never do.
|
|
2064
2064
|
|
|
2065
|
-
`
|
|
2065
|
+
`isArtifactFinding` proves the shape a reader may destructure and nothing about whether the verdict is one
|
|
2066
2066
|
an audit could have reached. `repair` and `remove` re-derive every verdict themselves and act only
|
|
2067
2067
|
on what they derived, so a verdict the comparison could not have produced is refused by name rather
|
|
2068
2068
|
than acted on.
|
|
@@ -2427,7 +2427,7 @@ one; `.claude/AGENTS.md` § Models owns the rule.
|
|
|
2427
2427
|
```ts
|
|
2428
2428
|
import { stageHost } from '@orkestrel/scaffold/server'
|
|
2429
2429
|
|
|
2430
|
-
stageHost(process.cwd(), 'dist/host') // one
|
|
2430
|
+
stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
|
|
2431
2431
|
```
|
|
2432
2432
|
|
|
2433
2433
|
Each staged path is copied to a storage name, and every dot that opens a segment comes off,
|
|
@@ -46,8 +46,6 @@ db.prepare('SELECT name FROM users WHERE age >= ?').all([18]) // → [{ name: 'A
|
|
|
46
46
|
|
|
47
47
|
### Constants
|
|
48
48
|
|
|
49
|
-
A `Shape` cell holds the constant's declared type.
|
|
50
|
-
|
|
51
49
|
| Name | Kind | Signature | Summary |
|
|
52
50
|
| ------------------- | ----- | --------- | -------------------------------------------------------------------------------- |
|
|
53
51
|
| `SQLITE_CONSTRAINT` | const | `19` | Names the SQLite result code whose low byte, `19`, flags a constraint violation. |
|
|
@@ -70,8 +68,6 @@ non-writable own property.
|
|
|
70
68
|
|
|
71
69
|
### Types
|
|
72
70
|
|
|
73
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
74
|
-
|
|
75
71
|
| Name | Kind | Signature | Summary |
|
|
76
72
|
| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
73
|
| `SQLiteValue` | type | `null \| number \| bigint \| string \| Uint8Array` | Represents a value SQLite stores and returns natively — the bridge between SQLite's storage classes and their JS types. |
|