chainlesschain 0.156.6 → 0.156.7

package/src/lib/packer/native-prebuild-collector.js

@@ -0,0 +1,305 @@
+/**
+ * Phase 4: native-prebuild-collector
+ *
+ * Locate prebuilt .node files for the optional native SQLite drivers
+ * (better-sqlite3-multiple-ciphers, better-sqlite3) and copy them into a
+ * per-target prebuilds/ folder that pkg will embed as assets.
+ *
+ * None of these are required: the runtime falls back to sql.js (WASM) —
+ * see packages/core-db/lib/database-manager.js `loadSQLiteDriver`. That
+ * fallback is what makes the pack runnable on platforms where the native
+ * module was never built (non-standard macOS/Linux hardware, CI images,
+ * ABI skew). We still try hard to include a native copy because it is
+ * 10-100x faster for typical workloads.
+ *
+ * Target identifier format mirrors @yao-pkg/pkg: nodeXX-<os>-<arch>
+ *   - nodeXX  -> module ABI (node20=115, node22=127)
+ *   - os      -> win, macos, linux, alpine
+ *   - arch    -> x64, arm64
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { PackError, EXIT } from "./errors.js";
+
+/**
+ * Modules we attempt to locate; all optional because sql.js covers the
+ * fallback. Missing ones are reported but never abort the build.
+ */
+const TARGET_MODULES = [
+  { name: "better-sqlite3-multiple-ciphers", required: false },
+  { name: "better-sqlite3", required: false },
+];
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.cliRoot
+ * @param {string[]} ctx.targets         e.g. ["node20-win-x64"]
+ * @param {string} ctx.tempDir           build temp dir
+ * @returns {{ prebuildsDir: string|null, collected: Array, missing: Array }}
+ */
+export function collectPrebuilds(ctx) {
+  const { cliRoot, targets, tempDir } = ctx;
+  const collected = [];
+  const missing = [];
+
+  if (!targets || targets.length === 0) {
+    return { prebuildsDir: null, collected, missing };
+  }
+
+  const prebuildsDir = path.join(tempDir, "prebuilds");
+  fs.mkdirSync(prebuildsDir, { recursive: true });
+
+  for (const target of targets) {
+    const platformKey = pkgTargetToPlatformKey(target);
+    if (!platformKey) {
+      throw new PackError(`Unrecognized pkg target: "${target}"`, EXIT.NATIVE);
+    }
+    const targetDir = path.join(prebuildsDir, platformKey);
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    for (const mod of TARGET_MODULES) {
+      const sourceNode = findInstalledNodeFile(cliRoot, mod.name);
+      if (!sourceNode) {
+        missing.push({ target, module: mod.name, required: mod.required });
+        continue;
+      }
+      const destFile = path.join(targetDir, `${mod.name}.node`);
+      fs.copyFileSync(sourceNode, destFile);
+      collected.push({
+        target,
+        module: mod.name,
+        from: sourceNode,
+        to: destFile,
+      });
+    }
+  }
+
+  // Nothing is hard-required anymore — the runtime falls back to sql.js
+  // (WASM) when no native driver loads. Callers should surface `missing`
+  // to the user so they understand the performance trade-off.
+  const sqlJs = collectSqlJsAssets(cliRoot, prebuildsDir);
+
+  return { prebuildsDir, collected, missing, sqlJs };
+}
+
+/**
+ * Copy sql.js runtime assets (sql-wasm.js + sql-wasm.wasm) into
+ * prebuildsDir/sqljs/ so the packed binary can find them. pkg itself
+ * cannot embed .wasm via dynamic require, so we treat it as an asset
+ * and load it from a disk path at runtime (database-manager falls back
+ * to sql.js automatically when natives are absent).
+ *
+ * Returns { assetDir, copied:[{from,to}] } or null when sql.js isn't
+ * installed — in that case the runtime will hit the "no SQLite driver"
+ * error, which the user will have seen flagged during pack.
+ */
+function collectSqlJsAssets(cliRoot, prebuildsDir) {
+  for (const dir of listCandidateModuleDirs(cliRoot, "sql.js")) {
+    const dist = path.join(dir, "dist");
+    if (!fs.existsSync(dist)) continue;
+    const js = path.join(dist, "sql-wasm.js");
+    const wasm = path.join(dist, "sql-wasm.wasm");
+    if (!fs.existsSync(js) || !fs.existsSync(wasm)) continue;
+
+    const assetDir = path.join(prebuildsDir, "sqljs");
+    fs.mkdirSync(assetDir, { recursive: true });
+    const copied = [];
+    for (const src of [js, wasm]) {
+      const to = path.join(assetDir, path.basename(src));
+      fs.copyFileSync(src, to);
+      copied.push({ from: src, to });
+    }
+    return { assetDir, copied };
+  }
+  return null;
+}
+
+/**
+ * Map "node20-win-x64" -> "win32-x64".
+ * Returns null for unrecognized targets.
+ */
+export function pkgTargetToPlatformKey(target) {
+  // node20-win-x64
+  const m = /^node\d+-([a-z]+)-([a-z0-9]+)$/.exec(target);
+  if (!m) return null;
+  const osMap = {
+    win: "win32",
+    macos: "darwin",
+    linux: "linux",
+    alpine: "linux",
+  };
+  const os = osMap[m[1]];
+  if (!os) return null;
+  return `${os}-${m[2]}`;
+}
+
+/**
+ * Collect ALL candidate install dirs for a module reachable from cliRoot.
+ * In a monorepo a module can exist in several places:
+ *   - the hoisted copy at <repoRoot>/node_modules/<mod> (often source-only,
+ *     no compiled binary)
+ *   - a transitive copy inside a sibling workspace package such as
+ *     <repoRoot>/packages/core-db/node_modules/<mod> (this one has the
+ *     actual compiled .node)
+ *   - the canonical resolved path returned by createRequire
+ *
+ * We return the union (in priority order) so the caller can pick the
+ * first candidate that actually has a usable .node binary, sidestepping
+ * the "resolver returns the source-only hoisted copy" trap.
+ */
+function listCandidateModuleDirs(cliRoot, moduleName) {
+  const out = [];
+  const seen = new Set();
+  const push = (dir) => {
+    if (!dir) return;
+    const norm = path.resolve(dir);
+    if (seen.has(norm)) return;
+    if (!fs.existsSync(path.join(norm, "package.json"))) return;
+    seen.add(norm);
+    out.push(norm);
+  };
+
+  // 1. Standard node resolution
+  try {
+    const req = createRequire(path.join(cliRoot, "package.json"));
+    push(path.dirname(req.resolve(`${moduleName}/package.json`)));
+  } catch {
+    /* skip */
+  }
+
+  // 2. Walk up parent chain
+  let cur = cliRoot;
+  while (true) {
+    push(path.join(cur, "node_modules", moduleName));
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  // 3. Sibling workspace packages may carry a nested copy with the
+  //    binary (common for monorepos with optional deps that the root
+  //    install hoisted but never built).
+  const repoRoot = findRepoRoot(cliRoot);
+  if (repoRoot) {
+    const packagesDir = path.join(repoRoot, "packages");
+    if (fs.existsSync(packagesDir)) {
+      let workspaces;
+      try {
+        workspaces = fs.readdirSync(packagesDir, { withFileTypes: true });
+      } catch {
+        workspaces = [];
+      }
+      for (const w of workspaces) {
+        if (!w.isDirectory()) continue;
+        push(path.join(packagesDir, w.name, "node_modules", moduleName));
+      }
+    }
+  }
+
+  // 4. Direct deps' nested node_modules (covers any other layout)
+  const directDeps = path.join(cliRoot, "node_modules");
+  if (fs.existsSync(directDeps)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(directDeps, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith("@")) {
+        const scopeDir = path.join(directDeps, e.name);
+        let scoped;
+        try {
+          scoped = fs.readdirSync(scopeDir, { withFileTypes: true });
+        } catch {
+          scoped = [];
+        }
+        for (const s of scoped) {
+          if (!s.isDirectory()) continue;
+          push(path.join(scopeDir, s.name, "node_modules", moduleName));
+        }
+      } else {
+        push(path.join(directDeps, e.name, "node_modules", moduleName));
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Crude monorepo root detection: nearest ancestor with a `packages/` dir. */
+function findRepoRoot(start) {
+  let cur = start;
+  while (true) {
+    if (fs.existsSync(path.join(cur, "packages"))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+/**
+ * Return the path to a usable .node file inside the given module dir,
+ * or null if this copy has no compiled binary (e.g. source-only hoist).
+ */
+function nodeFileInModuleDir(moduleDir, moduleName) {
+  const candidates = [
+    path.join(moduleDir, "build", "Release", `${moduleName}.node`),
+    path.join(
+      moduleDir,
+      "build",
+      "Release",
+      `${moduleName.replace(/-/g, "_")}.node`,
+    ),
+    // Generic fallback — a native fork (e.g. better-sqlite3-multiple-ciphers)
+    // often keeps its upstream binary name (better_sqlite3.node). Walk the
+    // whole build/Release dir before giving up.
+    path.join(moduleDir, "build", "Release"),
+    path.join(moduleDir, "prebuilds"),
+  ];
+
+  for (const c of candidates) {
+    if (!fs.existsSync(c)) continue;
+    const st = fs.statSync(c);
+    if (st.isFile()) return c;
+    if (st.isDirectory()) {
+      const nodeFile = findFirstNodeFile(c);
+      if (nodeFile) return nodeFile;
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk the candidate install dirs and return the first .node file found.
+ * This is what callers actually want.
+ */
+function findInstalledNodeFile(cliRoot, moduleName) {
+  for (const dir of listCandidateModuleDirs(cliRoot, moduleName)) {
+    const nodeFile = nodeFileInModuleDir(dir, moduleName);
+    if (nodeFile) return nodeFile;
+  }
+  return null;
+}
+
+function findFirstNodeFile(dir) {
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.name.endsWith(".node")) return full;
+    }
+  }
+  return null;
+}

package/src/lib/packer/pack-update-applier.js

@@ -0,0 +1,203 @@
+/**
+ * Phase 5c: replace the currently-running packed exe with a downloaded new
+ * artifact. This is the third step of the OTA chain:
+ *   Phase 5a (check) → Phase 5b (download+verify) → Phase 5c (apply)
+ *
+ * The two platform flavors behave very differently:
+ *
+ *   POSIX (Linux / macOS): the kernel keeps the running exe's inode open
+ *   independently of its directory entry. We can `rename(new, target)`
+ *   while the old process is still executing — the new bytes are on disk
+ *   under the target path, the old process continues running the old
+ *   inode until it exits, and a fresh spawn of `target` picks up the new
+ *   code. Clean, atomic, no sidecar.
+ *
+ *   Windows: the OS refuses to overwrite a running `.exe`. The only
+ *   reliable pattern is a sidecar script that (1) waits for the parent
+ *   PID to exit, (2) moves `<new>` → `<target>`, (3) optionally restarts.
+ *   We write a tiny `.cmd` to `%TEMP%` and spawn it detached; the parent
+ *   then exits on its own.
+ *
+ * All file-system mutations can be gated by `dryRun: true`, which just
+ * returns the plan (commands / paths the applier would have executed).
+ * Tests use `platform: 'win32' | 'posix'` to exercise both branches on any
+ * host without touching the running exe.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.newExePath              the verified artifact from Phase 5b
+ * @param {string} ctx.targetExePath           the exe to replace (usually process.execPath)
+ * @param {boolean} [ctx.restart=false]        spawn the new exe after replacement
+ * @param {boolean} [ctx.dryRun=false]         return the plan, do not mutate disk
+ * @param {"win32"|"posix"} [ctx.platform]     override host detection for tests
+ * @param {number} [ctx.parentPid]             PID to wait on (Windows sidecar); defaults to process.pid
+ * @param {(cmd:string,args:string[])=>object} [ctx.spawnImpl]  injected for tests
+ * @returns {Promise<{
+ *   platform: "win32"|"posix",
+ *   action: "replace-in-place"|"sidecar-cmd"|"dry-run",
+ *   targetExePath: string,
+ *   newExePath: string,
+ *   sidecarPath: string|null,
+ *   restartRequested: boolean,
+ * }>}
+ */
+export async function scheduleReplace(ctx) {
+  const {
+    newExePath,
+    targetExePath,
+    restart = false,
+    dryRun = false,
+    platform = process.platform === "win32" ? "win32" : "posix",
+    parentPid = process.pid,
+    spawnImpl = spawn,
+  } = ctx;
+
+  if (!newExePath || typeof newExePath !== "string") {
+    throw new ApplyError("newExePath is required", "NO_NEW_EXE");
+  }
+  if (!targetExePath || typeof targetExePath !== "string") {
+    throw new ApplyError("targetExePath is required", "NO_TARGET_EXE");
+  }
+  if (!fs.existsSync(newExePath)) {
+    throw new ApplyError(
+      `new exe does not exist: ${newExePath}`,
+      "NEW_EXE_MISSING",
+    );
+  }
+
+  if (dryRun) {
+    return {
+      platform,
+      action: "dry-run",
+      targetExePath,
+      newExePath,
+      sidecarPath: null,
+      restartRequested: Boolean(restart),
+    };
+  }
+
+  if (platform === "win32") {
+    const sidecarPath = writeWindowsSidecar({
+      newExePath,
+      targetExePath,
+      parentPid,
+      restart: Boolean(restart),
+    });
+    // Detach so the sidecar survives our process exit. `windowsHide: true`
+    // keeps the cmd window from flashing — the replace itself is silent.
+    const child = spawnImpl("cmd.exe", ["/c", sidecarPath], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    if (child && typeof child.unref === "function") child.unref();
+
+    return {
+      platform,
+      action: "sidecar-cmd",
+      targetExePath,
+      newExePath,
+      sidecarPath,
+      restartRequested: Boolean(restart),
+    };
+  }
+
+  // POSIX: atomic rename works even if targetExePath is the running exe.
+  // Preserve executable bit — a downloaded file from fetch defaults to 644.
+  try {
+    fs.chmodSync(newExePath, 0o755);
+  } catch {
+    /* best effort — non-fatal if chmod fails (e.g. on FAT32 volumes) */
+  }
+  try {
+    fs.renameSync(newExePath, targetExePath);
+  } catch (err) {
+    throw new ApplyError(`rename failed: ${err.message}`, "RENAME_FAILED");
+  }
+
+  if (restart) {
+    const child = spawnImpl(targetExePath, process.argv.slice(2), {
+      detached: true,
+      stdio: "ignore",
+    });
+    if (child && typeof child.unref === "function") child.unref();
+  }
+
+  return {
+    platform,
+    action: "replace-in-place",
+    targetExePath,
+    newExePath,
+    sidecarPath: null,
+    restartRequested: Boolean(restart),
+  };
+}
+
+/**
+ * Build the Windows sidecar `.cmd` that waits for the parent, moves the new
+ * exe over the target, and optionally restarts. Exposed (rather than inlined)
+ * so tests can read it back and assert on the shape without actually spawning.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.newExePath
+ * @param {string} ctx.targetExePath
+ * @param {number} ctx.parentPid
+ * @param {boolean} ctx.restart
+ * @returns {string} absolute path to the generated .cmd (lives in os.tmpdir())
+ */
+export function writeWindowsSidecar(ctx) {
+  const { newExePath, targetExePath, parentPid, restart } = ctx;
+
+  // `%TEMP%` is writable, survives across Explorer double-click launches, and
+  // gets auto-cleaned by Windows eventually. The unique name prevents two
+  // concurrent applies from clobbering each other.
+  const sidecarName = `cc-pack-apply-${Date.now()}-${Math.floor(Math.random() * 1e6)}.cmd`;
+  const sidecarPath = path.join(os.tmpdir(), sidecarName);
+
+  // tasklist /FI "PID eq <pid>" prints "INFO: No tasks..." when the PID is
+  // gone. We loop every 500ms up to ~10s; that's long enough for the parent
+  // to close its Electron/UI server gracefully but short enough to avoid
+  // stalling forever if the detection oddly fails.
+  const cmd = [
+    "@echo off",
+    "setlocal",
+    `set PARENT_PID=${parentPid}`,
+    `set NEW_EXE="${newExePath}"`,
+    `set TARGET_EXE="${targetExePath}"`,
+    "set /a ATTEMPTS=0",
+    ":waitloop",
+    'tasklist /FI "PID eq %PARENT_PID%" 2>NUL | find /I "%PARENT_PID%" >NUL',
+    "if errorlevel 1 goto doreplace",
+    "set /a ATTEMPTS=%ATTEMPTS%+1",
+    "if %ATTEMPTS% GEQ 20 goto doreplace",
+    // Timeout with /T /NOBREAK is the only idle-wait available in pure cmd.
+    "timeout /T 1 /NOBREAK >NUL",
+    "goto waitloop",
+    ":doreplace",
+    "move /Y %NEW_EXE% %TARGET_EXE% >NUL",
+    "if errorlevel 1 (",
+    "  echo cc-pack-apply: move failed & exit /b 1",
+    ")",
+    restart ? 'start "" %TARGET_EXE%' : "REM restart not requested",
+    // Self-delete — best effort. Leaving the .cmd in %TEMP% is harmless if
+    // this fails; Windows will reap it on the next disk-cleanup cycle.
+    '(goto) 2>NUL & del "%~f0"',
+  ].join("\r\n");
+
+  fs.writeFileSync(sidecarPath, cmd, { encoding: "utf-8" });
+  return sidecarPath;
+}
+
+export class ApplyError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "ApplyError";
+    this.code = code;
+  }
+}

package/src/lib/packer/pack-update-checker.js

@@ -0,0 +1,185 @@
+/**
+ * Phase 5a: cc pack check-update — manifest-based version check for packed exes.
+ *
+ * Unlike `cc update` (which runs `npm install -g chainlesschain@<v>`), a packed
+ * exe has no Node/npm to rely on. Instead, we publish a small JSON manifest at
+ * a known URL and have the exe fetch + compare + surface the diff. Download +
+ * self-replace are the job of Phase 5b/5c; this module only does the check.
+ *
+ * See docs/design/CC_PACK_打包指令设计文档.md §17.5-17.7.
+ *
+ * The expected manifest shape is:
+ *   {
+ *     schema: 1,
+ *     channel: "stable" | "beta",
+ *     latest: {
+ *       cliVersion: "0.157.0",
+ *       productVersion: "v5.0.3.0",
+ *       publishedAt: "2026-04-25T00:00:00Z",
+ *       releaseNotes: "https://…",
+ *       artifacts: [{ target, url, sha256 }, …]
+ *     }
+ *   }
+ *
+ * `target` matches pkg's `node20-<os>-<arch>` convention.
+ */
+
+import semver from "semver";
+
+const SUPPORTED_SCHEMA = 1;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Fetch a manifest URL and compare against the current version.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.manifestUrl          absolute http(s) URL
+ * @param {string} ctx.currentVersion       e.g. BAKED.packedCliVersion or VERSION
+ * @param {string} [ctx.target]             e.g. "node20-win-x64"; if set, the
+ *                                          returned artifact matches it
+ * @param {number} [ctx.timeoutMs=10000]
+ * @param {typeof fetch} [ctx.fetchImpl]    injected for tests
+ * @returns {Promise<{
+ *   updateAvailable: boolean,
+ *   currentVersion: string,
+ *   latestVersion: string,
+ *   artifact: {target:string,url:string,sha256:string}|null,
+ *   releaseNotes: string|null,
+ *   channel: string,
+ *   publishedAt: string|null,
+ * }>}
+ */
+export async function checkPackUpdate(ctx) {
+  const {
+    manifestUrl,
+    currentVersion,
+    target,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl = fetch,
+  } = ctx;
+
+  if (!manifestUrl || typeof manifestUrl !== "string") {
+    throw new PackUpdateError("manifestUrl is required", "NO_MANIFEST_URL");
+  }
+  if (!currentVersion || typeof currentVersion !== "string") {
+    throw new PackUpdateError(
+      "currentVersion is required",
+      "NO_CURRENT_VERSION",
+    );
+  }
+
+  let body;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(manifestUrl, {
+        headers: { Accept: "application/json" },
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        throw new PackUpdateError(
+          `manifest fetch failed: HTTP ${response.status}`,
+          "FETCH_FAILED",
+        );
+      }
+      body = await response.text();
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    if (err instanceof PackUpdateError) throw err;
+    const kind = err?.name === "AbortError" ? "TIMEOUT" : "NETWORK_ERROR";
+    throw new PackUpdateError(`manifest fetch failed: ${err.message}`, kind);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(body);
+  } catch (err) {
+    throw new PackUpdateError(
+      `manifest JSON parse failed: ${err.message}`,
+      "PARSE_FAILED",
+    );
+  }
+
+  return parseAndCompare(manifest, { currentVersion, target });
+}
+
+/**
+ * Pure parser — separated so tests can pass a manifest object directly
+ * without stubbing fetch.
+ *
+ * @param {object} manifest
+ * @param {object} ctx
+ * @param {string} ctx.currentVersion
+ * @param {string} [ctx.target]
+ */
+export function parseAndCompare(manifest, ctx) {
+  const { currentVersion, target } = ctx;
+
+  if (!manifest || typeof manifest !== "object") {
+    throw new PackUpdateError("manifest must be an object", "SCHEMA_MISMATCH");
+  }
+  if (manifest.schema !== SUPPORTED_SCHEMA) {
+    throw new PackUpdateError(
+      `unsupported manifest schema ${manifest.schema} (expected ${SUPPORTED_SCHEMA})`,
+      "SCHEMA_MISMATCH",
+    );
+  }
+  const latest = manifest.latest;
+  if (!latest || typeof latest.cliVersion !== "string") {
+    throw new PackUpdateError(
+      "manifest.latest.cliVersion missing",
+      "SCHEMA_MISMATCH",
+    );
+  }
+
+  const latestVersion = latest.cliVersion;
+  if (!semver.valid(latestVersion)) {
+    throw new PackUpdateError(
+      `manifest.latest.cliVersion "${latestVersion}" is not a valid semver`,
+      "INVALID_VERSION",
+    );
+  }
+  if (!semver.valid(currentVersion)) {
+    throw new PackUpdateError(
+      `currentVersion "${currentVersion}" is not a valid semver`,
+      "INVALID_VERSION",
+    );
+  }
+
+  const updateAvailable = semver.gt(latestVersion, currentVersion);
+
+  let artifact = null;
+  if (target && Array.isArray(latest.artifacts)) {
+    artifact =
+      latest.artifacts.find(
+        (a) => a && typeof a.target === "string" && a.target === target,
+      ) || null;
+  }
+
+  return {
+    updateAvailable,
+    currentVersion,
+    latestVersion,
+    artifact,
+    releaseNotes:
+      typeof latest.releaseNotes === "string" ? latest.releaseNotes : null,
+    channel: typeof manifest.channel === "string" ? manifest.channel : "stable",
+    publishedAt:
+      typeof latest.publishedAt === "string" ? latest.publishedAt : null,
+  };
+}
+
+/**
+ * Typed error with a machine-readable `code`. The `cc pack check-update`
+ * command turns these into friendly messages and non-zero exit codes.
+ */
+export class PackUpdateError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "PackUpdateError";
+    this.code = code;
+  }
+}