chainlesschain 0.156.6 → 0.157.0

package/src/lib/governance-v2-helpers.js

@@ -0,0 +1,109 @@
+/**
+ * Shared helpers for the "Governance V2" pattern used across 86+ surfaces
+ * (iter16–iter28 V2 ports) in packages/cli/src/lib/*.js.
+ *
+ * Every gov-V2 module declares roughly the same scaffolding:
+ *   - two Maps (profiles + jobs/sessions/etc.)
+ *   - four numeric caps (maxActivePerOwner, maxPendingPerProfile,
+ *     idleMs, stuckMs) with matching get/set pairs
+ *   - a positive-integer validator
+ *   - 4-state and 5-state transition tables + validators
+ *   - a _resetStateXxxGovV2() that re-initialises everything
+ *
+ * The shapes vary only in names and defaults, so these helpers let new
+ * (and migrated) modules replace ~50 lines of boilerplate with ~10.
+ *
+ * Migration guide: see GOV_V2_MIGRATION.md at repo root.
+ * `packages/cli` is an ESM package, so this helper exports ESM bindings.
+ */
+
+/**
+ * Validate that `n` is a finite positive integer. Throws with a label.
+ */
+function positiveInteger(n, label) {
+  const v = Math.floor(Number(n));
+  if (!Number.isFinite(v) || v <= 0) {
+    throw new Error(`${label} must be positive integer`);
+  }
+  return v;
+}
+
+/**
+ * Build a `checkTransition(from, to)` fn from a state-transition map.
+ * Throws with a domain-specific message when the transition is invalid.
+ *
+ * @param {Map<string, Set<string>>} transitions
+ * @param {string} label  e.g. "shgov profile"
+ */
+function createTransitionChecker(transitions, label) {
+  return function checkTransition(from, to) {
+    const allowed = transitions.get(from);
+    if (!allowed || !allowed.has(to)) {
+      throw new Error(`invalid ${label} transition ${from} → ${to}`);
+    }
+  };
+}
+
+/**
+ * Build a suite of cap (limit) accessors wired to a single mutable state
+ * object. Returns an object with `get<Name>V2()` / `set<Name>V2(n)` pairs
+ * for every field in `defaults`. The set variants run `positiveInteger`
+ * validation and apply the new value; reset() re-applies the defaults.
+ *
+ * @param {Object<string, number>} defaults map of capName → default value
+ * @returns {{ caps, resetCaps, setters, getters }}
+ */
+function createCapRegistry(defaults) {
+  const caps = { ...defaults };
+  const setters = {};
+  const getters = {};
+  for (const [name, defaultValue] of Object.entries(defaults)) {
+    setters[name] = (n) => {
+      caps[name] = positiveInteger(n, name);
+    };
+    getters[name] = () => caps[name];
+    // sanity: reject non-numeric defaults
+    if (!Number.isFinite(defaultValue) || defaultValue <= 0) {
+      throw new Error(
+        `governance-v2-helpers: default for ${name} must be a positive number`,
+      );
+    }
+  }
+  function resetCaps() {
+    for (const [name, defaultValue] of Object.entries(defaults)) {
+      caps[name] = defaultValue;
+    }
+  }
+  return { caps, resetCaps, setters, getters };
+}
+
+/**
+ * Count entries in a Map whose values satisfy `predicate`.
+ */
+function countBy(map, predicate) {
+  let c = 0;
+  for (const v of map.values()) {
+    if (predicate(v)) c++;
+  }
+  return c;
+}
+
+/**
+ * Build a state-transition Map from a plain object
+ *   { active: ["paused", "archived"], paused: ["active"] }
+ */
+function buildTransitionMap(table) {
+  const m = new Map();
+  for (const [from, tos] of Object.entries(table)) {
+    m.set(from, new Set(tos));
+  }
+  return m;
+}
+
+export {
+  positiveInteger,
+  createTransitionChecker,
+  createCapRegistry,
+  countBy,
+  buildTransitionMap,
+};

package/src/lib/packer/config-template-builder.js

