@packall/core 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @packall/core
+
+The registry-agnostic engine behind packall. It resolves package specs, walks their
+dependency closures, verifies downloads, and writes registry-shaped bundle artifacts.
+The engine does not know how a registry speaks HTTP: that boundary is the `Registry`
+service.
+
+## Install
+
+```bash
+npm install @packall/core effect
+```
+
+`effect` is a peer dependency. The default entry point is browser-safe. Node-specific
+archive support is available explicitly from `@packall/core/node`.
+
+## Registry service
+
+Implement or provide `Registry` when embedding the engine. A registry backend supplies
+three operations:
+
+- `preflight` checks that the registry is reachable.
+- `packument(name)` reads package metadata and published versions.
+- `download(manifest)` returns the tarball bytes for a resolved package.
+
+The engine then handles resolution, lockfile pinning, platform filtering, integrity
+verification, progress reporting, manifests, layouts, and archive planning.
+
+## Bundle from code
+
+```ts
+import * as Effect from "effect/Effect";
+import { bundle, defaultBundleOptions, parseSpec, Registry } from "@packall/core";
+
+const program = Effect.gen(function* () {
+	// The surrounding Effect runtime provides Registry, Progress, filesystem,
+	// crypto, and the Node archive layer.
+	yield* Registry;
+	return yield* bundle([parseSpec("react@18.2.0")], {
+		...defaultBundleOptions,
+		outDir: "./bundles",
+		toolVersion: "example",
+	});
+});
+```
+
+In practice, compose the program with an Effect layer that provides `Registry`,
+`Progress`, and the archive backend. The public API also exposes `plan`, `resolve`,
+`resolveLocked`, `bundleLocked`, input-file parsing, lockfile parsing, and manifest
+helpers for applications that need more control than `bundle` provides.
+
+See the [packall documentation](https://packall.localhost/docs) and the
+[`@packall/core` API reference](https://packall.localhost/docs/api/core) for the full
+typed surface.
+
+## License
+
+MIT

package/dist/archive-6sqTn1C4.js

@@ -0,0 +1,274 @@
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+
+//#region src/errors.ts
+var BundlerErrorBase = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+/** A package spec on the command line or in an input file could not be parsed. */
+var InvalidSpecError = class extends BundlerErrorBase {
+	_tag = "InvalidSpecError";
+	spec;
+	reason;
+	constructor(spec, reason) {
+		super(`Invalid package spec ${JSON.stringify(spec)}: ${reason}`);
+		this.spec = spec;
+		this.reason = reason;
+	}
+};
+/** `--file` pointed at something that is neither a usable package.json nor a spec list. */
+var InvalidInputFileError = class extends BundlerErrorBase {
+	_tag = "InvalidInputFileError";
+	path;
+	reason;
+	constructor(path, reason, options) {
+		super(`Cannot read specs from ${path}: ${reason}`, options);
+		this.path = path;
+		this.reason = reason;
+	}
+};
+/** A lockfile could not be read, or is in a format we do not support. */
+var LockfileError = class extends BundlerErrorBase {
+	_tag = "LockfileError";
+	path;
+	reason;
+	constructor(path, reason, options) {
+		super(`Lockfile ${path}: ${reason}`, options);
+		this.path = path;
+		this.reason = reason;
+	}
+};
+/**
+* The lockfile parsed, but does not pin everything the bundle needs.
+*
+* Falling back to a range here would defeat the entire point of reading a
+* lockfile — you would get a bundle that is *mostly* what CI installed, with no
+* indication of which parts were guessed. So this is fatal, and it names every
+* gap at once so one `npm install` fixes all of them.
+*/
+var LockfileIncompleteError = class extends BundlerErrorBase {
+	_tag = "LockfileIncompleteError";
+	path;
+	missing;
+	constructor(path, missing, detail, remedy) {
+		const shown = missing.slice(0, 10).map((entry) => `    ${entry}`).join("\n");
+		const rest = missing.length > 10 ? `\n    … and ${missing.length - 10} more` : "";
+		super(`${path} is incomplete — ${detail}:\n${shown}${rest}\n  ${remedy}\n  Or pass --lockfile off to resolve version ranges fresh instead.`);
+		this.path = path;
+		this.missing = missing;
+	}
+};
+/**
+* The lockfile pins versions the registry no longer serves.
+*
+* Unpublished, or never mirrored into a private registry. Either way the
+* bundle cannot be built as specified, and quietly substituting a nearby
+* version would produce exactly the mismatch this feature exists to prevent.
+*/
+var LockfileOutOfDateError = class extends BundlerErrorBase {
+	_tag = "LockfileOutOfDateError";
+	path;
+	registry;
+	missing;
+	constructor(path, registry, missing) {
+		const shown = missing.slice(0, 10).map((entry) => `    ${entry.name}@${entry.version} — ${entry.detail}`).join("\n");
+		const rest = missing.length > 10 ? `\n    … and ${missing.length - 10} more` : "";
+		super(`${path} pins ${missing.length} version${missing.length === 1 ? "" : "s"} that ${registry} does not serve:\n${shown}${rest}\n  Refresh the lockfile against this registry, or pass --lockfile off to\n  resolve version ranges fresh instead.`);
+		this.path = path;
+		this.registry = registry;
+		this.missing = missing.map(({ name, version }) => ({
+			name,
+			version
+		}));
+	}
+};
+/**
+* The registry could not be reached at all — DNS failure, refused connection,
+* proxy blackhole, or a preflight that timed out.
+*
+* This is the error that fixes "hangs forever with no network": we surface it
+* quickly and say which host we could not reach.
+*/
+var RegistryUnreachableError = class extends BundlerErrorBase {
+	_tag = "RegistryUnreachableError";
+	registry;
+	timeoutMs;
+	constructor(registry, detail, options) {
+		super(`Cannot reach registry ${registry}: ${detail}.\n  Check your network connection, VPN, and the proxy settings in your .npmrc.`, options);
+		this.registry = registry;
+		this.timeoutMs = options?.timeoutMs;
+	}
+};
+/** The registry answered, but has never heard of this package. */
+var PackageNotFoundError = class extends BundlerErrorBase {
+	_tag = "PackageNotFoundError";
+	packageName;
+	registry;
+	constructor(packageName, registry) {
+		super(`Package "${packageName}" was not found on ${registry}`);
+		this.packageName = packageName;
+		this.registry = registry;
+	}
+};
+/** The package exists but the exact version requested does not. */
+var VersionNotFoundError = class extends BundlerErrorBase {
+	_tag = "VersionNotFoundError";
+	packageName;
+	version;
+	available;
+	constructor(packageName, version, available) {
+		const tail = available.slice(-5).join(", ");
+		super(`${packageName}@${version} does not exist.` + (tail.length > 0 ? ` Most recent published versions: ${tail}` : ""));
+		this.packageName = packageName;
+		this.version = version;
+		this.available = available;
+	}
+};
+/** A range (or dist-tag) matched nothing that is actually published. */
+var NoMatchingVersionsError = class extends BundlerErrorBase {
+	_tag = "NoMatchingVersionsError";
+	packageName;
+	selector;
+	available;
+	constructor(packageName, selector, available) {
+		const tail = available.slice(-5).join(", ");
+		super(`No published version of ${packageName} satisfies "${selector}".` + (tail.length > 0 ? ` Most recent published versions: ${tail}` : ""));
+		this.packageName = packageName;
+		this.selector = selector;
+		this.available = available;
+	}
+};
+/** The registry responded, but with something we cannot use. */
+var RegistryResponseError = class extends BundlerErrorBase {
+	_tag = "RegistryResponseError";
+	url;
+	status;
+	constructor(url, detail, options) {
+		super(`Unexpected response from ${url}: ${detail}`, options);
+		this.url = url;
+		this.status = options?.status;
+	}
+};
+/** 401/403 — almost always a missing or stale token in `.npmrc`. */
+var AuthenticationError = class extends BundlerErrorBase {
+	_tag = "AuthenticationError";
+	registry;
+	status;
+	constructor(registry, status, packageName) {
+		super(`Registry ${registry} rejected the request with HTTP ${status}` + (packageName ? ` while fetching "${packageName}"` : "") + `.\n  Add credentials to your .npmrc, e.g.\n    //${safeHost(registry)}/:_authToken=\${NPM_TOKEN}`);
+		this.registry = registry;
+		this.status = status;
+	}
+};
+/**
+* A downloaded tarball did not match the checksum the registry advertised.
+*
+* Never soft-fail this: a bundle is a supply-chain artifact and a corrupt or
+* substituted tarball is exactly what integrity checking exists to catch.
+*/
+var IntegrityError = class extends BundlerErrorBase {
+	_tag = "IntegrityError";
+	packageName;
+	version;
+	expected;
+	actual;
+	constructor(packageName, version, expected, actual) {
+		super(`Integrity check failed for ${packageName}@${version}.\n  expected: ${expected}\n  actual:   ${actual}\n  The download was discarded. This is either corruption in transit or a tampered artifact.`);
+		this.packageName = packageName;
+		this.version = version;
+		this.expected = expected;
+		this.actual = actual;
+	}
+};
+/** Something went wrong writing the `.tgz`. */
+var ArchiveError = class extends BundlerErrorBase {
+	_tag = "ArchiveError";
+	path;
+	constructor(path, detail, options) {
+		super(`Failed to create archive ${path}: ${detail}`, options);
+		this.path = path;
+	}
+};
+/** Something went wrong preparing or writing to the output directory. */
+var OutputError = class extends BundlerErrorBase {
+	_tag = "OutputError";
+	path;
+	constructor(path, detail, options) {
+		super(`Output error at ${path}: ${detail}`, options);
+		this.path = path;
+	}
+};
+const safeHost = (registry) => {
+	try {
+		const url = new URL(registry);
+		return url.host + url.pathname.replace(/\/+$/, "");
+	} catch {
+		return registry;
+	}
+};
+
+//#endregion
+//#region src/progress.ts
+/** Service tag for progress reporting. */
+var Progress = class extends Context.Service()("@packall/core/Progress") {};
+/** Emits an event to whichever reporter is installed. */
+const emit = (event) => Effect.gen(function* () {
+	yield* (yield* Progress).emit(event);
+});
+/**
+* Discards every event.
+*
+* The default for library consumers and for tests that do not care about
+* progress — silence should never require ceremony.
+*/
+const layerSilent = Layer.succeed(Progress)({ emit: () => Effect.void });
+/** Sends every event to a callback. Used by the CLI renderer. */
+const layerCallback = (onEvent) => Layer.succeed(Progress)({ emit: (event) => Effect.sync(() => onEvent(event)) });
+/**
+* Accumulates every event into a `Ref`, for assertions.
+*
+* Returned as `{ layer, events }` so a test can provide the layer and then read
+* the transcript afterwards.
+*/
+const makeCollector = Effect.gen(function* () {
+	const ref = yield* Ref.make([]);
+	return {
+		layer: Layer.succeed(Progress)({ emit: (event) => Ref.update(ref, (events) => [...events, event]) }),
+		events: Ref.get(ref)
+	};
+});
+
+//#endregion
+//#region src/archive.ts
+/** Service tag for archive creation. */
+var Archiver = class extends Context.Service()("@packall/core/Archiver") {};
+/**
+* Packs an archive with whichever backend is installed.
+*
+* The progress events are emitted here rather than inside the backends, so
+* every implementation reports identically and a new one cannot forget to.
+*/
+const createArchive = (options) => Effect.gen(function* () {
+	const archiver = yield* Archiver;
+	yield* emit({
+		_tag: "ArchiveStarted",
+		path: options.outPath,
+		entryCount: options.entries.length
+	});
+	const result = yield* archiver.create(options);
+	yield* emit({
+		_tag: "ArchiveCompleted",
+		path: result.path,
+		bytes: result.bytes
+	});
+	return result;
+});
+
+//#endregion
+export { OutputError as _, layerCallback as a, RegistryUnreachableError as b, ArchiveError as c, InvalidInputFileError as d, InvalidSpecError as f, NoMatchingVersionsError as g, LockfileOutOfDateError as h, emit as i, AuthenticationError as l, LockfileIncompleteError as m, createArchive as n, layerSilent as o, LockfileError as p, Progress as r, makeCollector as s, Archiver as t, IntegrityError as u, PackageNotFoundError as v, VersionNotFoundError as x, RegistryResponseError as y };
+//# sourceMappingURL=archive-6sqTn1C4.js.map

package/dist/archive-6sqTn1C4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-6sqTn1C4.js","names":["layerSilent: Layer.Layer<Progress>","Progress.emit"],"sources":["../src/errors.ts","../src/progress.ts","../src/archive.ts"],"sourcesContent":["/**\n * Failure types for the bundler.\n *\n * These are deliberately plain classes carrying a literal `_tag` rather than\n * `Data.TaggedError`. They work with `Effect.catchTag` / `Effect.catchTags`\n * exactly the same way, and they keep the public error surface independent of\n * any single Effect release — useful while Effect v4 is still in beta.\n *\n * Every error carries enough context to be actionable without a stack trace,\n * because the primary consumer is somebody staring at a terminal on a\n * locked-down network trying to work out why a download did not happen.\n */\n\n/** Discriminant union of every failure the bundler can produce. */\nexport type BundlerError =\n\t| InvalidSpecError\n\t| InvalidInputFileError\n\t| LockfileError\n\t| LockfileIncompleteError\n\t| LockfileOutOfDateError\n\t| RegistryUnreachableError\n\t| PackageNotFoundError\n\t| VersionNotFoundError\n\t| NoMatchingVersionsError\n\t| RegistryResponseError\n\t| AuthenticationError\n\t| IntegrityError\n\t| ArchiveError\n\t| OutputError;\n\nabstract class BundlerErrorBase extends Error {\n\tabstract readonly _tag: string;\n\tconstructor(message: string, options?: ErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.name = new.target.name;\n\t}\n}\n\n/** A package spec on the command line or in an input file could not be parsed. */\nexport class InvalidSpecError extends BundlerErrorBase {\n\treadonly _tag = \"InvalidSpecError\" as const;\n\treadonly spec: string;\n\treadonly reason: string;\n\tconstructor(spec: string, reason: string) {\n\t\tsuper(`Invalid package spec ${JSON.stringify(spec)}: ${reason}`);\n\t\tthis.spec = spec;\n\t\tthis.reason = reason;\n\t}\n}\n\n/** `--file` pointed at something that is neither a usable package.json nor a spec list. */\nexport class InvalidInputFileError extends BundlerErrorBase {\n\treadonly _tag = \"InvalidInputFileError\" as const;\n\treadonly path: string;\n\treadonly reason: string;\n\tconstructor(path: string, reason: string, options?: { cause?: unknown }) {\n\t\tsuper(`Cannot read specs from ${path}: ${reason}`, options);\n\t\tthis.path = path;\n\t\tthis.reason = reason;\n\t}\n}\n\n/** A lockfile could not be read, or is in a format we do not support. */\nexport class LockfileError extends BundlerErrorBase {\n\treadonly _tag = \"LockfileError\" as const;\n\treadonly path: string;\n\treadonly reason: string;\n\tconstructor(path: string, reason: string, options?: { cause?: unknown }) {\n\t\t// Opens with \"Lockfile\" so the renderer's tag prefix does not stutter, and\n\t\t// because not every reason is a read failure — \"does not cover this\n\t\t// package\" is about a file that read perfectly well.\n\t\tsuper(`Lockfile ${path}: ${reason}`, options);\n\t\tthis.path = path;\n\t\tthis.reason = reason;\n\t}\n}\n\n/**\n * The lockfile parsed, but does not pin everything the bundle needs.\n *\n * Falling back to a range here would defeat the entire point of reading a\n * lockfile — you would get a bundle that is *mostly* what CI installed, with no\n * indication of which parts were guessed. So this is fatal, and it names every\n * gap at once so one `npm install` fixes all of them.\n */\nexport class LockfileIncompleteError extends BundlerErrorBase {\n\treadonly _tag = \"LockfileIncompleteError\" as const;\n\treadonly path: string;\n\treadonly missing: ReadonlyArray<string>;\n\tconstructor(path: string, missing: ReadonlyArray<string>, detail: string, remedy: string) {\n\t\tconst shown = missing\n\t\t\t.slice(0, 10)\n\t\t\t.map((entry) => `    ${entry}`)\n\t\t\t.join(\"\\n\");\n\t\tconst rest = missing.length > 10 ? `\\n    … and ${missing.length - 10} more` : \"\";\n\t\tsuper(\n\t\t\t`${path} is incomplete — ${detail}:\\n${shown}${rest}\\n` +\n\t\t\t\t`  ${remedy}\\n` +\n\t\t\t\t`  Or pass --lockfile off to resolve version ranges fresh instead.`,\n\t\t);\n\t\tthis.path = path;\n\t\tthis.missing = missing;\n\t}\n}\n\n/**\n * The lockfile pins versions the registry no longer serves.\n *\n * Unpublished, or never mirrored into a private registry. Either way the\n * bundle cannot be built as specified, and quietly substituting a nearby\n * version would produce exactly the mismatch this feature exists to prevent.\n */\nexport class LockfileOutOfDateError extends BundlerErrorBase {\n\treadonly _tag = \"LockfileOutOfDateError\" as const;\n\treadonly path: string;\n\treadonly registry: string;\n\treadonly missing: ReadonlyArray<{ readonly name: string; readonly version: string }>;\n\tconstructor(\n\t\tpath: string,\n\t\tregistry: string,\n\t\tmissing: ReadonlyArray<{\n\t\t\treadonly name: string;\n\t\t\treadonly version: string;\n\t\t\treadonly detail: string;\n\t\t}>,\n\t) {\n\t\tconst shown = missing\n\t\t\t.slice(0, 10)\n\t\t\t.map((entry) => `    ${entry.name}@${entry.version} — ${entry.detail}`)\n\t\t\t.join(\"\\n\");\n\t\tconst rest = missing.length > 10 ? `\\n    … and ${missing.length - 10} more` : \"\";\n\t\tsuper(\n\t\t\t`${path} pins ${missing.length} version${missing.length === 1 ? \"\" : \"s\"} ` +\n\t\t\t\t`that ${registry} does not serve:\\n${shown}${rest}\\n` +\n\t\t\t\t`  Refresh the lockfile against this registry, or pass --lockfile off to\\n` +\n\t\t\t\t`  resolve version ranges fresh instead.`,\n\t\t);\n\t\tthis.path = path;\n\t\tthis.registry = registry;\n\t\tthis.missing = missing.map(({ name, version }) => ({ name, version }));\n\t}\n}\n\n/**\n * The registry could not be reached at all — DNS failure, refused connection,\n * proxy blackhole, or a preflight that timed out.\n *\n * This is the error that fixes \"hangs forever with no network\": we surface it\n * quickly and say which host we could not reach.\n */\nexport class RegistryUnreachableError extends BundlerErrorBase {\n\treadonly _tag = \"RegistryUnreachableError\" as const;\n\treadonly registry: string;\n\treadonly timeoutMs: number | undefined;\n\tconstructor(\n\t\tregistry: string,\n\t\tdetail: string,\n\t\toptions?: { cause?: unknown; timeoutMs?: number },\n\t) {\n\t\tsuper(\n\t\t\t`Cannot reach registry ${registry}: ${detail}.\\n` +\n\t\t\t\t`  Check your network connection, VPN, and the proxy settings in your .npmrc.`,\n\t\t\toptions,\n\t\t);\n\t\tthis.registry = registry;\n\t\tthis.timeoutMs = options?.timeoutMs;\n\t}\n}\n\n/** The registry answered, but has never heard of this package. */\nexport class PackageNotFoundError extends BundlerErrorBase {\n\treadonly _tag = \"PackageNotFoundError\" as const;\n\treadonly packageName: string;\n\treadonly registry: string;\n\tconstructor(packageName: string, registry: string) {\n\t\tsuper(`Package \"${packageName}\" was not found on ${registry}`);\n\t\tthis.packageName = packageName;\n\t\tthis.registry = registry;\n\t}\n}\n\n/** The package exists but the exact version requested does not. */\nexport class VersionNotFoundError extends BundlerErrorBase {\n\treadonly _tag = \"VersionNotFoundError\" as const;\n\treadonly packageName: string;\n\treadonly version: string;\n\treadonly available: ReadonlyArray<string>;\n\tconstructor(packageName: string, version: string, available: ReadonlyArray<string>) {\n\t\tconst tail = available.slice(-5).join(\", \");\n\t\tsuper(\n\t\t\t`${packageName}@${version} does not exist.` +\n\t\t\t\t(tail.length > 0 ? ` Most recent published versions: ${tail}` : \"\"),\n\t\t);\n\t\tthis.packageName = packageName;\n\t\tthis.version = version;\n\t\tthis.available = available;\n\t}\n}\n\n/** A range (or dist-tag) matched nothing that is actually published. */\nexport class NoMatchingVersionsError extends BundlerErrorBase {\n\treadonly _tag = \"NoMatchingVersionsError\" as const;\n\treadonly packageName: string;\n\treadonly selector: string;\n\treadonly available: ReadonlyArray<string>;\n\tconstructor(packageName: string, selector: string, available: ReadonlyArray<string>) {\n\t\tconst tail = available.slice(-5).join(\", \");\n\t\tsuper(\n\t\t\t`No published version of ${packageName} satisfies \"${selector}\".` +\n\t\t\t\t(tail.length > 0 ? ` Most recent published versions: ${tail}` : \"\"),\n\t\t);\n\t\tthis.packageName = packageName;\n\t\tthis.selector = selector;\n\t\tthis.available = available;\n\t}\n}\n\n/** The registry responded, but with something we cannot use. */\nexport class RegistryResponseError extends BundlerErrorBase {\n\treadonly _tag = \"RegistryResponseError\" as const;\n\treadonly url: string;\n\treadonly status: number | undefined;\n\tconstructor(url: string, detail: string, options?: { cause?: unknown; status?: number }) {\n\t\tsuper(`Unexpected response from ${url}: ${detail}`, options);\n\t\tthis.url = url;\n\t\tthis.status = options?.status;\n\t}\n}\n\n/** 401/403 — almost always a missing or stale token in `.npmrc`. */\nexport class AuthenticationError extends BundlerErrorBase {\n\treadonly _tag = \"AuthenticationError\" as const;\n\treadonly registry: string;\n\treadonly status: number;\n\tconstructor(registry: string, status: number, packageName?: string) {\n\t\tsuper(\n\t\t\t`Registry ${registry} rejected the request with HTTP ${status}` +\n\t\t\t\t(packageName ? ` while fetching \"${packageName}\"` : \"\") +\n\t\t\t\t`.\\n  Add credentials to your .npmrc, e.g.\\n` +\n\t\t\t\t`    //${safeHost(registry)}/:_authToken=\\${NPM_TOKEN}`,\n\t\t);\n\t\tthis.registry = registry;\n\t\tthis.status = status;\n\t}\n}\n\n/**\n * A downloaded tarball did not match the checksum the registry advertised.\n *\n * Never soft-fail this: a bundle is a supply-chain artifact and a corrupt or\n * substituted tarball is exactly what integrity checking exists to catch.\n */\nexport class IntegrityError extends BundlerErrorBase {\n\treadonly _tag = \"IntegrityError\" as const;\n\treadonly packageName: string;\n\treadonly version: string;\n\treadonly expected: string;\n\treadonly actual: string;\n\tconstructor(packageName: string, version: string, expected: string, actual: string) {\n\t\tsuper(\n\t\t\t`Integrity check failed for ${packageName}@${version}.\\n` +\n\t\t\t\t`  expected: ${expected}\\n` +\n\t\t\t\t`  actual:   ${actual}\\n` +\n\t\t\t\t`  The download was discarded. This is either corruption in transit or a tampered artifact.`,\n\t\t);\n\t\tthis.packageName = packageName;\n\t\tthis.version = version;\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\n/** Something went wrong writing the `.tgz`. */\nexport class ArchiveError extends BundlerErrorBase {\n\treadonly _tag = \"ArchiveError\" as const;\n\treadonly path: string;\n\tconstructor(path: string, detail: string, options?: { cause?: unknown }) {\n\t\tsuper(`Failed to create archive ${path}: ${detail}`, options);\n\t\tthis.path = path;\n\t}\n}\n\n/** Something went wrong preparing or writing to the output directory. */\nexport class OutputError extends BundlerErrorBase {\n\treadonly _tag = \"OutputError\" as const;\n\treadonly path: string;\n\tconstructor(path: string, detail: string, options?: { cause?: unknown }) {\n\t\tsuper(`Output error at ${path}: ${detail}`, options);\n\t\tthis.path = path;\n\t}\n}\n\nconst safeHost = (registry: string): string => {\n\ttry {\n\t\tconst url = new URL(registry);\n\t\treturn url.host + url.pathname.replace(/\\/+$/, \"\");\n\t} catch {\n\t\treturn registry;\n\t}\n};\n","/**\n * Progress reporting.\n *\n * The engine emits structured events; it never writes to a terminal. That\n * separation is what lets the CLI draw a live TTY view, CI print plain lines,\n * and the test suite assert on an array of events without any of them\n * interfering with each other.\n */\nimport * as Context from \"effect/Context\";\nimport * as Effect from \"effect/Effect\";\nimport * as Layer from \"effect/Layer\";\nimport * as Ref from \"effect/Ref\";\n\nimport type { Phase } from \"./enums/phase.js\";\n\n/** A structured progress event. */\nexport type ProgressEvent =\n\t/** A phase began. `total` is set only when it is known up front. */\n\t| { readonly _tag: \"PhaseStarted\"; readonly phase: Phase; readonly total?: number | undefined }\n\t/** A phase finished. */\n\t| { readonly _tag: \"PhaseCompleted\"; readonly phase: Phase }\n\t/** The resolver discovered a package that has to be included. */\n\t| {\n\t\t\treadonly _tag: \"PackageResolved\";\n\t\t\treadonly name: string;\n\t\t\treadonly version: string;\n\t\t\t/** Running count of resolved packages, for a live counter. */\n\t\t\treadonly resolvedCount: number;\n\t\t\t/** Packages still queued for resolution. */\n\t\t\treadonly pendingCount: number;\n\t  }\n\t/** A tarball download started. */\n\t| { readonly _tag: \"DownloadStarted\"; readonly name: string; readonly version: string }\n\t/** A tarball download finished. */\n\t| {\n\t\t\treadonly _tag: \"DownloadCompleted\";\n\t\t\treadonly name: string;\n\t\t\treadonly version: string;\n\t\t\treadonly bytes: number;\n\t\t\treadonly completedCount: number;\n\t\t\treadonly totalCount: number;\n\t  }\n\t/** A download failed and will be retried. */\n\t| {\n\t\t\treadonly _tag: \"DownloadRetrying\";\n\t\t\treadonly name: string;\n\t\t\treadonly version: string;\n\t\t\treadonly attempt: number;\n\t\t\treadonly reason: string;\n\t  }\n\t/** An archive is being written. */\n\t| { readonly _tag: \"ArchiveStarted\"; readonly path: string; readonly entryCount: number }\n\t/** An archive finished. */\n\t| { readonly _tag: \"ArchiveCompleted\"; readonly path: string; readonly bytes: number }\n\t/** Something noteworthy but non-fatal, e.g. a deprecated package. */\n\t| { readonly _tag: \"Warning\"; readonly message: string };\n\nexport declare namespace Progress {\n\t/** The reporting sink. */\n\texport type Service = {\n\t\treadonly emit: (event: ProgressEvent) => Effect.Effect<void>;\n\t};\n}\n\n/** Service tag for progress reporting. */\nexport class Progress extends Context.Service<Progress, Progress.Service>()(\n\t\"@packall/core/Progress\",\n) {}\n\n/** Emits an event to whichever reporter is installed. */\nexport const emit = (event: ProgressEvent): Effect.Effect<void, never, Progress> =>\n\tEffect.gen(function* () {\n\t\tconst progress = yield* Progress;\n\t\tyield* progress.emit(event);\n\t});\n\n/**\n * Discards every event.\n *\n * The default for library consumers and for tests that do not care about\n * progress — silence should never require ceremony.\n */\nexport const layerSilent: Layer.Layer<Progress> = Layer.succeed(Progress)({\n\temit: () => Effect.void,\n});\n\n/** Sends every event to a callback. Used by the CLI renderer. */\nexport const layerCallback = (onEvent: (event: ProgressEvent) => void): Layer.Layer<Progress> =>\n\tLayer.succeed(Progress)({\n\t\temit: (event) => Effect.sync(() => onEvent(event)),\n\t});\n\n/**\n * Accumulates every event into a `Ref`, for assertions.\n *\n * Returned as `{ layer, events }` so a test can provide the layer and then read\n * the transcript afterwards.\n */\nexport const makeCollector = Effect.gen(function* () {\n\tconst ref = yield* Ref.make<ReadonlyArray<ProgressEvent>>([]);\n\tconst layer = Layer.succeed(Progress)({\n\t\temit: (event: ProgressEvent) => Ref.update(ref, (events) => [...events, event]),\n\t});\n\treturn { layer, events: Ref.get(ref) } as const;\n});\n","/**\n * Turning a staged directory tree into a gzipped tarball.\n *\n * A service rather than a function, because packing is the one step that has\n * to be implemented differently per platform. Everywhere else the engine\n * reaches the disk through `effect/FileSystem`, which is what lets an in-memory\n * filesystem carry the whole pipeline — but a tar writer is not filesystem\n * access, it is a format, and `node-tar` reads the paths it is given with\n * Node's own `fs` rather than through the injected service. Left as a direct\n * call, packing would quietly bypass the abstraction the rest of the engine\n * depends on, which stays invisible until something other than Node provides\n * the filesystem.\n *\n * The implementations live outside this module — `@packall/core/node` for\n * Node, a Web Streams writer in the browser — so nothing platform-specific is\n * reachable from the engine's own graph.\n */\nimport * as Context from \"effect/Context\";\nimport * as Effect from \"effect/Effect\";\nimport type * as FileSystem from \"effect/FileSystem\";\nimport type { PlatformError } from \"effect/PlatformError\";\n\nimport type { ArchiveError } from \"./errors.js\";\nimport * as Progress from \"./progress.js\";\n\n/** A finished archive. */\nexport type ArchiveResult = {\n\treadonly path: string;\n\treadonly bytes: number;\n};\n\n/** What to pack, and where to put it. */\nexport type CreateArchiveOptions = {\n\treadonly cwd: string;\n\t/** Entry paths, relative to `cwd`. */\n\treadonly entries: ReadonlyArray<string>;\n\treadonly outPath: string;\n\treadonly gzipLevel?: number | undefined;\n};\n\nexport declare namespace Archiver {\n\t/** The packing backend. */\n\texport type Service = {\n\t\t/**\n\t\t * Packs `entries` (paths relative to `cwd`) into a gzipped tar at\n\t\t * `outPath`.\n\t\t *\n\t\t * Implementations must produce byte-identical output for identical inputs —\n\t\t * normalised uid/gid/mtime, entries in a stable order — because a security\n\t\t * team diffing two bundles, or re-deriving one from its manifest, is a\n\t\t * thing that actually happens.\n\t\t */\n\t\treadonly create: (\n\t\t\toptions: CreateArchiveOptions,\n\t\t) => Effect.Effect<ArchiveResult, ArchiveError | PlatformError, FileSystem.FileSystem>;\n\t};\n}\n\n/** Service tag for archive creation. */\nexport class Archiver extends Context.Service<Archiver, Archiver.Service>()(\n\t\"@packall/core/Archiver\",\n) {}\n\n/**\n * Packs an archive with whichever backend is installed.\n *\n * The progress events are emitted here rather than inside the backends, so\n * every implementation reports identically and a new one cannot forget to.\n */\nexport const createArchive = (\n\toptions: CreateArchiveOptions,\n): Effect.Effect<\n\tArchiveResult,\n\tArchiveError | PlatformError,\n\tArchiver | FileSystem.FileSystem | Progress.Progress\n> =>\n\tEffect.gen(function* () {\n\t\tconst archiver = yield* Archiver;\n\n\t\tyield* Progress.emit({\n\t\t\t_tag: \"ArchiveStarted\",\n\t\t\tpath: options.outPath,\n\t\t\tentryCount: options.entries.length,\n\t\t});\n\n\t\tconst result = yield* archiver.create(options);\n\n\t\tyield* Progress.emit({\n\t\t\t_tag: \"ArchiveCompleted\",\n\t\t\tpath: result.path,\n\t\t\tbytes: result.bytes,\n\t\t});\n\n\t\treturn result;\n\t});\n"],"mappings":";;;;;;AA8BA,IAAe,mBAAf,cAAwC,MAAM;CAE7C,YAAY,SAAiB,SAAwB;AACpD,QAAM,SAAS,QAAQ;AACvB,OAAK,OAAO,IAAI,OAAO;;;;AAKzB,IAAa,mBAAb,cAAsC,iBAAiB;CACtD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,MAAc,QAAgB;AACzC,QAAM,wBAAwB,KAAK,UAAU,KAAK,CAAC,IAAI,SAAS;AAChE,OAAK,OAAO;AACZ,OAAK,SAAS;;;;AAKhB,IAAa,wBAAb,cAA2C,iBAAiB;CAC3D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,MAAc,QAAgB,SAA+B;AACxE,QAAM,0BAA0B,KAAK,IAAI,UAAU,QAAQ;AAC3D,OAAK,OAAO;AACZ,OAAK,SAAS;;;;AAKhB,IAAa,gBAAb,cAAmC,iBAAiB;CACnD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,MAAc,QAAgB,SAA+B;AAIxE,QAAM,YAAY,KAAK,IAAI,UAAU,QAAQ;AAC7C,OAAK,OAAO;AACZ,OAAK,SAAS;;;;;;;;;;;AAYhB,IAAa,0BAAb,cAA6C,iBAAiB;CAC7D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,MAAc,SAAgC,QAAgB,QAAgB;EACzF,MAAM,QAAQ,QACZ,MAAM,GAAG,GAAG,CACZ,KAAK,UAAU,OAAO,QAAQ,CAC9B,KAAK,KAAK;EACZ,MAAM,OAAO,QAAQ,SAAS,KAAK,eAAe,QAAQ,SAAS,GAAG,SAAS;AAC/E,QACC,GAAG,KAAK,mBAAmB,OAAO,KAAK,QAAQ,KAAK,MAC9C,OAAO,qEAEb;AACD,OAAK,OAAO;AACZ,OAAK,UAAU;;;;;;;;;;AAWjB,IAAa,yBAAb,cAA4C,iBAAiB;CAC5D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,YACC,MACA,UACA,SAKC;EACD,MAAM,QAAQ,QACZ,MAAM,GAAG,GAAG,CACZ,KAAK,UAAU,OAAO,MAAM,KAAK,GAAG,MAAM,QAAQ,KAAK,MAAM,SAAS,CACtE,KAAK,KAAK;EACZ,MAAM,OAAO,QAAQ,SAAS,KAAK,eAAe,QAAQ,SAAS,GAAG,SAAS;AAC/E,QACC,GAAG,KAAK,QAAQ,QAAQ,OAAO,UAAU,QAAQ,WAAW,IAAI,KAAK,IAAI,QAChE,SAAS,oBAAoB,QAAQ,KAAK,oHAGnD;AACD,OAAK,OAAO;AACZ,OAAK,WAAW;AAChB,OAAK,UAAU,QAAQ,KAAK,EAAE,MAAM,eAAe;GAAE;GAAM;GAAS,EAAE;;;;;;;;;;AAWxE,IAAa,2BAAb,cAA8C,iBAAiB;CAC9D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YACC,UACA,QACA,SACC;AACD,QACC,yBAAyB,SAAS,IAAI,OAAO,kFAE7C,QACA;AACD,OAAK,WAAW;AAChB,OAAK,YAAY,SAAS;;;;AAK5B,IAAa,uBAAb,cAA0C,iBAAiB;CAC1D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,aAAqB,UAAkB;AAClD,QAAM,YAAY,YAAY,qBAAqB,WAAW;AAC9D,OAAK,cAAc;AACnB,OAAK,WAAW;;;;AAKlB,IAAa,uBAAb,cAA0C,iBAAiB;CAC1D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,YAAY,aAAqB,SAAiB,WAAkC;EACnF,MAAM,OAAO,UAAU,MAAM,GAAG,CAAC,KAAK,KAAK;AAC3C,QACC,GAAG,YAAY,GAAG,QAAQ,qBACxB,KAAK,SAAS,IAAI,oCAAoC,SAAS,IACjE;AACD,OAAK,cAAc;AACnB,OAAK,UAAU;AACf,OAAK,YAAY;;;;AAKnB,IAAa,0BAAb,cAA6C,iBAAiB;CAC7D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,YAAY,aAAqB,UAAkB,WAAkC;EACpF,MAAM,OAAO,UAAU,MAAM,GAAG,CAAC,KAAK,KAAK;AAC3C,QACC,2BAA2B,YAAY,cAAc,SAAS,OAC5D,KAAK,SAAS,IAAI,oCAAoC,SAAS,IACjE;AACD,OAAK,cAAc;AACnB,OAAK,WAAW;AAChB,OAAK,YAAY;;;;AAKnB,IAAa,wBAAb,cAA2C,iBAAiB;CAC3D,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,KAAa,QAAgB,SAAgD;AACxF,QAAM,4BAA4B,IAAI,IAAI,UAAU,QAAQ;AAC5D,OAAK,MAAM;AACX,OAAK,SAAS,SAAS;;;;AAKzB,IAAa,sBAAb,cAAyC,iBAAiB;CACzD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,QAAgB,aAAsB;AACnE,QACC,YAAY,SAAS,kCAAkC,YACrD,cAAc,oBAAoB,YAAY,KAAK,MACpD,oDACS,SAAS,SAAS,CAAC,4BAC7B;AACD,OAAK,WAAW;AAChB,OAAK,SAAS;;;;;;;;;AAUhB,IAAa,iBAAb,cAAoC,iBAAiB;CACpD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,YAAY,aAAqB,SAAiB,UAAkB,QAAgB;AACnF,QACC,8BAA8B,YAAY,GAAG,QAAQ,iBACrC,SAAS,gBACT,OAAO,8FAEvB;AACD,OAAK,cAAc;AACnB,OAAK,UAAU;AACf,OAAK,WAAW;AAChB,OAAK,SAAS;;;;AAKhB,IAAa,eAAb,cAAkC,iBAAiB;CAClD,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,MAAc,QAAgB,SAA+B;AACxE,QAAM,4BAA4B,KAAK,IAAI,UAAU,QAAQ;AAC7D,OAAK,OAAO;;;;AAKd,IAAa,cAAb,cAAiC,iBAAiB;CACjD,AAAS,OAAO;CAChB,AAAS;CACT,YAAY,MAAc,QAAgB,SAA+B;AACxE,QAAM,mBAAmB,KAAK,IAAI,UAAU,QAAQ;AACpD,OAAK,OAAO;;;AAId,MAAM,YAAY,aAA6B;AAC9C,KAAI;EACH,MAAM,MAAM,IAAI,IAAI,SAAS;AAC7B,SAAO,IAAI,OAAO,IAAI,SAAS,QAAQ,QAAQ,GAAG;SAC3C;AACP,SAAO;;;;;;;ACxOT,IAAa,WAAb,cAA8B,QAAQ,SAAqC,CAC1E,yBACA,CAAC;;AAGF,MAAa,QAAQ,UACpB,OAAO,IAAI,aAAa;AAEvB,SADiB,OAAO,UACR,KAAK,MAAM;EAC1B;;;;;;;AAQH,MAAaA,cAAqC,MAAM,QAAQ,SAAS,CAAC,EACzE,YAAY,OAAO,MACnB,CAAC;;AAGF,MAAa,iBAAiB,YAC7B,MAAM,QAAQ,SAAS,CAAC,EACvB,OAAO,UAAU,OAAO,WAAW,QAAQ,MAAM,CAAC,EAClD,CAAC;;;;;;;AAQH,MAAa,gBAAgB,OAAO,IAAI,aAAa;CACpD,MAAM,MAAM,OAAO,IAAI,KAAmC,EAAE,CAAC;AAI7D,QAAO;EAAE,OAHK,MAAM,QAAQ,SAAS,CAAC,EACrC,OAAO,UAAyB,IAAI,OAAO,MAAM,WAAW,CAAC,GAAG,QAAQ,MAAM,CAAC,EAC/E,CAAC;EACc,QAAQ,IAAI,IAAI,IAAI;EAAE;EACrC;;;;;AC7CF,IAAa,WAAb,cAA8B,QAAQ,SAAqC,CAC1E,yBACA,CAAC;;;;;;;AAQF,MAAa,iBACZ,YAMA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO;AAExB,QAAOC,KAAc;EACpB,MAAM;EACN,MAAM,QAAQ;EACd,YAAY,QAAQ,QAAQ;EAC5B,CAAC;CAEF,MAAM,SAAS,OAAO,SAAS,OAAO,QAAQ;AAE9C,QAAOA,KAAc;EACpB,MAAM;EACN,MAAM,OAAO;EACb,OAAO,OAAO;EACd,CAAC;AAEF,QAAO;EACN"}

package/dist/archive.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Turning a staged directory tree into a gzipped tarball.
+ *
+ * A service rather than a function, because packing is the one step that has
+ * to be implemented differently per platform. Everywhere else the engine
+ * reaches the disk through `effect/FileSystem`, which is what lets an in-memory
+ * filesystem carry the whole pipeline — but a tar writer is not filesystem
+ * access, it is a format, and `node-tar` reads the paths it is given with
+ * Node's own `fs` rather than through the injected service. Left as a direct
+ * call, packing would quietly bypass the abstraction the rest of the engine
+ * depends on, which stays invisible until something other than Node provides
+ * the filesystem.
+ *
+ * The implementations live outside this module — `@packall/core/node` for
+ * Node, a Web Streams writer in the browser — so nothing platform-specific is
+ * reachable from the engine's own graph.
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type { PlatformError } from "effect/PlatformError";
+import type { ArchiveError } from "./errors.js";
+import * as Progress from "./progress.js";
+/** A finished archive. */
+export type ArchiveResult = {
+    readonly path: string;
+    readonly bytes: number;
+};
+/** What to pack, and where to put it. */
+export type CreateArchiveOptions = {
+    readonly cwd: string;
+    /** Entry paths, relative to `cwd`. */
+    readonly entries: ReadonlyArray<string>;
+    readonly outPath: string;
+    readonly gzipLevel?: number | undefined;
+};
+export declare namespace Archiver {
+    /** The packing backend. */
+    type Service = {
+        /**
+         * Packs `entries` (paths relative to `cwd`) into a gzipped tar at
+         * `outPath`.
+         *
+         * Implementations must produce byte-identical output for identical inputs —
+         * normalised uid/gid/mtime, entries in a stable order — because a security
+         * team diffing two bundles, or re-deriving one from its manifest, is a
+         * thing that actually happens.
+         */
+        readonly create: (options: CreateArchiveOptions) => Effect.Effect<ArchiveResult, ArchiveError | PlatformError, FileSystem.FileSystem>;
+    };
+}
+declare const Archiver_base: Context.ServiceClass<Archiver, "@packall/core/Archiver", Archiver.Service>;
+/** Service tag for archive creation. */
+export declare class Archiver extends Archiver_base {
+}
+/**
+ * Packs an archive with whichever backend is installed.
+ *
+ * The progress events are emitted here rather than inside the backends, so
+ * every implementation reports identically and a new one cannot forget to.
+ */
+export declare const createArchive: (options: CreateArchiveOptions) => Effect.Effect<ArchiveResult, ArchiveError | PlatformError, Archiver | FileSystem.FileSystem | Progress.Progress>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IACjC,2BAA2B;IAC3B,KAAY,OAAO,GAAG;QACrB;;;;;;;;WAQG;QACH,QAAQ,CAAC,MAAM,EAAE,CAChB,OAAO,EAAE,oBAAoB,KACzB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,GAAG,aAAa,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;KACvF,CAAC;CACF;;AAED,wCAAwC;AACxC,qBAAa,QAAS,SAAQ,aAE7B;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAChB,oBAAoB,KAC3B,MAAM,CAAC,MAAM,CACf,aAAa,EACb,YAAY,GAAG,aAAa,EAC5B,QAAQ,GAAG,UAAU,CAAC,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAoBlD,CAAC"}

package/dist/{Bundle.d.ts → bundle.d.ts}

@@ -1,8 +1,9 @@
 /**
  * End-to-end orchestration: specs in, tarballs out.
  *
- * Two properties this module is responsible for, both of them fixes for how
- * the original tool behaved:
+ * Two properties this module is responsible for — see `notes/requirements.md`
+ * § FR-5 and § NFR-9 for why they are requirements, and the mechanisms below
+ * for why the code reads as it does:
  *
  * 1. **Nothing is written outside the output directory.** Every intermediate
  *    file lives in a scoped temp directory obtained from
@@ -15,28 +16,34 @@
  *    shared download tree, so `per-spec` costs extra disk in the *output*, not
  *    extra network.
  */
+import type * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
-import type { BundlerError } from "./Errors.js";
-import type { BundleOptions, Layout } from "./Options.js";
-import * as Progress from "./Progress.js";
-import { Registry } from "./Registry.js";
-import type { Resolution } from "./Resolve.js";
-import type { PackageSpec } from "./Spec.js";
+import type { Archiver } from "./archive.js";
+import { ArtifactKind } from "./enums/artifact-kind.js";
+import { Layout } from "./enums/layout.js";
+import type { BundlerError } from "./errors.js";
+import type { LockedResolveOptions } from "./locked-resolve.js";
+import type { LockedTree } from "./lockfile/types.js";
+import type { BundleOptions } from "./options.js";
+import * as Progress from "./progress.js";
+import { Registry } from "./registry.js";
+import type { Resolution } from "./resolve.js";
+import type { PackageSpec } from "./spec.js";
 /** One thing written to the output directory. */
-export interface BundleArtifact {
-    readonly kind: "archive" | "directory";
+export type BundleArtifact = {
+    readonly kind: ArtifactKind;
     readonly path: string;
     readonly bytes: number;
     readonly packageCount: number;
     /** Which spec this artifact covers. Absent for `single` and `dir`. */
     readonly spec?: string | undefined;
     readonly version?: string | undefined;
-}
+};
 /** The outcome of a bundle run. */
-export interface BundleResult {
+export type BundleResult = {
     readonly resolution: Resolution;
     readonly artifacts: ReadonlyArray<BundleArtifact>;
     /** Total bytes downloaded from the registry. */
@@ -44,17 +51,17 @@ export interface BundleResult {
     /** Packages the registry advertised no usable checksum for. */
     readonly unverified: ReadonlyArray<string>;
     readonly dryRun: boolean;
-}
+};
 /** Everything `bundle` needs beyond the user-facing options. */
-export interface BundleContext extends BundleOptions {
+export type BundleContext = BundleOptions & {
     /** Recorded in the manifest so a bundle can be traced to the tool that built it. */
     readonly toolVersion: string;
-}
+};
 /**
  * A summary of what a resolution would produce, for deciding whether the
  * chosen layout is still the right one.
  */
-export interface PlanSummary {
+export type PlanSummary = {
     /** Distinct packages in the deduplicated union. */
     readonly uniquePackages: number;
     /** How many archives `per-spec` layout would emit. */
@@ -65,12 +72,27 @@ export interface PlanSummary {
      * `uniquePackages` is exactly what `single` layout would save.
      */
     readonly perSpecEntries: number;
-}
+};
+/**
+ * The files a run will write, known before anything is downloaded.
+ *
+ * `dir` layout is the odd one: it merges a package tree into `outDir`, and
+ * package paths are `name/-/name-version.tgz` — the same package at the same
+ * version is the same bytes, so an overlap there is idempotent rather than
+ * destructive. Only the two summary files are genuinely replaced, and those are
+ * the ones worth guarding.
+ */
+export type PlannedOutput = {
+    readonly file: string;
+    /** The root this file belongs to, when one file corresponds to one spec. */
+    readonly name?: string | undefined;
+    readonly version?: string | undefined;
+};
+type BundleEnv = Registry | Progress.Progress | FileSystem.FileSystem | Path.Path | Crypto.Crypto | Archiver;
 /** Computes the plan summary for a resolution. */
 export declare const summarize: (resolution: Resolution) => PlanSummary;
 /** Replaces the layout on a set of options. */
 export declare const withLayout: <T extends BundleOptions>(options: T, layout: Layout) => T;
-type BundleEnv = Registry | Progress.Progress | FileSystem.FileSystem | Path.Path;
 /**
  * Checks the registry is reachable, then resolves every spec.
  *
@@ -80,6 +102,16 @@ type BundleEnv = Registry | Progress.Progress | FileSystem.FileSystem | Path.Pat
  * expected.
  */
 export declare const plan: (specs: ReadonlyArray<PackageSpec>, options: BundleOptions) => Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress>;
+/**
+ * The lockfile counterpart of `plan`.
+ *
+ * Same preflight, same `Resolution` out; the difference is entirely in how the
+ * package set is arrived at. Kept as a separate entry point rather than an
+ * option on `plan` because the two take genuinely different inputs — a set of
+ * specs to satisfy versus a graph to reproduce — and blurring that is how a
+ * "pinned" run quietly starts resolving ranges again.
+ */
+export declare const planLocked: (lockfile: LockedTree, options: BundleOptions & LockedResolveOptions) => Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress>;
 /**
  * Resolves, downloads and packages a set of specs.
  *
@@ -88,6 +120,8 @@ export declare const plan: (specs: ReadonlyArray<PackageSpec>, options: BundleOp
  * download over a slow VPN.
  */
 export declare const bundle: (specs: ReadonlyArray<PackageSpec>, options: BundleContext) => Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv>;
+/** `bundle`, pinned to a lockfile. */
+export declare const bundleLocked: (lockfile: LockedTree, options: BundleContext & LockedResolveOptions) => Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv>;
 /**
  * Downloads and packages an already-computed resolution.
  *
@@ -97,27 +131,11 @@ export declare const bundle: (specs: ReadonlyArray<PackageSpec>, options: Bundle
  */
 export declare const bundleResolved: (resolution: Resolution, options: BundleContext) => Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv>;
 /**
- * Creates the output directory, refusing to clobber an existing non-empty one
- * unless `--force` was passed.
+ * The files a run will write.
  *
- * Silently overwriting somebody's previous bundle is the kind of thing a tool
- * only gets forgiven for once.
- */
-/**
- * The files a run will write, known before anything is downloaded.
- *
- * `dir` layout is the odd one: it merges a package tree into `outDir`, and
- * package paths are `name/-/name-version.tgz` — the same package at the same
- * version is the same bytes, so an overlap there is idempotent rather than
- * destructive. Only the two summary files are genuinely replaced, and those are
- * the ones worth guarding.
+ * Computed before anything is downloaded, so a collision is reported in the
+ * first second rather than after a twenty-minute transfer.
  */
-export interface PlannedOutput {
-    readonly file: string;
-    /** The root this file belongs to, when one file corresponds to one spec. */
-    readonly name?: string | undefined;
-    readonly version?: string | undefined;
-}
 export declare const plannedOutputs: (resolution: Resolution, options: BundleContext) => ReadonlyArray<PlannedOutput>;
 export {};
-//# sourceMappingURL=Bundle.d.ts.map
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/{DependencyRange.d.ts → dependency-range.d.ts}

@@ -1,4 +1,4 @@
-import type { Selector } from "./Spec.js";
+import type { Selector } from "./spec.js";
 /** What a dependency edge points at. */
 export type DependencyTarget = 
 /** A normal registry dependency. `name` may differ from the key under an alias. */
@@ -23,4 +23,4 @@ export type DependencyTarget =
  * treats them interchangeably and so do we.
  */
 export declare const parseDependencyTarget: (name: string, raw: string) => DependencyTarget;
-//# sourceMappingURL=DependencyRange.d.ts.map
+//# sourceMappingURL=dependency-range.d.ts.map