@yunxiaoyi/gitpack 0.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,60 @@
+## gitpack
+
+Pack a project into zip / tar.gz while respecting nested `.gitignore` rules. Provides both an interactive and a flag-based command-line mode. No `.git` directory required.
+
+## Setup
+
+```bash
+npm install -g @yunxiaoyi/gitpack
+```
+
+## Usage
+
+### Interactive mode
+
+```bash
+gitpack
+# or
+gpk
+```
+
+You will be prompted for the project root, archive format, and output directory.
+
+### Flag-based mode
+
+```bash
+gitpack --root <path> --format <zip|tar.gz> --out <dir>
+```
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `--root <path>` | Project root directory. Repeatable to pack multiple roots. |
+| `--roots <a,b,c>` | Comma- or semicolon-separated list of roots. |
+| `--format zip\|tar.gz` | Output archive format. |
+| `--out <dir>` | Output directory (file name is auto-generated). |
+| `--out-file <path>` | Full path of the archive (overrides `--out` naming). |
+| `--timestamp` | Append a `-<time>` suffix to the auto-generated file name. |
+| `--no-timestamp` | Use `<folder>.<ext>` only (default; same as omitting both flags). `--source-timestamp` / `--no-source-timestamp` are also accepted. |
+| `--force` | Overwrite an existing output file without prompting (non-interactive). |
+| `-y, --yes, --no-interactive` | Skip prompts. Requires `--format`, `--out` or `--out-file`, and `--root` / `--roots`. |
+| `-q, --quiet` | Suppress scan / compress progress output. |
+| `-h, --help` | Show help. |
+
+#### Examples
+
+```bash
+# Interactive (defaults from CWD)
+gitpack
+
+# Non-interactive single root
+gitpack --no-interactive --root . --out .. --format zip
+
+# Pack multiple roots into one tar.gz
+gitpack --roots "D:/a,D:/b" --out D:/dist --format tar.gz
+```
+
+## License
+
+MIT

