@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
|
@@ -1287,9 +1287,8 @@ function readHostManifest(host, name = MANIFEST_NAME) {
|
|
|
1287
1287
|
*/
|
|
1288
1288
|
function readHostFloor(root) {
|
|
1289
1289
|
const location = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
|
|
1290
|
-
const module = (0, node_path.dirname)(location);
|
|
1291
1290
|
const source = root === void 0 && (0, node_path.extname)(location) === ".ts";
|
|
1292
|
-
const host = root ?? (
|
|
1291
|
+
const host = root ?? resolveHostRoot();
|
|
1293
1292
|
if (!isPhysicalDirectory(host)) throw new _src_core.ScaffoldError("TARGET", `The vendored host root is not readable at ${host}`, { host });
|
|
1294
1293
|
const manifest = readHostManifest(host, source ? _src_core.HOST_INVENTORY_PATH : MANIFEST_NAME);
|
|
1295
1294
|
if (manifest === void 0) throw new _src_core.ScaffoldError("TARGET", `The vendored host carries no manifest at ${host}`, { host });
|
|
@@ -1672,10 +1671,13 @@ function stageHost(checkout, host, options) {
|
|
|
1672
1671
|
};
|
|
1673
1672
|
});
|
|
1674
1673
|
const collisions = readSurfaceCollisions((0, node_path.join)(root, "guides"));
|
|
1675
|
-
const growth = published === void 0 ? [] : [...collisions].
|
|
1676
|
-
|
|
1677
|
-
|
|
1678
|
-
})
|
|
1674
|
+
const growth = published === void 0 ? [] : (0, _src_core.compareSurfaceCollisions)([...collisions].map(([name, owners]) => ({
|
|
1675
|
+
name,
|
|
1676
|
+
owners
|
|
1677
|
+
})), [...published].map(([name, owners]) => ({
|
|
1678
|
+
name,
|
|
1679
|
+
owners
|
|
1680
|
+
}))).filter(({ standing }) => standing === "error").map(({ name, owners }) => `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})`);
|
|
1679
1681
|
if (growth.length > 0) throw new _src_core.ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
|
|
1680
1682
|
checkout: source,
|
|
1681
1683
|
host: root,
|
|
@@ -1728,26 +1730,202 @@ function stageHost(checkout, host, options) {
|
|
|
1728
1730
|
* ```
|
|
1729
1731
|
*/
|
|
1730
1732
|
function readSurfaceCollisions(root) {
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
|
|
1735
|
-
|
|
1733
|
+
return new Map((0, _src_core.collectSurfaceCollisions)(readSurfaceClaims(root)).map(({ name, owners }) => [name, owners]));
|
|
1734
|
+
}
|
|
1735
|
+
/**
|
|
1736
|
+
* Resolves the bundled host root from the executing module's location.
|
|
1737
|
+
*
|
|
1738
|
+
* @example
|
|
1739
|
+
* ```ts
|
|
1740
|
+
* import { resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
1741
|
+
* resolveHostRoot() // the checkout in source, or the installed dist/host directory
|
|
1742
|
+
* ```
|
|
1743
|
+
*/
|
|
1744
|
+
function resolveHostRoot() {
|
|
1745
|
+
const location = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
|
|
1746
|
+
return (0, node_path.resolve)((0, node_path.dirname)(location), (0, node_path.extname)(location) === ".ts" ? "../.." : "../../host");
|
|
1747
|
+
}
|
|
1748
|
+
/**
|
|
1749
|
+
* Loads and validates the guide functions required by surface reflection.
|
|
1750
|
+
*
|
|
1751
|
+
* @param loader - The module resolver. Default: Node resolution from this module.
|
|
1752
|
+
* @throws Thrown with TARGET when the module is absent or lacks a required function.
|
|
1753
|
+
* @example
|
|
1754
|
+
* ```ts
|
|
1755
|
+
* import { readSurfaceModule } from '@orkestrel/scaffold/server'
|
|
1756
|
+
* readSurfaceModule().createGuide('# Sample').surface() // []
|
|
1757
|
+
* ```
|
|
1758
|
+
*/
|
|
1759
|
+
function readSurfaceModule(loader = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)) {
|
|
1760
|
+
const loaded = (0, _orkestrel_contract.attempt)(() => loader("@orkestrel/guide"));
|
|
1761
|
+
if (!loaded.success || !isSurfaceModule(loaded.value)) throw new _src_core.ScaffoldError("TARGET", "Surface reflection requires @orkestrel/guide with createGuide, createSource, extractSourceLines, and isGuideError. Supply that module in scaffold's resolution path.", { ...!loaded.success ? { error: loaded.error } : {} });
|
|
1762
|
+
return loaded.value;
|
|
1763
|
+
}
|
|
1764
|
+
/**
|
|
1765
|
+
* Reads one guide's claims and reports parser refusals with its owner and source.
|
|
1766
|
+
*
|
|
1767
|
+
* @param source - The source label or path to name in a refusal.
|
|
1768
|
+
* @throws Thrown with TARGET when the module is unusable or the guide parser refuses the guide
|
|
1769
|
+
* with an error its `isGuideError` guard accepts; every other parser error propagates unchanged.
|
|
1770
|
+
* @example
|
|
1771
|
+
* ```ts
|
|
1772
|
+
* import { readSurfaceGuide } from '@orkestrel/scaffold/server'
|
|
1773
|
+
* readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
|
|
1774
|
+
* ```
|
|
1775
|
+
*/
|
|
1776
|
+
function readSurfaceGuide(text, owner, source, loader) {
|
|
1777
|
+
const guide = readSurfaceModule(loader);
|
|
1778
|
+
const parsed = (0, _orkestrel_contract.attempt)(() => guide.createGuide(text).surface().map(({ name }) => name));
|
|
1779
|
+
if (parsed.success) return {
|
|
1780
|
+
owner,
|
|
1781
|
+
names: parsed.value
|
|
1782
|
+
};
|
|
1783
|
+
if (!guide.isGuideError(parsed.error)) throw parsed.error;
|
|
1784
|
+
throw new _src_core.ScaffoldError("TARGET", `Surface guide for ${JSON.stringify(owner.slice(0, 512))} from ${JSON.stringify(source.slice(0, 512))} was refused: ${parsed.error.message}`, {
|
|
1785
|
+
owner,
|
|
1786
|
+
source,
|
|
1787
|
+
code: parsed.error.code
|
|
1736
1788
|
});
|
|
1737
|
-
|
|
1738
|
-
|
|
1789
|
+
}
|
|
1790
|
+
/**
|
|
1791
|
+
* Reads each immediate package guide's bare names under its file owner.
|
|
1792
|
+
*
|
|
1793
|
+
* @param root - The directory containing the package guides; README.md is excluded.
|
|
1794
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
1795
|
+
* @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
|
|
1796
|
+
*
|
|
1797
|
+
* @example
|
|
1798
|
+
* ```ts
|
|
1799
|
+
* import { readSurfaceClaims } from '@orkestrel/scaffold/server'
|
|
1800
|
+
*
|
|
1801
|
+
* readSurfaceClaims('./guides') // owners and the names their guides claim
|
|
1802
|
+
* ```
|
|
1803
|
+
*/
|
|
1804
|
+
function readSurfaceClaims(root, loader) {
|
|
1805
|
+
if (!isPhysicalDirectory(root)) throw new _src_core.ScaffoldError("TARGET", `Surface guide directory is not readable at ${root}`, { root });
|
|
1806
|
+
readSurfaceModule(loader);
|
|
1807
|
+
return listFiles(root).filter((path) => !path.includes("/") && (0, node_path.extname)(path) === ".md" && path !== "README.md").map((path) => {
|
|
1739
1808
|
const text = readFileText(root, path);
|
|
1740
1809
|
if (text === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${path}`, {
|
|
1741
1810
|
root,
|
|
1742
1811
|
path
|
|
1743
1812
|
});
|
|
1744
|
-
return
|
|
1813
|
+
return readSurfaceGuide(text, (0, node_path.basename)(path, ".md"), (0, node_path.join)(root, path), loader);
|
|
1745
1814
|
});
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1815
|
+
}
|
|
1816
|
+
/**
|
|
1817
|
+
* Reads a checkout's combined guide and barrel claims under its manifest owner.
|
|
1818
|
+
*
|
|
1819
|
+
* @remarks
|
|
1820
|
+
* Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
|
|
1821
|
+
* src environment through @orkestrel/guide, loaded only when called, and reports each
|
|
1822
|
+
* name two or more environments export as a conflict.
|
|
1823
|
+
* Reads only .ts files and refuses barrel statements outside relative .js star exports.
|
|
1824
|
+
* A present unreadable guide refuses the candidate even when src exists.
|
|
1825
|
+
* `loader` selects the resolver used by the shared validated guide loader.
|
|
1826
|
+
* @throws Thrown when the manifest is unreadable, both claim sources are absent,
|
|
1827
|
+
* a source cannot be read, or @orkestrel/guide cannot be loaded.
|
|
1828
|
+
*
|
|
1829
|
+
* @example
|
|
1830
|
+
* ```ts
|
|
1831
|
+
* import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
|
|
1832
|
+
*
|
|
1833
|
+
* readSurfaceCandidate('.') // the working checkout's owner and combined names
|
|
1834
|
+
* ```
|
|
1835
|
+
*/
|
|
1836
|
+
function readSurfaceCandidate(root, loader) {
|
|
1837
|
+
const manifest = readFileText(root, "package.json", _src_core.MAX_MANIFEST_BYTES);
|
|
1838
|
+
const name = manifest === void 0 ? void 0 : (0, _src_core.manifestToName)(manifest);
|
|
1839
|
+
if (name === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} needs package.json with a valid name.`, { root });
|
|
1840
|
+
const owner = name.replace(/^@orkestrel\//u, "");
|
|
1841
|
+
const guide = readSurfaceFile(root, owner, "candidate", loader);
|
|
1842
|
+
const source = (0, node_path.join)(root, "src");
|
|
1843
|
+
if (guide === void 0 && !isPhysicalDirectory(source)) throw new _src_core.ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} has neither ${JSON.stringify(`guides/${owner}.md`)} nor src/. Add its guide or source directory before checking its claims.`, { root });
|
|
1844
|
+
const reflection = readSurfaceModule(loader);
|
|
1845
|
+
const files = Object.fromEntries(listFiles(source).filter((file) => file.endsWith(".ts")).map((file) => {
|
|
1846
|
+
const text = readFileText(source, file);
|
|
1847
|
+
if (text === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} cannot read ${JSON.stringify(`src/${file}`.slice(0, 512))}. Restore a readable source file before checking its claims.`, {
|
|
1848
|
+
root,
|
|
1849
|
+
path: file
|
|
1850
|
+
});
|
|
1851
|
+
return [`src/${file}`, text];
|
|
1750
1852
|
}));
|
|
1853
|
+
for (const [file, text] of Object.entries(files)) {
|
|
1854
|
+
if (!file.endsWith("/index.ts")) continue;
|
|
1855
|
+
for (const line of reflection.extractSourceLines(text)) {
|
|
1856
|
+
if (line.code.trim() === "" || /^\s*export\s+\*\s+from\s+(?:'(\.\.?\/[^']+\.js)'|"(\.\.?\/[^"]+\.js)")\s*;?\s*$/u.test(line.code)) continue;
|
|
1857
|
+
throw new _src_core.ScaffoldError("TARGET", `Surface candidate barrel ${JSON.stringify((0, node_path.join)(root, file).slice(0, 512))} refuses statement ${JSON.stringify(line.source.trim().slice(0, 512))}; use only export * from './module.js' declarations.`, {
|
|
1858
|
+
root,
|
|
1859
|
+
path: file
|
|
1860
|
+
});
|
|
1861
|
+
}
|
|
1862
|
+
}
|
|
1863
|
+
const exports = Object.fromEntries(listDirectories(source).filter((directory) => !directory.includes("/")).map((directory) => [directory, reflection.createSource({
|
|
1864
|
+
files,
|
|
1865
|
+
module: `src/${directory}`
|
|
1866
|
+
}).surface().map((symbol) => symbol.name)]));
|
|
1867
|
+
return {
|
|
1868
|
+
owner,
|
|
1869
|
+
names: [.../* @__PURE__ */ new Set([...guide?.names ?? [], ...Object.values(exports).flat()])].sort(),
|
|
1870
|
+
conflicts: (0, _src_core.collectSurfaceConflicts)(owner, exports)
|
|
1871
|
+
};
|
|
1872
|
+
}
|
|
1873
|
+
/**
|
|
1874
|
+
* Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
|
|
1875
|
+
*
|
|
1876
|
+
* @param root - The checkout or data root holding the guide, or a verified host whose bytes
|
|
1877
|
+
* carry it at that destination.
|
|
1878
|
+
* @param owner - The unscoped package name the guide file is named for.
|
|
1879
|
+
* @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
|
|
1880
|
+
* @param loader - The module resolver used by the shared validated guide loader.
|
|
1881
|
+
* @returns The claim, or `undefined` when no file sits at the path or the host declares none.
|
|
1882
|
+
* @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
|
|
1883
|
+
* file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
|
|
1884
|
+
*
|
|
1885
|
+
* @example
|
|
1886
|
+
* ```ts
|
|
1887
|
+
* import { readSurfaceFile } from '@orkestrel/scaffold/server'
|
|
1888
|
+
*
|
|
1889
|
+
* readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
|
|
1890
|
+
* ```
|
|
1891
|
+
*/
|
|
1892
|
+
function readSurfaceFile(root, owner, label, loader) {
|
|
1893
|
+
const destination = `guides/${owner}.md`;
|
|
1894
|
+
if (!(0, _orkestrel_contract.isString)(root)) {
|
|
1895
|
+
const hex = root.bytes[destination];
|
|
1896
|
+
const declared = hex === void 0 ? void 0 : decodeHexText(hex);
|
|
1897
|
+
if (hex !== void 0 && declared === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(destination)}`, { path: destination });
|
|
1898
|
+
return declared === void 0 ? void 0 : readSurfaceGuide(declared, owner, `${label} ${destination}`, loader);
|
|
1899
|
+
}
|
|
1900
|
+
const path = (0, node_path.join)(root, "guides", `${owner}.md`);
|
|
1901
|
+
const text = readFileText(root, destination);
|
|
1902
|
+
if (text === void 0 && isExactCaseFile(path)) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(path.slice(0, 512))}`, {
|
|
1903
|
+
root,
|
|
1904
|
+
path: `guides/${owner}.md`
|
|
1905
|
+
});
|
|
1906
|
+
return text === void 0 ? void 0 : readSurfaceGuide(text, owner, `${label} ${path}`, loader);
|
|
1907
|
+
}
|
|
1908
|
+
/**
|
|
1909
|
+
* Reads a data root's verified collision record.
|
|
1910
|
+
*
|
|
1911
|
+
* @param root - The data root holding `manifest.json` or `host.json`.
|
|
1912
|
+
* @remarks
|
|
1913
|
+
* Reads `manifest.json` first, then `host.json` when no built manifest exists.
|
|
1914
|
+
* Reads only local files and never contacts upstream or writes an inventory.
|
|
1915
|
+
* @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
|
|
1916
|
+
* throws when one is unreadable, malformed, or inconsistent with its digest.
|
|
1917
|
+
*
|
|
1918
|
+
* @example
|
|
1919
|
+
* ```ts
|
|
1920
|
+
* import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
|
|
1921
|
+
*
|
|
1922
|
+
* readSurfaceRecord(resolveHostRoot()) // the bundled collision record
|
|
1923
|
+
* ```
|
|
1924
|
+
*/
|
|
1925
|
+
function readSurfaceRecord(root) {
|
|
1926
|
+
const record = readSurfaceBaseline(root, "manifest.json") ?? readSurfaceBaseline(root);
|
|
1927
|
+
if (record === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface data root ${JSON.stringify(root.slice(0, 512))} needs manifest.json or host.json with a surface record. Supply an inventoried root with --from.`, { root });
|
|
1928
|
+
return record;
|
|
1751
1929
|
}
|
|
1752
1930
|
/**
|
|
1753
1931
|
* Reads the Surface collision baseline from a committed inventory.
|
|
@@ -1992,6 +2170,18 @@ function matchesPrecondition(precondition) {
|
|
|
1992
2170
|
}
|
|
1993
2171
|
// src/server/validators.ts
|
|
1994
2172
|
/**
|
|
2173
|
+
* Narrows a value to the callable guide functions surface reflection requires.
|
|
2174
|
+
*
|
|
2175
|
+
* @example
|
|
2176
|
+
* ```ts
|
|
2177
|
+
* import { isSurfaceModule } from '@orkestrel/scaffold/server'
|
|
2178
|
+
* isSurfaceModule({}) // false
|
|
2179
|
+
* ```
|
|
2180
|
+
*/
|
|
2181
|
+
function isSurfaceModule(value) {
|
|
2182
|
+
return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isObject)(value) && "createGuide" in value && (0, _orkestrel_contract.isFunction)(value.createGuide) && "createSource" in value && (0, _orkestrel_contract.isFunction)(value.createSource) && "extractSourceLines" in value && (0, _orkestrel_contract.isFunction)(value.extractSourceLines) && "isGuideError" in value && (0, _orkestrel_contract.isFunction)(value.isGuideError));
|
|
2183
|
+
}
|
|
2184
|
+
/**
|
|
1995
2185
|
* Narrows a value to a path naming a location on this host.
|
|
1996
2186
|
*
|
|
1997
2187
|
* @param value - The candidate host path.
|
|
@@ -4102,7 +4292,7 @@ var Upstream = class {
|
|
|
4102
4292
|
const observed = this.#accept(current, _src_core.isSnapshot, "current");
|
|
4103
4293
|
if (accepted.length === 0) return [];
|
|
4104
4294
|
const allowance = new ReadAllowance(this.#budget);
|
|
4105
|
-
const inventory = await this
|
|
4295
|
+
const inventory = await this.inventory(allowance);
|
|
4106
4296
|
return this.#gather(accepted, (path) => this.#file(path, inventory, observed, allowance));
|
|
4107
4297
|
}
|
|
4108
4298
|
/**
|
|
@@ -4121,7 +4311,9 @@ var Upstream = class {
|
|
|
4121
4311
|
* unreadable list would otherwise be written into a target's catalog table as
|
|
4122
4312
|
* a fleet with no packages in it. A package whose own version lookup then
|
|
4123
4313
|
* fails still keeps its row, carrying the cause instead of a version, because
|
|
4124
|
-
* the list already proved the package is published.
|
|
4314
|
+
* the list already proved the package is published. The `FETCH` failure's
|
|
4315
|
+
* context carries `unreachable: true` only when the list request produced no
|
|
4316
|
+
* HTTP response.
|
|
4125
4317
|
*
|
|
4126
4318
|
* @example
|
|
4127
4319
|
* ```ts
|
|
@@ -4139,6 +4331,56 @@ var Upstream = class {
|
|
|
4139
4331
|
return this.#gather(names, (name) => this.#entry(name, allowance));
|
|
4140
4332
|
}
|
|
4141
4333
|
/**
|
|
4334
|
+
* Reads the verified upstream inventory and its collision record.
|
|
4335
|
+
*
|
|
4336
|
+
* @param allowance - A shared call allowance; omitted calls open their own budget.
|
|
4337
|
+
* @returns A found inventory with its surface, or an unfound verdict with empty collections,
|
|
4338
|
+
* carrying `unreachable: true` only when the request produced no HTTP response.
|
|
4339
|
+
* @throws Thrown with DESTROYED when the reader has been torn down.
|
|
4340
|
+
* @example
|
|
4341
|
+
* ```ts
|
|
4342
|
+
* import { Upstream } from '@orkestrel/scaffold/server'
|
|
4343
|
+
* const upstream = new Upstream()
|
|
4344
|
+
* const inventory = await upstream.inventory()
|
|
4345
|
+
* inventory.surface // the verified record when lookup is found
|
|
4346
|
+
* upstream.destroy()
|
|
4347
|
+
* ```
|
|
4348
|
+
*/
|
|
4349
|
+
async inventory(allowance = new ReadAllowance(this.#budget)) {
|
|
4350
|
+
this.#assertAlive();
|
|
4351
|
+
const url = this.#vendorURL(_src_core.HOST_INVENTORY_PATH);
|
|
4352
|
+
const empty = {
|
|
4353
|
+
digests: /* @__PURE__ */ new Map(),
|
|
4354
|
+
duplicates: /* @__PURE__ */ new Set(),
|
|
4355
|
+
surface: []
|
|
4356
|
+
};
|
|
4357
|
+
const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
|
|
4358
|
+
if (outcome.lookup !== "found") return {
|
|
4359
|
+
...empty,
|
|
4360
|
+
lookup: outcome.lookup,
|
|
4361
|
+
note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`,
|
|
4362
|
+
...outcome.unreachable === true ? { unreachable: true } : {}
|
|
4363
|
+
};
|
|
4364
|
+
const manifest = (0, _orkestrel_contract.parseJSONAs)(outcome.content, isHostManifest);
|
|
4365
|
+
if (manifest === void 0) return {
|
|
4366
|
+
...empty,
|
|
4367
|
+
lookup: "failed",
|
|
4368
|
+
note: `the vendored inventory at ${url} is not a readable manifest`
|
|
4369
|
+
};
|
|
4370
|
+
if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
|
|
4371
|
+
...empty,
|
|
4372
|
+
lookup: "failed",
|
|
4373
|
+
note: `the vendored inventory at ${url} does not match its own membership digest`
|
|
4374
|
+
};
|
|
4375
|
+
return {
|
|
4376
|
+
lookup: "found",
|
|
4377
|
+
digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
|
|
4378
|
+
duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
|
|
4379
|
+
surface: manifest.surface,
|
|
4380
|
+
note: ""
|
|
4381
|
+
};
|
|
4382
|
+
}
|
|
4383
|
+
/**
|
|
4142
4384
|
* Tears the reader down, aborting every request in flight. Teardown is idempotent.
|
|
4143
4385
|
*
|
|
4144
4386
|
* @returns Nothing.
|
|
@@ -4280,36 +4522,6 @@ var Upstream = class {
|
|
|
4280
4522
|
...carried
|
|
4281
4523
|
};
|
|
4282
4524
|
}
|
|
4283
|
-
async #inventory(allowance) {
|
|
4284
|
-
const url = this.#vendorURL(_src_core.HOST_INVENTORY_PATH);
|
|
4285
|
-
const empty = {
|
|
4286
|
-
digests: /* @__PURE__ */ new Map(),
|
|
4287
|
-
duplicates: /* @__PURE__ */ new Set()
|
|
4288
|
-
};
|
|
4289
|
-
const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
|
|
4290
|
-
if (outcome.lookup !== "found") return {
|
|
4291
|
-
...empty,
|
|
4292
|
-
lookup: outcome.lookup,
|
|
4293
|
-
note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`
|
|
4294
|
-
};
|
|
4295
|
-
const manifest = (0, _orkestrel_contract.parseJSONAs)(outcome.content, isHostManifest);
|
|
4296
|
-
if (manifest === void 0) return {
|
|
4297
|
-
...empty,
|
|
4298
|
-
lookup: "failed",
|
|
4299
|
-
note: `the vendored inventory at ${url} is not a readable manifest`
|
|
4300
|
-
};
|
|
4301
|
-
if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
|
|
4302
|
-
...empty,
|
|
4303
|
-
lookup: "failed",
|
|
4304
|
-
note: `the vendored inventory at ${url} does not match its own membership digest`
|
|
4305
|
-
};
|
|
4306
|
-
return {
|
|
4307
|
-
lookup: "found",
|
|
4308
|
-
digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
|
|
4309
|
-
duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
|
|
4310
|
-
note: ""
|
|
4311
|
-
};
|
|
4312
|
-
}
|
|
4313
4525
|
async #entry(name, allowance) {
|
|
4314
4526
|
const outcome = await this.#readWithRetries(this.#registryURL(name), this.#registryTimeout, allowance, PACKUMENT_MEDIA_TYPE);
|
|
4315
4527
|
const version = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
|
|
@@ -4345,7 +4557,8 @@ var Upstream = class {
|
|
|
4345
4557
|
const outcome = await this.#readWithRetries(url, this.#registryTimeout, allowance);
|
|
4346
4558
|
if (outcome.lookup !== "found") throw this.#error("FETCH", `The organization package list at ${url} produced no answer.`, {
|
|
4347
4559
|
url,
|
|
4348
|
-
note: outcome.note
|
|
4560
|
+
note: outcome.note,
|
|
4561
|
+
...outcome.unreachable === true ? { unreachable: true } : {}
|
|
4349
4562
|
});
|
|
4350
4563
|
const parsed = (0, _orkestrel_contract.parseJSON)(outcome.content);
|
|
4351
4564
|
if (!(0, _orkestrel_contract.isRecord)(parsed)) throw this.#error("FETCH", `The organization package list at ${url} is not a record.`, { url });
|
|
@@ -4405,15 +4618,7 @@ var Upstream = class {
|
|
|
4405
4618
|
url,
|
|
4406
4619
|
note
|
|
4407
4620
|
});
|
|
4408
|
-
return
|
|
4409
|
-
lookup: "failed",
|
|
4410
|
-
hex: "",
|
|
4411
|
-
note
|
|
4412
|
-
} : {
|
|
4413
|
-
lookup: "failed",
|
|
4414
|
-
content: "",
|
|
4415
|
-
note
|
|
4416
|
-
};
|
|
4621
|
+
return outcome;
|
|
4417
4622
|
}
|
|
4418
4623
|
async #request(url, timeout, allowance, accept, binary = false) {
|
|
4419
4624
|
if (allowance.remaining <= 0) {
|
|
@@ -4428,12 +4633,28 @@ var Upstream = class {
|
|
|
4428
4633
|
note
|
|
4429
4634
|
};
|
|
4430
4635
|
}
|
|
4636
|
+
const fetched = await fetch(url, {
|
|
4637
|
+
signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
|
|
4638
|
+
redirect: "manual",
|
|
4639
|
+
...accept === void 0 ? {} : { headers: { accept } }
|
|
4640
|
+
}).then((response) => ({ response }), (error) => ({ error }));
|
|
4641
|
+
if ("error" in fetched) {
|
|
4642
|
+
this.#assertAlive();
|
|
4643
|
+
const note = this.#note(fetched.error);
|
|
4644
|
+
return binary ? {
|
|
4645
|
+
lookup: "failed",
|
|
4646
|
+
hex: "",
|
|
4647
|
+
note,
|
|
4648
|
+
unreachable: true
|
|
4649
|
+
} : {
|
|
4650
|
+
lookup: "failed",
|
|
4651
|
+
content: "",
|
|
4652
|
+
note,
|
|
4653
|
+
unreachable: true
|
|
4654
|
+
};
|
|
4655
|
+
}
|
|
4431
4656
|
try {
|
|
4432
|
-
const response =
|
|
4433
|
-
signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
|
|
4434
|
-
redirect: "manual",
|
|
4435
|
-
...accept === void 0 ? {} : { headers: { accept } }
|
|
4436
|
-
});
|
|
4657
|
+
const response = fetched.response;
|
|
4437
4658
|
if (response.status === 404) {
|
|
4438
4659
|
await response.body?.cancel();
|
|
4439
4660
|
return binary ? {
|
|
@@ -4559,7 +4780,7 @@ var Upstream = class {
|
|
|
4559
4780
|
#note(error) {
|
|
4560
4781
|
if (!(0, _orkestrel_contract.isError)(error)) return "the request failed for an unreported reason";
|
|
4561
4782
|
const cause = error.cause;
|
|
4562
|
-
const code = (0, _orkestrel_contract.
|
|
4783
|
+
const code = (0, _orkestrel_contract.isObject)(cause) && "code" in cause && (0, _orkestrel_contract.isString)(cause.code) ? cause.code : void 0;
|
|
4563
4784
|
const message = `${error.name}: ${error.message}`;
|
|
4564
4785
|
return code === void 0 ? message : `${message} (${code})`;
|
|
4565
4786
|
}
|
|
@@ -4656,6 +4877,7 @@ exports.isMirrors = isMirrors;
|
|
|
4656
4877
|
exports.isPaths = isPaths;
|
|
4657
4878
|
exports.isPhysicalDirectory = isPhysicalDirectory;
|
|
4658
4879
|
exports.isPhysicalFile = isPhysicalFile;
|
|
4880
|
+
exports.isSurfaceModule = isSurfaceModule;
|
|
4659
4881
|
exports.isTimeout = isTimeout;
|
|
4660
4882
|
exports.isUpstreamHooks = isUpstreamHooks;
|
|
4661
4883
|
exports.isUpstreamOptions = isUpstreamOptions;
|
|
@@ -4684,8 +4906,15 @@ exports.readHostManifest = readHostManifest;
|
|
|
4684
4906
|
exports.readManifestEntry = readManifestEntry;
|
|
4685
4907
|
exports.readSnapshot = readSnapshot;
|
|
4686
4908
|
exports.readSurfaceBaseline = readSurfaceBaseline;
|
|
4909
|
+
exports.readSurfaceCandidate = readSurfaceCandidate;
|
|
4910
|
+
exports.readSurfaceClaims = readSurfaceClaims;
|
|
4687
4911
|
exports.readSurfaceCollisions = readSurfaceCollisions;
|
|
4912
|
+
exports.readSurfaceFile = readSurfaceFile;
|
|
4913
|
+
exports.readSurfaceGuide = readSurfaceGuide;
|
|
4914
|
+
exports.readSurfaceModule = readSurfaceModule;
|
|
4915
|
+
exports.readSurfaceRecord = readSurfaceRecord;
|
|
4688
4916
|
exports.resolveContainedPath = resolveContainedPath;
|
|
4917
|
+
exports.resolveHostRoot = resolveHostRoot;
|
|
4689
4918
|
exports.resolveRealPath = resolveRealPath;
|
|
4690
4919
|
exports.stageBytes = stageBytes;
|
|
4691
4920
|
exports.stageHost = stageHost;
|