@orkestrel/scaffold 0.0.63 → 0.0.65

package/dist/src/server/index.d.cts

@@ -1,18 +1,18 @@
-import { Audit } from '@orkestrel/scaffold';
-import { CatalogEntry } from '@orkestrel/scaffold';
-import { Dependency } from '@orkestrel/scaffold';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { Group } from '@orkestrel/scaffold';
-import { Guard } from '@orkestrel/contract';
-import { HostFile } from '@orkestrel/scaffold';
-import { Lookup } from '@orkestrel/scaffold';
-import { ManifestRegionSet } from '@orkestrel/scaffold';
-import { Mirror } from '@orkestrel/scaffold';
-import { Plan } from '@orkestrel/scaffold';
-import { Release } from '@orkestrel/scaffold';
-import { Snapshot } from '@orkestrel/scaffold';
+import type { Audit } from '@orkestrel/scaffold';
+import type { CatalogEntry } from '@orkestrel/scaffold';
+import type { Dependency } from '@orkestrel/scaffold';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Group } from '@orkestrel/scaffold';
+import type { Guard } from '@orkestrel/contract';
+import type { HostFile } from '@orkestrel/scaffold';
+import type { Lookup } from '@orkestrel/scaffold';
+import type { ManifestRegionSet } from '@orkestrel/scaffold';
+import type { Mirror } from '@orkestrel/scaffold';
+import type { Plan } from '@orkestrel/scaffold';
+import type { Release } from '@orkestrel/scaffold';
+import type { Snapshot } from '@orkestrel/scaffold';
 
 /**
  * Matches the Git branch syntax the repository endpoint accepts.
@@ -1052,7 +1052,9 @@ export declare function matchesSensitivePath(path: string): boolean;
  * declare const plan: Plan
  *
  * const materializer = new Materializer({ host: './dist/host' })
- * materializer.materialize(plan, './packages/router')
+ * const result = materializer.materialize(plan, './packages/router')
+ *
+ * result.written // every path created
  * materializer.destroy()
  * ```
  */
