chainlesschain 0.156.6 → 0.156.7

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

@@ -0,0 +1,162 @@
+/**
+ * Phase 5b: stream a packed exe to disk and verify its SHA-256 against the
+ * manifest. Self-replacement is Phase 5c; this module just writes the new
+ * artifact next to the old one (conventionally `<exePath>.new`).
+ *
+ * Design notes:
+ *   - Streaming, not buffered: artifacts are ~80-140 MB, so we write chunks
+ *     straight to disk and hash incrementally. Node's fetch yields a web
+ *     ReadableStream, which we consume via its async iterator.
+ *   - Atomicity: we write to `<outputPath>.partial` and rename on success.
+ *     A SHA mismatch or mid-stream failure deletes the partial so a retry
+ *     starts from scratch.
+ *   - No resume: first cut skips Range / If-Range. Large-artifact resume
+ *     is a Phase 5d concern if it becomes painful.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * @param {object} ctx
+ * @param {string}   ctx.url                  absolute http(s) URL to the artifact
+ * @param {string}   ctx.sha256               lowercase hex SHA-256 from the manifest
+ * @param {string}   ctx.outputPath           where the verified artifact lands
+ * @param {typeof fetch} [ctx.fetchImpl]      injected for tests
+ * @param {(p:{bytes:number,total:number|null})=>void} [ctx.onProgress]
+ *                                            fires as chunks arrive; total
+ *                                            is null if Content-Length was
+ *                                            absent or unparseable
+ * @returns {Promise<{outputPath:string,bytes:number,sha256:string}>}
+ */
+export async function downloadAndVerify(ctx) {
+  const { url, sha256, outputPath, fetchImpl = fetch, onProgress } = ctx;
+
+  if (!url || typeof url !== "string") {
+    throw new DownloadError("url is required", "NO_URL");
+  }
+  if (!sha256 || !SHA256_HEX.test(sha256)) {
+    throw new DownloadError(
+      `sha256 must be a 64-char lowercase hex string (got ${JSON.stringify(sha256)})`,
+      "BAD_SHA256",
+    );
+  }
+  if (!outputPath || typeof outputPath !== "string") {
+    throw new DownloadError("outputPath is required", "NO_OUTPUT");
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const partialPath = outputPath + ".partial";
+
+  // Clean up any stale partial from a prior interrupted attempt. Ignoring
+  // ENOENT is fine — we just want to start with a blank slate.
+  try {
+    fs.unlinkSync(partialPath);
+  } catch {
+    /* no prior partial */
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(url, { headers: { Accept: "*/*" } });
+  } catch (err) {
+    throw new DownloadError(
+      `fetch failed: ${err.message}`,
+      err?.name === "AbortError" ? "TIMEOUT" : "NETWORK_ERROR",
+    );
+  }
+  if (!response.ok) {
+    throw new DownloadError(
+      `artifact fetch failed: HTTP ${response.status}`,
+      "FETCH_FAILED",
+    );
+  }
+
+  const totalRaw = response.headers?.get?.("content-length");
+  const total = totalRaw ? Number(totalRaw) : null;
+  const body = response.body;
+  if (!body) {
+    throw new DownloadError(
+      "response has no body stream (fetch impl returned no body)",
+      "NO_BODY",
+    );
+  }
+
+  const hasher = crypto.createHash("sha256");
+  const out = fs.createWriteStream(partialPath);
+  let bytes = 0;
+
+  try {
+    // Web ReadableStream exposes an async iterator in Node ≥18. We prefer
+    // that over pumping via pipe() because we need to see each chunk for
+    // hashing + progress, and we want the final rename deterministic.
+    for await (const chunk of body) {
+      // `chunk` is a Uint8Array
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      hasher.update(buf);
+      bytes += buf.length;
+      const ok = out.write(buf);
+      if (!ok) {
+        await new Promise((r) => out.once("drain", r));
+      }
+      if (typeof onProgress === "function") {
+        try {
+          onProgress({ bytes, total: Number.isFinite(total) ? total : null });
+        } catch {
+          /* progress callback errors must not interrupt the download */
+        }
+      }
+    }
+    await new Promise((resolve, reject) => {
+      out.end((err) => (err ? reject(err) : resolve()));
+    });
+  } catch (err) {
+    try {
+      out.destroy();
+      fs.unlinkSync(partialPath);
+    } catch {
+      /* best effort */
+    }
+    throw new DownloadError(`stream aborted: ${err.message}`, "STREAM_ERROR");
+  }
+
+  const actualSha = hasher.digest("hex");
+  if (actualSha !== sha256.toLowerCase()) {
+    try {
+      fs.unlinkSync(partialPath);
+    } catch {
+      /* best effort */
+    }
+    throw new DownloadError(
+      `SHA-256 mismatch: expected ${sha256}, got ${actualSha}`,
+      "SHA_MISMATCH",
+    );
+  }
+
+  // Atomic rename — on Windows this fails if the destination exists; delete
+  // first. On POSIX rename atomically replaces, but the extra unlink is
+  // harmless and keeps behavior symmetric across platforms.
+  try {
+    fs.unlinkSync(outputPath);
+  } catch {
+    /* no prior artifact */
+  }
+  fs.renameSync(partialPath, outputPath);
+
+  return { outputPath, bytes, sha256: actualSha };
+}
+
+/**
+ * Typed error with a machine-readable `code`. The `cc pack check-update
+ * --download` command turns these into friendly messages + exit codes.
+ */
+export class DownloadError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "DownloadError";
+    this.code = code;
+  }
+}

