@packall/core 0.1.0 → 0.2.0

package/src/bundle.ts

@@ -1,616 +1,736 @@
-/**
- * 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:
- *
- * 1. **Nothing is written outside the output directory.** Every intermediate
- *    file lives in a scoped temp directory obtained from
- *    `makeTempDirectoryScoped`, so the scope closing — on success, on failure,
- *    or on Ctrl-C — takes the whole staging tree with it. The working
- *    directory is never touched.
- *
- * 2. **Each package is downloaded exactly once**, no matter how many bundles
- *    it ends up in. Per-spec archives are assembled by hard-linking out of one
- *    shared download tree, so `per-spec` costs extra disk in the *output*, not
- *    extra network.
- */
-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 { Scope } from "effect/Scope"
-import { createArchive } from "./archive.js"
-import { downloadAll } from "./download.js"
-import { ArtifactKind } from "./enums/artifact-kind.js"
-import { Layout } from "./enums/layout.js"
-import { Phase } from "./enums/phase.js"
-import type { BundlerError } from "./errors.js"
-import { OutputError } from "./errors.js"
-import {
-  importGuide,
-  MANIFEST_FILE,
-  packagePath,
-  perSpecArchiveName,
-  README_FILE,
-  singleArchiveName
-} from "./layout.js"
-import type { LockedResolveOptions } from "./locked-resolve.js"
-import { resolveLocked } from "./locked-resolve.js"
-import type { LockedTree } from "./lockfile/types.js"
-import { buildManifest, serializeManifest } from "./manifest.js"
-import type { BundleOptions } from "./options.js"
-import * as Progress from "./progress.js"
-import { Registry } from "./registry.js"
-import type { PackageKey, Resolution, ResolvedPackage } from "./resolve.js"
-import { indexPackages, resolve } from "./resolve.js"
-import type { PackageSpec } from "./spec.js"
-import { formatSpec } from "./spec.js"
-
-/** One thing written to the output 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 type BundleResult = {
-  readonly resolution: Resolution
-  readonly artifacts: ReadonlyArray<BundleArtifact>
-  /** Total bytes downloaded from the registry. */
-  readonly downloadedBytes: number
-  /** Packages the registry advertised no usable checksum for. */
-  readonly unverified: ReadonlyArray<string>
-  readonly dryRun: boolean
-}
-
-/** Everything `bundle` needs beyond the user-facing options. */
-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 type PlanSummary = {
-  /** Distinct packages in the deduplicated union. */
-  readonly uniquePackages: number
-  /** How many archives `per-spec` layout would emit. */
-  readonly perSpecArchives: number
-  /**
-   * Total package entries across all per-spec archives, counting shared
-   * dependencies once per archive they appear in. The gap between this and
-   * `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
-
-type EmitInput = {
-  readonly resolution: Resolution
-  readonly options: BundleContext
-  readonly packagesDir: string
-  readonly report: { readonly sizes: ReadonlyMap<string, number> }
-  readonly registryInfo: { readonly kind: string; readonly url: string }
-}
-
-/** Computes the plan summary for a resolution. */
-export const summarize = (resolution: Resolution): PlanSummary => {
-  let perSpecArchives = 0
-  let perSpecEntries = 0
-  for (const root of resolution.roots) {
-    for (const version of root.versions) {
-      perSpecArchives += 1
-      perSpecEntries += (root.closures.get(version) ?? []).length
-    }
-  }
-  return {
-    uniquePackages: resolution.packages.length,
-    perSpecArchives,
-    perSpecEntries
-  }
-}
-
-/** Replaces the layout on a set of options. */
-export const withLayout = <T extends BundleOptions>(options: T, layout: Layout): T => ({
-  ...options,
-  layout
-})
-
-/**
- * Checks the registry is reachable, then resolves every spec.
- *
- * Split out from `bundle` so a caller can inspect the plan — how many packages,
- * how many archives — and act on it before any bytes move. The CLI uses this to
- * offer a different layout when a run turns out to be much larger than
- * expected.
- */
-export const plan = (
-  specs: ReadonlyArray<PackageSpec>,
-  options: BundleOptions
-): Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress> =>
-  Effect.gen(function*() {
-    yield* preflight
-    return yield* resolve(specs, options)
-  })
-
-/**
- * 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 const planLocked = (
-  lockfile: LockedTree,
-  options: BundleOptions & LockedResolveOptions
-): Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress> =>
-  Effect.gen(function*() {
-    yield* preflight
-    return yield* resolveLocked(lockfile, options)
-  })
-
-const preflight: Effect.Effect<void, BundlerError, Registry | Progress.Progress> = Effect.gen(
-  function*() {
-    const registry = yield* Registry
-    yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Preflight })
-    yield* registry.preflight
-    yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Preflight })
-  }
-)
-
-/**
- * Resolves, downloads and packages a set of specs.
- *
- * Under `dryRun` this stops after resolution and reports the plan — useful for
- * checking what a command *would* pull before committing to a multi-gigabyte
- * download over a slow VPN.
- */
-export const bundle = (
-  specs: ReadonlyArray<PackageSpec>,
-  options: BundleContext
-): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
-  Effect.gen(function*() {
-    const resolution = yield* plan(specs, options)
-    return yield* bundleResolved(resolution, options)
-  })
-
-/** `bundle`, pinned to a lockfile. */
-export const bundleLocked = (
-  lockfile: LockedTree,
-  options: BundleContext & LockedResolveOptions
-): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
-  Effect.gen(function*() {
-    const resolution = yield* planLocked(lockfile, options)
-    return yield* bundleResolved(resolution, options)
-  })
-
-/**
- * Downloads and packages an already-computed resolution.
- *
- * Everything from here on touches the disk, and all of it happens inside
- * `Effect.scoped` — so the staging tree's lifetime is exactly this call,
- * including when it fails partway through or the user hits Ctrl-C.
- */
-export const bundleResolved = (
-  resolution: Resolution,
-  options: BundleContext
-): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
-  Effect.gen(function*() {
-    if (options.dryRun) {
-      return {
-        resolution,
-        artifacts: [],
-        downloadedBytes: 0,
-        unverified: [],
-        dryRun: true
-      }
-    }
-    return yield* Effect.scoped(runBundle(resolution, options))
-  })
-
-/**
- * The files a run will write.
- *
- * Computed before anything is downloaded, so a collision is reported in the
- * first second rather than after a twenty-minute transfer.
- */
-export const plannedOutputs = (
-  resolution: Resolution,
-  options: BundleContext
-): ReadonlyArray<PlannedOutput> => {
-  if (options.layout === Layout.Dir) return [{ file: MANIFEST_FILE }, { file: README_FILE }]
-  if (options.layout === Layout.Single) {
-    return [{ file: singleArchiveName(options.archiveName ?? "bundle") }]
-  }
-  return resolution.roots.flatMap((root) =>
-    root.versions.map((version) => ({
-      file: perSpecArchiveName(root.spec.name, version),
-      name: root.spec.name,
-      version
-    }))
-  )
-}
-
-const runBundle = (
-  resolution: Resolution,
-  options: BundleContext
-): Effect.Effect<
-  BundleResult,
-  BundlerError | PlatformError,
-  BundleEnv | Scope
-> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const path = yield* Path.Path
-    const registry = yield* Registry
-
-    yield* prepareOutputDir(resolution, options)
-
-    const staging = yield* fs.makeTempDirectoryScoped({ prefix: "packall-" })
-    const packagesDir = path.join(staging, "packages")
-    yield* fs.makeDirectory(packagesDir, { recursive: true })
-
-    const report = yield* downloadAll(resolution.packages, packagesDir, {
-      concurrency: options.concurrency,
-      verifyIntegrity: options.verifyIntegrity
-    })
-
-    yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Archive })
-
-    const input: EmitInput = {
-      resolution,
-      options,
-      packagesDir,
-      report,
-      registryInfo: {
-        kind: registry.kind,
-        url: registry.registryFor(resolution.roots[0]?.spec.name ?? "")
-      }
-    }
-
-    const artifacts = yield* emit(input, staging)
-
-    yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Archive })
-    yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Done })
-
-    return {
-      resolution,
-      artifacts,
-      downloadedBytes: report.totalBytes,
-      unverified: report.unverified,
-      dryRun: false
-    }
-  })
-
-/* -------------------------------------------------------------------------- */
-/* Emitters                                                                   */
-/* -------------------------------------------------------------------------- */
-
-const emit = (
-  input: EmitInput,
-  staging: string
-): Effect.Effect<
-  ReadonlyArray<BundleArtifact>,
-  BundlerError | PlatformError,
-  FileSystem.FileSystem | Path.Path | Progress.Progress
-> => {
-  switch (input.options.layout) {
-    case Layout.Single:
-      return emitSingle(input)
-    case Layout.Dir:
-      return emitDirectory(input)
-    case Layout.PerSpec:
-      return emitPerSpec(input, staging)
-  }
-}
-
-/** One tarball containing the deduplicated union of every closure. */
-const emitSingle = (
-  input: EmitInput
-): Effect.Effect<
-  ReadonlyArray<BundleArtifact>,
-  BundlerError | PlatformError,
-  FileSystem.FileSystem | Path.Path | Progress.Progress
-> =>
-  Effect.gen(function*() {
-    const path = yield* Path.Path
-
-    const archiveName = singleArchiveName(input.options.archiveName ?? "bundle")
-    // Declined at the prompt, and it is the run's only output.
-    if (input.options.skipExisting?.has(archiveName) === true) return []
-
-    yield* writeBundleMetadata({
-      dir: input.packagesDir,
-      resolution: input.resolution,
-      included: input.resolution.packages,
-      options: input.options,
-      registryInfo: input.registryInfo,
-      sizes: input.report.sizes
-    })
-
-    const outPath = path.join(input.options.outDir, archiveName)
-
-    const result = yield* createArchive({
-      cwd: input.packagesDir,
-      entries: yield* topLevelEntries(input.packagesDir),
-      outPath
-    })
-
-    return [
-      {
-        kind: ArtifactKind.Archive,
-        path: result.path,
-        bytes: result.bytes,
-        packageCount: input.resolution.packages.length
-      }
-    ]
-  })
-
-/** The raw npm-layout tree, no archive. */
-const emitDirectory = (
-  input: EmitInput
-): Effect.Effect<
-  ReadonlyArray<BundleArtifact>,
-  BundlerError | PlatformError,
-  FileSystem.FileSystem | Path.Path
-> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-
-    yield* writeBundleMetadata({
-      dir: input.packagesDir,
-      resolution: input.resolution,
-      included: input.resolution.packages,
-      options: input.options,
-      registryInfo: input.registryInfo,
-      sizes: input.report.sizes
-    })
-
-    // The staging tree is about to be deleted with its scope, so this is a
-    // real copy rather than a move — `copy` also works across devices, which
-    // matters because the temp dir often lives on a different filesystem.
-    yield* fs.copy(input.packagesDir, input.options.outDir, { overwrite: true }).pipe(
-      Effect.mapError(
-        (cause) => new OutputError(input.options.outDir, "could not write output tree", { cause })
-      )
-    )
-
-    const bytes = [...input.report.sizes.values()].reduce((a, b) => a + b, 0)
-
-    return [
-      {
-        kind: ArtifactKind.Directory,
-        path: input.options.outDir,
-        bytes,
-        packageCount: input.resolution.packages.length
-      }
-    ]
-  })
-
-/**
- * One tarball per resolved root *version*.
- *
- * Under `--all-versions react@^18` this produces `react-18.0.0.tgz`,
- * `react-18.1.0.tgz` and so on, each independently importable — which is the
- * whole reason to prefer this layout.
- */
-const emitPerSpec = (
-  input: EmitInput,
-  staging: string
-): Effect.Effect<
-  ReadonlyArray<BundleArtifact>,
-  BundlerError | PlatformError,
-  FileSystem.FileSystem | Path.Path | Progress.Progress
-> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const path = yield* Path.Path
-    const index = indexPackages(input.resolution)
-    const artifacts: Array<BundleArtifact> = []
-
-    let counter = 0
-    for (const root of input.resolution.roots) {
-      for (const version of root.versions) {
-        // Declined at the prompt: the existing file stays, and this archive is
-        // simply never built. Skipping the staging work too, not just the write.
-        if (input.options.skipExisting?.has(perSpecArchiveName(root.spec.name, version)) === true) {
-          continue
-        }
-
-        const included = includedPackages(index, root.closures.get(version) ?? [])
-
-        const rootDir = path.join(staging, "roots", String(counter++))
-        yield* fs.makeDirectory(rootDir, { recursive: true })
-
-        for (const pkg of included) {
-          const parts = packagePath(pkg.name, pkg.version).split("/")
-          const source = path.join(input.packagesDir, ...parts)
-          const target = path.join(rootDir, ...parts)
-          yield* fs.makeDirectory(path.dirname(target), { recursive: true })
-          yield* linkOrCopy(source, target)
-        }
-
-        yield* writeBundleMetadata({
-          dir: rootDir,
-          resolution: {
-            ...input.resolution,
-            roots: [{ ...root, versions: [version] }]
-          },
-          included,
-          options: input.options,
-          registryInfo: input.registryInfo,
-          sizes: input.report.sizes
-        })
-
-        const outPath = path.join(
-          input.options.outDir,
-          perSpecArchiveName(root.spec.name, version)
-        )
-
-        const result = yield* createArchive({
-          cwd: rootDir,
-          entries: yield* topLevelEntries(rootDir),
-          outPath
-        })
-
-        artifacts.push({
-          kind: ArtifactKind.Archive,
-          path: result.path,
-          bytes: result.bytes,
-          packageCount: included.length,
-          spec: formatSpec(root.spec),
-          version
-        })
-      }
-    }
-
-    return artifacts
-  })
-
-/* -------------------------------------------------------------------------- */
-/* Helpers                                                                    */
-/* -------------------------------------------------------------------------- */
-
-const includedPackages = (
-  index: ReadonlyMap<PackageKey, ResolvedPackage>,
-  closure: ReadonlyArray<PackageKey>
-): ReadonlyArray<ResolvedPackage> => closure.flatMap((key) => index.get(key) ?? [])
-
-/**
- * Hard-links a file, falling back to a copy.
- *
- * Hard links make `per-spec` layout nearly free in the staging tree. They fail
- * across devices and on some Windows configurations, so the copy fallback is
- * not optional.
- */
-const linkOrCopy = (
-  source: string,
-  target: string
-): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    yield* fs.link(source, target).pipe(
-      Effect.catch(() => fs.copyFile(source, target))
-    )
-  })
-
-/** Writes the manifest and import guide into a staging directory. */
-const writeBundleMetadata = (input: {
-  readonly dir: string
-  readonly resolution: Resolution
-  readonly included: ReadonlyArray<ResolvedPackage>
-  readonly options: BundleContext
-  readonly registryInfo: { readonly kind: string; readonly url: string }
-  readonly sizes: ReadonlyMap<string, number>
-}): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const path = yield* Path.Path
-
-    const createdAt = new Date()
-    const manifest = buildManifest({
-      resolution: input.resolution,
-      included: input.included,
-      options: input.options,
-      registry: input.registryInfo,
-      toolVersion: input.options.toolVersion,
-      sizes: input.sizes,
-      createdAt
-    })
-
-    yield* fs.writeFileString(path.join(input.dir, MANIFEST_FILE), serializeManifest(manifest))
-    yield* fs.writeFileString(
-      path.join(input.dir, README_FILE),
-      importGuide({
-        packageCount: input.included.length,
-        createdAt: createdAt.toISOString(),
-        toolVersion: input.options.toolVersion
-      })
-    )
-  })
-
-/** Sorted top-level entries of a directory, used as the tar entry list. */
-const topLevelEntries = (
-  dir: string
-): Effect.Effect<ReadonlyArray<string>, PlatformError, FileSystem.FileSystem> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const entries = yield* fs.readDirectory(dir)
-    return entries.toSorted()
-  })
-
-/**
- * Fails if the run would overwrite something, unless `--force`.
- *
- * The guard is on the *files this run writes*, not on whether the directory has
- * anything in it. An output directory accumulating bundles is the normal way to
- * use this — bundling `esbuild` into an `out/` that already holds `tsdown` is
- * not a conflict, and refusing it made `--out` a single-use directory and the
- * default `.` unusable.
- *
- * Checked before anything is downloaded. Discovering the collision *after* a
- * twenty-minute download would be a uniquely irritating way to fail.
- */
-const prepareOutputDir = (
-  resolution: Resolution,
-  options: BundleContext
-): Effect.Effect<void, OutputError | PlatformError, FileSystem.FileSystem | Path.Path> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-    const path = yield* Path.Path
-    const outDir = options.outDir
-
-    if (!options.force) {
-      const clashes: Array<string> = []
-      for (const planned of plannedOutputs(resolution, options)) {
-        if (options.skipExisting?.has(planned.file) === true) continue
-        if (options.overwrite?.has(planned.file) === true) continue
-        const exists = yield* fs
-          .exists(path.join(outDir, planned.file))
-          .pipe(Effect.orElseSucceed(() => false))
-        if (exists) clashes.push(planned.file)
-      }
-
-      if (clashes.length > 0) {
-        return yield* Effect.fail(
-          new OutputError(
-            outDir,
-            `would overwrite ${clashes.length} existing file${clashes.length === 1 ? "" : "s"} ` +
-              `(${clashes.slice(0, 3).join(", ")}${clashes.length > 3 ? ", …" : ""}). ` +
-              `Pass --force true to replace ${clashes.length === 1 ? "it" : "them"}, or choose a different --out.`
-          )
-        )
-      }
-    }
-
-    yield* fs.makeDirectory(outDir, { recursive: true }).pipe(
-      Effect.mapError((cause) => new OutputError(outDir, "could not create output directory", { cause }))
-    )
-  })
+/**
+ * End-to-end orchestration: specs in, tarballs out.
+ *
+ * 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
+ *    `makeTempDirectoryScoped`, so the scope closing — on success, on failure,
+ *    or on Ctrl-C — takes the whole staging tree with it. The working
+ *    directory is never touched.
+ *
+ * 2. **Each package is downloaded exactly once**, no matter how many bundles
+ *    it ends up in. Per-spec archives are assembled by hard-linking out of one
+ *    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 { Scope } from "effect/Scope";
+
+import type { Archiver } from "./archive.js";
+import { createArchive } from "./archive.js";
+import { downloadAll } from "./download.js";
+import { ArtifactKind } from "./enums/artifact-kind.js";
+import { Layout } from "./enums/layout.js";
+import { Phase } from "./enums/phase.js";
+import type { BundlerError } from "./errors.js";
+import { OutputError } from "./errors.js";
+import {
+	importGuide,
+	MANIFEST_FILE,
+	packagePath,
+	perSpecArchiveName,
+	README_FILE,
+	singleArchiveName,
+} from "./layout.js";
+import type { LockedResolveOptions } from "./locked-resolve.js";
+import { resolveLocked } from "./locked-resolve.js";
+import type { LockedTree } from "./lockfile/types.js";
+import { buildManifest, serializeManifest } from "./manifest.js";
+import type { BundleOptions } from "./options.js";
+import * as Progress from "./progress.js";
+import { Registry } from "./registry.js";
+import type { PackageKey, Resolution, ResolvedPackage, RootResolution } from "./resolve.js";
+import { indexPackages, resolve } from "./resolve.js";
+import type { PackageSpec } from "./spec.js";
+import { formatSpec } from "./spec.js";
+
+/** One thing written to the output 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 type BundleResult = {
+	readonly resolution: Resolution;
+	readonly artifacts: ReadonlyArray<BundleArtifact>;
+	/** Total bytes downloaded from the registry. */
+	readonly downloadedBytes: number;
+	/** Packages the registry advertised no usable checksum for. */
+	readonly unverified: ReadonlyArray<string>;
+	readonly dryRun: boolean;
+};
+
+/** Everything `bundle` needs beyond the user-facing options. */
+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 type PlanSummary = {
+	/** Distinct packages in the deduplicated union. */
+	readonly uniquePackages: number;
+	/** How many archives `per-spec` layout would emit. */
+	readonly perSpecArchives: number;
+	/**
+	 * Total package entries across all per-spec archives, counting shared
+	 * dependencies once per archive they appear in. The gap between this and
+	 * `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;
+
+type EmitInput = {
+	readonly resolution: Resolution;
+	readonly options: BundleContext;
+	readonly packagesDir: string;
+	readonly report: { readonly sizes: ReadonlyMap<string, number> };
+	readonly registryInfo: { readonly kind: string; readonly url: string };
+};
+
+/** One archive `per-spec` layout will write: a root, at one of its versions. */
+type PerSpecTarget = {
+	readonly root: RootResolution;
+	readonly version: string;
+};
+
+/**
+ * The archives `per-spec` emits — one per distinct root package version.
+ *
+ * Roots are *specs*, and several specs can name one package: `react`,
+ * `react@latest` and `react@19.2.8` are three ways of asking for the same
+ * thing, and after resolution they are indistinguishable. Without this they
+ * were three archives — the same bytes, under the same file name, written over
+ * each other. The run then reported three artifacts and three times the size
+ * for one file on disk, and the duplication ratio it computes to decide whether
+ * to ask about the layout counted them too, so the tool would offer to
+ * deduplicate a bundle it had duplicated itself.
+ *
+ * Keyed by name and version rather than by the archive's file name. A scoped
+ * name is flattened to make a file name, so `@foo/bar` and `foo-bar` can spell
+ * the same one — and those are two different packages, which should collide
+ * loudly rather than being merged here.
+ *
+ * Roots only. The packages *inside* an archive were deduplicated by resolution
+ * long before this, which is why the same closure fetched from twenty specs is
+ * fetched once.
+ */
+const perSpecTargets = (resolution: Resolution): ReadonlyArray<PerSpecTarget> => {
+	const seen = new Set<string>();
+
+	return resolution.roots.flatMap((root) =>
+		root.versions.flatMap((version) => {
+			const key = `${root.spec.name}@${version}`;
+			if (seen.has(key)) return [];
+
+			seen.add(key);
+			return { root, version };
+		}),
+	);
+};
+
+/** Computes the plan summary for a resolution. */
+export const summarize = (resolution: Resolution): PlanSummary => {
+	let perSpecArchives = 0;
+	let perSpecEntries = 0;
+	for (const { root, version } of perSpecTargets(resolution)) {
+		perSpecArchives += 1;
+		perSpecEntries += (root.closures.get(version) ?? []).length;
+	}
+	return {
+		uniquePackages: resolution.packages.length,
+		perSpecArchives,
+		perSpecEntries,
+	};
+};
+
+/** Replaces the layout on a set of options. */
+export const withLayout = <T extends BundleOptions>(options: T, layout: Layout): T => ({
+	...options,
+	layout,
+});
+
+/**
+ * Checks the registry is reachable, then resolves every spec.
+ *
+ * Split out from `bundle` so a caller can inspect the plan — how many packages,
+ * how many archives — and act on it before any bytes move. The CLI uses this to
+ * offer a different layout when a run turns out to be much larger than
+ * expected.
+ */
+export const plan = (
+	specs: ReadonlyArray<PackageSpec>,
+	options: BundleOptions,
+): Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress> =>
+	Effect.gen(function* () {
+		yield* preflight;
+		return yield* resolve(specs, options);
+	});
+
+/**
+ * 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 const planLocked = (
+	lockfile: LockedTree,
+	options: BundleOptions & LockedResolveOptions,
+): Effect.Effect<Resolution, BundlerError, Registry | Progress.Progress> =>
+	Effect.gen(function* () {
+		yield* preflight;
+		return yield* resolveLocked(lockfile, options);
+	});
+
+const preflight: Effect.Effect<void, BundlerError, Registry | Progress.Progress> = Effect.gen(
+	function* () {
+		const registry = yield* Registry;
+		yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Preflight });
+		yield* registry.preflight;
+		yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Preflight });
+	},
+);
+
+/**
+ * Resolves, downloads and packages a set of specs.
+ *
+ * Under `dryRun` this stops after resolution and reports the plan — useful for
+ * checking what a command *would* pull before committing to a multi-gigabyte
+ * download over a slow VPN.
+ */
+export const bundle = (
+	specs: ReadonlyArray<PackageSpec>,
+	options: BundleContext,
+): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
+	Effect.gen(function* () {
+		const resolution = yield* plan(specs, options);
+		return yield* bundleResolved(resolution, options);
+	});
+
+/** `bundle`, pinned to a lockfile. */
+export const bundleLocked = (
+	lockfile: LockedTree,
+	options: BundleContext & LockedResolveOptions,
+): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
+	Effect.gen(function* () {
+		const resolution = yield* planLocked(lockfile, options);
+		return yield* bundleResolved(resolution, options);
+	});
+
+/**
+ * Downloads and packages an already-computed resolution.
+ *
+ * Everything from here on touches the disk, and all of it happens inside
+ * `Effect.scoped` — so the staging tree's lifetime is exactly this call,
+ * including when it fails partway through or the user hits Ctrl-C.
+ */
+export const bundleResolved = (
+	resolution: Resolution,
+	options: BundleContext,
+): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv> =>
+	Effect.gen(function* () {
+		if (options.dryRun) {
+			return {
+				resolution,
+				artifacts: [],
+				downloadedBytes: 0,
+				unverified: [],
+				dryRun: true,
+			};
+		}
+		return yield* Effect.scoped(runBundle(resolution, options));
+	});
+
+/**
+ * The files a run will write.
+ *
+ * Computed before anything is downloaded, so a collision is reported in the
+ * first second rather than after a twenty-minute transfer.
+ */
+export const plannedOutputs = (
+	resolution: Resolution,
+	options: BundleContext,
+): ReadonlyArray<PlannedOutput> => {
+	if (options.layout === Layout.Dir) return [{ file: MANIFEST_FILE }, { file: README_FILE }];
+	if (options.layout === Layout.Single) {
+		return [{ file: singleArchiveName(options.archiveName ?? "bundle") }];
+	}
+	return perSpecTargets(resolution).map(({ root, version }) => ({
+		file: perSpecArchiveName(root.spec.name, version),
+		name: root.spec.name,
+		version,
+	}));
+};
+
+const runBundle = (
+	resolution: Resolution,
+	options: BundleContext,
+): Effect.Effect<BundleResult, BundlerError | PlatformError, BundleEnv | Scope> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const registry = yield* Registry;
+
+		yield* prepareOutputDir(resolution, options);
+
+		const staging = yield* fs.makeTempDirectoryScoped({ prefix: "packall-" });
+		const packagesDir = path.join(staging, "packages");
+		yield* fs.makeDirectory(packagesDir, { recursive: true });
+
+		const report = yield* downloadAll(resolution.packages, packagesDir, {
+			concurrency: options.concurrency,
+			verifyIntegrity: options.verifyIntegrity,
+		});
+
+		yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Archive });
+
+		const input: EmitInput = {
+			resolution,
+			options,
+			packagesDir,
+			report,
+			registryInfo: {
+				kind: registry.kind,
+				url: registry.registryFor(resolution.roots[0]?.spec.name ?? ""),
+			},
+		};
+
+		const artifacts = yield* emit(input, staging);
+
+		yield* Progress.emit({ _tag: "PhaseCompleted", phase: Phase.Archive });
+		yield* Progress.emit({ _tag: "PhaseStarted", phase: Phase.Done });
+
+		return {
+			resolution,
+			artifacts,
+			downloadedBytes: report.totalBytes,
+			unverified: report.unverified,
+			dryRun: false,
+		};
+	});
+
+/* -------------------------------------------------------------------------- */
+/* Emitters                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const emit = (
+	input: EmitInput,
+	staging: string,
+): Effect.Effect<
+	ReadonlyArray<BundleArtifact>,
+	BundlerError | PlatformError,
+	FileSystem.FileSystem | Path.Path | Progress.Progress | Archiver
+> => {
+	switch (input.options.layout) {
+		case Layout.Single:
+			return emitSingle(input);
+		case Layout.Dir:
+			return emitDirectory(input);
+		case Layout.PerSpec:
+			return emitPerSpec(input, staging);
+	}
+};
+
+/** One tarball containing the deduplicated union of every closure. */
+const emitSingle = (
+	input: EmitInput,
+): Effect.Effect<
+	ReadonlyArray<BundleArtifact>,
+	BundlerError | PlatformError,
+	FileSystem.FileSystem | Path.Path | Progress.Progress | Archiver
+> =>
+	Effect.gen(function* () {
+		const path = yield* Path.Path;
+
+		const archiveName = singleArchiveName(input.options.archiveName ?? "bundle");
+		// Declined at the prompt, and it is the run's only output.
+		if (input.options.skipExisting?.has(archiveName) === true) return [];
+
+		yield* writeBundleMetadata({
+			dir: input.packagesDir,
+			resolution: input.resolution,
+			included: input.resolution.packages,
+			options: input.options,
+			registryInfo: input.registryInfo,
+			sizes: input.report.sizes,
+		});
+
+		const outPath = path.join(input.options.outDir, archiveName);
+
+		const result = yield* createArchive({
+			cwd: input.packagesDir,
+			entries: yield* topLevelEntries(input.packagesDir),
+			outPath,
+		});
+
+		return [
+			{
+				kind: ArtifactKind.Archive,
+				path: result.path,
+				bytes: result.bytes,
+				packageCount: input.resolution.packages.length,
+			},
+		];
+	});
+
+/** The raw npm-layout tree, no archive. */
+const emitDirectory = (
+	input: EmitInput,
+): Effect.Effect<
+	ReadonlyArray<BundleArtifact>,
+	BundlerError | PlatformError,
+	FileSystem.FileSystem | Path.Path
+> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+
+		yield* writeBundleMetadata({
+			dir: input.packagesDir,
+			resolution: input.resolution,
+			included: input.resolution.packages,
+			options: input.options,
+			registryInfo: input.registryInfo,
+			sizes: input.report.sizes,
+		});
+
+		// The staging tree is about to be deleted with its scope, so this is a
+		// real copy rather than a move — `copy` also works across devices, which
+		// matters because the temp dir often lives on a different filesystem.
+		yield* fs.copy(input.packagesDir, input.options.outDir, { overwrite: true }).pipe(
+			Effect.mapError(
+				(cause) =>
+					new OutputError(input.options.outDir, "could not write output tree", {
+						cause,
+					}),
+			),
+		);
+
+		const bytes = [...input.report.sizes.values()].reduce((a, b) => a + b, 0);
+
+		return [
+			{
+				kind: ArtifactKind.Directory,
+				path: input.options.outDir,
+				bytes,
+				packageCount: input.resolution.packages.length,
+			},
+		];
+	});
+
+/**
+ * One tarball per resolved root *version*.
+ *
+ * Under `--all-versions react@^18` this produces `react-18.0.0.tgz`,
+ * `react-18.1.0.tgz` and so on, each independently importable — which is the
+ * whole reason to prefer this layout.
+ */
+const emitPerSpec = (
+	input: EmitInput,
+	staging: string,
+): Effect.Effect<
+	ReadonlyArray<BundleArtifact>,
+	BundlerError | PlatformError,
+	FileSystem.FileSystem | Path.Path | Progress.Progress | Archiver
+> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const index = indexPackages(input.resolution);
+		const artifacts: Array<BundleArtifact> = [];
+
+		let counter = 0;
+		for (const { root, version } of perSpecTargets(input.resolution)) {
+			// Declined at the prompt: the existing file stays, and this archive is
+			// simply never built. Skipping the staging work too, not just the write.
+			if (
+				input.options.skipExisting?.has(perSpecArchiveName(root.spec.name, version)) ===
+				true
+			) {
+				continue;
+			}
+
+			const included = includedPackages(index, root.closures.get(version) ?? []);
+
+			const rootDir = path.join(staging, "roots", String(counter++));
+			yield* fs.makeDirectory(rootDir, { recursive: true });
+
+			for (const pkg of included) {
+				const parts = packagePath(pkg.name, pkg.version).split("/");
+				const source = path.join(input.packagesDir, ...parts);
+				const target = path.join(rootDir, ...parts);
+				yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+				yield* linkOrCopy(source, target);
+			}
+
+			yield* writeBundleMetadata({
+				dir: rootDir,
+				resolution: {
+					...input.resolution,
+					roots: [{ ...root, versions: [version] }],
+				},
+				included,
+				options: input.options,
+				registryInfo: input.registryInfo,
+				sizes: input.report.sizes,
+			});
+
+			const outPath = path.join(
+				input.options.outDir,
+				perSpecArchiveName(root.spec.name, version),
+			);
+
+			const result = yield* createArchive({
+				cwd: rootDir,
+				entries: yield* topLevelEntries(rootDir),
+				outPath,
+			});
+
+			artifacts.push({
+				kind: ArtifactKind.Archive,
+				path: result.path,
+				bytes: result.bytes,
+				packageCount: included.length,
+				spec: formatSpec(root.spec),
+				version,
+			});
+		}
+
+		return artifacts;
+	});
+
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                    */
+/* -------------------------------------------------------------------------- */
+
+const includedPackages = (
+	index: ReadonlyMap<PackageKey, ResolvedPackage>,
+	closure: ReadonlyArray<PackageKey>,
+): ReadonlyArray<ResolvedPackage> => closure.flatMap((key) => index.get(key) ?? []);
+
+/**
+ * Hard-links a file, falling back to a copy.
+ *
+ * Hard links make `per-spec` layout nearly free in the staging tree. They fail
+ * across devices and on some Windows configurations, so the copy fallback is
+ * not optional.
+ */
+const linkOrCopy = (
+	source: string,
+	target: string,
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		yield* fs.link(source, target).pipe(Effect.catch(() => fs.copyFile(source, target)));
+	});
+
+/** Writes the manifest and import guide into a staging directory. */
+const writeBundleMetadata = (input: {
+	readonly dir: string;
+	readonly resolution: Resolution;
+	readonly included: ReadonlyArray<ResolvedPackage>;
+	readonly options: BundleContext;
+	readonly registryInfo: { readonly kind: string; readonly url: string };
+	readonly sizes: ReadonlyMap<string, number>;
+}): Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+
+		const createdAt = new Date();
+		const manifest = buildManifest({
+			resolution: input.resolution,
+			included: input.included,
+			options: input.options,
+			registry: input.registryInfo,
+			toolVersion: input.options.toolVersion,
+			sizes: input.sizes,
+			createdAt,
+		});
+
+		yield* fs.writeFileString(path.join(input.dir, MANIFEST_FILE), serializeManifest(manifest));
+		yield* fs.writeFileString(
+			path.join(input.dir, README_FILE),
+			importGuide({
+				packageCount: input.included.length,
+				createdAt: createdAt.toISOString(),
+				toolVersion: input.options.toolVersion,
+			}),
+		);
+	});
+
+/** Sorted top-level entries of a directory, used as the tar entry list. */
+const topLevelEntries = (
+	dir: string,
+): Effect.Effect<ReadonlyArray<string>, PlatformError, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const entries = yield* fs.readDirectory(dir);
+		return entries.toSorted();
+	});
+
+/**
+ * Two different packages must not want the same file name.
+ *
+ * Most of what this used to catch is now impossible: an archive is named for
+ * the spec, `@types-react@19.2.18.tgz`, and an unscoped npm name may not begin
+ * with `@`, so it cannot spell a scoped one. What survives is **two scoped
+ * packages whose scope boundary falls in a different place**, because that
+ * boundary is the one character the file name drops:
+ *
+ *     @a/b-c  ->  @a-b-c@1.0.0.tgz
+ *     @a-b/c  ->  @a-b-c@1.0.0.tgz
+ *
+ * Pathological rather than plausible — it needs somebody to hold the `@a-b`
+ * scope as well as `@a`, and both packages in one run at one version. It is
+ * kept anyway because of what it costs to be wrong: they are *different
+ * packages*, so deduplicating them would be wrong, and writing both is worse —
+ * the second lands on the first and the run reports two artifacts for the one
+ * file that survived. A bundle short a package, called complete, found at the
+ * far end of an air gap by somebody who cannot go and fetch the missing one.
+ *
+ * Nothing else would catch it. The overwrite check below compares this run's
+ * planned files against what is *already on disk*, and both of these are new.
+ *
+ * So it refuses, and names both specs. Not silently renamed: an archive whose
+ * name nobody chose is a file somebody has to identify later.
+ *
+ * Unconditional, unlike the overwrite check: `--force` is permission to replace
+ * what was already in the directory, not to let one run overwrite itself.
+ */
+const assertDistinctOutputs = (
+	resolution: Resolution,
+	options: BundleContext,
+): Effect.Effect<void, OutputError> =>
+	Effect.gen(function* () {
+		const owners = new Map<string, Array<string>>();
+
+		// Over `plannedOutputs` rather than the per-spec targets, so this asks
+		// about the layout that is actually running. `single` writes one archive
+		// and `dir` two summary files, neither of which can collide — and a check
+		// that refused those would make its own advice impossible to take.
+		for (const planned of plannedOutputs(resolution, options)) {
+			const claimed = owners.get(planned.file);
+			const spec =
+				planned.name === undefined ? planned.file : `${planned.name}@${planned.version}`;
+
+			if (claimed === undefined) owners.set(planned.file, [spec]);
+			else claimed.push(spec);
+		}
+
+		const collisions = [...owners].filter(([, specs]) => specs.length > 1);
+		if (collisions.length === 0) return;
+
+		const described = collisions
+			.map(([file, specs]) => `${specs.join(" and ")} would both be ${file}`)
+			.join("; ");
+
+		return yield* Effect.fail(
+			new OutputError(
+				options.outDir,
+				`two packages want the same archive name — ${described}. The \`/\` in a ` +
+					`scope becomes a \`-\` to make a file name, so \`@a/b-c\` and \`@a-b/c\` ` +
+					`meet. Use --layout single, or bundle them into separate --out ` +
+					`directories.`,
+			),
+		);
+	});
+
+/**
+ * Fails if the run would overwrite something, unless `--force`.
+ *
+ * The guard is on the *files this run writes*, not on whether the directory has
+ * anything in it. An output directory accumulating bundles is the normal way to
+ * use this — bundling `esbuild` into an `out/` that already holds `tsdown` is
+ * not a conflict, and refusing it made `--out` a single-use directory and the
+ * default `.` unusable.
+ *
+ * Checked before anything is downloaded. Discovering the collision *after* a
+ * twenty-minute download would be a uniquely irritating way to fail — which is
+ * also why `assertDistinctOutputs` runs from here rather than at emit time.
+ */
+const prepareOutputDir = (
+	resolution: Resolution,
+	options: BundleContext,
+): Effect.Effect<void, OutputError | PlatformError, FileSystem.FileSystem | Path.Path> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const outDir = options.outDir;
+
+		yield* assertDistinctOutputs(resolution, options);
+
+		if (!options.force) {
+			const clashes: Array<string> = [];
+			for (const planned of plannedOutputs(resolution, options)) {
+				if (options.skipExisting?.has(planned.file) === true) continue;
+				if (options.overwrite?.has(planned.file) === true) continue;
+				const exists = yield* fs
+					.exists(path.join(outDir, planned.file))
+					.pipe(Effect.orElseSucceed(() => false));
+				if (exists) clashes.push(planned.file);
+			}
+
+			if (clashes.length > 0) {
+				return yield* Effect.fail(
+					new OutputError(
+						outDir,
+						`would overwrite ${clashes.length} existing file${clashes.length === 1 ? "" : "s"} ` +
+							`(${clashes.slice(0, 3).join(", ")}${clashes.length > 3 ? ", …" : ""}). ` +
+							`Pass --force true to replace ${clashes.length === 1 ? "it" : "them"}, or choose a different --out.`,
+					),
+				);
+			}
+		}
+
+		yield* fs
+			.makeDirectory(outDir, { recursive: true })
+			.pipe(
+				Effect.mapError(
+					(cause) =>
+						new OutputError(outDir, "could not create output directory", { cause }),
+				),
+			);
+	});