@@ -1093,8 +1095,7 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns One finding per hydrated planned path, plus the foreign files
-      * beneath owned host roots and inside the instruction canon.
+      * @returns Findings for hydrated planned paths and selected foreign candidates.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -1102,10 +1103,10 @@ export declare class Materializer implements MaterializerInterface {
           * @remarks
           * Host directories expand before the target is read, so this method and
           * {@link repair} compare the same paths with the same ownership. Foreign
-          * candidates are files beneath those expanded roots and files the target holds
-          * at a `CANON_PATHS` member, each in a group the plan selects; a file outside
-          * both populations never becomes a deletion candidate merely because its group
-          * is selected.
+          * candidates are files beneath those expanded roots and files the target holds at
+          * a `CANON_PATHS` member. A
+          * file outside these populations never becomes a deletion candidate merely
+          * because its group is selected.
           *
           * The canon is staged for reading rather than for a target, so a copy of one of
           * its paths sitting in a target is a superseded artifact and reports foreign. A
@@ -1238,13 +1239,12 @@ export declare class Materializer implements MaterializerInterface {
                 * recovery mechanism, so a path it cannot restore is not one this verb takes.
                 * A tree carrying uncommitted work is refused whole for the same reason.
                 *
-                * One candidate list carries both foreign populations {@link audit} reports, so
-                * a superseded instruction copy the target holds inside the canon is deleted in
-                * the same transaction as a stray beneath an owned root. Membership decides it,
-                * never byte identity: a copy a release behind no longer matches the bytes the
-                * canon now stages, and matching bytes is exactly how such a copy would be
-                * spared. An untracked leftover is left where it sits and stays a finding, which
-                * is the seam a maintainer keeps a git-ignored file in.
+                * The candidate list carries every foreign population {@link audit} reports. A
+                * superseded instruction copy inside the canon and a stray beneath an owned root
+                * therefore follow the same transaction rules.
+                * Membership decides it, never byte identity. An untracked leftover stays in
+                * place and remains a finding, which is the seam a maintainer uses to keep a
+                * git-ignored file.
                 *
                 * The whole call refuses when the preview disagrees with the re-derivation on
                 * any foreign finding, including one the deletion itself would skip, because a
@@ -1312,7 +1312,11 @@ export declare class Materializer implements MaterializerInterface {
                 *
                 * @param plan - The compiled plan to compare.
                 * @param target - The directory to inspect.
-                * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+                * @returns Findings for hydrated planned paths and selected foreign candidates.
+                *
+                * @remarks
+                * Foreign candidates are files beneath expanded host roots and files held at a
+                * selected instruction-canon path.
                 */
                audit(plan: Plan, target: string): Audit;
                /**
@@ -1391,7 +1395,6 @@ export declare class Materializer implements MaterializerInterface {
                 * unlinked, so a failure part way through restores what it already took.
                 * The package's own source and application trees are never candidates,
                 * whatever the audit reports.
-                *
                 * The whole audit is guarded before any of it is read, so an audit produced by
                 * an earlier version of this package is refused at runtime rather than only at
                 * compile time. Only foreign findings are candidates and those never carried
@@ -1987,11 +1990,11 @@ export declare class Materializer implements MaterializerInterface {
             * such a path is skipped. A path either list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
-            * @example
+            * @example Vendored data root
             * ```ts
             * import { stageHost } from '@orkestrel/scaffold/server'
             *
-            * stageHost(process.cwd(), 'dist/host').length // the files staged
+            * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
             * ```
             */
            export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
@@ -2079,6 +2082,8 @@ export declare class Materializer implements MaterializerInterface {
             *
             * const upstream = new Upstream({ registry: { timeout: 5_000 } })
             * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
+            *
+            * releases.filter((release) => release.lookup === 'found')
             * upstream.destroy()
             * ```
             */

package/dist/src/server/index.d.ts

@@ -1,18 +1,18 @@
-import { Audit } from '@orkestrel/scaffold';
-import { CatalogEntry } from '@orkestrel/scaffold';
-import { Dependency } from '@orkestrel/scaffold';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { Group } from '@orkestrel/scaffold';
-import { Guard } from '@orkestrel/contract';
-import { HostFile } from '@orkestrel/scaffold';
-import { Lookup } from '@orkestrel/scaffold';
-import { ManifestRegionSet } from '@orkestrel/scaffold';
-import { Mirror } from '@orkestrel/scaffold';
-import { Plan } from '@orkestrel/scaffold';
-import { Release } from '@orkestrel/scaffold';
-import { Snapshot } from '@orkestrel/scaffold';
+import type { Audit } from '@orkestrel/scaffold';
+import type { CatalogEntry } from '@orkestrel/scaffold';
+import type { Dependency } from '@orkestrel/scaffold';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Group } from '@orkestrel/scaffold';
+import type { Guard } from '@orkestrel/contract';
+import type { HostFile } from '@orkestrel/scaffold';
+import type { Lookup } from '@orkestrel/scaffold';
+import type { ManifestRegionSet } from '@orkestrel/scaffold';
+import type { Mirror } from '@orkestrel/scaffold';
+import type { Plan } from '@orkestrel/scaffold';
+import type { Release } from '@orkestrel/scaffold';
+import type { Snapshot } from '@orkestrel/scaffold';
 
 /**
  * Matches the Git branch syntax the repository endpoint accepts.
@@ -1052,7 +1052,9 @@ export declare function matchesSensitivePath(path: string): boolean;
  * declare const plan: Plan
  *
  * const materializer = new Materializer({ host: './dist/host' })
- * materializer.materialize(plan, './packages/router')
+ * const result = materializer.materialize(plan, './packages/router')
+ *
+ * result.written // every path created
  * materializer.destroy()
  * ```
  */
@@ -1093,8 +1095,7 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns One finding per hydrated planned path, plus the foreign files
-      * beneath owned host roots and inside the instruction canon.
+      * @returns Findings for hydrated planned paths and selected foreign candidates.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -1102,10 +1103,10 @@ export declare class Materializer implements MaterializerInterface {
           * @remarks
           * Host directories expand before the target is read, so this method and
           * {@link repair} compare the same paths with the same ownership. Foreign
-          * candidates are files beneath those expanded roots and files the target holds
-          * at a `CANON_PATHS` member, each in a group the plan selects; a file outside
-          * both populations never becomes a deletion candidate merely because its group
-          * is selected.
+          * candidates are files beneath those expanded roots and files the target holds at
+          * a `CANON_PATHS` member. A
+          * file outside these populations never becomes a deletion candidate merely
+          * because its group is selected.
           *
           * The canon is staged for reading rather than for a target, so a copy of one of
           * its paths sitting in a target is a superseded artifact and reports foreign. A
@@ -1238,13 +1239,12 @@ export declare class Materializer implements MaterializerInterface {
                 * recovery mechanism, so a path it cannot restore is not one this verb takes.
                 * A tree carrying uncommitted work is refused whole for the same reason.
                 *
-                * One candidate list carries both foreign populations {@link audit} reports, so
-                * a superseded instruction copy the target holds inside the canon is deleted in
-                * the same transaction as a stray beneath an owned root. Membership decides it,
-                * never byte identity: a copy a release behind no longer matches the bytes the
-                * canon now stages, and matching bytes is exactly how such a copy would be
-                * spared. An untracked leftover is left where it sits and stays a finding, which
-                * is the seam a maintainer keeps a git-ignored file in.
+                * The candidate list carries every foreign population {@link audit} reports. A
+                * superseded instruction copy inside the canon and a stray beneath an owned root
+                * therefore follow the same transaction rules.
+                * Membership decides it, never byte identity. An untracked leftover stays in
+                * place and remains a finding, which is the seam a maintainer uses to keep a
+                * git-ignored file.
                 *
                 * The whole call refuses when the preview disagrees with the re-derivation on
                 * any foreign finding, including one the deletion itself would skip, because a
@@ -1312,7 +1312,11 @@ export declare class Materializer implements MaterializerInterface {
                 *
                 * @param plan - The compiled plan to compare.
                 * @param target - The directory to inspect.
-                * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+                * @returns Findings for hydrated planned paths and selected foreign candidates.
+                *
+                * @remarks
+                * Foreign candidates are files beneath expanded host roots and files held at a
+                * selected instruction-canon path.
                 */
                audit(plan: Plan, target: string): Audit;
                /**
@@ -1391,7 +1395,6 @@ export declare class Materializer implements MaterializerInterface {
                 * unlinked, so a failure part way through restores what it already took.
                 * The package's own source and application trees are never candidates,
                 * whatever the audit reports.
-                *
                 * The whole audit is guarded before any of it is read, so an audit produced by
                 * an earlier version of this package is refused at runtime rather than only at
                 * compile time. Only foreign findings are candidates and those never carried
@@ -1987,11 +1990,11 @@ export declare class Materializer implements MaterializerInterface {
             * such a path is skipped. A path either list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
-            * @example
+            * @example Vendored data root
             * ```ts
             * import { stageHost } from '@orkestrel/scaffold/server'
             *
-            * stageHost(process.cwd(), 'dist/host').length // the files staged
+            * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
             * ```
             */
            export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
@@ -2079,6 +2082,8 @@ export declare class Materializer implements MaterializerInterface {
             *
             * const upstream = new Upstream({ registry: { timeout: 5_000 } })
             * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
+            *
+            * releases.filter((release) => release.lookup === 'found')
             * upstream.destroy()
             * ```
             */

package/dist/src/server/index.js

@@ -1834,11 +1834,11 @@ function stageBytes(host, root, destinations) {
 * such a path is skipped. A path either list names itself is curated data
 * rather than discovery, so it is staged or the stage is refused.
 *
-* @example
+* @example Vendored data root
 * ```ts
 * import { stageHost } from '@orkestrel/scaffold/server'
 *
-* stageHost(process.cwd(), 'dist/host').length // the files staged
+* stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
 * ```
 */
 function stageHost(checkout, host) {
@@ -2727,7 +2727,9 @@ var WriteTransaction = class {
 * declare const plan: Plan
 *
 * const materializer = new Materializer({ host: './dist/host' })
-* materializer.materialize(plan, './packages/router')
+* const result = materializer.materialize(plan, './packages/router')
+*
+* result.written // every path created
 * materializer.destroy()
 * ```
 */
@@ -2802,8 +2804,7 @@ var Materializer = class {
 	*
 	* @param plan - The compiled plan to compare.
 	* @param target - The directory to inspect.
-	* @returns One finding per hydrated planned path, plus the foreign files
-	* beneath owned host roots and inside the instruction canon.
+	* @returns Findings for hydrated planned paths and selected foreign candidates.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
 	* exact shape, `TARGET` when the host or target cannot be read within its
 	* bounds, and `DESTROYED` after teardown.
@@ -2811,10 +2812,10 @@ var Materializer = class {
 	* @remarks
 	* Host directories expand before the target is read, so this method and
 	* {@link repair} compare the same paths with the same ownership. Foreign
-	* candidates are files beneath those expanded roots and files the target holds
-	* at a `CANON_PATHS` member, each in a group the plan selects; a file outside
-	* both populations never becomes a deletion candidate merely because its group
-	* is selected.
+	* candidates are files beneath those expanded roots and files the target holds at
+	* a `CANON_PATHS` member. A
+	* file outside these populations never becomes a deletion candidate merely
+	* because its group is selected.
 	*
 	* The canon is staged for reading rather than for a target, so a copy of one of
 	* its paths sitting in a target is a superseded artifact and reports foreign. A
@@ -3019,13 +3020,12 @@ var Materializer = class {
 	* recovery mechanism, so a path it cannot restore is not one this verb takes.
 	* A tree carrying uncommitted work is refused whole for the same reason.
 	*
-	* One candidate list carries both foreign populations {@link audit} reports, so
-	* a superseded instruction copy the target holds inside the canon is deleted in
-	* the same transaction as a stray beneath an owned root. Membership decides it,
-	* never byte identity: a copy a release behind no longer matches the bytes the
-	* canon now stages, and matching bytes is exactly how such a copy would be
-	* spared. An untracked leftover is left where it sits and stays a finding, which
-	* is the seam a maintainer keeps a git-ignored file in.
+	* The candidate list carries every foreign population {@link audit} reports. A
+	* superseded instruction copy inside the canon and a stray beneath an owned root
+	* therefore follow the same transaction rules.
+	* Membership decides it, never byte identity. An untracked leftover stays in
+	* place and remains a finding, which is the seam a maintainer uses to keep a
+	* git-ignored file.
 	*
 	* The whole call refuses when the preview disagrees with the re-derivation on
 	* any foreign finding, including one the deletion itself would skip, because a
@@ -3497,22 +3497,26 @@ var Materializer = class {
 				`\`${entry.name}\``,
 				this.#cell(entry.note),
 				"",
+				"",
 				""
 			];
 			const layer = placed.get(entry.name);
 			const edges = entry.dependencies.map((dependency) => `\`${dependency.name}\` \`${dependency.range}\``).join(", ");
+			const peers = entry.peers.map((dependency) => `\`${dependency.name}\` \`${dependency.range}\``).join(", ");
 			return [
 				`\`${entry.name}\``,
 				`\`${entry.version}\``,
 				layer === void 0 ? "" : `L${String(layer)}`,
-				edges
+				edges,
+				peers
 			];
 		});
 		const headers = [
 			"Package",
 			"Version",
 			"Layer",
-			"Runtime dependencies"
+			"Runtime dependencies",
+			"Peer dependencies"
 		];
 		const widths = headers.map((header, column) => {
 			let width = Math.max(3, header.length);
@@ -3603,6 +3607,8 @@ var Materializer = class {
 *
 * const upstream = new Upstream({ registry: { timeout: 5_000 } })
 * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
+*
+* releases.filter((release) => release.lookup === 'found')
 * upstream.destroy()
 * ```
 */
@@ -3989,7 +3995,8 @@ var Upstream = class {
 			name,
 			lookup: "found",
 			version,
-			dependencies: this.#edges(outcome.content, version)
+			dependencies: this.#edges(outcome.content, version, "dependencies"),
+			peers: this.#edges(outcome.content, version, "peerDependencies")
 		};
 		return {
 			name,
@@ -3997,14 +4004,14 @@ var Upstream = class {
 			note: outcome.lookup === "found" ? UNREADABLE_VERSION_NOTE : outcome.note
 		};
 	}
-	#edges(content, version) {
+	#edges(content, version, section) {
 		const parsed = parseJSON(content);
 		if (!isRecord(parsed)) return [];
 		const versions = parsed.versions;
 		if (!isRecord(versions)) return [];
 		const manifest = versions[version];
 		if (!isRecord(manifest)) return [];
-		const declared = manifest.dependencies;
+		const declared = manifest[section];
 		if (!isRecord(declared)) return [];
 		const edges = [];
 		for (const [name, range] of Object.entries(declared)) {