@packall/core 0.0.1 → 0.1.0

package/src/{Bundle.ts → bundle.ts}

@@ -1,570 +1,616 @@
-/**
- * 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 type { BundlerError } from "./Errors.js"
-import { OutputError } from "./Errors.js"
-import {
-  importGuide,
-  MANIFEST_FILE,
-  packagePath,
-  perSpecArchiveName,
-  README_FILE,
-  singleArchiveName
-} from "./Layout.js"
-import { buildManifest, serializeManifest } from "./Manifest.js"
-import type { BundleOptions, Layout } 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 interface BundleArtifact {
-  readonly kind: "archive" | "directory"
-  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 {
-  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 interface BundleContext extends 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 {
-  /** 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
-}
-
-/** 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
-})
-
-type BundleEnv = Registry | Progress.Progress | FileSystem.FileSystem | Path.Path
-
-/**
- * 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*() {
-    const registry = yield* Registry
-
-    yield* Progress.emit({ _tag: "PhaseStarted", phase: "preflight" })
-    yield* registry.preflight
-    yield* Progress.emit({ _tag: "PhaseCompleted", phase: "preflight" })
-
-    return yield* resolve(specs, options)
-  })
-
-/**
- * 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)
-  })
-
-/**
- * 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))
-  })
-
-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: "archive" })
-
-    const registryInfo = {
-      kind: registry.kind,
-      url: registry.registryFor(resolution.roots[0]?.spec.name ?? "")
-    }
-
-    const index = indexPackages(resolution)
-
-    const artifacts =
-      options.layout === "single"
-        ? yield* emitSingle({ resolution, options, staging, packagesDir, report, registryInfo })
-        : options.layout === "dir"
-          ? yield* emitDirectory({ resolution, options, packagesDir, report, registryInfo })
-          : yield* emitPerSpec({
-              resolution,
-              options,
-              staging,
-              packagesDir,
-              report,
-              registryInfo,
-              index
-            })
-
-    yield* Progress.emit({ _tag: "PhaseCompleted", phase: "archive" })
-    yield* Progress.emit({ _tag: "PhaseStarted", phase: "done" })
-
-    return {
-      resolution,
-      artifacts,
-      downloadedBytes: report.totalBytes,
-      unverified: report.unverified,
-      dryRun: false
-    }
-  })
-
-/* -------------------------------------------------------------------------- */
-/* Emitters                                                                   */
-/* -------------------------------------------------------------------------- */
-
-interface 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 tarball containing the deduplicated union of every closure. */
-const emitSingle = (
-  input: EmitInput & { readonly staging: string }
-): 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: "archive" as const,
-        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: "directory" as const,
-        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 & {
-    readonly staging: string
-    readonly index: ReadonlyMap<PackageKey, ResolvedPackage>
-  }
-): 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 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 closure = root.closures.get(version) ?? []
-        const included = closure
-          .map((key) => input.index.get(key))
-          .filter((pkg): pkg is ResolvedPackage => pkg !== undefined)
-
-        const rootDir = path.join(input.staging, "roots", String(counter++))
-        yield* fs.makeDirectory(rootDir, { recursive: true })
-
-        for (const pkg of included) {
-          const relative = packagePath(pkg.name, pkg.version)
-          const parts = relative.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: "archive",
-          path: result.path,
-          bytes: result.bytes,
-          packageCount: included.length,
-          spec: formatSpec(root.spec),
-          version
-        })
-      }
-    }
-
-    return artifacts
-  })
-
-/* -------------------------------------------------------------------------- */
-/* Helpers                                                                    */
-/* -------------------------------------------------------------------------- */
-
-/**
- * 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].sort()
-  })
-
-/**
- * Creates the output directory, refusing to clobber an existing non-empty one
- * unless `--force` was passed.
- *
- * 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.
- */
-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 const plannedOutputs = (
-  resolution: Resolution,
-  options: BundleContext
-): ReadonlyArray<PlannedOutput> => {
-  if (options.layout === "dir") return [{ file: MANIFEST_FILE }, { file: README_FILE }]
-  if (options.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
-    }))
-  )
-}
-
-/**
- * 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, 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 }))
+    )
+  })