@packall/core 0.1.0 → 0.2.0

package/src/archive.ts

@@ -1,92 +1,95 @@
-/**
- * Turning a staged directory tree into a gzipped tarball.
- *
- * Uses `node-tar`, the same library npm itself packs with. Writing a USTAR
- * encoder by hand would be a fun afternoon and a bad idea: scoped package
- * paths routinely exceed the 100-byte name field, so correctness depends on
- * prefix-splitting and PAX headers that `tar` already gets right.
- */
-import * as Effect from "effect/Effect"
-import * as FileSystem from "effect/FileSystem"
-import type { PlatformError } from "effect/PlatformError"
-import { create } from "tar"
-import { ArchiveError } from "./errors.js"
-import * as Progress from "./progress.js"
-
-/** A finished archive. */
-export type ArchiveResult = {
-  readonly path: string
-  readonly bytes: number
-}
-
-/**
- * Packs `entries` (paths relative to `cwd`) into a gzipped tar at `outPath`.
- *
- * `portable` normalises uid/gid/mtime so the same inputs produce byte-identical
- * output — which matters when a security team wants to diff two bundles or
- * re-derive one from a manifest.
- */
-export const createArchive = (options: {
-  readonly cwd: string
-  readonly entries: ReadonlyArray<string>
-  readonly outPath: string
-  readonly gzipLevel?: number | undefined
-}): Effect.Effect<ArchiveResult, ArchiveError | PlatformError, FileSystem.FileSystem | Progress.Progress> =>
-  Effect.gen(function*() {
-    const fs = yield* FileSystem.FileSystem
-
-    yield* Progress.emit({
-      _tag: "ArchiveStarted",
-      path: options.outPath,
-      entryCount: options.entries.length
-    })
-
-    yield* Effect.tryPromise({
-      try: () =>
-        create(
-          {
-            gzip: options.gzipLevel === undefined ? true : { level: options.gzipLevel },
-            file: options.outPath,
-            cwd: options.cwd,
-            portable: true,
-            // Undo the `./` added below, so recorded entry names stay exactly
-            // the registry paths the manifest lists.
-            onWriteEntry: (entry) => {
-              entry.path = entry.path.replace(/^\.\//, "")
-            }
-          },
-          // Sorted so archive order is stable across runs and platforms.
-          options.entries.toSorted().map(dotSlash)
-        ),
-      catch: (cause) => new ArchiveError(options.outPath, describe(cause), { cause })
-    })
-
-    const info = yield* fs.stat(options.outPath)
-    const bytes = Number(info.size)
-
-    yield* Progress.emit({ _tag: "ArchiveCompleted", path: options.outPath, bytes })
-
-    return { path: options.outPath, bytes }
-  })
-
-/**
- * Guards every entry against tar's `@` convention.
- *
- * In a tar file list, a leading `@` means "splice in the entries of this other
- * archive" — a GNU convention `node-tar` implements by stripping the `@` and
- * looking for what is left. Every scoped package is a top-level entry starting
- * with `@`, so this hit the bundler in both possible ways:
- *
- * - `@oxc-project` became `oxc-project`, which does not exist, and the run died
- *   with an ENOENT naming a path that appears nowhere in the staging tree.
- * - `@esbuild` became `esbuild`, which *does* exist — the unscoped package of
- *   the same name sitting right next to it. No error, and every scoped tarball
- *   silently missing from a bundle that reported success. That is the dangerous
- *   one: you would not find out until the install failed behind the firewall.
- *
- * `./@scope` is not subject to the convention and resolves identically.
- */
-const dotSlash = (entry: string): string => (entry.startsWith("./") ? entry : `./${entry}`)
-
-const describe = (cause: unknown): string =>
-  cause instanceof Error ? cause.message : String(cause)
+/**
+ * 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. */
+	export 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>;
+	};
+}
+
+/** Service tag for archive creation. */
+export class Archiver extends Context.Service<Archiver, Archiver.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.
+ */
+export const createArchive = (
+	options: CreateArchiveOptions,
+): Effect.Effect<
+	ArchiveResult,
+	ArchiveError | PlatformError,
+	Archiver | FileSystem.FileSystem | Progress.Progress
+> =>
+	Effect.gen(function* () {
+		const archiver = yield* Archiver;
+
+		yield* Progress.emit({
+			_tag: "ArchiveStarted",
+			path: options.outPath,
+			entryCount: options.entries.length,
+		});
+
+		const result = yield* archiver.create(options);
+
+		yield* Progress.emit({
+			_tag: "ArchiveCompleted",
+			path: result.path,
+			bytes: result.bytes,
+		});
+
+		return result;
+	});