package/src/lib/packer/pkg-config-generator.js

@@ -0,0 +1,325 @@
+/**
+ * Phase 5: pkg-config-generator
+ *
+ * Produce a transient pkg config (written next to a temp entry script) that
+ * tells @yao-pkg/pkg which scripts to compile and which assets to embed.
+ *
+ * The pkg config used here is the standard "pkg" key shape:
+ *   {
+ *     "scripts": ["src/**\/*.js"],
+ *     "assets":  ["src/assets/web-panel/**\/*", "templates/**\/*", "prebuilds/**\/*"],
+ *     "targets": ["node20-win-x64"],
+ *     "outputPath": "dist"
+ *   }
+ *
+ * We do NOT mutate the real packages/cli/package.json — we write a synthesized
+ * package.json into the build temp dir that re-exports the bin and adds the
+ * "pkg" key. pkg is invoked against that file.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.cliRoot                packages/cli/
+ * @param {string} ctx.tempDir                build temp dir
+ * @param {string} ctx.distDir                web-panel dist absolute path
+ * @param {string|null} ctx.prebuildsDir      prebuilds/ absolute path or null
+ * @param {string} ctx.templatesDir           templates/ absolute path
+ * @param {string[]} ctx.targets
+ * @param {string} ctx.outputPath             absolute output path (no ext)
+ * @param {boolean} ctx.compress
+ * @param {object}  [ctx.runtime]             defaults baked into the entry
+ * @param {string}  [ctx.runtime.token]       'auto' = regenerate each run,
+ *                                            '' = no auth, any other string
+ *                                            is hardcoded.
+ * @param {string}  [ctx.runtime.bindHost]    default --host for `ui`
+ * @param {number}  [ctx.runtime.wsPort]      default --ws-port
+ * @param {number}  [ctx.runtime.uiPort]      default --port
+ * @param {object|null} [ctx.project]         project-mode payload from
+ *                                            project-assets-collector. When
+ *                                            present, the entry script
+ *                                            materializes the bundled
+ *                                            .chainlesschain/ to a user-data
+ *                                            dir and chdirs into it.
+ * @param {string}  [ctx.project.projectDir]  tempDir/project absolute path
+ * @param {string}  [ctx.project.projectName]
+ * @param {string}  [ctx.project.configSha]
+ * @param {string}  [ctx.projectEntry]        default subcommand for project
+ *                                            mode (e.g. 'ui', 'chat'). If
+ *                                            omitted, reads from the bundled
+ *                                            config's `pack.entry` field.
+ * @param {boolean} [ctx.forceRefreshOnLaunch] re-materialize every launch
+ * @param {string|null} [ctx.updateManifestUrl] Phase 5a OTA manifest URL;
+ *                                            baked into BAKED.updateManifestUrl
+ *                                            and surfaced via `cc pack check-update`
+ * @returns {{ pkgConfigDir: string, pkgConfigFile: string, entryScript: string, projectMeta: object|null }}
+ */
+export function generatePkgConfig(ctx) {
+  const {
+    cliRoot,
+    tempDir,
+    distDir,
+    prebuildsDir,
+    templatesDir,
+    targets,
+    outputPath,
+    compress,
+    runtime = {},
+    project = null,
+    projectEntry,
+    forceRefreshOnLaunch = false,
+    updateManifestUrl = null,
+  } = ctx;
+
+  const bakedTokenMode =
+    typeof runtime.token === "string" ? runtime.token : "auto";
+  const bakedHost =
+    typeof runtime.bindHost === "string" && runtime.bindHost
+      ? runtime.bindHost
+      : "127.0.0.1";
+  const bakedWsPort = Number.isFinite(runtime.wsPort)
+    ? String(runtime.wsPort)
+    : "18800";
+  const bakedUiPort = Number.isFinite(runtime.uiPort)
+    ? String(runtime.uiPort)
+    : "18810";
+
+  // ── Project mode: read pack.* from bundled config ─────────────────────────
+  let projectBaked = null;
+  if (project) {
+    const bundledConfigPath = path.join(
+      project.projectDir,
+      ".chainlesschain",
+      "config.json",
+    );
+    let packConfig = {};
+    try {
+      const raw = JSON.parse(fs.readFileSync(bundledConfigPath, "utf-8"));
+      packConfig = raw.pack || {};
+    } catch {
+      /* already validated by Phase 3.5 — missing config falls back to defaults */
+    }
+
+    const resolvedEntry =
+      typeof projectEntry === "string" && projectEntry.trim()
+        ? projectEntry.trim()
+        : typeof packConfig.entry === "string" && packConfig.entry.trim()
+          ? packConfig.entry.trim()
+          : "ui";
+
+    projectBaked = {
+      projectMode: true,
+      projectName: project.projectName,
+      projectEntry: resolvedEntry,
+      projectConfigSha: project.configSha,
+      projectAutoPersona:
+        typeof packConfig.autoPersona === "string"
+          ? packConfig.autoPersona
+          : null,
+      projectAllowedSubcommands: Array.isArray(packConfig.allowedSubcommands)
+        ? packConfig.allowedSubcommands
+        : ["ui", "chat", "agent", "skill"],
+      // Absolute path to the bundled .chainlesschain/ inside the pkg snapshot FS.
+      // At runtime, pkg surfaces assets at their original absolute paths.
+      projectBundledDir: posixify(
+        path.join(project.projectDir, ".chainlesschain"),
+      ),
+      forceRefreshOnLaunch: Boolean(forceRefreshOnLaunch),
+    };
+  }
+
+  const pkgConfigDir = path.join(tempDir, "pkg-config");
+  fs.mkdirSync(pkgConfigDir, { recursive: true });
+
+  // Read the real CLI package.json to inherit version/dependencies
+  const realPkg = JSON.parse(
+    fs.readFileSync(path.join(cliRoot, "package.json"), "utf-8"),
+  );
+
+  // Phase 5a: bake OTA manifest URL + the exact CLI version shipped in this
+  // artifact so `cc pack check-update` can compare against the manifest's
+  // latest.cliVersion without relying on the unpacked CLI's VERSION constant.
+  const bakedObj = {
+    tokenMode: bakedTokenMode,
+    host: bakedHost,
+    wsPort: bakedWsPort,
+    uiPort: bakedUiPort,
+    packedCliVersion: realPkg.version || null,
+    updateManifestUrl:
+      typeof updateManifestUrl === "string" && updateManifestUrl
+        ? updateManifestUrl
+        : null,
+    ...(projectBaked || {}),
+  };
+
+  // Inline the real bin's logic directly. We can't use `import('...')`
+  // because pkg's snapshot bootstrap does not register a dynamic-import
+  // callback (ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING). Static ESM
+  // imports compile fine via yao-pkg's ESM mode.
+  const entryScript = path.join(pkgConfigDir, "pack-entry.js");
+  const ensureUtf8Path = posixify(
+    path.join(cliRoot, "src", "lib", "ensure-utf8.js"),
+  );
+  const indexPath = posixify(path.join(cliRoot, "src", "index.js"));
+  fs.writeFileSync(
+    entryScript,
+    [
+      "#!/usr/bin/env node",
+      "// pkg entry — inlines the real CLI bin (see bin/chainlesschain.js).",
+      "// CC_PACK_MODE flips the WS layer to allow chat/agent over execute.",
+      "process.env.CC_PACK_MODE = '1';",
+      "import crypto from 'node:crypto';",
+      "import fs from 'node:fs';",
+      "import os from 'node:os';",
+      "import path from 'node:path';",
+      `import { ensureUtf8 } from '${ensureUtf8Path}';`,
+      `import { createProgram } from '${indexPath}';`,
+      "ensureUtf8();",
+      "// Build-time defaults baked by the packer. Each is overridable at",
+      "// runtime either via the matching env var or by passing the flag.",
+      `const BAKED = Object.freeze(${JSON.stringify(bakedObj)});`,
+      "// Expose BAKED on globalThis so downstream subcommands (e.g. `cc pack",
+      "// check-update`) can read packedCliVersion / updateManifestUrl without",
+      "// importing from the packer. No-op in CLI-only builds outside pkg.",
+      "globalThis.BAKED = BAKED;",
+      "// Merge-copy helper: copies src tree into dest, skipping files that",
+      "// already exist (preserves user modifications). Used only in project mode.",
+      "function copyRecursiveMerge(src, dest) {",
+      "  if (!fs.existsSync(src)) return;",
+      "  fs.mkdirSync(dest, { recursive: true });",
+      "  for (const e of fs.readdirSync(src, { withFileTypes: true })) {",
+      "    const sp = path.join(src, e.name), dp = path.join(dest, e.name);",
+      "    if (e.isDirectory()) { copyRecursiveMerge(sp, dp); }",
+      "    else if (!fs.existsSync(dp)) { fs.copyFileSync(sp, dp); }",
+      "    else { console.warn('[cc-pack] Keeping existing file (user-modified):', dp); }",
+      "  }",
+      "}",
+      "// ── Project mode: materialize bundled .chainlesschain/ to user-data dir ──",
+      "// BAKED.projectMode is absent (falsy) in CLI-only builds — entire block skipped.",
+      "if (BAKED.projectMode) {",
+      "  const _userDataDir = path.join(",
+      "    os.homedir(), '.chainlesschain-projects',",
+      "    `${BAKED.projectName}-${BAKED.projectConfigSha.slice(0, 8)}`,",
+      "  );",
+      "  const _markerFile = path.join(_userDataDir, '.chainlesschain', '.pack-version');",
+      "  const _needsMaterialize =",
+      "    BAKED.forceRefreshOnLaunch ||",
+      "    !fs.existsSync(_markerFile) ||",
+      "    fs.readFileSync(_markerFile, 'utf8').trim() !== BAKED.projectConfigSha;",
+      "  if (_needsMaterialize) {",
+      "    copyRecursiveMerge(BAKED.projectBundledDir, path.join(_userDataDir, '.chainlesschain'));",
+      "    fs.mkdirSync(path.dirname(_markerFile), { recursive: true });",
+      "    fs.writeFileSync(_markerFile, BAKED.projectConfigSha, 'utf8');",
+      "  }",
+      "  process.env.CC_PROJECT_ROOT = _userDataDir;",
+      "  if (BAKED.projectAllowedSubcommands) {",
+      "    process.env.CC_PROJECT_ALLOWED_SUBCOMMANDS = BAKED.projectAllowedSubcommands.join(',');",
+      "  }",
+      "  // Phase 3b: expose the baked auto-persona via env so downstream",
+      "  // consumers (skill-loader / persona resolver) can pick it up.",
+      "  if (BAKED.projectAutoPersona) {",
+      "    process.env.CC_PACK_AUTO_PERSONA = BAKED.projectAutoPersona;",
+      "  }",
+      "}",
+      "// Double-click from Explorer arrives with no subcommand — without",
+      "// this default, commander prints help and exits, which looks like",
+      "// a black console 'flash and close'. In project mode the baked",
+      "// entry subcommand is used instead of the CLI-only 'ui' fallback.",
+      "const _rest = process.argv.slice(2);",
+      "const _hasSub = _rest.some((a) => a && !a.startsWith('-'));",
+      "const _argSet = new Set(_rest);",
+      "const _hasFlag = (...names) => names.some((n) => _argSet.has(n));",
+      "// Commander short-circuits --version / --help before running any",
+      "// command — don't pollute their stdout with the token banner and",
+      "// baked defaults they'd never see anyway.",
+      "const _shortCircuits = _hasFlag('-v', '--version', '-h', '--help');",
+      "if (!_hasSub && !_shortCircuits) {",
+      "  const _entryCmd = BAKED.projectMode ? BAKED.projectEntry : 'ui';",
+      "  for (const _p of _entryCmd.split(/\\s+/).filter(Boolean)) process.argv.push(_p);",
+      "  if (_entryCmd.split(/\\s+/)[0] === 'ui') {",
+      "    if (!_hasFlag('-p', '--port'))",
+      "      process.argv.push('--port', process.env.CC_PACK_UI_PORT || BAKED.uiPort);",
+      "    if (!_hasFlag('--ws-port'))",
+      "      process.argv.push('--ws-port', process.env.CC_PACK_WS_PORT || BAKED.wsPort);",
+      "    if (!_hasFlag('-H', '--host'))",
+      "      process.argv.push('--host', process.env.CC_PACK_HOST || BAKED.host);",
+      "    if (!_hasFlag('--token') && BAKED.tokenMode) {",
+      "      let tok = process.env.CC_PACK_TOKEN || BAKED.tokenMode;",
+      "      if (tok === 'auto') {",
+      "        tok = crypto.randomBytes(16).toString('hex');",
+      "        console.log('');",
+      "        console.log('  \\u2139  Access token (auto-generated this run):');",
+      "        console.log('     ' + tok);",
+      "        console.log('     set CC_PACK_TOKEN=<value> to pin a stable token.');",
+      "        console.log('');",
+      "      }",
+      "      process.argv.push('--token', tok);",
+      "    }",
+      "  }",
+      "}",
+      "// When launched from Explorer, Node exits as soon as the event loop",
+      "// drains. If something throws before the UI server starts listening,",
+      "// we want the user to see the error — pause on fatal errors.",
+      "process.on('uncaughtException', (err) => {",
+      "  console.error('\\n[cc-pack] Fatal error:', err && err.stack || err);",
+      "  if (process.stdin.isTTY) {",
+      "    console.error('\\nPress any key to exit...');",
+      "    try { process.stdin.setRawMode(true); process.stdin.resume(); process.stdin.once('data', () => process.exit(1)); } catch { process.exit(1); }",
+      "  } else { process.exit(1); }",
+      "});",
+      "const program = createProgram();",
+      "program.parse(process.argv);",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const assets = [
+    `${posixify(distDir)}/**/*`,
+    `${posixify(templatesDir)}/**/*`,
+  ];
+  if (prebuildsDir) assets.push(`${posixify(prebuildsDir)}/**/*`);
+  // Project mode: bundle the collected .chainlesschain/ snapshot as an asset.
+  // At runtime, pkg surfaces it at its original absolute path in the snapshot FS.
+  if (project) assets.push(`${posixify(project.projectDir)}/**/*`);
+
+  const synthesizedPkg = {
+    name: realPkg.name + "-pack",
+    version: realPkg.version,
+    bin: "pack-entry.js",
+    type: "module",
+    pkg: {
+      scripts: [
+        // Glob covers the entire CLI source tree, since dependencies are
+        // resolved from cliRoot/node_modules.
+        `${posixify(cliRoot)}/src/**/*.js`,
+        `${posixify(cliRoot)}/src/**/*.cjs`,
+        `${posixify(cliRoot)}/bin/**/*.js`,
+      ],
+      assets,
+      targets,
+      outputPath: path.dirname(outputPath),
+      compress: compress ? "GZip" : "None",
+    },
+  };
+
+  const pkgConfigFile = path.join(pkgConfigDir, "package.json");
+  fs.writeFileSync(
+    pkgConfigFile,
+    JSON.stringify(synthesizedPkg, null, 2),
+    "utf-8",
+  );
+
+  return {
+    pkgConfigDir,
+    pkgConfigFile,
+    entryScript,
+    projectMeta: projectBaked,
+  };
+}
+
+function posixify(p) {
+  return p.replace(/\\/g, "/");
+}

package/src/lib/packer/pkg-runner.js

@@ -0,0 +1,139 @@
+/**
+ * Phase 6: pkg-runner
+ *
+ * Spawn @yao-pkg/pkg with the synthesized config and capture output.
+ *
+ * Phase 1 implementation: prefer the locally-installed binary at
+ * node_modules/.bin/pkg (or @yao-pkg/pkg/lib-es5/bin.js). If pkg is not
+ * installed, throw a clear error pointing at `npm install -D @yao-pkg/pkg`.
+ *
+ * We deliberately avoid bundling pkg as a runtime dep — it's a dev tool and
+ * users who never run `cc pack` should not pay its install cost.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { PackError, EXIT } from "./errors.js";
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.cliRoot
+ * @param {string} ctx.pkgConfigFile     synthesized package.json path
+ * @param {string} ctx.outputPath        absolute final output path (no ext)
+ * @param {string[]} ctx.targets
+ * @param {object} [ctx.logger]
+ * @returns {{ outputs: string[] }}
+ */
+export function runPkg(ctx) {
+  const { cliRoot, pkgConfigFile, outputPath, targets, logger } = ctx;
+  const log = logger?.log || (() => {});
+
+  const pkgBin = locatePkgBinary(cliRoot);
+  if (!pkgBin) {
+    throw new PackError(
+      "@yao-pkg/pkg not found in node_modules. Install it as a devDependency:\n" +
+        "    npm install -D @yao-pkg/pkg --workspace packages/cli",
+      EXIT.PKG,
+    );
+  }
+
+  // Use --output to control the produced filename; pkg auto-appends platform
+  // suffix only when multiple targets are passed.
+  const args = [
+    pkgBin.script,
+    pkgConfigFile,
+    "--targets",
+    targets.join(","),
+    "--output",
+    outputPath,
+  ];
+
+  log(`  [pkg] Running: ${pkgBin.runtime} ${args.join(" ")}`);
+  const res = spawnSync(pkgBin.runtime, args, {
+    cwd: path.dirname(pkgConfigFile),
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  if (res.status !== 0) {
+    throw new PackError(
+      `pkg exited with code ${res.status}. See output above for details.`,
+      EXIT.PKG,
+    );
+  }
+
+  const outputs = collectOutputs(outputPath, targets);
+  if (outputs.length === 0) {
+    throw new PackError(
+      `pkg reported success but no output file found at ${outputPath}*`,
+      EXIT.PKG,
+    );
+  }
+  // Pair each produced artifact with the pkg target it came from. For a
+  // single target build, pkg writes to the bare --output path; for multi
+  // target it suffixes with "-<platformKey>". We match on the suffix
+  // when possible and fall back to positional pairing.
+  const rich = outputs.map((p) => {
+    const base = path.basename(outputPath);
+    const name = path.basename(p, path.extname(p));
+    const suffix = name.startsWith(base + "-")
+      ? name.slice(base.length + 1)
+      : null;
+    let target = null;
+    if (suffix && targets.length > 1) {
+      target = targets.find((t) => t.endsWith(suffix)) || null;
+    }
+    if (!target && targets.length === 1) target = targets[0];
+    return { path: p, target };
+  });
+  return { outputs: rich };
+}
+
+/**
+ * Locate a runnable pkg binary using node's resolution algorithm so we
+ * find both local and monorepo-hoisted installs of @yao-pkg/pkg (or
+ * legacy vercel/pkg) without hard-coding paths.
+ */
+function locatePkgBinary(cliRoot) {
+  const req = createRequire(path.join(cliRoot, "package.json"));
+  for (const pkgName of ["@yao-pkg/pkg", "pkg"]) {
+    try {
+      const pkgJson = req.resolve(`${pkgName}/package.json`);
+      const moduleDir = path.dirname(pkgJson);
+      const meta = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+      const binEntry = typeof meta.bin === "string" ? meta.bin : meta.bin?.pkg;
+      if (binEntry) {
+        const script = path.join(moduleDir, binEntry);
+        if (fs.existsSync(script)) {
+          return { runtime: process.execPath, script };
+        }
+      }
+    } catch {
+      /* not installed via this name */
+    }
+  }
+  return null;
+}
+
+/**
+ * For a single target, pkg writes to the exact --output path (with .exe on
+ * Windows). For multiple targets it suffixes -<platform>-<arch>.
+ */
+function collectOutputs(outputPath, targets) {
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) return [];
+  const base = path.basename(outputPath);
+  const all = fs.readdirSync(dir);
+  return all
+    .filter(
+      (name) =>
+        name === base ||
+        name.startsWith(base + "-") ||
+        name === base + ".exe" ||
+        name.startsWith(base + "-"),
+    )
+    .map((name) => path.join(dir, name))
+    .filter((p) => fs.statSync(p).isFile());
+}