@@ -0,0 +1,151 @@
+/**
+ * Phase 3: config-template-builder
+ *
+ * Build the .chainlesschain/ template that the artifact will release into the
+ * user's data dir on first run. Optionally merges a --preset-config provided
+ * by the packager, after a strict secret scan.
+ *
+ * Secrets policy: any non-empty string at a path matching SECRET_PATTERNS
+ * causes a hard error unless --allow-secrets is passed. Reason: if the
+ * packager accidentally bundles their own API key, every downstream user
+ * gets it.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { PackError, EXIT } from "./errors.js";
+
+/**
+ * Field paths (regex on the joined dotted path) that, if set to a non-empty
+ * string, are considered sensitive credentials.
+ */
+export const SECRET_PATTERNS = Object.freeze([
+  /(^|\.)apiKey$/i,
+  /(^|\.)api_key$/i,
+  /(^|\.)secret$/i,
+  /(^|\.)privateKey$/i,
+  /(^|\.)private_key$/i,
+  /(^|\.)mnemonic$/i,
+  /(^|\.)password$/i,
+  /(^|\.)token$/i,
+  /(^|\.)access_token$/i,
+  /(^|\.)refresh_token$/i,
+]);
+
+/**
+ * Walk an object, return [{ path, value }] for every leaf that matches a
+ * secret pattern with a non-empty string value. Numbers / booleans / nulls
+ * are ignored.
+ */
+export function findSecrets(obj, prefix = "") {
+  const hits = [];
+  if (obj === null || typeof obj !== "object") return hits;
+  for (const [key, val] of Object.entries(obj)) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      hits.push(...findSecrets(val, dotted));
+    } else if (typeof val === "string" && val.length > 0) {
+      if (SECRET_PATTERNS.some((re) => re.test(dotted))) {
+        hits.push({ path: dotted, value: val });
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * @param {object} ctx
+ * @param {string|null} ctx.presetConfigPath
+ * @param {boolean} ctx.allowSecrets
+ * @param {object} [ctx.logger]
+ * @returns {{ template: object, secrets: Array<{path:string}> }}
+ */
+export function buildConfigTemplate(ctx) {
+  const { presetConfigPath, allowSecrets, logger } = ctx;
+  const log = logger?.log || (() => {});
+
+  const baseTemplate = {
+    schema: 1,
+    server: {
+      bindHost: ctx.bindHost || "127.0.0.1",
+      wsPort: ctx.wsPort || 18800,
+      uiPort: ctx.uiPort || 18810,
+      enableTls: Boolean(ctx.enableTls),
+    },
+    llm: { providers: {} },
+    mcp: { servers: {} },
+    note: {},
+  };
+
+  let preset = null;
+  if (presetConfigPath) {
+    if (!fs.existsSync(presetConfigPath)) {
+      throw new PackError(
+        `--preset-config file not found: ${presetConfigPath}`,
+        EXIT.PRECHECK,
+      );
+    }
+    try {
+      preset = JSON.parse(fs.readFileSync(presetConfigPath, "utf-8"));
+    } catch (e) {
+      throw new PackError(
+        `--preset-config is not valid JSON: ${e.message}`,
+        EXIT.PRECHECK,
+      );
+    }
+  }
+
+  if (preset) {
+    const secrets = findSecrets(preset);
+    if (secrets.length > 0 && !allowSecrets) {
+      const list = secrets.map((s) => `    - ${s.path}`).join("\n");
+      throw new PackError(
+        `Preset config contains ${secrets.length} sensitive field(s):\n${list}\n` +
+          "  Refusing to bundle credentials into a distributable artifact.\n" +
+          "  Pass --allow-secrets to override (DANGEROUS), or remove the values from the preset.",
+        EXIT.SECRETS,
+      );
+    }
+    if (secrets.length > 0 && allowSecrets) {
+      log(
+        `  [config-template] WARNING: bundling ${secrets.length} secret value(s) — artifact must NOT be redistributed.`,
+      );
+    }
+    deepMerge(baseTemplate, preset);
+    return { template: baseTemplate, secrets };
+  }
+
+  return { template: baseTemplate, secrets: [] };
+}
+
+/**
+ * In-place deep merge: source overrides target on conflict; arrays replaced wholesale.
+ */
+function deepMerge(target, source) {
+  for (const [k, v] of Object.entries(source)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      !Array.isArray(v) &&
+      target[k] &&
+      typeof target[k] === "object" &&
+      !Array.isArray(target[k])
+    ) {
+      deepMerge(target[k], v);
+    } else {
+      target[k] = v;
+    }
+  }
+  return target;
+}
+
+/**
+ * Write the resolved template to disk inside the build temp dir.
+ * Returns the absolute path so pkg-config-generator can include it as an asset.
+ */
+export function writeTemplate(template, outDir) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, "config.example.json");
+  fs.writeFileSync(file, JSON.stringify(template, null, 2), "utf-8");
+  return file;
+}

