@orkestrel/scaffold 0.0.114 → 0.0.116
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 +137 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +5 -7
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/claude/rules/tests.md +7 -4
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- 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 +361 -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 +554 -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 +93 -93
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +89 -3
- 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 +87 -4
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +292 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +188 -6
- package/dist/src/server/index.d.ts +188 -6
- package/dist/src/server/index.js +287 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -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,72 @@ 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 or the guide parser refuses the reading.
|
|
2121
|
+
* @example
|
|
2122
|
+
* ```ts
|
|
2123
|
+
* import { readSurfaceGuide } from '@orkestrel/scaffold/server'
|
|
2124
|
+
* readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
|
|
2125
|
+
* ```
|
|
2126
|
+
*/
|
|
2127
|
+
export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
|
|
2128
|
+
|
|
2129
|
+
/**
|
|
2130
|
+
* Loads and validates the guide functions required by surface reflection.
|
|
2131
|
+
*
|
|
2132
|
+
* @param loader - The module resolver. Default: Node resolution from this module.
|
|
2133
|
+
* @throws Thrown with TARGET when the module is absent or lacks a required function.
|
|
2134
|
+
* @example
|
|
2135
|
+
* ```ts
|
|
2136
|
+
* import { readSurfaceModule } from '@orkestrel/scaffold/server'
|
|
2137
|
+
* readSurfaceModule().createGuide('# Sample').surface() // []
|
|
2138
|
+
* ```
|
|
2139
|
+
*/
|
|
2140
|
+
export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
|
|
2141
|
+
|
|
2142
|
+
/**
|
|
2143
|
+
* Reads a data root's verified collision record.
|
|
2144
|
+
*
|
|
2145
|
+
* @param root - The data root holding `manifest.json` or `host.json`.
|
|
2146
|
+
* @remarks
|
|
2147
|
+
* Reads `manifest.json` first, then `host.json` when no built manifest exists.
|
|
2148
|
+
* Reads only local files and never contacts upstream or writes an inventory.
|
|
2149
|
+
* @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
|
|
2150
|
+
* throws when one is unreadable, malformed, or inconsistent with its digest.
|
|
2151
|
+
*
|
|
2152
|
+
* @example
|
|
2153
|
+
* ```ts
|
|
2154
|
+
* import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2155
|
+
*
|
|
2156
|
+
* readSurfaceRecord(resolveHostRoot()) // the bundled collision record
|
|
2157
|
+
* ```
|
|
2158
|
+
*/
|
|
2159
|
+
export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
|
|
2160
|
+
|
|
2037
2161
|
/**
|
|
2038
2162
|
* Matches the Windows device names that stay reserved even when an extension follows.
|
|
2039
2163
|
*
|
|
@@ -2084,6 +2208,17 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2084
2208
|
*/
|
|
2085
2209
|
export declare function resolveContainedPath(root: string, path: string): string | undefined;
|
|
2086
2210
|
|
|
2211
|
+
/**
|
|
2212
|
+
* Resolves the bundled host root from the executing module's location.
|
|
2213
|
+
*
|
|
2214
|
+
* @example
|
|
2215
|
+
* ```ts
|
|
2216
|
+
* import { resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2217
|
+
* resolveHostRoot() // the checkout in source, or the installed dist/host directory
|
|
2218
|
+
* ```
|
|
2219
|
+
*/
|
|
2220
|
+
export declare function resolveHostRoot(): string;
|
|
2221
|
+
|
|
2087
2222
|
/**
|
|
2088
2223
|
* Resolves a path through the real filesystem, keeping the part that does not exist yet.
|
|
2089
2224
|
*
|
|
@@ -2278,10 +2413,34 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2278
2413
|
*/
|
|
2279
2414
|
export declare function stageInventory(checkout: string, path?: string): HostManifest;
|
|
2280
2415
|
|
|
2281
|
-
/**
|
|
2282
|
-
export declare
|
|
2283
|
-
|
|
2284
|
-
|
|
2416
|
+
/** Loads a module by specifier for validated surface reflection. */
|
|
2417
|
+
export declare type SurfaceLoader = (specifier: string) => unknown;
|
|
2418
|
+
|
|
2419
|
+
/**
|
|
2420
|
+
* Describes the guide module functions required by surface reflection.
|
|
2421
|
+
*
|
|
2422
|
+
* @remarks
|
|
2423
|
+
* Declares only the members surface reflection calls, so a consumer of these declarations needs
|
|
2424
|
+
* no copy of `@orkestrel/guide`.
|
|
2425
|
+
*/
|
|
2426
|
+
export declare interface SurfaceModule {
|
|
2427
|
+
readonly createGuide: (text: string) => {
|
|
2428
|
+
readonly surface: () => ReadonlyArray<{
|
|
2429
|
+
readonly name: string;
|
|
2430
|
+
}>;
|
|
2431
|
+
};
|
|
2432
|
+
readonly createSource: (options: {
|
|
2433
|
+
readonly files: Readonly<Record<string, string>>;
|
|
2434
|
+
readonly module: string;
|
|
2435
|
+
}) => {
|
|
2436
|
+
readonly surface: () => ReadonlyArray<{
|
|
2437
|
+
readonly name: string;
|
|
2438
|
+
}>;
|
|
2439
|
+
};
|
|
2440
|
+
readonly extractSourceLines: (text: string) => ReadonlyArray<{
|
|
2441
|
+
readonly code: string;
|
|
2442
|
+
readonly source: string;
|
|
2443
|
+
}>;
|
|
2285
2444
|
}
|
|
2286
2445
|
|
|
2287
2446
|
/**
|
|
@@ -2291,11 +2450,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2291
2450
|
* `content` carries the body only when `lookup` is `found`; otherwise it is
|
|
2292
2451
|
* empty and `note` states what happened. A read that is not `found` is an answer
|
|
2293
2452
|
* rather than a throw, which is what lets one dead row sit beside live ones.
|
|
2453
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
2294
2454
|
*/
|
|
2295
2455
|
export declare interface TextReadResult {
|
|
2296
2456
|
readonly lookup: Lookup;
|
|
2297
2457
|
readonly content: string;
|
|
2298
2458
|
readonly note: string;
|
|
2459
|
+
readonly unreachable?: boolean;
|
|
2299
2460
|
}
|
|
2300
2461
|
|
|
2301
2462
|
/** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
|
|
@@ -2479,7 +2640,9 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2479
2640
|
* unreadable list would otherwise be written into a target's catalog table as
|
|
2480
2641
|
* a fleet with no packages in it. A package whose own version lookup then
|
|
2481
2642
|
* fails still keeps its row, carrying the cause instead of a version, because
|
|
2482
|
-
* the list already proved the package is published.
|
|
2643
|
+
* the list already proved the package is published. The `FETCH` failure's
|
|
2644
|
+
* context carries `unreachable: true` only when the list request produced no
|
|
2645
|
+
* HTTP response.
|
|
2483
2646
|
*
|
|
2484
2647
|
* @example
|
|
2485
2648
|
* ```ts
|
|
@@ -2491,6 +2654,23 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2491
2654
|
* ```
|
|
2492
2655
|
*/
|
|
2493
2656
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2657
|
+
/**
|
|
2658
|
+
* Reads the verified upstream inventory and its collision record.
|
|
2659
|
+
*
|
|
2660
|
+
* @param allowance - A shared call allowance; omitted calls open their own budget.
|
|
2661
|
+
* @returns A found inventory with its surface, or an unfound verdict with empty collections,
|
|
2662
|
+
* carrying `unreachable: true` only when the request produced no HTTP response.
|
|
2663
|
+
* @throws Thrown with DESTROYED when the reader has been torn down.
|
|
2664
|
+
* @example
|
|
2665
|
+
* ```ts
|
|
2666
|
+
* import { Upstream } from '@orkestrel/scaffold/server'
|
|
2667
|
+
* const upstream = new Upstream()
|
|
2668
|
+
* const inventory = await upstream.inventory()
|
|
2669
|
+
* inventory.surface // the verified record when lookup is found
|
|
2670
|
+
* upstream.destroy()
|
|
2671
|
+
* ```
|
|
2672
|
+
*/
|
|
2673
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2494
2674
|
/**
|
|
2495
2675
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2496
2676
|
*
|
|
@@ -2575,6 +2755,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2575
2755
|
* @returns One row per published package, sorted by name.
|
|
2576
2756
|
*/
|
|
2577
2757
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2758
|
+
/** Reads the verified upstream inventory and its collision record. */
|
|
2759
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2578
2760
|
/**
|
|
2579
2761
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2580
2762
|
*
|
|
@@ -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,72 @@ 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 or the guide parser refuses the reading.
|
|
2121
|
+
* @example
|
|
2122
|
+
* ```ts
|
|
2123
|
+
* import { readSurfaceGuide } from '@orkestrel/scaffold/server'
|
|
2124
|
+
* readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
|
|
2125
|
+
* ```
|
|
2126
|
+
*/
|
|
2127
|
+
export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
|
|
2128
|
+
|
|
2129
|
+
/**
|
|
2130
|
+
* Loads and validates the guide functions required by surface reflection.
|
|
2131
|
+
*
|
|
2132
|
+
* @param loader - The module resolver. Default: Node resolution from this module.
|
|
2133
|
+
* @throws Thrown with TARGET when the module is absent or lacks a required function.
|
|
2134
|
+
* @example
|
|
2135
|
+
* ```ts
|
|
2136
|
+
* import { readSurfaceModule } from '@orkestrel/scaffold/server'
|
|
2137
|
+
* readSurfaceModule().createGuide('# Sample').surface() // []
|
|
2138
|
+
* ```
|
|
2139
|
+
*/
|
|
2140
|
+
export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
|
|
2141
|
+
|
|
2142
|
+
/**
|
|
2143
|
+
* Reads a data root's verified collision record.
|
|
2144
|
+
*
|
|
2145
|
+
* @param root - The data root holding `manifest.json` or `host.json`.
|
|
2146
|
+
* @remarks
|
|
2147
|
+
* Reads `manifest.json` first, then `host.json` when no built manifest exists.
|
|
2148
|
+
* Reads only local files and never contacts upstream or writes an inventory.
|
|
2149
|
+
* @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
|
|
2150
|
+
* throws when one is unreadable, malformed, or inconsistent with its digest.
|
|
2151
|
+
*
|
|
2152
|
+
* @example
|
|
2153
|
+
* ```ts
|
|
2154
|
+
* import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2155
|
+
*
|
|
2156
|
+
* readSurfaceRecord(resolveHostRoot()) // the bundled collision record
|
|
2157
|
+
* ```
|
|
2158
|
+
*/
|
|
2159
|
+
export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
|
|
2160
|
+
|
|
2037
2161
|
/**
|
|
2038
2162
|
* Matches the Windows device names that stay reserved even when an extension follows.
|
|
2039
2163
|
*
|
|
@@ -2084,6 +2208,17 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2084
2208
|
*/
|
|
2085
2209
|
export declare function resolveContainedPath(root: string, path: string): string | undefined;
|
|
2086
2210
|
|
|
2211
|
+
/**
|
|
2212
|
+
* Resolves the bundled host root from the executing module's location.
|
|
2213
|
+
*
|
|
2214
|
+
* @example
|
|
2215
|
+
* ```ts
|
|
2216
|
+
* import { resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
2217
|
+
* resolveHostRoot() // the checkout in source, or the installed dist/host directory
|
|
2218
|
+
* ```
|
|
2219
|
+
*/
|
|
2220
|
+
export declare function resolveHostRoot(): string;
|
|
2221
|
+
|
|
2087
2222
|
/**
|
|
2088
2223
|
* Resolves a path through the real filesystem, keeping the part that does not exist yet.
|
|
2089
2224
|
*
|
|
@@ -2278,10 +2413,34 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2278
2413
|
*/
|
|
2279
2414
|
export declare function stageInventory(checkout: string, path?: string): HostManifest;
|
|
2280
2415
|
|
|
2281
|
-
/**
|
|
2282
|
-
export declare
|
|
2283
|
-
|
|
2284
|
-
|
|
2416
|
+
/** Loads a module by specifier for validated surface reflection. */
|
|
2417
|
+
export declare type SurfaceLoader = (specifier: string) => unknown;
|
|
2418
|
+
|
|
2419
|
+
/**
|
|
2420
|
+
* Describes the guide module functions required by surface reflection.
|
|
2421
|
+
*
|
|
2422
|
+
* @remarks
|
|
2423
|
+
* Declares only the members surface reflection calls, so a consumer of these declarations needs
|
|
2424
|
+
* no copy of `@orkestrel/guide`.
|
|
2425
|
+
*/
|
|
2426
|
+
export declare interface SurfaceModule {
|
|
2427
|
+
readonly createGuide: (text: string) => {
|
|
2428
|
+
readonly surface: () => ReadonlyArray<{
|
|
2429
|
+
readonly name: string;
|
|
2430
|
+
}>;
|
|
2431
|
+
};
|
|
2432
|
+
readonly createSource: (options: {
|
|
2433
|
+
readonly files: Readonly<Record<string, string>>;
|
|
2434
|
+
readonly module: string;
|
|
2435
|
+
}) => {
|
|
2436
|
+
readonly surface: () => ReadonlyArray<{
|
|
2437
|
+
readonly name: string;
|
|
2438
|
+
}>;
|
|
2439
|
+
};
|
|
2440
|
+
readonly extractSourceLines: (text: string) => ReadonlyArray<{
|
|
2441
|
+
readonly code: string;
|
|
2442
|
+
readonly source: string;
|
|
2443
|
+
}>;
|
|
2285
2444
|
}
|
|
2286
2445
|
|
|
2287
2446
|
/**
|
|
@@ -2291,11 +2450,13 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2291
2450
|
* `content` carries the body only when `lookup` is `found`; otherwise it is
|
|
2292
2451
|
* empty and `note` states what happened. A read that is not `found` is an answer
|
|
2293
2452
|
* rather than a throw, which is what lets one dead row sit beside live ones.
|
|
2453
|
+
* `unreachable` is true only when the request produced no HTTP response.
|
|
2294
2454
|
*/
|
|
2295
2455
|
export declare interface TextReadResult {
|
|
2296
2456
|
readonly lookup: Lookup;
|
|
2297
2457
|
readonly content: string;
|
|
2298
2458
|
readonly note: string;
|
|
2459
|
+
readonly unreachable?: boolean;
|
|
2299
2460
|
}
|
|
2300
2461
|
|
|
2301
2462
|
/** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
|
|
@@ -2479,7 +2640,9 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2479
2640
|
* unreadable list would otherwise be written into a target's catalog table as
|
|
2480
2641
|
* a fleet with no packages in it. A package whose own version lookup then
|
|
2481
2642
|
* fails still keeps its row, carrying the cause instead of a version, because
|
|
2482
|
-
* the list already proved the package is published.
|
|
2643
|
+
* the list already proved the package is published. The `FETCH` failure's
|
|
2644
|
+
* context carries `unreachable: true` only when the list request produced no
|
|
2645
|
+
* HTTP response.
|
|
2483
2646
|
*
|
|
2484
2647
|
* @example
|
|
2485
2648
|
* ```ts
|
|
@@ -2491,6 +2654,23 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2491
2654
|
* ```
|
|
2492
2655
|
*/
|
|
2493
2656
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2657
|
+
/**
|
|
2658
|
+
* Reads the verified upstream inventory and its collision record.
|
|
2659
|
+
*
|
|
2660
|
+
* @param allowance - A shared call allowance; omitted calls open their own budget.
|
|
2661
|
+
* @returns A found inventory with its surface, or an unfound verdict with empty collections,
|
|
2662
|
+
* carrying `unreachable: true` only when the request produced no HTTP response.
|
|
2663
|
+
* @throws Thrown with DESTROYED when the reader has been torn down.
|
|
2664
|
+
* @example
|
|
2665
|
+
* ```ts
|
|
2666
|
+
* import { Upstream } from '@orkestrel/scaffold/server'
|
|
2667
|
+
* const upstream = new Upstream()
|
|
2668
|
+
* const inventory = await upstream.inventory()
|
|
2669
|
+
* inventory.surface // the verified record when lookup is found
|
|
2670
|
+
* upstream.destroy()
|
|
2671
|
+
* ```
|
|
2672
|
+
*/
|
|
2673
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2494
2674
|
/**
|
|
2495
2675
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2496
2676
|
*
|
|
@@ -2575,6 +2755,8 @@ export declare class Materializer implements MaterializerInterface {
|
|
|
2575
2755
|
* @returns One row per published package, sorted by name.
|
|
2576
2756
|
*/
|
|
2577
2757
|
catalog(): Promise<readonly CatalogEntry[]>;
|
|
2758
|
+
/** Reads the verified upstream inventory and its collision record. */
|
|
2759
|
+
inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
|
|
2578
2760
|
/**
|
|
2579
2761
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
2580
2762
|
*
|