@orkestrel/scaffold 0.0.119 → 0.0.121
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 +19 -19
- 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 +52 -51
- 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/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- 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/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- 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/terminal.md +0 -26
- 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/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- 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 +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -1,10 +1,10 @@
|
|
|
1
|
+
import type { ArtifactGroup } from '@orkestrel/scaffold';
|
|
1
2
|
import type { Audit } from '@orkestrel/scaffold';
|
|
2
3
|
import type { CatalogEntry } from '@orkestrel/scaffold';
|
|
3
4
|
import type { Dependency } from '@orkestrel/scaffold';
|
|
4
5
|
import type { EmitterErrorHandler } from '@orkestrel/emitter';
|
|
5
6
|
import type { EmitterHooks } from '@orkestrel/emitter';
|
|
6
7
|
import type { EmitterInterface } from '@orkestrel/emitter';
|
|
7
|
-
import type { Group } from '@orkestrel/scaffold';
|
|
8
8
|
import type { Guard } from '@orkestrel/contract';
|
|
9
9
|
import type { HostFile } from '@orkestrel/scaffold';
|
|
10
10
|
import type { Lookup } from '@orkestrel/scaffold';
|
|
@@ -16,6 +16,7 @@ import type { Snapshot } from '@orkestrel/scaffold';
|
|
|
16
16
|
import type { SurfaceCandidate } from '@orkestrel/scaffold';
|
|
17
17
|
import type { SurfaceCollision } from '@orkestrel/scaffold';
|
|
18
18
|
import type { SurfaceContract } from '@orkestrel/scaffold';
|
|
19
|
+
import type { SurfaceTransfer } from '@orkestrel/scaffold';
|
|
19
20
|
|
|
20
21
|
/**
|
|
21
22
|
* Matches the Git branch syntax the repository endpoint accepts.
|
|
@@ -165,7 +166,7 @@ export declare function computeFileDigest(path: string): string | undefined;
|
|
|
165
166
|
* computeManifestDigest([], [], []) // the digest of the empty membership
|
|
166
167
|
* ```
|
|
167
168
|
*/
|
|
168
|
-
export declare function computeManifestDigest(entries: readonly
|
|
169
|
+
export declare function computeManifestDigest(entries: readonly HostManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
|
|
169
170
|
|
|
170
171
|
/**
|
|
171
172
|
* Decodes exact bytes stated in hexadecimal as strict UTF-8 text.
|
|
@@ -356,12 +357,27 @@ export declare interface HostInventory {
|
|
|
356
357
|
* contract.
|
|
357
358
|
*/
|
|
358
359
|
export declare interface HostManifest {
|
|
359
|
-
readonly entries: readonly
|
|
360
|
+
readonly entries: readonly HostManifestEntry[];
|
|
360
361
|
readonly roots: readonly string[];
|
|
361
362
|
readonly surface: readonly SurfaceCollision[];
|
|
362
363
|
readonly digest: string;
|
|
363
364
|
}
|
|
364
365
|
|
|
366
|
+
/**
|
|
367
|
+
* Represents one file record of the vendored host's manifest.
|
|
368
|
+
*
|
|
369
|
+
* @remarks
|
|
370
|
+
* `digest` is the SHA-256 of the file's exact bytes. A live read compares it
|
|
371
|
+
* against the target's copy, and verifies host-supplied bytes against it before
|
|
372
|
+
* treating them as that entry.
|
|
373
|
+
*/
|
|
374
|
+
export declare interface HostManifestEntry {
|
|
375
|
+
readonly storage: string;
|
|
376
|
+
readonly destination: string;
|
|
377
|
+
readonly executable: boolean;
|
|
378
|
+
readonly digest: string;
|
|
379
|
+
}
|
|
380
|
+
|
|
365
381
|
/**
|
|
366
382
|
* Configures the committed inventory baseline and staging reports.
|
|
367
383
|
*
|
|
@@ -370,11 +386,13 @@ export declare interface HostManifest {
|
|
|
370
386
|
* `inventory` is relative to the checkout. Default: `host.json`.
|
|
371
387
|
* `establish`: if `true`, an absent inventory establishes the baseline; if `false`,
|
|
372
388
|
* an absent inventory refuses staging. Default: `false`.
|
|
389
|
+
* `transfers` lists the declared transfers the stage admits. Default: `SURFACE_TRANSFERS`.
|
|
373
390
|
*/
|
|
374
391
|
export declare interface HostStageOptions {
|
|
375
392
|
readonly inventory?: string;
|
|
376
393
|
readonly establish?: boolean;
|
|
377
394
|
readonly report?: (message: string) => void;
|
|
395
|
+
readonly transfers?: readonly SurfaceTransfer[];
|
|
378
396
|
}
|
|
379
397
|
|
|
380
398
|
/**
|
|
@@ -557,6 +575,29 @@ export declare const isHost: Guard<Host>;
|
|
|
557
575
|
*/
|
|
558
576
|
export declare const isHostManifest: Guard<HostManifest>;
|
|
559
577
|
|
|
578
|
+
/**
|
|
579
|
+
* Narrows a value to one {@link HostManifestEntry}.
|
|
580
|
+
*
|
|
581
|
+
* @remarks
|
|
582
|
+
* Both paths are measured by the core path law, because a vendored host's
|
|
583
|
+
* storage name and the destination it maps to are each a path inside a
|
|
584
|
+
* workspace. That is what stops a hand-edited manifest from mapping a vendored
|
|
585
|
+
* file to a destination outside the target.
|
|
586
|
+
*
|
|
587
|
+
* @example
|
|
588
|
+
* ```ts
|
|
589
|
+
* import { isHostManifestEntry } from '@orkestrel/scaffold/server'
|
|
590
|
+
*
|
|
591
|
+
* isHostManifestEntry({
|
|
592
|
+
* storage: 'AGENTS.md',
|
|
593
|
+
* destination: 'AGENTS.md',
|
|
594
|
+
* executable: false,
|
|
595
|
+
* digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
|
|
596
|
+
* }) // true
|
|
597
|
+
* ```
|
|
598
|
+
*/
|
|
599
|
+
export declare const isHostManifestEntry: Guard<HostManifestEntry>;
|
|
600
|
+
|
|
560
601
|
/**
|
|
561
602
|
* Narrows a value to a working-tree inventory within the limit one target may report.
|
|
562
603
|
*
|
|
@@ -582,29 +623,6 @@ export declare const isHostManifest: Guard<HostManifest>;
|
|
|
582
623
|
*/
|
|
583
624
|
export declare function isInventory(value: unknown): value is readonly unknown[];
|
|
584
625
|
|
|
585
|
-
/**
|
|
586
|
-
* Narrows a value to one {@link ManifestEntry}.
|
|
587
|
-
*
|
|
588
|
-
* @remarks
|
|
589
|
-
* Both paths are measured by the core path law, because a vendored host's
|
|
590
|
-
* storage name and the destination it maps to are each a path inside a
|
|
591
|
-
* workspace. That is what stops a hand-edited manifest from mapping a vendored
|
|
592
|
-
* file to a destination outside the target.
|
|
593
|
-
*
|
|
594
|
-
* @example
|
|
595
|
-
* ```ts
|
|
596
|
-
* import { isManifestEntry } from '@orkestrel/scaffold/server'
|
|
597
|
-
*
|
|
598
|
-
* isManifestEntry({
|
|
599
|
-
* storage: 'AGENTS.md',
|
|
600
|
-
* destination: 'AGENTS.md',
|
|
601
|
-
* executable: false,
|
|
602
|
-
* digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
|
|
603
|
-
* }) // true
|
|
604
|
-
* ```
|
|
605
|
-
*/
|
|
606
|
-
export declare const isManifestEntry: Guard<ManifestEntry>;
|
|
607
|
-
|
|
608
626
|
/**
|
|
609
627
|
* Narrows a value to one {@link ManifestRegionSet}.
|
|
610
628
|
*
|
|
@@ -871,7 +889,7 @@ export declare function listAncestors(path: string, limit?: number): readonly st
|
|
|
871
889
|
* listCanonPaths('vacant', ['orchestration']) // []
|
|
872
890
|
* ```
|
|
873
891
|
*/
|
|
874
|
-
export declare function listCanonPaths(target: string, groups: readonly
|
|
892
|
+
export declare function listCanonPaths(target: string, groups: readonly ArtifactGroup[]): readonly string[];
|
|
875
893
|
|
|
876
894
|
/**
|
|
877
895
|
* Lists a directory's descendant directories as sorted root-relative paths.
|
|
@@ -945,21 +963,6 @@ export declare function listFiles(root: string): readonly string[];
|
|
|
945
963
|
*/
|
|
946
964
|
export declare const MANIFEST_NAME = "manifest.json";
|
|
947
965
|
|
|
948
|
-
/**
|
|
949
|
-
* Represents one file record of the vendored host's manifest.
|
|
950
|
-
*
|
|
951
|
-
* @remarks
|
|
952
|
-
* `digest` is the SHA-256 of the file's exact bytes. A live read compares it
|
|
953
|
-
* against the target's copy, and verifies host-supplied bytes against it before
|
|
954
|
-
* treating them as that entry.
|
|
955
|
-
*/
|
|
956
|
-
export declare interface ManifestEntry {
|
|
957
|
-
readonly storage: string;
|
|
958
|
-
readonly destination: string;
|
|
959
|
-
readonly executable: boolean;
|
|
960
|
-
readonly digest: string;
|
|
961
|
-
}
|
|
962
|
-
|
|
963
966
|
/**
|
|
964
967
|
* Tests whether a path still holds the captured directory identity.
|
|
965
968
|
*
|
|
@@ -1296,7 +1299,7 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1296
1299
|
* match the ones the audit carried for every path the plan owns; anything else
|
|
1297
1300
|
* means the target moved, and the whole call is refused. The audit is checked
|
|
1298
1301
|
* for agreement rather than for plausibility, so a verdict the comparison could
|
|
1299
|
-
* not have produced — a birth-owned path reported stale, which the `
|
|
1302
|
+
* not have produced — a birth-owned path reported stale, which the `ArtifactFinding`
|
|
1300
1303
|
* shape admits — disagrees with the derived one and is refused. A missing
|
|
1301
1304
|
* destination is restored whatever its ownership; a stale one is replaced only
|
|
1302
1305
|
* where the artifact claims its bytes, which is what leaves a presence-owned
|
|
@@ -1491,7 +1494,7 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1491
1494
|
* @remarks
|
|
1492
1495
|
* The audit is checked for agreement rather than for plausibility, so a verdict
|
|
1493
1496
|
* the comparison could not have produced — a birth-owned path reported stale,
|
|
1494
|
-
* which the `
|
|
1497
|
+
* which the `ArtifactFinding` shape admits — disagrees with the derived one and is
|
|
1495
1498
|
* refused.
|
|
1496
1499
|
*
|
|
1497
1500
|
* The whole audit is guarded before any of it is read, so an audit produced by
|
|
@@ -1974,13 +1977,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1974
1977
|
*
|
|
1975
1978
|
* @example
|
|
1976
1979
|
* ```ts
|
|
1977
|
-
* import {
|
|
1980
|
+
* import { readHostManifestEntry } from '@orkestrel/scaffold/server'
|
|
1978
1981
|
*
|
|
1979
|
-
*
|
|
1982
|
+
* readHostManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
|
|
1980
1983
|
* // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
|
|
1981
1984
|
* ```
|
|
1982
1985
|
*/
|
|
1983
|
-
export declare function
|
|
1986
|
+
export declare function readHostManifestEntry(destination: string, source: string): HostManifestEntry | undefined;
|
|
1984
1987
|
|
|
1985
1988
|
/**
|
|
1986
1989
|
* Reads a target's current bytes at the paths a plan claims.
|
|
@@ -2315,15 +2318,15 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2315
2318
|
* // [{ storage: 'scripts/codex.sh', destination: 'scripts/codex.sh', executable: true, digest: '…' }]
|
|
2316
2319
|
* ```
|
|
2317
2320
|
*/
|
|
2318
|
-
export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly
|
|
2321
|
+
export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly HostManifestEntry[];
|
|
2319
2322
|
|
|
2320
2323
|
/**
|
|
2321
2324
|
* Stages a vendored host root from a real checkout.
|
|
2322
2325
|
*
|
|
2323
2326
|
* @param checkout - The checkout the vendored paths are read from.
|
|
2324
2327
|
* @param host - The vendored host root to fill; it must be absent or empty.
|
|
2325
|
-
* @param options - The inventory selection, establishment switch,
|
|
2326
|
-
* Default: no reporting
|
|
2328
|
+
* @param options - The inventory selection, establishment switch, reporting callback, and
|
|
2329
|
+
* declared transfers. Default: no reporting, and the transfers in `SURFACE_TRANSFERS`.
|
|
2327
2330
|
* @returns One entry per staged file, sorted by storage name.
|
|
2328
2331
|
* @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
|
|
2329
2332
|
* or a vendored path leaves the checkout or the host root.
|
|
@@ -2331,8 +2334,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2331
2334
|
* host root is not vacant, the checkout does not carry every vendored path, two
|
|
2332
2335
|
* vendored files claim one storage name, a vendored file is not a plain file
|
|
2333
2336
|
* within the artifact ceiling, published guides are unreadable, a staged
|
|
2334
|
-
* collision's owner set is not a subset of its published owner set, a
|
|
2335
|
-
*
|
|
2337
|
+
* collision's owner set is not a subset of its published owner set, a declared
|
|
2338
|
+
* transfer is spent because its keeper alone claims the name, the
|
|
2336
2339
|
* inventory is absent without `establish: true`, or the staged manifest does not read back.
|
|
2337
2340
|
* @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
|
|
2338
2341
|
* be written.
|
|
@@ -2369,10 +2372,11 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2369
2372
|
* the canon and reference files for reading. Every catalog package must have a
|
|
2370
2373
|
* guide in the discovered membership before the host is written.
|
|
2371
2374
|
* Copied guides must carry no collision whose name and exact owner set the
|
|
2372
|
-
* committed inventory lacks. A
|
|
2373
|
-
*
|
|
2374
|
-
*
|
|
2375
|
-
*
|
|
2375
|
+
* committed inventory lacks. A declared transfer that another guide claims admits
|
|
2376
|
+
* its keeper beside the recorded owners, or beside the one owner of a name the
|
|
2377
|
+
* inventory lacks, and the staged surface records that keeper whether or not its
|
|
2378
|
+
* guide is mirrored. `options.transfers` declares the transfers, and its default is
|
|
2379
|
+
* `SURFACE_TRANSFERS`. An absent inventory requires `establish: true`;
|
|
2376
2380
|
* an inventory without a valid recorded Surface is refused.
|
|
2377
2381
|
* Everything downstream — the missing-path refusal, the
|
|
2378
2382
|
* storage collision guard, the sort, the digests, and the root inventory — reads
|
|
@@ -2387,10 +2391,10 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2387
2391
|
* ```ts
|
|
2388
2392
|
* import { stageHost } from '@orkestrel/scaffold/server'
|
|
2389
2393
|
*
|
|
2390
|
-
* stageHost(process.cwd(), 'dist/host') // one
|
|
2394
|
+
* stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
|
|
2391
2395
|
* ```
|
|
2392
2396
|
*/
|
|
2393
|
-
export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly
|
|
2397
|
+
export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly HostManifestEntry[];
|
|
2394
2398
|
|
|
2395
2399
|
/**
|
|
2396
2400
|
* Stages the committed inventory of the files a vendored host carries.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
+
import type { ArtifactGroup } from '@orkestrel/scaffold';
|
|
1
2
|
import type { Audit } from '@orkestrel/scaffold';
|
|
2
3
|
import type { CatalogEntry } from '@orkestrel/scaffold';
|
|
3
4
|
import type { Dependency } from '@orkestrel/scaffold';
|
|
4
5
|
import type { EmitterErrorHandler } from '@orkestrel/emitter';
|
|
5
6
|
import type { EmitterHooks } from '@orkestrel/emitter';
|
|
6
7
|
import type { EmitterInterface } from '@orkestrel/emitter';
|
|
7
|
-
import type { Group } from '@orkestrel/scaffold';
|
|
8
8
|
import type { Guard } from '@orkestrel/contract';
|
|
9
9
|
import type { HostFile } from '@orkestrel/scaffold';
|
|
10
10
|
import type { Lookup } from '@orkestrel/scaffold';
|
|
@@ -16,6 +16,7 @@ import type { Snapshot } from '@orkestrel/scaffold';
|
|
|
16
16
|
import type { SurfaceCandidate } from '@orkestrel/scaffold';
|
|
17
17
|
import type { SurfaceCollision } from '@orkestrel/scaffold';
|
|
18
18
|
import type { SurfaceContract } from '@orkestrel/scaffold';
|
|
19
|
+
import type { SurfaceTransfer } from '@orkestrel/scaffold';
|
|
19
20
|
|
|
20
21
|
/**
|
|
21
22
|
* Matches the Git branch syntax the repository endpoint accepts.
|
|
@@ -165,7 +166,7 @@ export declare function computeFileDigest(path: string): string | undefined;
|
|
|
165
166
|
* computeManifestDigest([], [], []) // the digest of the empty membership
|
|
166
167
|
* ```
|
|
167
168
|
*/
|
|
168
|
-
export declare function computeManifestDigest(entries: readonly
|
|
169
|
+
export declare function computeManifestDigest(entries: readonly HostManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
|
|
169
170
|
|
|
170
171
|
/**
|
|
171
172
|
* Decodes exact bytes stated in hexadecimal as strict UTF-8 text.
|
|
@@ -356,12 +357,27 @@ export declare interface HostInventory {
|
|
|
356
357
|
* contract.
|
|
357
358
|
*/
|
|
358
359
|
export declare interface HostManifest {
|
|
359
|
-
readonly entries: readonly
|
|
360
|
+
readonly entries: readonly HostManifestEntry[];
|
|
360
361
|
readonly roots: readonly string[];
|
|
361
362
|
readonly surface: readonly SurfaceCollision[];
|
|
362
363
|
readonly digest: string;
|
|
363
364
|
}
|
|
364
365
|
|
|
366
|
+
/**
|
|
367
|
+
* Represents one file record of the vendored host's manifest.
|
|
368
|
+
*
|
|
369
|
+
* @remarks
|
|
370
|
+
* `digest` is the SHA-256 of the file's exact bytes. A live read compares it
|
|
371
|
+
* against the target's copy, and verifies host-supplied bytes against it before
|
|
372
|
+
* treating them as that entry.
|
|
373
|
+
*/
|
|
374
|
+
export declare interface HostManifestEntry {
|
|
375
|
+
readonly storage: string;
|
|
376
|
+
readonly destination: string;
|
|
377
|
+
readonly executable: boolean;
|
|
378
|
+
readonly digest: string;
|
|
379
|
+
}
|
|
380
|
+
|
|
365
381
|
/**
|
|
366
382
|
* Configures the committed inventory baseline and staging reports.
|
|
367
383
|
*
|
|
@@ -370,11 +386,13 @@ export declare interface HostManifest {
|
|
|
370
386
|
* `inventory` is relative to the checkout. Default: `host.json`.
|
|
371
387
|
* `establish`: if `true`, an absent inventory establishes the baseline; if `false`,
|
|
372
388
|
* an absent inventory refuses staging. Default: `false`.
|
|
389
|
+
* `transfers` lists the declared transfers the stage admits. Default: `SURFACE_TRANSFERS`.
|
|
373
390
|
*/
|
|
374
391
|
export declare interface HostStageOptions {
|
|
375
392
|
readonly inventory?: string;
|
|
376
393
|
readonly establish?: boolean;
|
|
377
394
|
readonly report?: (message: string) => void;
|
|
395
|
+
readonly transfers?: readonly SurfaceTransfer[];
|
|
378
396
|
}
|
|
379
397
|
|
|
380
398
|
/**
|
|
@@ -557,6 +575,29 @@ export declare const isHost: Guard<Host>;
|
|
|
557
575
|
*/
|
|
558
576
|
export declare const isHostManifest: Guard<HostManifest>;
|
|
559
577
|
|
|
578
|
+
/**
|
|
579
|
+
* Narrows a value to one {@link HostManifestEntry}.
|
|
580
|
+
*
|
|
581
|
+
* @remarks
|
|
582
|
+
* Both paths are measured by the core path law, because a vendored host's
|
|
583
|
+
* storage name and the destination it maps to are each a path inside a
|
|
584
|
+
* workspace. That is what stops a hand-edited manifest from mapping a vendored
|
|
585
|
+
* file to a destination outside the target.
|
|
586
|
+
*
|
|
587
|
+
* @example
|
|
588
|
+
* ```ts
|
|
589
|
+
* import { isHostManifestEntry } from '@orkestrel/scaffold/server'
|
|
590
|
+
*
|
|
591
|
+
* isHostManifestEntry({
|
|
592
|
+
* storage: 'AGENTS.md',
|
|
593
|
+
* destination: 'AGENTS.md',
|
|
594
|
+
* executable: false,
|
|
595
|
+
* digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
|
|
596
|
+
* }) // true
|
|
597
|
+
* ```
|
|
598
|
+
*/
|
|
599
|
+
export declare const isHostManifestEntry: Guard<HostManifestEntry>;
|
|
600
|
+
|
|
560
601
|
/**
|
|
561
602
|
* Narrows a value to a working-tree inventory within the limit one target may report.
|
|
562
603
|
*
|
|
@@ -582,29 +623,6 @@ export declare const isHostManifest: Guard<HostManifest>;
|
|
|
582
623
|
*/
|
|
583
624
|
export declare function isInventory(value: unknown): value is readonly unknown[];
|
|
584
625
|
|
|
585
|
-
/**
|
|
586
|
-
* Narrows a value to one {@link ManifestEntry}.
|
|
587
|
-
*
|
|
588
|
-
* @remarks
|
|
589
|
-
* Both paths are measured by the core path law, because a vendored host's
|
|
590
|
-
* storage name and the destination it maps to are each a path inside a
|
|
591
|
-
* workspace. That is what stops a hand-edited manifest from mapping a vendored
|
|
592
|
-
* file to a destination outside the target.
|
|
593
|
-
*
|
|
594
|
-
* @example
|
|
595
|
-
* ```ts
|
|
596
|
-
* import { isManifestEntry } from '@orkestrel/scaffold/server'
|
|
597
|
-
*
|
|
598
|
-
* isManifestEntry({
|
|
599
|
-
* storage: 'AGENTS.md',
|
|
600
|
-
* destination: 'AGENTS.md',
|
|
601
|
-
* executable: false,
|
|
602
|
-
* digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
|
|
603
|
-
* }) // true
|
|
604
|
-
* ```
|
|
605
|
-
*/
|
|
606
|
-
export declare const isManifestEntry: Guard<ManifestEntry>;
|
|
607
|
-
|
|
608
626
|
/**
|
|
609
627
|
* Narrows a value to one {@link ManifestRegionSet}.
|
|
610
628
|
*
|
|
@@ -871,7 +889,7 @@ export declare function listAncestors(path: string, limit?: number): readonly st
|
|
|
871
889
|
* listCanonPaths('vacant', ['orchestration']) // []
|
|
872
890
|
* ```
|
|
873
891
|
*/
|
|
874
|
-
export declare function listCanonPaths(target: string, groups: readonly
|
|
892
|
+
export declare function listCanonPaths(target: string, groups: readonly ArtifactGroup[]): readonly string[];
|
|
875
893
|
|
|
876
894
|
/**
|
|
877
895
|
* Lists a directory's descendant directories as sorted root-relative paths.
|
|
@@ -945,21 +963,6 @@ export declare function listFiles(root: string): readonly string[];
|
|
|
945
963
|
*/
|
|
946
964
|
export declare const MANIFEST_NAME = "manifest.json";
|
|
947
965
|
|
|
948
|
-
/**
|
|
949
|
-
* Represents one file record of the vendored host's manifest.
|
|
950
|
-
*
|
|
951
|
-
* @remarks
|
|
952
|
-
* `digest` is the SHA-256 of the file's exact bytes. A live read compares it
|
|
953
|
-
* against the target's copy, and verifies host-supplied bytes against it before
|
|
954
|
-
* treating them as that entry.
|
|
955
|
-
*/
|
|
956
|
-
export declare interface ManifestEntry {
|
|
957
|
-
readonly storage: string;
|
|
958
|
-
readonly destination: string;
|
|
959
|
-
readonly executable: boolean;
|
|
960
|
-
readonly digest: string;
|
|
961
|
-
}
|
|
962
|
-
|
|
963
966
|
/**
|
|
964
967
|
* Tests whether a path still holds the captured directory identity.
|
|
965
968
|
*
|
|
@@ -1296,7 +1299,7 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1296
1299
|
* match the ones the audit carried for every path the plan owns; anything else
|
|
1297
1300
|
* means the target moved, and the whole call is refused. The audit is checked
|
|
1298
1301
|
* for agreement rather than for plausibility, so a verdict the comparison could
|
|
1299
|
-
* not have produced — a birth-owned path reported stale, which the `
|
|
1302
|
+
* not have produced — a birth-owned path reported stale, which the `ArtifactFinding`
|
|
1300
1303
|
* shape admits — disagrees with the derived one and is refused. A missing
|
|
1301
1304
|
* destination is restored whatever its ownership; a stale one is replaced only
|
|
1302
1305
|
* where the artifact claims its bytes, which is what leaves a presence-owned
|
|
@@ -1491,7 +1494,7 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1491
1494
|
* @remarks
|
|
1492
1495
|
* The audit is checked for agreement rather than for plausibility, so a verdict
|
|
1493
1496
|
* the comparison could not have produced — a birth-owned path reported stale,
|
|
1494
|
-
* which the `
|
|
1497
|
+
* which the `ArtifactFinding` shape admits — disagrees with the derived one and is
|
|
1495
1498
|
* refused.
|
|
1496
1499
|
*
|
|
1497
1500
|
* The whole audit is guarded before any of it is read, so an audit produced by
|
|
@@ -1974,13 +1977,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
1974
1977
|
*
|
|
1975
1978
|
* @example
|
|
1976
1979
|
* ```ts
|
|
1977
|
-
* import {
|
|
1980
|
+
* import { readHostManifestEntry } from '@orkestrel/scaffold/server'
|
|
1978
1981
|
*
|
|
1979
|
-
*
|
|
1982
|
+
* readHostManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
|
|
1980
1983
|
* // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
|
|
1981
1984
|
* ```
|
|
1982
1985
|
*/
|
|
1983
|
-
export declare function
|
|
1986
|
+
export declare function readHostManifestEntry(destination: string, source: string): HostManifestEntry | undefined;
|
|
1984
1987
|
|
|
1985
1988
|
/**
|
|
1986
1989
|
* Reads a target's current bytes at the paths a plan claims.
|
|
@@ -2315,15 +2318,15 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2315
2318
|
* // [{ storage: 'scripts/codex.sh', destination: 'scripts/codex.sh', executable: true, digest: '…' }]
|
|
2316
2319
|
* ```
|
|
2317
2320
|
*/
|
|
2318
|
-
export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly
|
|
2321
|
+
export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly HostManifestEntry[];
|
|
2319
2322
|
|
|
2320
2323
|
/**
|
|
2321
2324
|
* Stages a vendored host root from a real checkout.
|
|
2322
2325
|
*
|
|
2323
2326
|
* @param checkout - The checkout the vendored paths are read from.
|
|
2324
2327
|
* @param host - The vendored host root to fill; it must be absent or empty.
|
|
2325
|
-
* @param options - The inventory selection, establishment switch,
|
|
2326
|
-
* Default: no reporting
|
|
2328
|
+
* @param options - The inventory selection, establishment switch, reporting callback, and
|
|
2329
|
+
* declared transfers. Default: no reporting, and the transfers in `SURFACE_TRANSFERS`.
|
|
2327
2330
|
* @returns One entry per staged file, sorted by storage name.
|
|
2328
2331
|
* @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
|
|
2329
2332
|
* or a vendored path leaves the checkout or the host root.
|
|
@@ -2331,8 +2334,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2331
2334
|
* host root is not vacant, the checkout does not carry every vendored path, two
|
|
2332
2335
|
* vendored files claim one storage name, a vendored file is not a plain file
|
|
2333
2336
|
* within the artifact ceiling, published guides are unreadable, a staged
|
|
2334
|
-
* collision's owner set is not a subset of its published owner set, a
|
|
2335
|
-
*
|
|
2337
|
+
* collision's owner set is not a subset of its published owner set, a declared
|
|
2338
|
+
* transfer is spent because its keeper alone claims the name, the
|
|
2336
2339
|
* inventory is absent without `establish: true`, or the staged manifest does not read back.
|
|
2337
2340
|
* @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
|
|
2338
2341
|
* be written.
|
|
@@ -2369,10 +2372,11 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2369
2372
|
* the canon and reference files for reading. Every catalog package must have a
|
|
2370
2373
|
* guide in the discovered membership before the host is written.
|
|
2371
2374
|
* Copied guides must carry no collision whose name and exact owner set the
|
|
2372
|
-
* committed inventory lacks. A
|
|
2373
|
-
*
|
|
2374
|
-
*
|
|
2375
|
-
*
|
|
2375
|
+
* committed inventory lacks. A declared transfer that another guide claims admits
|
|
2376
|
+
* its keeper beside the recorded owners, or beside the one owner of a name the
|
|
2377
|
+
* inventory lacks, and the staged surface records that keeper whether or not its
|
|
2378
|
+
* guide is mirrored. `options.transfers` declares the transfers, and its default is
|
|
2379
|
+
* `SURFACE_TRANSFERS`. An absent inventory requires `establish: true`;
|
|
2376
2380
|
* an inventory without a valid recorded Surface is refused.
|
|
2377
2381
|
* Everything downstream — the missing-path refusal, the
|
|
2378
2382
|
* storage collision guard, the sort, the digests, and the root inventory — reads
|
|
@@ -2387,10 +2391,10 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2387
2391
|
* ```ts
|
|
2388
2392
|
* import { stageHost } from '@orkestrel/scaffold/server'
|
|
2389
2393
|
*
|
|
2390
|
-
* stageHost(process.cwd(), 'dist/host') // one
|
|
2394
|
+
* stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
|
|
2391
2395
|
* ```
|
|
2392
2396
|
*/
|
|
2393
|
-
export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly
|
|
2397
|
+
export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly HostManifestEntry[];
|
|
2394
2398
|
|
|
2395
2399
|
/**
|
|
2396
2400
|
* Stages the committed inventory of the files a vendored host carries.
|