package/src/lib/packer/errors.js

@@ -0,0 +1,30 @@
+/**
+ * PackError — typed error for the pack pipeline. Carries an exit code that
+ * `cc pack` propagates back to the OS so CI can branch on failure category.
+ *
+ * Exit code map (mirror docs/design/CC_PACK_打包指令设计文档.md §5.3):
+ *   10 — precheck failed
+ *   11 — web-panel build failed
+ *   12 — native module prebuild missing
+ *   13 — pkg build failed
+ *   14 — smoke test failed
+ *   15 — code-signing failed
+ *   16 — preset config contained sensitive credentials
+ */
+export class PackError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "PackError";
+    this.exitCode = exitCode;
+  }
+}
+
+export const EXIT = Object.freeze({
+  PRECHECK: 10,
+  WEB_PANEL: 11,
+  NATIVE: 12,
+  PKG: 13,
+  SMOKE: 14,
+  SIGN: 15,
+  SECRETS: 16,
+});

package/src/lib/packer/index.js

@@ -0,0 +1,383 @@
+/**
+ * `cc pack` orchestrator. Runs the 7-phase pipeline:
+ *   1. precheck            — git/node_modules sanity
+ *   2. ensureWebPanel      — Vue panel built or buildable
+ *   3. buildConfigTemplate — config.example.json with secret scan
+ *   4. collectPrebuilds    — better-sqlite3 .node files per target
+ *   5. generatePkgConfig   — synthesized package.json + pack-entry.js
+ *   6. runPkg              — invoke @yao-pkg/pkg
+ *   7. writeManifests      — sidecar metadata + SHA-256
+ *
+ * --dry-run stops after phase 5 and reports the build plan without
+ * invoking pkg or writing the artifact.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { precheck } from "./precheck.js";
+import { ensureWebPanel } from "./web-panel-builder.js";
+import {
+  buildConfigTemplate,
+  writeTemplate,
+} from "./config-template-builder.js";
+import { collectPrebuilds } from "./native-prebuild-collector.js";
+import { collectProjectAssets } from "./project-assets-collector.js";
+import { generatePkgConfig } from "./pkg-config-generator.js";
+import { runPkg } from "./pkg-runner.js";
+import { writeManifests } from "./manifest-writer.js";
+import { smokeTestExe } from "./smoke-runner.js";
+import { PackError } from "./errors.js";
+
+/**
+ * Public entry — invoked from packages/cli/src/commands/pack.js.
+ *
+ * @param {object} cliOpts                   raw Commander option object
+ * @param {object} [deps]
+ * @param {object} [deps.logger]             logger.log/info/error
+ * @returns {Promise<{outputPath?:string, sha256?:string, steps:Array}>}
+ */
+export async function runPack(cliOpts, deps = {}) {
+  const logger = deps.logger || console;
+  const log = (msg) => {
+    if (typeof logger.log === "function") logger.log(msg);
+    else if (typeof logger.info === "function") logger.info(msg);
+  };
+
+  const projectRoot = path.resolve(cliOpts.cwd || process.cwd());
+  const targets = (cliOpts.targets || "node20-win-x64")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  log(
+    chalk.bold("\n  cc pack — bundling project into standalone executable\n"),
+  );
+  log(`  Project root : ${projectRoot}`);
+  log(`  Targets      : ${targets.join(", ")}`);
+  log(`  Dry-run      : ${cliOpts.dryRun ? "YES" : "no"}`);
+  log("");
+
+  const steps = [];
+
+  // ── Phase 1 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [1/7] Precheck"));
+  const pre = precheck({
+    projectRoot,
+    allowDirty: Boolean(cliOpts.allowDirty),
+    projectMode: cliOpts.project, // tri-state: true / false / undefined
+    projectConfigOverride: cliOpts.projectConfigOverride || null,
+  });
+  steps.push({ phase: "precheck", ok: true, ...pre });
+  log(
+    `        cliRoot=${pre.cliRoot}\n` +
+      `        gitCommit=${pre.gitCommit || "(no git)"} dirty=${pre.dirty}\n` +
+      `        projectMode=${pre.projectMode} ` +
+      `projectConfig=${pre.projectConfigPath || "(none)"}`,
+  );
+
+  // ── Phase 2 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [2/7] Ensure web-panel"));
+  const wp = ensureWebPanel({
+    cliRoot: pre.cliRoot,
+    skipBuild: Boolean(cliOpts.skipWebPanelBuild),
+    logger,
+  });
+  steps.push({ phase: "web-panel", ok: true, ...wp });
+  log(
+    `        distDir=${wp.distDir}\n` +
+      `        rebuilt=${wp.rebuilt} assetCount=${wp.assetCount}`,
+  );
+
+  // ── Build temp dir (lives under OS tmp; cleaned on success) ────────────
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "cc-pack-"));
+  log(chalk.dim(`        tempDir=${tempDir}`));
+
+  // ── Phase 3 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [3/7] Build config template"));
+  const cfg = buildConfigTemplate({
+    presetConfigPath: cliOpts.presetConfig || null,
+    allowSecrets: Boolean(cliOpts.allowSecrets),
+    bindHost: cliOpts.bindHost,
+    wsPort: parseInt(cliOpts.wsPort, 10),
+    uiPort: parseInt(cliOpts.uiPort, 10),
+    enableTls: Boolean(cliOpts.enableTls),
+    logger,
+  });
+  const templatesDir = path.join(tempDir, "templates");
+  const templateFile = writeTemplate(cfg.template, templatesDir);
+  steps.push({
+    phase: "config-template",
+    ok: true,
+    file: templateFile,
+    secretsFound: cfg.secrets.length,
+  });
+  log(`        template=${templateFile}`);
+  log(`        secretsFound=${cfg.secrets.length}`);
+
+  // ── Phase 3.5 (project mode only) ─────────────────────────────────────
+  // Snapshot projectRoot/.chainlesschain/ into tempDir/project/ so pkg can
+  // bundle it as an asset. The runtime entry script materializes this at
+  // first launch. See docs/design/CC_PACK_项目模式_设计文档.md §6.
+  let project = null;
+  if (pre.projectMode) {
+    log(chalk.cyan("  [3.5/7] Collect project assets"));
+    project = collectProjectAssets({
+      projectRoot,
+      tempDir,
+      allowSecrets: Boolean(cliOpts.allowSecrets),
+      forceLargeProject: Boolean(cliOpts.forceLargeProject),
+      logger,
+    });
+    steps.push({
+      phase: "project-assets",
+      ok: true,
+      projectName: project.projectName,
+      fileCount: project.fileCount,
+      totalBytes: project.totalBytes,
+      bundledSkills: project.bundledSkills.map((s) => s.name),
+      configSha: project.configSha,
+    });
+    log(
+      `        projectName=${project.projectName}\n` +
+        `        files=${project.fileCount} size=${formatMB(project.totalBytes)}\n` +
+        `        bundledSkills=[${project.bundledSkills.map((s) => s.name).join(", ")}]\n` +
+        `        configSha=${project.configSha.slice(0, 12)}...`,
+    );
+  }
+
+  // ── Phase 4 ────────────────────────────────────────────────────────────
+  // None of the native drivers are required anymore — the runtime falls
+  // back to sql.js (WASM). Missing natives are reported, not fatal.
+  log(chalk.cyan("  [4/7] Collect native prebuilds"));
+  const native = collectPrebuilds({
+    cliRoot: pre.cliRoot,
+    targets,
+    tempDir,
+  });
+  steps.push({
+    phase: "native-prebuilds",
+    ok: true,
+    collected: native.collected.length,
+    missing: native.missing.length,
+    sqlJs: Boolean(native.sqlJs),
+  });
+  log(
+    `        collected=${native.collected.length} missing=${native.missing.length}` +
+      ` sqlJs=${native.sqlJs ? "bundled" : "absent"}`,
+  );
+  if (native.missing.length > 0) {
+    for (const m of native.missing) {
+      log(
+        chalk.yellow(
+          `        - missing: ${m.module} (${m.target}) — will fall back to sql.js at runtime`,
+        ),
+      );
+    }
+  }
+  if (native.collected.length === 0 && !native.sqlJs) {
+    log(
+      chalk.red(
+        "        WARN: no native SQLite driver found AND sql.js not installed.\n" +
+          "              The packed binary will fail at DB init. Install sql.js" +
+          " in the workspace before packing.",
+      ),
+    );
+  }
+
+  // ── Phase 5 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [5/7] Generate pkg config"));
+  // In project mode the artifact is named after the project, not the CLI.
+  const artifactBase =
+    pre.projectMode && project?.projectName
+      ? `${project.projectName}-portable-${targets[0]}`
+      : `chainlesschain-portable-${targets[0]}`;
+  const outputPath = path.resolve(
+    cliOpts.output || path.join(projectRoot, "dist", artifactBase),
+  );
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const pkgCfg = generatePkgConfig({
+    cliRoot: pre.cliRoot,
+    tempDir,
+    distDir: wp.distDir,
+    prebuildsDir: native.prebuildsDir,
+    templatesDir,
+    targets,
+    outputPath,
+    compress: cliOpts.compress !== false,
+    runtime: {
+      token: typeof cliOpts.token === "string" ? cliOpts.token : "auto",
+      bindHost: cliOpts.bindHost,
+      wsPort: parseInt(cliOpts.wsPort, 10),
+      uiPort: parseInt(cliOpts.uiPort, 10),
+    },
+    project,
+    projectEntry: cliOpts.entry || null,
+    forceRefreshOnLaunch: Boolean(cliOpts.forceRefreshOnLaunch),
+    updateManifestUrl: cliOpts.updateManifestUrl || null,
+  });
+  steps.push({
+    phase: "pkg-config",
+    ok: true,
+    pkgConfigFile: pkgCfg.pkgConfigFile,
+    entryScript: pkgCfg.entryScript,
+  });
+  log(`        pkgConfig=${pkgCfg.pkgConfigFile}`);
+  log(`        entry=${pkgCfg.entryScript}`);
+
+  if (cliOpts.dryRun) {
+    log(chalk.yellow("\n  [dry-run] Stopping before pkg invocation."));
+    log(chalk.dim(`  Plan written to: ${pkgCfg.pkgConfigFile}`));
+    return { steps, dryRun: true, tempDir, project };
+  }
+
+  // ── Phase 6 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [6/7] Run pkg"));
+  const built = runPkg({
+    cliRoot: pre.cliRoot,
+    pkgConfigFile: pkgCfg.pkgConfigFile,
+    outputPath,
+    targets,
+    logger,
+  });
+  steps.push({ phase: "pkg-run", ok: true, outputs: built.outputs });
+  log(`        outputs=${built.outputs.length}`);
+
+  // ── Phase 7 ────────────────────────────────────────────────────────────
+  log(chalk.cyan("  [7/7] Write manifest"));
+  const manifests = writeManifests({
+    outputs: built.outputs,
+    cliRoot: pre.cliRoot,
+    gitCommit: pre.gitCommit,
+    gitDirty: pre.dirty,
+    targets,
+    ports: {
+      ws: parseInt(cliOpts.wsPort, 10),
+      ui: parseInt(cliOpts.uiPort, 10),
+    },
+    includeDb: cliOpts.includeDb !== false,
+    includeModels: Boolean(cliOpts.includeModels),
+    commands: [],
+  });
+  steps.push({ phase: "manifest", ok: true, count: manifests.length });
+
+  // Project manifest sidecar: <artifact>.project.json beside each exe.
+  if (project && manifests.length > 0) {
+    const projectManifest = {
+      schema: 1,
+      projectName: project.projectName,
+      configSha: project.configSha,
+      fileCount: project.fileCount,
+      bundledSkills: project.bundledSkills.map((s) => ({
+        name: s.name,
+        dir: s.dir,
+      })),
+    };
+    for (const { artifact } of manifests) {
+      fs.writeFileSync(
+        artifact + ".project.json",
+        JSON.stringify(projectManifest, null, 2),
+        "utf-8",
+      );
+    }
+  }
+
+  // ── Phase 8 (optional) ────────────────────────────────────────────────
+  // The `--no-smoke-test` flag and cross-target builds skip this: pkg can
+  // compile a linux-x64 artifact on Windows, but we can't execute it. We
+  // also skip when the artifact is for an OS/arch other than the host.
+  const hostTargetable = targets.filter((t) => isHostExecutable(t));
+  const smokeable = built.outputs.filter((o) =>
+    hostTargetable.some((t) => o.target === t),
+  );
+  if (cliOpts.smokeTest !== false && smokeable.length > 0) {
+    log(chalk.cyan("  [8/8] Smoke-test artifact"));
+    for (const out of smokeable) {
+      log(`        probing: ${out.path}`);
+      try {
+        // Pick ports guaranteed not to clash with a user's running
+        // instance on the defaults 18800/18810. These flow into the
+        // spawned exe via CC_PACK_{UI,WS}_PORT env.
+        const res = await smokeTestExe({
+          exePath: out.path,
+          uiPort: 18951,
+          wsPort: 18950,
+          bundledSkillNames: project?.bundledSkills?.map((s) => s.name) ?? null,
+          logger,
+        });
+        steps.push({
+          phase: "smoke",
+          ok: true,
+          target: out.target,
+          uiStatus: res.uiStatus,
+          wsListening: res.wsListening,
+        });
+      } catch (e) {
+        steps.push({
+          phase: "smoke",
+          ok: false,
+          target: out.target,
+          error: e.message,
+        });
+        throw e;
+      }
+    }
+  } else if (cliOpts.smokeTest === false) {
+    log(chalk.dim("  [8/8] Smoke-test skipped (--no-smoke-test)"));
+  } else {
+    log(
+      chalk.dim(
+        `  [8/8] Smoke-test skipped — no host-executable target in ${targets.join(",")}`,
+      ),
+    );
+  }
+
+  // Optional cleanup of temp dir on success
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+
+  // For UX, return the first artifact path
+  const first = manifests[0] || {};
+  return {
+    outputPath: first.artifact,
+    sha256: first.sha256,
+    manifests,
+    steps,
+    project, // null in CLI-only mode
+  };
+}
+
+/**
+ * Return true if a pkg target can actually run on the current host. We
+ * only smoke-test artifacts that match the host platform+arch — pkg can
+ * cross-compile to other OS/arch combos, but we have no way to execute
+ * them locally. The small shape of the target string (`nodeXX-<os>-<arch>`)
+ * makes a purely string comparison safe.
+ */
+function isHostExecutable(target) {
+  const parts = String(target).split("-");
+  if (parts.length < 3) return false;
+  const [, os, arch] = parts;
+  const hostOs =
+    process.platform === "win32"
+      ? "win"
+      : process.platform === "darwin"
+        ? "macos"
+        : "linux";
+  const hostArch = process.arch; // 'x64' | 'arm64' | ...
+  // 'alpine' is linux with musl; still host-executable on a glibc host in
+  // practice for smoke tests, but skip to avoid false negatives.
+  if (os === "alpine") return false;
+  return os === hostOs && arch === hostArch;
+}
+
+function formatMB(bytes) {
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+// Re-export the typed error so callers can introspect exit codes if needed.
+export { PackError };