@orkestrel/scaffold 0.0.115 → 0.0.117
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 +138 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +368 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +558 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +55 -55
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +90 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +88 -5
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +295 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +193 -6
- package/dist/src/server/index.d.ts +193 -6
- package/dist/src/server/index.js +290 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -13,6 +13,9 @@ import type { Mirror } from '@orkestrel/scaffold';
|
|
|
13
13
|
import type { Plan } from '@orkestrel/scaffold';
|
|
14
14
|
import type { Release } from '@orkestrel/scaffold';
|
|
15
15
|
import type { Snapshot } from '@orkestrel/scaffold';
|
|
16
|
+
import type { SurfaceCandidate } from '@orkestrel/scaffold';
|
|
17
|
+
import type { SurfaceClaim } from '@orkestrel/scaffold';
|
|
18
|
+
import type { SurfaceCollision } from '@orkestrel/scaffold';
|
|
16
19
|
|
|
17
20
|
/**
|
|
18
21
|
* Matches the Git branch syntax the repository endpoint accepts.
|
|
@@ -33,11 +36,13 @@ export declare const BRANCH_PATTERN: RegExp;
|
|
|
33
36
|
* `found`; otherwise it is empty and `note` states what happened. Bytes rather
|
|
34
37
|
* than text, because a vendored file is compared by digest and a decode would
|
|
35
38
|
* change what is hashed.
|
|
39
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
36
40
|
*/
|
|
37
41
|
export declare interface BytesReadResult {
|
|
38
42
|
readonly lookup: Lookup;
|
|
39
43
|
readonly hex: string;
|
|
40
44
|
readonly note: string;
|
|
45
|
+
readonly unreachable?: boolean;
|
|
41
46
|
}
|
|
42
47
|
|
|
43
48
|
/**
|
|
@@ -324,13 +329,17 @@ export declare interface Host {
|
|
|
324
329
|
* call inherits it when it is not `found`. `digests` maps a target-relative
|
|
325
330
|
* destination to the exact bytes the inventory declares for it, `duplicates`
|
|
326
331
|
* names every destination the inventory claims more than once, and `note` states
|
|
327
|
-
* why a lookup that is not `found` produced no inventory.
|
|
332
|
+
* why a lookup that is not `found` produced no inventory. `surface` holds the
|
|
333
|
+
* verified collision record when found and an empty collection otherwise.
|
|
334
|
+
* `unreachable` is true only when the inventory request produced no HTTP response.
|
|
328
335
|
*/
|
|
329
336
|
export declare interface HostInventory {
|
|
330
337
|
readonly lookup: Lookup;
|
|
331
338
|
readonly digests: ReadonlyMap<string, string>;
|
|
332
339
|
readonly duplicates: ReadonlySet<string>;
|
|
333
340
|
readonly note: string;
|
|
341
|
+
readonly surface: readonly SurfaceCollision[];
|
|
342
|
+
readonly unreachable?: boolean;
|
|
334
343
|
}
|
|
335
344
|
|
|
336
345
|
/**
|
|
@@ -713,6 +722,17 @@ export declare function isPhysicalDirectory(path: string): boolean;
|
|
|
713
722
|
*/
|
|
714
723
|
export declare function isPhysicalFile(path: string): boolean;
|
|
715
724
|
|
|
725
|
+
/**
|
|
726
|
+
* Narrows a value to the callable guide functions surface reflection requires.
|
|
727
|
+
*
|
|
728
|
+
* @example
|
|
729
|
+
* ```ts
|
|
730
|
+
* import { isSurfaceModule } from '@orkestrel/scaffold/server'
|
|
731
|
+
* isSurfaceModule({}) // false
|
|
732
|
+
* ```
|
|
733
|
+
*/
|
|
734
|
+
export declare function isSurfaceModule(value: unknown): value is SurfaceModule;
|
|
735
|
+
|
|
716
736
|
/**
|
|
717
737
|
* Narrows a value to a per-request timeout in milliseconds.
|
|
718
738
|
*
|
|
@@ -2011,6 +2031,44 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2011
2031
|
*/
|
|
2012
2032
|
export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
|
|
2013
2033
|
|
|
2034
|
+
/**
|
|
2035
|
+
* Reads a checkout's combined guide and barrel claims under its manifest owner.
|
|
2036
|
+
*
|
|
2037
|
+
* @remarks
|
|
2038
|
+
* Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
|
|
2039
|
+
* src environment through @orkestrel/guide, loaded only when called, and reports each
|
|
2040
|
+
* name two or more environments export as a conflict.
|
|
2041
|
+
* Reads only .ts files and refuses barrel statements outside relative .js star exports.
|
|
2042
|
+
* A present unreadable guide refuses the candidate even when src exists.
|
|
2043
|
+
* `loader` selects the resolver used by the shared validated guide loader.
|
|
2044
|
+
* @throws Thrown when the manifest is unreadable, both claim sources are absent,
|
|
2045
|
+
* a source cannot be read, or @orkestrel/guide cannot be loaded.
|
|
2046
|
+
*
|
|
2047
|
+
* @example
|
|
2048
|
+
* ```ts
|
|
2049
|
+
* import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
|
|
2050
|
+
*
|
|
2051
|
+
* readSurfaceCandidate('.') // the working checkout's owner and combined names
|
|
2052
|
+
* ```
|
|
2053
|
+
*/
|
|
2054
|
+
export declare function readSurfaceCandidate(root: string, loader?: SurfaceLoader): SurfaceCandidate;
|
|
2055
|
+
|
|
2056
|
+
/**
|
|
2057
|
+
* Reads each immediate package guide's bare names under its file owner.
|
|
2058
|
+
*
|
|
2059
|
+
* @param root - The directory containing the package guides; README.md is excluded.
|
|
2060
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
2061
|
+
* @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
|
|
2062
|
+
*
|
|
2063
|
+
* @example
|
|
2064
|
+
* ```ts
|
|
2065
|
+
* import { readSurfaceClaims } from '@orkestrel/scaffold/server'
|
|
2066
|
+
*
|
|
2067
|
+
* readSurfaceClaims('./guides') // owners and the names their guides claim
|
|
2068
|
+
* ```
|
|
2069
|
+
*/
|
|
2070
|
+
export declare function readSurfaceClaims(root: string, loader?: SurfaceLoader): readonly SurfaceClaim[];
|
|
2071
|
+
|
|
2014
2072
|
/**
|
|
2015
2073
|
* Reads bare Surface names claimed by distinct package guides.
|
|
2016
2074
|
*
|
|
@@ -2034,6 +2092,73 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2034
2092
|
*/
|
|
2035
2093
|
export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
|
|
2036
2094
|
|
|
2095
|
+
/**
|
|
2096
|
+
* Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
|
|
2097
|
+
*
|
|
2098
|
+
* @param root - The checkout or data root holding the guide, or a verified host whose bytes
|
|
2099
|
+
* carry it at that destination.
|
|
2100
|
+
* @param owner - The unscoped package name the guide file is named for.
|
|
2101
|
+
* @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
|
|
2102
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
2103
|
+
* @returns The claim, or `undefined` when no file sits at the path or the host declares none.
|
|
2104
|
+
* @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
|
|
2105
|
+
* file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
|
|
2106
|
+
*
|
|
2107
|
+
* @example
|
|
2108
|
+
* ```ts
|
|
2109
|
+
* import { readSurfaceFile } from '@orkestrel/scaffold/server'
|
|
2110
|
+
*
|
|
2111
|
+
* readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
|
|
2112
|
+
* ```
|
|
2113
|
+
*/
|
|
2114
|
+
export declare function readSurfaceFile(root: string | Host, owner: string, label: string, loader?: SurfaceLoader): SurfaceClaim | undefined;
|
|
2115
|
+
|
|
2116
|
+
/**
|
|
2117
|
+
* Reads one guide's claims and reports parser refusals with its owner and source.
|
|
2118
|
+
*
|
|
2119
|
+
* @param source - The source label or path to name in a refusal.
|
|
2120
|
+
* @throws Thrown with TARGET when the module is unusable or the guide parser refuses the guide
|
|
2121
|
+
* with an error its `isGuideError` guard accepts; every other parser error propagates unchanged.
|
|
2122
|
+
* @example
|
|
2123
|
+
* ```ts
|
|
2124
|
+
* import { readSurfaceGuide } from '@orkestrel/scaffold/server'
|
|
2125
|
+
* readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
|
|
2126
|
+
* ```
|
|
2127
|
+
*/
|
|
2128
|
+
export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
|
|
2129
|
+
|
|
2130
|
+
/**
|
|
2131
|
+
* Loads and validates the guide functions required by surface reflection.
|
|
2132
|
+
*
|
|
2133
|
+
* @param loader - The module resolver. Default: Node resolution from this module.
|
|
2134
|
+
* @throws Thrown with TARGET when the module is absent or lacks a required function.
|
|
2135
|
+
* @example
|
|
2136
|
+
* ```ts
|
|
2137
|
+
* import { readSurfaceModule } from '@orkestrel/scaffold/server'
|
|
2138
|
+
* readSurfaceModule().createGuide('# Sample').surface() // []
|
|
2139
|
+
* ```
|
|
2140
|
+
*/
|
|
2141
|
+
export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
|
|
2142
|
+
|
|
2143
|
+
/**
|
|
2144
|
+
* Reads a data root's verified collision record.
|
|
2145
|
+
*
|
|
2146
|
+
* @param root - The data root holding `manifest.json` or `host.json`.
|
|
2147
|
+
* @remarks
|
|
2148
|
+
* Reads `manifest.json` first, then `host.json` when no built manifest exists.
|
|
2149
|
+
* Reads only local files and never contacts upstream or writes an inventory.
|
|
2150
|
+
* @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
|
|
2151
|
+
* throws when one is unreadable, malformed, or inconsistent with its digest.
|
|
2152
|
+
*
|
|
2153
|
+
* @example
|
|
2154
|
+
* ```ts
|
|
2155
|
+
* import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2156
|
+
*
|
|
2157
|
+
* readSurfaceRecord(resolveHostRoot()) // the bundled collision record
|
|
2158
|
+
* ```
|
|
2159
|
+
*/
|
|
2160
|
+
export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
|
|
2161
|
+
|
|
2037
2162
|
/**
|
|
2038
2163
|
* Matches the Windows device names that stay reserved even when an extension follows.
|
|
2039
2164
|
*
|
|
@@ -2084,6 +2209,17 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2084
2209
|
*/
|
|
2085
2210
|
export declare function resolveContainedPath(root: string, path: string): string | undefined;
|
|
2086
2211
|
|
|
2212
|
+
/**
|
|
2213
|
+
* Resolves the bundled host root from the executing module's location.
|
|
2214
|
+
*
|
|
2215
|
+
* @example
|
|
2216
|
+
* ```ts
|
|
2217
|
+
* import { resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2218
|
+
* resolveHostRoot() // the checkout in source, or the installed dist/host directory
|
|
2219
|
+
* ```
|
|
2220
|
+
*/
|
|
2221
|
+
export declare function resolveHostRoot(): string;
|
|
2222
|
+
|
|
2087
2223
|
/**
|
|
2088
2224
|
* Resolves a path through the real filesystem, keeping the part that does not exist yet.
|
|
2089
2225
|
*
|
|
@@ -2278,10 +2414,38 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2278
2414
|
*/
|
|
2279
2415
|
export declare function stageInventory(checkout: string, path?: string): HostManifest;
|
|
2280
2416
|
|
|
2281
|
-
/**
|
|
2282
|
-
export declare
|
|
2283
|
-
|
|
2284
|
-
|
|
2417
|
+
/** Loads a module by specifier for validated surface reflection. */
|
|
2418
|
+
export declare type SurfaceLoader = (specifier: string) => unknown;
|
|
2419
|
+
|
|
2420
|
+
/**
|
|
2421
|
+
* Describes the guide module functions required by surface reflection.
|
|
2422
|
+
*
|
|
2423
|
+
* @remarks
|
|
2424
|
+
* Declares only the members surface reflection calls, so a consumer of these declarations needs
|
|
2425
|
+
* no copy of `@orkestrel/guide`.
|
|
2426
|
+
*/
|
|
2427
|
+
export declare interface SurfaceModule {
|
|
2428
|
+
readonly createGuide: (text: string) => {
|
|
2429
|
+
readonly surface: () => ReadonlyArray<{
|
|
2430
|
+
readonly name: string;
|
|
2431
|
+
}>;
|
|
2432
|
+
};
|
|
2433
|
+
readonly createSource: (options: {
|
|
2434
|
+
readonly files: Readonly<Record<string, string>>;
|
|
2435
|
+
readonly module: string;
|
|
2436
|
+
}) => {
|
|
2437
|
+
readonly surface: () => ReadonlyArray<{
|
|
2438
|
+
readonly name: string;
|
|
2439
|
+
}>;
|
|
2440
|
+
};
|
|
2441
|
+
readonly extractSourceLines: (text: string) => ReadonlyArray<{
|
|
2442
|
+
readonly code: string;
|
|
2443
|
+
readonly source: string;
|
|
2444
|
+
}>;
|
|
2445
|
+
readonly isGuideError: (value: unknown) => value is Error & {
|
|
2446
|
+
readonly code: string;
|
|
2447
|
+
readonly message: string;
|
|
2448
|
+
};
|
|
2285
2449
|
}
|
|
2286
2450
|
|
|
2287
2451
|
/**
|
|
@@ -2291,11 +2455,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2291
2455
|
* `content` carries the body only when `lookup` is `found`; otherwise it is
|
|
2292
2456
|
* empty and `note` states what happened. A read that is not `found` is an answer
|
|
2293
2457
|
* rather than a throw, which is what lets one dead row sit beside live ones.
|
|
2458
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
2294
2459
|
*/
|
|
2295
2460
|
export declare interface TextReadResult {
|
|
2296
2461
|
readonly lookup: Lookup;
|
|
2297
2462
|
readonly content: string;
|
|
2298
2463
|
readonly note: string;
|
|
2464
|
+
readonly unreachable?: boolean;
|
|
2299
2465
|
}
|
|
2300
2466
|
|
|
2301
2467
|
/** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
|
|
@@ -2479,7 +2645,9 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2479
2645
|
* unreadable list would otherwise be written into a target's catalog table as
|
|
2480
2646
|
* a fleet with no packages in it. A package whose own version lookup then
|
|
2481
2647
|
* fails still keeps its row, carrying the cause instead of a version, because
|
|
2482
|
-
* the list already proved the package is published.
|
|
2648
|
+
* the list already proved the package is published. The `FETCH` failure's
|
|
2649
|
+
* context carries `unreachable: true` only when the list request produced no
|
|
2650
|
+
* HTTP response.
|
|
2483
2651
|
*
|
|
2484
2652
|
* @example
|
|
2485
2653
|
* ```ts
|
|
@@ -2491,6 +2659,23 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2491
2659
|
* ```
|
|
2492
2660
|
*/
|
|
2493
2661
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2662
|
+
/**
|
|
2663
|
+
* Reads the verified upstream inventory and its collision record.
|
|
2664
|
+
*
|
|
2665
|
+
* @param allowance - A shared call allowance; omitted calls open their own budget.
|
|
2666
|
+
* @returns A found inventory with its surface, or an unfound verdict with empty collections,
|
|
2667
|
+
* carrying `unreachable: true` only when the request produced no HTTP response.
|
|
2668
|
+
* @throws Thrown with DESTROYED when the reader has been torn down.
|
|
2669
|
+
* @example
|
|
2670
|
+
* ```ts
|
|
2671
|
+
* import { Upstream } from '@orkestrel/scaffold/server'
|
|
2672
|
+
* const upstream = new Upstream()
|
|
2673
|
+
* const inventory = await upstream.inventory()
|
|
2674
|
+
* inventory.surface // the verified record when lookup is found
|
|
2675
|
+
* upstream.destroy()
|
|
2676
|
+
* ```
|
|
2677
|
+
*/
|
|
2678
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2494
2679
|
/**
|
|
2495
2680
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2496
2681
|
*
|
|
@@ -2575,6 +2760,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2575
2760
|
* @returns One row per published package, sorted by name.
|
|
2576
2761
|
*/
|
|
2577
2762
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2763
|
+
/** Reads the verified upstream inventory and its collision record. */
|
|
2764
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2578
2765
|
/**
|
|
2579
2766
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2580
2767
|
*
|
|
@@ -13,6 +13,9 @@ import type { Mirror } from '@orkestrel/scaffold';
|
|
|
13
13
|
import type { Plan } from '@orkestrel/scaffold';
|
|
14
14
|
import type { Release } from '@orkestrel/scaffold';
|
|
15
15
|
import type { Snapshot } from '@orkestrel/scaffold';
|
|
16
|
+
import type { SurfaceCandidate } from '@orkestrel/scaffold';
|
|
17
|
+
import type { SurfaceClaim } from '@orkestrel/scaffold';
|
|
18
|
+
import type { SurfaceCollision } from '@orkestrel/scaffold';
|
|
16
19
|
|
|
17
20
|
/**
|
|
18
21
|
* Matches the Git branch syntax the repository endpoint accepts.
|
|
@@ -33,11 +36,13 @@ export declare const BRANCH_PATTERN: RegExp;
|
|
|
33
36
|
* `found`; otherwise it is empty and `note` states what happened. Bytes rather
|
|
34
37
|
* than text, because a vendored file is compared by digest and a decode would
|
|
35
38
|
* change what is hashed.
|
|
39
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
36
40
|
*/
|
|
37
41
|
export declare interface BytesReadResult {
|
|
38
42
|
readonly lookup: Lookup;
|
|
39
43
|
readonly hex: string;
|
|
40
44
|
readonly note: string;
|
|
45
|
+
readonly unreachable?: boolean;
|
|
41
46
|
}
|
|
42
47
|
|
|
43
48
|
/**
|
|
@@ -324,13 +329,17 @@ export declare interface Host {
|
|
|
324
329
|
* call inherits it when it is not `found`. `digests` maps a target-relative
|
|
325
330
|
* destination to the exact bytes the inventory declares for it, `duplicates`
|
|
326
331
|
* names every destination the inventory claims more than once, and `note` states
|
|
327
|
-
* why a lookup that is not `found` produced no inventory.
|
|
332
|
+
* why a lookup that is not `found` produced no inventory. `surface` holds the
|
|
333
|
+
* verified collision record when found and an empty collection otherwise.
|
|
334
|
+
* `unreachable` is true only when the inventory request produced no HTTP response.
|
|
328
335
|
*/
|
|
329
336
|
export declare interface HostInventory {
|
|
330
337
|
readonly lookup: Lookup;
|
|
331
338
|
readonly digests: ReadonlyMap<string, string>;
|
|
332
339
|
readonly duplicates: ReadonlySet<string>;
|
|
333
340
|
readonly note: string;
|
|
341
|
+
readonly surface: readonly SurfaceCollision[];
|
|
342
|
+
readonly unreachable?: boolean;
|
|
334
343
|
}
|
|
335
344
|
|
|
336
345
|
/**
|
|
@@ -713,6 +722,17 @@ export declare function isPhysicalDirectory(path: string): boolean;
|
|
|
713
722
|
*/
|
|
714
723
|
export declare function isPhysicalFile(path: string): boolean;
|
|
715
724
|
|
|
725
|
+
/**
|
|
726
|
+
* Narrows a value to the callable guide functions surface reflection requires.
|
|
727
|
+
*
|
|
728
|
+
* @example
|
|
729
|
+
* ```ts
|
|
730
|
+
* import { isSurfaceModule } from '@orkestrel/scaffold/server'
|
|
731
|
+
* isSurfaceModule({}) // false
|
|
732
|
+
* ```
|
|
733
|
+
*/
|
|
734
|
+
export declare function isSurfaceModule(value: unknown): value is SurfaceModule;
|
|
735
|
+
|
|
716
736
|
/**
|
|
717
737
|
* Narrows a value to a per-request timeout in milliseconds.
|
|
718
738
|
*
|
|
@@ -2011,6 +2031,44 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2011
2031
|
*/
|
|
2012
2032
|
export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
|
|
2013
2033
|
|
|
2034
|
+
/**
|
|
2035
|
+
* Reads a checkout's combined guide and barrel claims under its manifest owner.
|
|
2036
|
+
*
|
|
2037
|
+
* @remarks
|
|
2038
|
+
* Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
|
|
2039
|
+
* src environment through @orkestrel/guide, loaded only when called, and reports each
|
|
2040
|
+
* name two or more environments export as a conflict.
|
|
2041
|
+
* Reads only .ts files and refuses barrel statements outside relative .js star exports.
|
|
2042
|
+
* A present unreadable guide refuses the candidate even when src exists.
|
|
2043
|
+
* `loader` selects the resolver used by the shared validated guide loader.
|
|
2044
|
+
* @throws Thrown when the manifest is unreadable, both claim sources are absent,
|
|
2045
|
+
* a source cannot be read, or @orkestrel/guide cannot be loaded.
|
|
2046
|
+
*
|
|
2047
|
+
* @example
|
|
2048
|
+
* ```ts
|
|
2049
|
+
* import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
|
|
2050
|
+
*
|
|
2051
|
+
* readSurfaceCandidate('.') // the working checkout's owner and combined names
|
|
2052
|
+
* ```
|
|
2053
|
+
*/
|
|
2054
|
+
export declare function readSurfaceCandidate(root: string, loader?: SurfaceLoader): SurfaceCandidate;
|
|
2055
|
+
|
|
2056
|
+
/**
|
|
2057
|
+
* Reads each immediate package guide's bare names under its file owner.
|
|
2058
|
+
*
|
|
2059
|
+
* @param root - The directory containing the package guides; README.md is excluded.
|
|
2060
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
2061
|
+
* @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
|
|
2062
|
+
*
|
|
2063
|
+
* @example
|
|
2064
|
+
* ```ts
|
|
2065
|
+
* import { readSurfaceClaims } from '@orkestrel/scaffold/server'
|
|
2066
|
+
*
|
|
2067
|
+
* readSurfaceClaims('./guides') // owners and the names their guides claim
|
|
2068
|
+
* ```
|
|
2069
|
+
*/
|
|
2070
|
+
export declare function readSurfaceClaims(root: string, loader?: SurfaceLoader): readonly SurfaceClaim[];
|
|
2071
|
+
|
|
2014
2072
|
/**
|
|
2015
2073
|
* Reads bare Surface names claimed by distinct package guides.
|
|
2016
2074
|
*
|
|
@@ -2034,6 +2092,73 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2034
2092
|
*/
|
|
2035
2093
|
export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
|
|
2036
2094
|
|
|
2095
|
+
/**
|
|
2096
|
+
* Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
|
|
2097
|
+
*
|
|
2098
|
+
* @param root - The checkout or data root holding the guide, or a verified host whose bytes
|
|
2099
|
+
* carry it at that destination.
|
|
2100
|
+
* @param owner - The unscoped package name the guide file is named for.
|
|
2101
|
+
* @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
|
|
2102
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
2103
|
+
* @returns The claim, or `undefined` when no file sits at the path or the host declares none.
|
|
2104
|
+
* @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
|
|
2105
|
+
* file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
|
|
2106
|
+
*
|
|
2107
|
+
* @example
|
|
2108
|
+
* ```ts
|
|
2109
|
+
* import { readSurfaceFile } from '@orkestrel/scaffold/server'
|
|
2110
|
+
*
|
|
2111
|
+
* readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
|
|
2112
|
+
* ```
|
|
2113
|
+
*/
|
|
2114
|
+
export declare function readSurfaceFile(root: string | Host, owner: string, label: string, loader?: SurfaceLoader): SurfaceClaim | undefined;
|
|
2115
|
+
|
|
2116
|
+
/**
|
|
2117
|
+
* Reads one guide's claims and reports parser refusals with its owner and source.
|
|
2118
|
+
*
|
|
2119
|
+
* @param source - The source label or path to name in a refusal.
|
|
2120
|
+
* @throws Thrown with TARGET when the module is unusable or the guide parser refuses the guide
|
|
2121
|
+
* with an error its `isGuideError` guard accepts; every other parser error propagates unchanged.
|
|
2122
|
+
* @example
|
|
2123
|
+
* ```ts
|
|
2124
|
+
* import { readSurfaceGuide } from '@orkestrel/scaffold/server'
|
|
2125
|
+
* readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
|
|
2126
|
+
* ```
|
|
2127
|
+
*/
|
|
2128
|
+
export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
|
|
2129
|
+
|
|
2130
|
+
/**
|
|
2131
|
+
* Loads and validates the guide functions required by surface reflection.
|
|
2132
|
+
*
|
|
2133
|
+
* @param loader - The module resolver. Default: Node resolution from this module.
|
|
2134
|
+
* @throws Thrown with TARGET when the module is absent or lacks a required function.
|
|
2135
|
+
* @example
|
|
2136
|
+
* ```ts
|
|
2137
|
+
* import { readSurfaceModule } from '@orkestrel/scaffold/server'
|
|
2138
|
+
* readSurfaceModule().createGuide('# Sample').surface() // []
|
|
2139
|
+
* ```
|
|
2140
|
+
*/
|
|
2141
|
+
export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
|
|
2142
|
+
|
|
2143
|
+
/**
|
|
2144
|
+
* Reads a data root's verified collision record.
|
|
2145
|
+
*
|
|
2146
|
+
* @param root - The data root holding `manifest.json` or `host.json`.
|
|
2147
|
+
* @remarks
|
|
2148
|
+
* Reads `manifest.json` first, then `host.json` when no built manifest exists.
|
|
2149
|
+
* Reads only local files and never contacts upstream or writes an inventory.
|
|
2150
|
+
* @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
|
|
2151
|
+
* throws when one is unreadable, malformed, or inconsistent with its digest.
|
|
2152
|
+
*
|
|
2153
|
+
* @example
|
|
2154
|
+
* ```ts
|
|
2155
|
+
* import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2156
|
+
*
|
|
2157
|
+
* readSurfaceRecord(resolveHostRoot()) // the bundled collision record
|
|
2158
|
+
* ```
|
|
2159
|
+
*/
|
|
2160
|
+
export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
|
|
2161
|
+
|
|
2037
2162
|
/**
|
|
2038
2163
|
* Matches the Windows device names that stay reserved even when an extension follows.
|
|
2039
2164
|
*
|
|
@@ -2084,6 +2209,17 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2084
2209
|
*/
|
|
2085
2210
|
export declare function resolveContainedPath(root: string, path: string): string | undefined;
|
|
2086
2211
|
|
|
2212
|
+
/**
|
|
2213
|
+
* Resolves the bundled host root from the executing module's location.
|
|
2214
|
+
*
|
|
2215
|
+
* @example
|
|
2216
|
+
* ```ts
|
|
2217
|
+
* import { resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2218
|
+
* resolveHostRoot() // the checkout in source, or the installed dist/host directory
|
|
2219
|
+
* ```
|
|
2220
|
+
*/
|
|
2221
|
+
export declare function resolveHostRoot(): string;
|
|
2222
|
+
|
|
2087
2223
|
/**
|
|
2088
2224
|
* Resolves a path through the real filesystem, keeping the part that does not exist yet.
|
|
2089
2225
|
*
|
|
@@ -2278,10 +2414,38 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2278
2414
|
*/
|
|
2279
2415
|
export declare function stageInventory(checkout: string, path?: string): HostManifest;
|
|
2280
2416
|
|
|
2281
|
-
/**
|
|
2282
|
-
export declare
|
|
2283
|
-
|
|
2284
|
-
|
|
2417
|
+
/** Loads a module by specifier for validated surface reflection. */
|
|
2418
|
+
export declare type SurfaceLoader = (specifier: string) => unknown;
|
|
2419
|
+
|
|
2420
|
+
/**
|
|
2421
|
+
* Describes the guide module functions required by surface reflection.
|
|
2422
|
+
*
|
|
2423
|
+
* @remarks
|
|
2424
|
+
* Declares only the members surface reflection calls, so a consumer of these declarations needs
|
|
2425
|
+
* no copy of `@orkestrel/guide`.
|
|
2426
|
+
*/
|
|
2427
|
+
export declare interface SurfaceModule {
|
|
2428
|
+
readonly createGuide: (text: string) => {
|
|
2429
|
+
readonly surface: () => ReadonlyArray<{
|
|
2430
|
+
readonly name: string;
|
|
2431
|
+
}>;
|
|
2432
|
+
};
|
|
2433
|
+
readonly createSource: (options: {
|
|
2434
|
+
readonly files: Readonly<Record<string, string>>;
|
|
2435
|
+
readonly module: string;
|
|
2436
|
+
}) => {
|
|
2437
|
+
readonly surface: () => ReadonlyArray<{
|
|
2438
|
+
readonly name: string;
|
|
2439
|
+
}>;
|
|
2440
|
+
};
|
|
2441
|
+
readonly extractSourceLines: (text: string) => ReadonlyArray<{
|
|
2442
|
+
readonly code: string;
|
|
2443
|
+
readonly source: string;
|
|
2444
|
+
}>;
|
|
2445
|
+
readonly isGuideError: (value: unknown) => value is Error & {
|
|
2446
|
+
readonly code: string;
|
|
2447
|
+
readonly message: string;
|
|
2448
|
+
};
|
|
2285
2449
|
}
|
|
2286
2450
|
|
|
2287
2451
|
/**
|
|
@@ -2291,11 +2455,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2291
2455
|
* `content` carries the body only when `lookup` is `found`; otherwise it is
|
|
2292
2456
|
* empty and `note` states what happened. A read that is not `found` is an answer
|
|
2293
2457
|
* rather than a throw, which is what lets one dead row sit beside live ones.
|
|
2458
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
2294
2459
|
*/
|
|
2295
2460
|
export declare interface TextReadResult {
|
|
2296
2461
|
readonly lookup: Lookup;
|
|
2297
2462
|
readonly content: string;
|
|
2298
2463
|
readonly note: string;
|
|
2464
|
+
readonly unreachable?: boolean;
|
|
2299
2465
|
}
|
|
2300
2466
|
|
|
2301
2467
|
/** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
|
|
@@ -2479,7 +2645,9 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2479
2645
|
* unreadable list would otherwise be written into a target's catalog table as
|
|
2480
2646
|
* a fleet with no packages in it. A package whose own version lookup then
|
|
2481
2647
|
* fails still keeps its row, carrying the cause instead of a version, because
|
|
2482
|
-
* the list already proved the package is published.
|
|
2648
|
+
* the list already proved the package is published. The `FETCH` failure's
|
|
2649
|
+
* context carries `unreachable: true` only when the list request produced no
|
|
2650
|
+
* HTTP response.
|
|
2483
2651
|
*
|
|
2484
2652
|
* @example
|
|
2485
2653
|
* ```ts
|
|
@@ -2491,6 +2659,23 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2491
2659
|
* ```
|
|
2492
2660
|
*/
|
|
2493
2661
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2662
|
+
/**
|
|
2663
|
+
* Reads the verified upstream inventory and its collision record.
|
|
2664
|
+
*
|
|
2665
|
+
* @param allowance - A shared call allowance; omitted calls open their own budget.
|
|
2666
|
+
* @returns A found inventory with its surface, or an unfound verdict with empty collections,
|
|
2667
|
+
* carrying `unreachable: true` only when the request produced no HTTP response.
|
|
2668
|
+
* @throws Thrown with DESTROYED when the reader has been torn down.
|
|
2669
|
+
* @example
|
|
2670
|
+
* ```ts
|
|
2671
|
+
* import { Upstream } from '@orkestrel/scaffold/server'
|
|
2672
|
+
* const upstream = new Upstream()
|
|
2673
|
+
* const inventory = await upstream.inventory()
|
|
2674
|
+
* inventory.surface // the verified record when lookup is found
|
|
2675
|
+
* upstream.destroy()
|
|
2676
|
+
* ```
|
|
2677
|
+
*/
|
|
2678
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2494
2679
|
/**
|
|
2495
2680
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2496
2681
|
*
|
|
@@ -2575,6 +2760,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2575
2760
|
* @returns One row per published package, sorted by name.
|
|
2576
2761
|
*/
|
|
2577
2762
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2763
|
+
/** Reads the verified upstream inventory and its collision record. */
|
|
2764
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2578
2765
|
/**
|
|
2579
2766
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2580
2767
|
*
|