@codepress/design-kit 0.7.0 → 0.9.0

package/src/storage/common.mjs

@@ -0,0 +1,125 @@
+/**
+ * What every kit store shares: the error a store raises, where a fetched kit
+ * is cached, and how the repository and its default branch are found.
+ */
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { unzipTo } from "./zip.mjs";
+
+/**
+ * A store refused or could not be reached. `code` is the store's own name
+ * for it (the backend's `reason`, such as `forbidden` or `no_kit`), or
+ * `kit_storage_unavailable` when the store could not be reached at all.
+ * Exits 1.
+ */
+export class StorageError extends Error {
+  constructor(code, message) {
+    super(message ? `${code}: ${message}` : code);
+    this.code = code;
+  }
+}
+
+/** The first line of what a failed command said. */
+export function errorText(error) {
+  const stderr = error?.stderr ? String(error.stderr).trim() : "";
+  return (stderr || error?.message || String(error)).split("\n")[0];
+}
+
+/**
+ * `sha` when it is a commit id (7 to 64 hex digits), else a StorageError. A
+ * store's answer names the commit, and it becomes a folder and file name,
+ * so nothing else (a `/`, a `..`) may reach a path.
+ */
+export function checkSha(sha, from) {
+  if (typeof sha === "string" && /^[0-9a-f]{7,64}$/i.test(sha)) return sha;
+  throw new StorageError(
+    "invalid_kit_sha",
+    `${from} names the kit's commit as ${JSON.stringify(sha)}, which is not a commit id`,
+  );
+}
+
+/** Where a fetched kit is kept: `$TMPDIR/design-kit-<sha>`. */
+export function kitCacheDir(sha, env = process.env) {
+  return join(
+    env.TMPDIR || tmpdir(),
+    `design-kit-${checkSha(sha, "the store")}`,
+  );
+}
+
+/**
+ * Unzips `zip` into `out` through a sibling scratch folder and a rename,
+ * so `out` never holds half a kit.
+ */
+export function installKit(zip, out) {
+  const target = resolve(out);
+  mkdirSync(dirname(target), { recursive: true });
+  const scratch = mkdtempSync(`${target}.partial-`);
+  try {
+    unzipTo(zip, scratch);
+    if (!existsSync(join(scratch, "manifest.json")))
+      throw new Error("the stored kit has no manifest.json");
+    rmSync(target, { recursive: true, force: true });
+    renameSync(scratch, target);
+  } catch (error) {
+    rmSync(scratch, { recursive: true, force: true });
+    throw error;
+  }
+  return target;
+}
+
+/** A cached kit is a folder with its manifest.json. */
+export function isKit(dir) {
+  return existsSync(join(dir, "manifest.json"));
+}
+
+function git(cwd, args) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/** `owner/name` from a github.com remote URL, or null. */
+export function repoFromRemote(url) {
+  const match = String(url).match(
+    /github\.com[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/,
+  );
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+/**
+ * The repository as `owner/name`: `--repo`, then GITHUB_REPOSITORY, then
+ * the `origin` remote of the checkout holding `cwd`. Null when none says.
+ */
+export function findRepo({ repo, env = process.env, cwd = process.cwd() }) {
+  if (repo) return repo;
+  if (env.GITHUB_REPOSITORY) return env.GITHUB_REPOSITORY;
+  try {
+    return repoFromRemote(git(cwd, ["remote", "get-url", "origin"]));
+  } catch {
+    return null;
+  }
+}
+
+/** The default branch `origin/HEAD` names in the checkout, or null. */
+export function originDefaultBranch(cwd = process.cwd()) {
+  try {
+    return (
+      git(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).replace(
+        /^origin\//,
+        "",
+      ) || null
+    );
+  } catch {
+    return null;
+  }
+}

package/src/storage/github.mjs

@@ -0,0 +1,175 @@
+/**
+ * `github` storage (the default): each kit is a `design-kit` GitHub Actions
+ * artifact, uploaded by the workflow's `actions/upload-artifact` step and
+ * read through the `gh` CLI. Artifacts last at most 90 days on a public
+ * repository (400 on a private one), so the workflow rebuilds before then.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { ConfigError } from "../config.mjs";
+import {
+  StorageError,
+  checkSha,
+  errorText,
+  isKit,
+  kitCacheDir,
+} from "./common.mjs";
+
+export const ARTIFACT = "design-kit";
+const PAGES = 5;
+
+/** Runs `gh` and returns its stdout. */
+export function runGh(args, { env = process.env } = {}) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/** Every `design-kit` artifact of the repository, newest first. */
+function listKits({ repo, gh }) {
+  const artifacts = [];
+  for (let page = 1; page <= PAGES; page += 1) {
+    const body = JSON.parse(
+      gh([
+        "api",
+        `repos/${repo}/actions/artifacts?name=${ARTIFACT}&per_page=100&page=${page}`,
+      ]),
+    );
+    const batch = body?.artifacts ?? [];
+    artifacts.push(...batch);
+    if (batch.length < 100) break;
+  }
+  return artifacts
+    .filter((artifact) => artifact.name === ARTIFACT)
+    .sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
+}
+
+/**
+ * The newest unexpired kit on `branch`: `{id, sha, createdAt, runId}`, or
+ * null when there is none. Throws when the store cannot be read.
+ */
+export function findNewestKit({ repo, branch, gh = runGh }) {
+  const kit = listKits({ repo, gh }).find(
+    (artifact) =>
+      !artifact.expired && artifact.workflow_run?.head_branch === branch,
+  );
+  if (!kit?.workflow_run?.head_sha) return null;
+  return {
+    id: String(kit.id),
+    sha: kit.workflow_run.head_sha,
+    createdAt: kit.created_at,
+    runId: kit.workflow_run.id ? String(kit.workflow_run.id) : null,
+  };
+}
+
+/**
+ * Deletes the kits on `branch` older than the one `keep` names (an artifact
+ * id). Returns `{deleted: [ids], failed: [{id, error}], keptFound}`; never
+ * throws for a single failed delete. When the kept kit is not in the listing
+ * (not listed yet, or on another branch), nothing is deleted: "older" has
+ * nothing to be measured against.
+ */
+export function deleteOlderKits({ repo, branch, keep, gh = runGh }) {
+  const kits = listKits({ repo, gh }).filter(
+    (artifact) => artifact.workflow_run?.head_branch === branch,
+  );
+  const kept = kits.find((artifact) => String(artifact.id) === String(keep));
+  const deleted = [];
+  const failed = [];
+  if (!kept) return { deleted, failed, keptFound: false };
+  for (const artifact of kits) {
+    if (String(artifact.id) === String(keep)) continue;
+    // Only kits uploaded before the one just kept: a newer one, or one
+    // uploaded in the same instant, is never removed.
+    if (!(Date.parse(artifact.created_at) < Date.parse(kept.created_at)))
+      continue;
+    try {
+      gh([
+        "api",
+        "--method",
+        "DELETE",
+        `repos/${repo}/actions/artifacts/${artifact.id}`,
+      ]);
+      deleted.push(String(artifact.id));
+    } catch (error) {
+      failed.push({ id: String(artifact.id), error: errorText(error) });
+    }
+  }
+  return { deleted, failed, keptFound: Boolean(kept) };
+}
+
+/**
+ * The `github` store. `repo` is `owner/name`; `gh` runs the GitHub CLI
+ * (tests pass their own).
+ */
+export function githubStorage({ repo, env = process.env, gh } = {}) {
+  const run = gh ?? ((args) => runGh(args, { env }));
+  const needRepo = () => {
+    if (!repo)
+      throw new ConfigError(
+        "--repo <owner/name> is needed: no GITHUB_REPOSITORY and no github.com origin remote",
+      );
+    return repo;
+  };
+  const defaultBranch = () =>
+    JSON.parse(run(["api", `repos/${needRepo()}`])).default_branch;
+  return {
+    type: "github",
+    latest({ branch }) {
+      return findNewestKit({
+        repo: needRepo(),
+        branch: branch ?? defaultBranch(),
+        gh: run,
+      });
+    },
+    upload() {
+      throw new ConfigError(
+        'github storage uploads the kit with the workflow\'s actions/upload-artifact step, so there is nothing for design-kit upload to do. Set "storage" in the config to codepress, s3 or r2 to upload with this command.',
+      );
+    },
+    fetch({ branch, out }) {
+      const name = branch ?? defaultBranch();
+      const kit = findNewestKit({ repo: needRepo(), branch: name, gh: run });
+      if (!kit?.runId)
+        throw new StorageError(
+          "no_kit",
+          `no unexpired design-kit artifact on ${name} in ${repo}`,
+        );
+      checkSha(kit.sha, "The artifact's workflow run");
+      const path = resolve(out ?? kitCacheDir(kit.sha, env));
+      if (isKit(path))
+        return { path, sha: kit.sha, branch: name, cached: true };
+      mkdirSync(dirname(path), { recursive: true });
+      const scratch = mkdtempSync(`${path}.partial-`);
+      try {
+        run([
+          "run",
+          "download",
+          kit.runId,
+          "--repo",
+          repo,
+          "-n",
+          ARTIFACT,
+          "-D",
+          scratch,
+        ]);
+        if (!isKit(scratch))
+          throw new StorageError(
+            "no_kit",
+            `the artifact of run ${kit.runId} has no manifest.json`,
+          );
+        rmSync(path, { recursive: true, force: true });
+        renameSync(scratch, path);
+      } catch (error) {
+        rmSync(scratch, { recursive: true, force: true });
+        throw error;
+      }
+      return { path, sha: kit.sha, branch: name, cached: false };
+    },
+  };
+}

package/src/storage/index.mjs

@@ -0,0 +1,149 @@
+/**
+ * Where a kit is stored, chosen by the config's `storage` key, behind one
+ * interface:
+ *
+ *     latest({branch})          → {sha, createdAt} | null
+ *     upload({dir, branch, sha}) → {sha, branch, sizeBytes}
+ *     fetch({branch, out})      → {path, sha, branch, cached}
+ *
+ * `github` (the default) is a GitHub Actions artifact; `codepress` is
+ * CodePress; `s3` and `r2` are the user's own bucket. The commands
+ * `design-kit upload`, `fetch` and `latest` are here too.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { ConfigError, loadConfig } from "../config.mjs";
+import { bucketStorage } from "./bucket.mjs";
+import { codepressStorage } from "./codepress.mjs";
+import { findRepo, originDefaultBranch } from "./common.mjs";
+import { githubStorage } from "./github.mjs";
+
+export { StorageError } from "./common.mjs";
+
+export const STORAGE_TYPES = ["github", "codepress", "s3", "r2"];
+
+/**
+ * The store for a config's `storage` object (`{type: "github"}` when
+ * absent). `context`: `repo` (owner/name), `env`, `tokenFile`, and for
+ * tests `gh` and `aws`.
+ */
+export function storageFor(storage, context = {}) {
+  const config = storage ?? { type: "github" };
+  if (config.type === "github") return githubStorage(context);
+  if (config.type === "codepress") return codepressStorage(config, context);
+  if (config.type === "s3" || config.type === "r2")
+    return bucketStorage(config, context);
+  throw new ConfigError(
+    `storage.type: must be one of ${STORAGE_TYPES.join(", ")}`,
+  );
+}
+
+/** The branch a read means when --branch is not given. */
+function readBranch(options, storage, configDir) {
+  if (options.branch) return options.branch;
+  // github asks GitHub and codepress asks CodePress for the default branch;
+  // a bucket knows no repository, so the checkout's origin/HEAD says.
+  if (storage.type === "s3" || storage.type === "r2")
+    return originDefaultBranch(configDir) ?? undefined;
+  return undefined;
+}
+
+function contextFor(options, config, { env, gh, aws }) {
+  return {
+    repo: findRepo({ repo: options.repo, env, cwd: config.configDir }),
+    env,
+    tokenFile: options["token-file"],
+    gh,
+    aws,
+  };
+}
+
+function storageOf(config) {
+  return config.storage ?? { type: "github" };
+}
+
+/**
+ * `design-kit upload --dir <kit>`: uploads a built kit to the configured
+ * store. `github` storage exits 2: the workflow's upload-artifact step
+ * uploads it.
+ */
+export async function uploadCommand(
+  options,
+  { env = process.env, gh, aws } = {},
+) {
+  const config = loadConfig(options.config);
+  const storage = storageOf(config);
+  const dir = resolve(options.dir ?? config.out ?? "design-kit");
+  if (storage.type !== "github" && !existsSync(join(dir, "manifest.json")))
+    throw new ConfigError(
+      `${dir} is not a kit (no manifest.json); pass --dir <kit folder>`,
+    );
+  const store = storageFor(
+    storage,
+    contextFor(options, config, { env, gh, aws }),
+  );
+  const result = await store.upload({
+    dir,
+    branch: options.branch ?? env.GITHUB_REF_NAME,
+    sha: options.sha ?? env.GITHUB_SHA,
+  });
+  console.log(
+    `Uploaded the kit of ${String(result.sha).slice(0, 7)} on ${result.branch} to ${storage.type} storage (${result.sizeBytes} bytes zipped).`,
+  );
+  console.log(`sha=${result.sha}`);
+  console.log(`branch=${result.branch}`);
+  return 0;
+}
+
+/**
+ * `design-kit fetch [--branch b] [--out dir]`: downloads the newest kit
+ * (once per commit: it is cached under $TMPDIR/design-kit-<sha>) and prints
+ * `path=`, `sha=` and `branch=`.
+ */
+export async function fetchCommand(
+  options,
+  { env = process.env, gh, aws } = {},
+) {
+  const config = loadConfig(options.config);
+  const storage = storageOf(config);
+  const store = storageFor(
+    storage,
+    contextFor(options, config, { env, gh, aws }),
+  );
+  const kit = await store.fetch({
+    branch: readBranch(options, storage, config.configDir),
+    out: options.out,
+  });
+  console.log(`path=${kit.path}`);
+  console.log(`sha=${kit.sha}`);
+  if (kit.branch) console.log(`branch=${kit.branch}`);
+  return 0;
+}
+
+/**
+ * `design-kit latest [--branch b]`: prints the newest kit's `sha=` and
+ * `created=`. No kit exits 1.
+ */
+export async function latestCommand(
+  options,
+  { env = process.env, gh, aws } = {},
+) {
+  const config = loadConfig(options.config);
+  const storage = storageOf(config);
+  const store = storageFor(
+    storage,
+    contextFor(options, config, { env, gh, aws }),
+  );
+  const branch = readBranch(options, storage, config.configDir);
+  const kit = await store.latest({ branch });
+  if (!kit) {
+    console.error(
+      `design-kit: no_kit: no kit stored${branch ? ` on ${branch}` : " on the default branch"} in ${storage.type} storage`,
+    );
+    return 1;
+  }
+  console.log(`sha=${kit.sha}`);
+  console.log(`created=${kit.createdAt ?? ""}`);
+  return 0;
+}

package/src/storage/zip.mjs

@@ -0,0 +1,249 @@
+/**
+ * Zips a kit folder and unzips one, with Node's zlib and no other
+ * dependency. The archive is deterministic: entries sorted by path, every
+ * timestamp 1980-01-01, so the same kit always zips to the same bytes.
+ * ZIP64 end records are written and read when a kit has 65,535 or more
+ * files; a single file must stay under 4 GB.
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+/** The CRC-32 a zip entry records. */
+export function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1)
+    crc = CRC_TABLE[(crc ^ buffer[i]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Every regular file under `dir`, as forward-slash paths relative to it. */
+function filesUnder(dir) {
+  const files = [];
+  const walk = (folder) => {
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+      const path = join(folder, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile())
+        files.push(relative(dir, path).split(sep).join("/"));
+    }
+  };
+  walk(dir);
+  return files.sort();
+}
+
+const DOS_TIME = 0;
+const DOS_DATE = (1 << 5) | 1; // 1980-01-01
+const MAX32 = 0xffffffff;
+const MAX16 = 0xffff;
+
+/** The folder `dir`, zipped, as one Buffer. */
+export function zipDirectory(dir) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const path of filesUnder(dir)) {
+    const data = readFileSync(join(dir, path));
+    const name = Buffer.from(path, "utf8");
+    const deflated = deflateRawSync(data);
+    // Stored when deflating does not help (fonts, images).
+    const method = deflated.length < data.length ? 8 : 0;
+    const body = method === 8 ? deflated : data;
+    if (data.length >= MAX32 || body.length >= MAX32)
+      throw new Error(`${path} is too large to zip (4 GB or more)`);
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    parts.push(local, name, body);
+
+    const zip64Offset = offset >= MAX32;
+    const extra = zip64Offset ? Buffer.alloc(12) : Buffer.alloc(0);
+    if (zip64Offset) {
+      extra.writeUInt16LE(0x0001, 0);
+      extra.writeUInt16LE(8, 2);
+      extra.writeBigUInt64LE(BigInt(offset), 4);
+    }
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(0x02014b50, 0);
+    header.writeUInt16LE(zip64Offset ? 45 : 20, 4); // version made by
+    header.writeUInt16LE(zip64Offset ? 45 : 20, 6); // version needed
+    header.writeUInt16LE(0x0800, 8);
+    header.writeUInt16LE(method, 10);
+    header.writeUInt16LE(DOS_TIME, 12);
+    header.writeUInt16LE(DOS_DATE, 14);
+    header.writeUInt32LE(crc, 16);
+    header.writeUInt32LE(body.length, 20);
+    header.writeUInt32LE(data.length, 24);
+    header.writeUInt16LE(name.length, 28);
+    header.writeUInt16LE(extra.length, 30);
+    header.writeUInt16LE(0, 32); // comment
+    header.writeUInt16LE(0, 34); // disk
+    header.writeUInt16LE(0, 36); // internal attributes
+    header.writeUInt32LE(0, 38); // external attributes
+    header.writeUInt32LE(zip64Offset ? MAX32 : offset, 42);
+    central.push(header, name, extra);
+    offset += local.length + name.length + body.length;
+  }
+  const count = central.length / 3;
+  const centralSize = central.reduce((sum, part) => sum + part.length, 0);
+  const centralOffset = offset;
+  const tail = [];
+  const zip64 =
+    count >= MAX16 || centralOffset >= MAX32 || centralSize >= MAX32;
+  if (zip64) {
+    const record = Buffer.alloc(56);
+    record.writeUInt32LE(0x06064b50, 0);
+    record.writeBigUInt64LE(44n, 4);
+    record.writeUInt16LE(45, 12);
+    record.writeUInt16LE(45, 14);
+    record.writeUInt32LE(0, 16);
+    record.writeUInt32LE(0, 20);
+    record.writeBigUInt64LE(BigInt(count), 24);
+    record.writeBigUInt64LE(BigInt(count), 32);
+    record.writeBigUInt64LE(BigInt(centralSize), 40);
+    record.writeBigUInt64LE(BigInt(centralOffset), 48);
+    const locator = Buffer.alloc(20);
+    locator.writeUInt32LE(0x07064b50, 0);
+    locator.writeUInt32LE(0, 4);
+    locator.writeBigUInt64LE(BigInt(centralOffset + centralSize), 8);
+    locator.writeUInt32LE(1, 16);
+    tail.push(record, locator);
+  }
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(zip64 ? MAX16 : count, 8);
+  end.writeUInt16LE(zip64 ? MAX16 : count, 10);
+  end.writeUInt32LE(zip64 ? MAX32 : centralSize, 12);
+  end.writeUInt32LE(zip64 ? MAX32 : centralOffset, 16);
+  end.writeUInt16LE(0, 20);
+  tail.push(end);
+  return Buffer.concat([...parts, ...central, ...tail]);
+}
+
+/** Where the end-of-central-directory record starts, or -1. */
+function findEnd(zip) {
+  const last = Math.max(0, zip.length - 22 - MAX16);
+  for (let i = zip.length - 22; i >= last; i -= 1)
+    if (zip.readUInt32LE(i) === 0x06054b50) return i;
+  return -1;
+}
+
+/**
+ * The entries of a zip: `[{path, data}]`. Throws on anything it cannot
+ * read: a damaged archive, an encrypted entry, or an unknown method.
+ */
+export function readZip(zip) {
+  const end = findEnd(zip);
+  if (end < 0) throw new Error("not a zip archive (no end record)");
+  let count = zip.readUInt16LE(end + 10);
+  let centralOffset = zip.readUInt32LE(end + 16);
+  if (
+    (count === MAX16 || centralOffset === MAX32) &&
+    end >= 20 &&
+    zip.readUInt32LE(end - 20) === 0x07064b50
+  ) {
+    const record = Number(zip.readBigUInt64LE(end - 20 + 8));
+    if (zip.readUInt32LE(record) !== 0x06064b50)
+      throw new Error("not a zip archive (bad ZIP64 record)");
+    count = Number(zip.readBigUInt64LE(record + 32));
+    centralOffset = Number(zip.readBigUInt64LE(record + 48));
+  }
+  const entries = [];
+  let at = centralOffset;
+  for (let index = 0; index < count; index += 1) {
+    if (zip.readUInt32LE(at) !== 0x02014b50)
+      throw new Error("damaged zip archive (bad central directory)");
+    const flags = zip.readUInt16LE(at + 8);
+    const method = zip.readUInt16LE(at + 10);
+    const crc = zip.readUInt32LE(at + 16);
+    let compressed = zip.readUInt32LE(at + 20);
+    let size = zip.readUInt32LE(at + 24);
+    const nameLength = zip.readUInt16LE(at + 28);
+    const extraLength = zip.readUInt16LE(at + 30);
+    const commentLength = zip.readUInt16LE(at + 32);
+    let local = zip.readUInt32LE(at + 42);
+    const path = zip.toString("utf8", at + 46, at + 46 + nameLength);
+    // ZIP64 extra field: the 64-bit values, in order, for the 32-bit
+    // fields that are 0xffffffff.
+    let extraAt = at + 46 + nameLength;
+    const extraEnd = extraAt + extraLength;
+    while (extraAt + 4 <= extraEnd) {
+      const id = zip.readUInt16LE(extraAt);
+      const length = zip.readUInt16LE(extraAt + 2);
+      if (id === 0x0001) {
+        let field = extraAt + 4;
+        if (size === MAX32) {
+          size = Number(zip.readBigUInt64LE(field));
+          field += 8;
+        }
+        if (compressed === MAX32) {
+          compressed = Number(zip.readBigUInt64LE(field));
+          field += 8;
+        }
+        if (local === MAX32) local = Number(zip.readBigUInt64LE(field));
+      }
+      extraAt += 4 + length;
+    }
+    at = extraEnd + commentLength;
+    if (path.endsWith("/")) continue;
+    if (flags & 1) throw new Error(`${path}: encrypted entries are not read`);
+    if (zip.readUInt32LE(local) !== 0x04034b50)
+      throw new Error(`damaged zip archive (${path} has no local header)`);
+    const start =
+      local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+    const body = zip.subarray(start, start + compressed);
+    let data;
+    if (method === 0) data = body;
+    else if (method === 8) data = inflateRawSync(body);
+    else throw new Error(`${path}: compression method ${method} is not read`);
+    if (data.length !== size || crc32(data) !== crc)
+      throw new Error(`damaged zip archive (${path} fails its checksum)`);
+    entries.push({ path, data });
+  }
+  return entries;
+}
+
+/**
+ * Unzips `zip` into `dir`. An entry whose path is absolute or climbs out of
+ * `dir` (`..`) is refused before anything is written.
+ */
+export function unzipTo(zip, dir) {
+  const root = resolve(dir);
+  const entries = readZip(zip);
+  for (const { path } of entries) {
+    const target = resolve(root, path);
+    if (
+      /^[\\/]/.test(path) ||
+      /^[A-Za-z]:/.test(path) ||
+      !`${target}`.startsWith(`${root}${sep}`)
+    )
+      throw new Error(`refusing the zip entry ${path}: it is outside the kit`);
+  }
+  mkdirSync(root, { recursive: true });
+  for (const { path, data } of entries) {
+    const target = resolve(root, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, data);
+  }
+  return entries.length;
+}