package/bin/gitpack.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+await main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@yunxiaoyi/gitpack",
+  "version": "0.1.1",
+  "description": "Pack a project into zip / tar.gz while respecting nested `.gitignore` rules. Provides both an interactive and a flag-based command-line mode. No `.git` directory required.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Yun Xiaoyi",
+  "keywords": [
+    "archive",
+    "zip",
+    "tar",
+    "tar.gz",
+    "gitignore",
+    "pack",
+    "cli"
+  ],
+  "bin": {
+    "gitpack": "bin/gitpack.js",
+    "gpk": "bin/gitpack.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "bugs": "https://github.com/OneCalmCloud/gitpack/issues",
+  "scripts": {
+    "start": "node ./bin/gitpack.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "archiver": "^8.0.0",
+    "globby": "^16.2.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,445 @@
+import * as p from "@clack/prompts";
+import { existsSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { writeArchive } from "./pack.mjs";
+
+function parseArgs(argv) {
+  const flags = {
+    roots: [],
+    format: null,
+    out: null,
+    outFile: null,
+    /** @type {boolean | undefined} undefined = default true */
+    timestamp: undefined,
+    force: false,
+    noInteractive: false,
+    quiet: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      flags.help = true;
+      continue;
+    }
+    if (a === "-y" || a === "--yes" || a === "--no-interactive") {
+      flags.noInteractive = true;
+      continue;
+    }
+    if (a === "--quiet" || a === "-q") {
+      flags.quiet = true;
+      continue;
+    }
+    if (a === "--root") {
+      const next = argv[++i];
+      if (!next) throw new Error("--root requires a path");
+      flags.roots.push(resolve(next));
+      continue;
+    }
+    if (a === "--roots") {
+      const next = argv[++i] || "";
+      for (const part of next.split(/[,;]/)) {
+        const t = part.trim();
+        if (t) flags.roots.push(resolve(t));
+      }
+      continue;
+    }
+    if (a === "--format") {
+      flags.format = argv[++i];
+      continue;
+    }
+    if (a === "--out") {
+      flags.out = resolve(argv[++i]);
+      continue;
+    }
+    if (a === "--out-file") {
+      flags.outFile = resolve(argv[++i]);
+      continue;
+    }
+    if (a === "--timestamp" || a === "--source-timestamp") {
+      flags.timestamp = true;
+      continue;
+    }
+    if (a === "--no-timestamp" || a === "--no-source-timestamp") {
+      flags.timestamp = false;
+      continue;
+    }
+    if (a === "--force") {
+      flags.force = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${a}`);
+  }
+  return flags;
+}
+
+function printHelp() {
+  console.log(`gitpack — pack directories into zip / tar.gz (respects nested .gitignore; no .git required)
+
+Usage:
+  gitpack [options]
+
+Options:
+  --root <path>       Project root (repeatable)
+  --roots <a,b,c>     Comma- or semicolon-separated roots
+  --format zip|tar.gz Output format
+  --out <dir>         Output directory (file name is auto-generated)
+  --out-file <path>   Full path of archive (overrides --out name)
+  --timestamp         Auto name includes -<time> suffix
+  --no-timestamp      Auto name is <folder>.zip only (default; same as omitting both flags)
+                        (--source-timestamp / --no-source-timestamp still accepted)
+  --force             Overwrite existing output file without prompting (non-interactive)
+  -y, --yes, --no-interactive   Do not prompt; require --format, --out or --out-file, and --root/--roots
+  -q, --quiet         Do not print progress (scan / compress) to stderr or update the spinner text
+  -h, --help          Show help
+
+Examples:
+  gitpack
+  gitpack --no-interactive --root . --out .. --format zip
+  gitpack --roots "D:/a,D:/b" --out D:/dist --format tar.gz
+`);
+}
+
+/** Avoid `String(undefined)` becoming the literal `"undefined"` and being treated as a path. */
+function trimmedTextOr(value, fallback) {
+  const t = value == null ? "" : String(value).trim();
+  return t === "" ? fallback : t;
+}
+
+function validateRoots(roots) {
+  if (roots.length === 0) throw new Error("At least one project root directory is required.");
+  for (const r of roots) {
+    if (!existsSync(r) || !statSync(r).isDirectory()) {
+      throw new Error(`Not a valid directory: ${r}`);
+    }
+  }
+}
+
+/** When no output directory is specified: use the current working directory (where `gitpack` is executed). */
+function defaultOutDir() {
+  return resolve(process.cwd());
+}
+
+function stamp() {
+  return new Date()
+    .toISOString()
+    .replaceAll(":", "")
+    .replace("T", "-")
+    .slice(0, 15);
+}
+
+/**
+ * @param {string[]} roots
+ * @param {'zip' | 'tar.gz'} format
+ * @param {boolean} useTimestamp
+ */
+function defaultArchiveName(roots, format, useTimestamp) {
+  const ext = format === "zip" ? "zip" : "tar.gz";
+  const mid = useTimestamp ? `-${stamp()}` : "";
+  if (roots.length === 1) {
+    return `${basename(roots[0])}${mid}.${ext}`;
+  }
+  return `bundle-${roots.length}-roots${mid}.${ext}`;
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * @param {{ spinner: ReturnType<typeof p.spinner> | null; quiet: boolean; noPrompt: boolean }} opts
+ */
+function createProgressHandler(opts) {
+  const { spinner, quiet, noPrompt } = opts;
+  const state = { stderrLine: false, lastCiLog: 0 };
+
+  /** @param {*} e */
+  return {
+    state,
+    onProgress(e) {
+      if (quiet) return;
+      if (e.phase === "collect") {
+        const name = basename(e.root);
+        if (e.filesInRoot === null) {
+          const msg = `Scanning ${e.index}/${e.total} · ${name}`;
+          if (spinner) spinner.message(msg);
+          else if (noPrompt && !process.stderr.isTTY) {
+            console.error(`[gitpack] ${msg}`);
+          } else if (noPrompt) {
+            process.stderr.write(`\r\x1b[K[gitpack] ${msg}`);
+            state.stderrLine = true;
+          }
+        } else {
+          const msg = `Listed ${e.filesInRoot} files · ${name} (${e.index}/${e.total})`;
+          if (spinner) spinner.message(msg);
+          else if (noPrompt && !process.stderr.isTTY) {
+            console.error(`[gitpack] ${msg}`);
+          } else if (noPrompt) {
+            process.stderr.write(`\r\x1b[K[gitpack] ${msg}`);
+            state.stderrLine = true;
+          }
+        }
+      } else if (e.phase === "collect_done") {
+        const msg = `Compressing · ${e.totalFiles} files total`;
+        if (spinner) spinner.message(msg);
+        else if (noPrompt && !process.stderr.isTTY) {
+          console.error(`[gitpack] ${msg}`);
+        } else if (noPrompt) {
+          process.stderr.write(`\r\x1b[K[gitpack] ${msg}`);
+          state.stderrLine = true;
+        }
+      } else if (e.phase === "compress") {
+        const { entries, fs } = e;
+        const t = entries.total || 0;
+        const c = entries.processed || 0;
+        const tb = fs.totalBytes || 0;
+        const pb = fs.processedBytes || 0;
+        const entryPct = t ? Math.min(100, Math.round((c / t) * 100)) : 0;
+        const bytePct = tb ? Math.min(100, Math.round((pb / tb) * 100)) : 0;
+        const msg = `Compress ${c}/${t} · entries ${entryPct}% · size ~${bytePct}% (${fmtBytes(pb)}${tb ? ` / ${fmtBytes(tb)}` : ""})`;
+        if (spinner) spinner.message(msg);
+        else if (noPrompt) {
+          if (process.stderr.isTTY) {
+            process.stderr.write(`\r\x1b[K[gitpack] ${msg}`);
+            state.stderrLine = true;
+          } else {
+            const now = Date.now();
+            if (c >= t || now - state.lastCiLog > 900) {
+              state.lastCiLog = now;
+              console.error(`[gitpack] ${msg}`);
+            }
+          }
+        }
+      }
+
+    },
+  };
+}
+
+/**
+ * @param {{ roots: string[]; format: 'zip' | 'tar.gz'; outDir: string; flags: Record<string, unknown>; noPrompt: boolean }} opts
+ */
+async function resolveOutputArchivePath(opts) {
+  const { roots, format, outDir, flags, noPrompt } = opts;
+
+  let useTimestamp = flags.timestamp === true;
+
+  if (!noPrompt) {
+    const tsQ = await p.confirm({
+      message: "Include timestamp in file name?",
+      initialValue: false,
+    });
+    if (p.isCancel(tsQ)) process.exit(0);
+    useTimestamp = !!tsQ;
+  }
+
+  const ext = format === "zip" ? ".zip" : ".tar.gz";
+
+  for (;;) {
+    const name = defaultArchiveName(roots, format, useTimestamp);
+    const candidate = join(outDir, name);
+    if (!existsSync(candidate)) {
+      return candidate;
+    }
+    if (noPrompt) {
+      if (flags.force) {
+        return candidate;
+      }
+      console.error(
+        `Output file already exists: ${candidate}\nUse --force to overwrite, or delete the file and try again.`,
+      );
+      process.exit(1);
+    }
+    const ow = await p.confirm({
+      message: `The following file already exists. Overwrite it?\n${candidate}`,
+      initialValue: false,
+    });
+    if (p.isCancel(ow)) process.exit(0);
+    if (ow) {
+      return candidate;
+    }
+    const fix = await p.select({
+      message: "Choose an option (without overwriting):",
+      options: [
+        { value: "enable-ts", label: "Use a timestamped file name" },
+        { value: "custom", label: "Custom file name (without extension)" },
+        { value: "abort", label: "Cancel" },
+      ],
+      initialValue: "enable-ts",
+    });
+    if (p.isCancel(fix) || fix === "abort") {
+      p.outro("Canceled");
+      process.exit(0);
+    }
+    if (fix === "enable-ts") {
+      useTimestamp = true;
+      continue;
+    }
+    const base = await p.text({
+      message: `Enter a file name (without extension ${ext})`,
+      initialValue: basename(roots[0]),
+    });
+    if (p.isCancel(base)) process.exit(0);
+    const customPath = join(outDir, `${trimmedTextOr(base, basename(roots[0]))}${ext}`);
+    if (!existsSync(customPath)) {
+      return customPath;
+    }
+    p.log.warn(`This name also exists: ${customPath}`);
+  }
+}
+
+export async function main() {
+  let flags;
+  try {
+    flags = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+
+  if (flags.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const noPrompt =
+    flags.noInteractive ||
+    process.env.GITPACK_NO_PROMPT === "1" ||
+    process.env.CI === "true" ||
+    !process.stdin.isTTY;
+
+  let roots = [...flags.roots];
+  let format = flags.format;
+  let outDir = flags.out;
+  let outFile = flags.outFile;
+
+  if (!noPrompt) {
+    p.intro("gitpack");
+
+    if (roots.length > 0) {
+      validateRoots(roots);
+    }
+
+    if (roots.length === 0) {
+      const first = await p.text({
+        message: "Project root directory to pack",
+        placeholder: process.cwd(),
+        initialValue: "",
+      });
+      if (p.isCancel(first)) process.exit(0);
+      roots.push(resolve(trimmedTextOr(first, process.cwd())));
+    }
+
+    validateRoots(roots);
+
+    if (!format) {
+      const f = await p.select({
+        message: "Archive format",
+        options: [
+          { value: "zip", label: "zip" },
+          { value: "tar.gz", label: "tar.gz" },
+        ],
+        initialValue: "zip",
+      });
+      if (p.isCancel(f)) process.exit(0);
+      format = f;
+    }
+
+    if (!outFile && !outDir) {
+      const suggested = defaultOutDir();
+      const o = await p.text({
+        message: "Output directory",
+        placeholder: suggested,
+        initialValue: "",
+      });
+      if (p.isCancel(o)) process.exit(0);
+      outDir = resolve(trimmedTextOr(o, suggested));
+    }
+  } else {
+    if (roots.length === 0) {
+      console.error("Non-interactive mode requires --root or --roots.");
+      process.exit(1);
+    }
+    validateRoots(roots);
+    if (!format || (!outDir && !outFile)) {
+      console.error("Non-interactive mode requires --format and either --out or --out-file.");
+      process.exit(1);
+    }
+    if (!outFile && outDir) {
+      outDir = resolve(outDir);
+    }
+  }
+
+  if (format !== "zip" && format !== "tar.gz") {
+    console.error('format must be zip or tar.gz');
+    process.exit(1);
+  }
+
+  validateRoots(roots);
+
+  if (!outFile) {
+    outDir = resolve(outDir || defaultOutDir());
+    outFile = await resolveOutputArchivePath({
+      roots,
+      format,
+      outDir,
+      flags,
+      noPrompt,
+    });
+  } else {
+    outFile = resolve(outFile);
+    if (existsSync(outFile)) {
+      if (noPrompt) {
+        if (!flags.force) {
+          console.error(`File already exists: ${outFile}\nUse --force to overwrite.`);
+          process.exit(1);
+        }
+      } else {
+        const ow = await p.confirm({
+          message: `The following file already exists. Overwrite it?\n${outFile}`,
+          initialValue: false,
+        });
+        if (p.isCancel(ow)) process.exit(0);
+        if (!ow) {
+          p.outro("Canceled (not overwritten)");
+          process.exit(0);
+        }
+      }
+    }
+  }
+
+  const spinner = !noPrompt ? p.spinner() : null;
+  spinner?.start(flags.quiet ? "Packing…" : "Preparing to pack…");
+
+  const progress = createProgressHandler({
+    spinner: flags.quiet ? null : spinner,
+    quiet: flags.quiet,
+    noPrompt,
+  });
+
+  try {
+    const { bytes, fileCount } = await writeArchive({
+      roots,
+      format,
+      outFile,
+      onProgress: flags.quiet ? undefined : progress.onProgress,
+    });
+    if (progress.state.stderrLine) {
+      process.stderr.write("\n");
+    }
+    spinner?.stop(`Packed: ${fileCount} files → ${outFile} (${bytes} bytes)`);
+    if (!noPrompt) {
+      p.outro("Done");
+    } else {
+      console.log(outFile);
+      console.log(`${fileCount} files, ${bytes} bytes`);
+    }
+  } catch (e) {
+    spinner?.stop("Failed", 1);
+    console.error(e);
+    process.exit(1);
+  }
+}

package/src/pack.mjs

@@ -0,0 +1,340 @@
+import { globby, isIgnoredByIgnoreFiles } from "globby";
+import { ZipArchive,TarArchive } from 'archiver'
+import {
+  createWriteStream,
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+const GITIGNORE = ".gitignore";
+
+/** Relative POSIX path from `root` to `target`, or null if `target` is not under `root`. */
+export function posixRelativeUnderRoot(rootAbs, targetAbs) {
+  const root = resolve(rootAbs);
+  const target = resolve(targetAbs);
+  const rel = relative(root, target);
+  if (rel === "" || rel.startsWith("..") || rel.startsWith(`..${sep}`)) {
+    return null;
+  }
+  return rel.split(sep).join("/");
+}
+
+/** Whether root `.gitignore` explicitly ignores itself (non-negated patterns). */
+export function rootGitignoreExplicitlyIgnoresSelf(text) {
+  for (const raw of text.split(/\r?\n/)) {
+    let line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const hash = line.indexOf("#");
+    if (hash !== -1) {
+      line = line.slice(0, hash).trimEnd();
+      if (!line) continue;
+    }
+    if (line.startsWith("!")) continue;
+    if (line === GITIGNORE || line === `/${GITIGNORE}` || line === `**/${GITIGNORE}`) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} rootAbs
+ * @param {{ ignoreRelative?: string[] }} [opts]
+ * @returns {Promise<string[]>} paths relative to root, POSIX separators
+ */
+export async function listPackablePaths(rootAbs, opts = {}) {
+  const ignore = [...(opts.ignoreRelative || [])].filter(Boolean);
+
+  let relPaths = await globby(["**/*"], {
+    cwd: rootAbs,
+    gitignore: true,
+    dot: true,
+    onlyFiles: true,
+    ignore,
+  });
+
+  relPaths = relPaths.map((p) => p.split(sep).join("/")).sort();
+
+  const giAbs = join(rootAbs, GITIGNORE);
+  if (existsSync(giAbs)) {
+    let selfExplicit = false;
+    try {
+      selfExplicit = rootGitignoreExplicitlyIgnoresSelf(readFileSync(giAbs, "utf8"));
+    } catch {
+      /* unreadable */
+    }
+    if (!selfExplicit && !relPaths.includes(GITIGNORE)) {
+      relPaths.push(GITIGNORE);
+      relPaths.sort();
+    }
+  }
+
+  return relPaths;
+}
+
+const GITIGNORE_FILES = "**/.gitignore";
+
+/**
+ * Leaf-empty directories under `rootAbs` (readdir has no entries), respecting the same
+ * `.gitignore` rules as {@link listPackablePaths} plus `ignoreRelative` glob entries.
+ *
+ * @param {string} rootAbs
+ * @param {{ ignoreRelative?: string[] }} [opts]
+ * @returns {Promise<string[]>} paths relative to root, POSIX separators, no trailing slash
+ */
+export async function listEmptyDirectoryPaths(rootAbs, opts = {}) {
+  const ignore = [...(opts.ignoreRelative || [])].filter(Boolean);
+  const isIgnored = await isIgnoredByIgnoreFiles(GITIGNORE_FILES, {
+    cwd: rootAbs,
+    dot: true,
+    ignore,
+  });
+
+  /** Gitignore `dir/` patterns match `rel/` only, not plain `rel`. */
+  const dirIgnored = (dirAbs) => {
+    if (isIgnored(dirAbs)) return true;
+    const rel = posixRelativeUnderRoot(rootAbs, dirAbs);
+    if (rel === null || rel === "") return false;
+    return isIgnored(`${rel}/`);
+  };
+
+  /** @type {string[]} */
+  const out = [];
+
+  /**
+   * @param {string} dirAbs
+   */
+  async function walk(dirAbs) {
+    const relToRoot = posixRelativeUnderRoot(rootAbs, dirAbs);
+    if (relToRoot !== null && relToRoot !== "") {
+      if (dirIgnored(dirAbs)) return;
+    }
+
+    /** @type {import('node:fs').Dirent[]} */
+    let entries;
+    try {
+      entries = await readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    let hasNonDir = false;
+    /** @type {string[]} */
+    const subdirs = [];
+    for (const ent of entries) {
+      // Treat anything other than a "real subdirectory" as content, so FIFO/socket entries
+      // (which are neither isFile nor isDirectory) are not misclassified as empty directories.
+      if (ent.isDirectory()) {
+        subdirs.push(join(dirAbs, ent.name));
+      } else {
+        hasNonDir = true;
+      }
+    }
+
+    for (const s of subdirs) {
+      await walk(s);
+    }
+
+    if (hasNonDir) return;
+    if (subdirs.length > 0) return;
+
+    if (relToRoot !== null && relToRoot !== "" && !dirIgnored(dirAbs)) {
+      out.push(relToRoot);
+    }
+  }
+
+  await walk(rootAbs);
+  return [...new Set(out)].sort();
+}
+
+/**
+ * @param {() => void} fn
+ * @param {number} ms
+ */
+function throttle(fn, ms) {
+  let last = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let pending = null;
+  return () => {
+    const now = Date.now();
+    const run = () => {
+      last = Date.now();
+      pending = null;
+      fn();
+    };
+    if (now - last >= ms) {
+      if (pending) {
+        clearTimeout(pending);
+        pending = null;
+      }
+      run();
+      return;
+    }
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(run, ms - (now - last));
+  };
+}
+
+/**
+ * @typedef {{
+ *   phase: 'collect';
+ *   index: number;
+ *   total: number;
+ *   root: string;
+ *   filesInRoot: number | null;
+ * }} ProgressCollect
+ * @typedef {{
+ *   phase: 'collect_done';
+ *   totalFiles: number;
+ * }} ProgressCollectDone
+ * @typedef {{
+ *   phase: 'compress';
+ *   entries: { total: number; processed: number };
+ *   fs: { totalBytes: number; processedBytes: number };
+ * }} ProgressCompress
+ * @typedef {ProgressCollect | ProgressCollectDone | ProgressCompress} ProgressEvent
+ */
+
+/**
+ * @param {{ roots: string[]; format: 'zip' | 'tar.gz'; outFile: string; onProgress?: (e: ProgressEvent) => void }} opts
+ * @returns {Promise<{ bytes: number; outFile: string; fileCount: number }>}
+ */
+export async function writeArchive(opts) {
+  const { roots, format, outFile, onProgress } = opts;
+  const outDir = dirname(outFile);
+  await mkdir(outDir, { recursive: true });
+
+  /** When packing multiple roots, disambiguate identical basenames by index to avoid path collisions inside the archive. */
+  const baseCounts = new Map();
+  if (roots.length > 1) {
+    for (const r of roots) {
+      const b = basename(resolve(r)) || "root";
+      baseCounts.set(b, (baseCounts.get(b) ?? 0) + 1);
+    }
+  }
+
+  /** @type {Array<{ kind: 'file'; disk: string; nameInArchive: string } | { kind: 'dir'; nameInArchive: string }>} */
+  const entries = [];
+  let fileCount = 0;
+
+  for (let ri = 0; ri < roots.length; ri++) {
+    const root = roots[ri];
+    const ignoreRel = [];
+    // Only exclude the archive path being generated, to prevent the output from being packed into itself (output may live inside the project directory).
+    const outRel = posixRelativeUnderRoot(root, outFile);
+    if (outRel) ignoreRel.push(outRel);
+
+    onProgress?.({
+      phase: "collect",
+      index: ri + 1,
+      total: roots.length,
+      root,
+      filesInRoot: null,
+    });
+
+    const rels = await listPackablePaths(root, { ignoreRelative: ignoreRel });
+    const emptyDirs = await listEmptyDirectoryPaths(root, {
+      ignoreRelative: ignoreRel,
+    });
+    const base = basename(resolve(root)) || "root";
+    const prefix =
+      roots.length === 1
+        ? ""
+        : (baseCounts.get(base) ?? 0) > 1
+          ? `${ri + 1}-${base}/`
+          : `${base}/`;
+
+    let addedHere = 0;
+    for (const rel of emptyDirs) {
+      const nameInArchive = prefix ? `${prefix}${rel}/` : `${rel}/`;
+      entries.push({ kind: "dir", nameInArchive });
+    }
+
+    for (const rel of rels) {
+      const disk = join(root, rel);
+      if (!existsSync(disk) || !statSync(disk).isFile()) continue;
+      const nameInArchive = prefix ? `${prefix}${rel}` : rel;
+      entries.push({ kind: "file", disk, nameInArchive });
+      fileCount += 1;
+      addedHere += 1;
+    }
+
+    onProgress?.({
+      phase: "collect",
+      index: ri + 1,
+      total: roots.length,
+      root,
+      filesInRoot: addedHere,
+    });
+  }
+
+  entries.sort((a, b) => {
+    if (a.kind !== b.kind) return a.kind === "dir" ? -1 : 1;
+    if (a.kind === "dir") {
+      return (
+        a.nameInArchive.length - b.nameInArchive.length ||
+        a.nameInArchive.localeCompare(b.nameInArchive)
+      );
+    }
+    return a.nameInArchive.localeCompare(b.nameInArchive);
+  });
+
+  onProgress?.({ phase: "collect_done", totalFiles: entries.length });
+
+  const output = createWriteStream(outFile);
+  const archive =
+    format === "zip"
+      ? new ZipArchive({ zlib: { level: 9 } })
+      : new TarArchive({ gzipOptions: { level: 9 } });
+
+  /** @type {(() => void) | null} */
+  let flushProgress = null;
+  if (onProgress) {
+    /** @type {{ entries: { total: number; processed: number }; fs: { totalBytes: number; processedBytes: number } } | null} */
+    let last = null;
+    const throttled = throttle(() => {
+      if (last) {
+        onProgress({ phase: "compress", entries: last.entries, fs: last.fs });
+      }
+    }, 120);
+    archive.on("progress", (p) => {
+      last = p;
+      throttled();
+    });
+    flushProgress = () => {
+      if (last) onProgress({ phase: "compress", entries: last.entries, fs: last.fs });
+    };
+  }
+
+  await new Promise((resolvePromise, reject) => {
+    archive.on("error", reject);
+    output.on("error", reject);
+    archive.on("warning", (err) => {
+      if (err.code !== "ENOENT") {
+        console.warn("[archiver]", err.message);
+      }
+    });
+    output.once("finish", resolvePromise);
+    archive.pipe(output);
+
+    for (const e of entries) {
+      if (e.kind === "file") {
+        archive.file(e.disk, { name: e.nameInArchive });
+      } else {
+        archive.append(Buffer.alloc(0), {
+          name: e.nameInArchive,
+          type: "directory",
+        });
+      }
+    }
+    archive.finalize();
+  });
+
+  flushProgress?.();
+
+  const bytes = statSync(outFile).size;
+  return { bytes, outFile, fileCount };
+}