alp-code 0.9.0

package/scripts/lib/uninstall.cjs

@@ -0,0 +1,252 @@
+// uninstall.cjs — gỡ cài đặt alp-code nhưng không làm mất memory âm thầm.
+//
+// Mặc định:
+//   · gỡ config alp init khỏi mọi workspace còn tồn tại
+//   · chuyển memory ra một backup cạnh `~/.alp`
+//   · gỡ bản cài theo đúng cách của channel đó, gỡ shim/symlink `alp` và PATH do installer thêm
+//   · xoá state của alp-code trong `~/.alp` — theo DANH SÁCH TÊN, không xoá cả thư mục
+//   · giữ trust Claude/Codex: entry có thể đã tồn tại trước alp-code và để lại thì vô hại
+//
+// `--purge-memory` do alp.cjs chuyển vào mới cho phép memory bị xoá.
+//
+// Hai điều thay đổi từ v0.9.0, và cả hai đều là chuyện mất dữ liệu nếu làm sai:
+//
+//   1. Memory không còn nằm trong thư mục cài, mà ở `~/.alp/memory`. Xoá thư mục cài không
+//      còn đụng tới nó — nhưng xoá `~/.alp` thì đụng, nên chỗ đó phải xoá có chọn lọc.
+//   2. Thư mục cài không còn luôn là một git clone. Bản npm phải để npm gỡ; `rm -rf` sau
+//      lưng npm để lại một entry ma trong registry global của nó.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const CLI = require("./cli-link.cjs");
+const P = require("./install-paths.cjs");
+
+/**
+ * Những gì trong `~/.alp` thuộc về alp-code.
+ *
+ * Danh sách tên chứ không phải `rm -rf` cả thư mục: `~/.alp` là nhà chung, và một lệnh
+ * uninstall không có quyền xoá thứ nó không tạo ra. `memory` cố tình vắng mặt ở đây — nó đi
+ * đường riêng qua backup hoặc `--purge-memory`.
+ */
+const OWNED_STATE = [
+  "agents",
+  "hooks",
+  "executions",
+  "delegation",
+  "install.json",
+  "update-check.json",
+  "mode.json",
+  "projects.json",
+];
+
+function uninstall(repoRoot, opts = {}) {
+  repoRoot = path.resolve(repoRoot);
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const purgeMemory = !!opts.purgeMemory;
+  const force = !!opts.force;
+  const log = [];
+  const say = (level, text) => log.push({ level, text });
+
+  const channel = opts.channel || P.detectChannel(repoRoot);
+  const stateHome = opts.stateHome || P.stateHome(env);
+  const memory = opts.memoryRoot || P.memoryRoot(env);
+
+  assertInstallRoot(repoRoot);
+  if (isWithin(repoRoot, cwd))
+    throw new Error(`cwd đang nằm trong ${repoRoot} — cd ra ngoài thư mục này rồi chạy lại \`alp uninstall\``);
+  if (!force) assertGitSafe(repoRoot);
+
+  // Lấy registry machine-local trước khi xoá state.
+  const projects = opts.projectPaths || registeredProjects(repoRoot, platform, env);
+
+  // Memory đi trước mọi thao tác xoá: nếu bước sau hỏng, dữ liệu đã nằm an toàn ở backup.
+  let memoryBackup = null;
+  if (!purgeMemory && fs.existsSync(memory)) {
+    memoryBackup = nextBackupPath(stateHome, opts.now || new Date());
+    fs.renameSync(memory, memoryBackup);
+    say("SAVED", `${memory} → ${memoryBackup}`);
+  }
+
+  // Nếu gỡ bản cài thất bại, trả memory về chỗ cũ: một uninstall dở dang không được để dữ
+  // liệu bị tách khỏi một bản cài vẫn còn đang chạy.
+  try {
+    removeInstall(repoRoot, channel, opts, say);
+  } catch (error) {
+    if (memoryBackup && fs.existsSync(memoryBackup) && !fs.existsSync(memory)) {
+      try { fs.renameSync(memoryBackup, memory); } catch { /* backup vẫn còn, tên vẫn rõ */ }
+    }
+    throw error;
+  }
+
+  // Module đã được Node nạp vào RAM nên vẫn tiếp tục cleanup được sau khi thư mục cài biến mất.
+  cleanupProjects(projects, say);
+  removeOwnedState(stateHome, say);
+  const purged = purgeMemory && fs.existsSync(memory);
+  if (purged) fs.rmSync(memory, { recursive: true, force: true });
+  try {
+    for (const entry of CLI.uninstallCli(repoRoot, { ...opts, env, platform }))
+      say(entry.level, entry.text);
+  } catch (e) {
+    say("WARN", `không gỡ hết CLI/PATH: ${e.message}`);
+  }
+
+  if (purged) say("PURGED", `${memory} đã bị xoá theo yêu cầu --purge-memory`);
+  else if (!memoryBackup) say("ABSENT", `không có ${memory} để backup`);
+  say("KEEP", "trust Claude/Codex — vô hại và có thể đã tồn tại trước alp-code");
+  return { log, memoryBackup, projects, channel };
+}
+
+/**
+ * Gỡ thư mục cài theo đúng cách của channel.
+ *
+ * Bản npm phải do npm gỡ: `rm -rf` thư mục package để lại entry ma trong registry global,
+ * và lần `npm i -g alp-code` sau đó có thể im lặng không làm gì vì npm tin rằng nó đã cài rồi.
+ */
+function removeInstall(repoRoot, channel, opts, say) {
+  if (channel === "npm") {
+    const run = opts.runCommand || npmCommand;
+    const result = run("npm", ["uninstall", "--global", "alp-code"]);
+    if (result.error || result.status !== 0)
+      throw new Error(`\`npm uninstall -g alp-code\` thất bại: ${(result.stderr || result.error?.message || `exit ${result.status}`).toString().trim()}`);
+    say("REMOVED", `bản npm ${repoRoot} (qua npm uninstall -g)`);
+    return;
+  }
+
+  // Tarball: xoá cả nhà `~/.alp-code` — versions/, current, chứ không riêng version đang chạy.
+  const home = channel === "tarball" ? tarballHomeOf(repoRoot) : repoRoot;
+  try {
+    fs.rmSync(home, { recursive: true, force: false });
+  } catch (error) {
+    throw new Error(`không xoá được ${home}: ${error.message}`);
+  }
+  say("REMOVED", home);
+}
+
+/** `<home>/versions/<tag>` hoặc `<home>/current` → `<home>`; layout lạ thì giữ nguyên. */
+function tarballHomeOf(repoRoot) {
+  const parent = path.dirname(repoRoot);
+  if (path.basename(parent) === "versions") return path.dirname(parent);
+  if (path.basename(repoRoot) === "current") return parent;
+  return repoRoot;
+}
+
+function npmCommand(command, args) {
+  const { spawnSyncCommand } = require("./delegation/command-runner.cjs");
+  return spawnSyncCommand(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/**
+ * Xoá phần state của alp-code trong `~/.alp`, đúng từng tên trong OWNED_STATE.
+ *
+ * Thư mục này là nhà chung — `alp` bản khác, config, và những thứ người dùng tự để vào đều
+ * có thể đang ở đó. `rm -rf ~/.alp` là cách nhanh nhất để một lệnh gỡ cài đặt xoá mất thứ
+ * không phải của nó.
+ */
+function removeOwnedState(stateHome, say) {
+  if (!stateHome || !fs.existsSync(stateHome)) {
+    say("ABSENT", "state cục bộ");
+    return;
+  }
+  const removed = [];
+  for (const name of OWNED_STATE) {
+    const target = path.join(stateHome, name);
+    if (!fs.existsSync(target)) continue;
+    fs.rmSync(target, { recursive: true, force: true });
+    removed.push(name);
+  }
+  if (removed.length) say("REMOVED", `${stateHome}: ${removed.join(", ")}`);
+  else say("ABSENT", `${stateHome} không có state của alp-code`);
+  try { if (!fs.readdirSync(stateHome).length) fs.rmdirSync(stateHome); } catch { /* còn thứ của người khác */ }
+}
+
+function assertInstallRoot(repoRoot) {
+  if (path.dirname(repoRoot) === repoRoot)
+    throw new Error(`từ chối uninstall đường dẫn gốc: ${repoRoot}`);
+  for (const required of ["package.json", path.join("scripts", "alp.cjs")]) {
+    if (!fs.existsSync(path.join(repoRoot, required)))
+      throw new Error(`${repoRoot} không phải một bản cài alp-code (thiếu ${required})`);
+  }
+}
+
+/** Không xoá một dev clone còn việc chưa commit hoặc commit chưa push. */
+function assertGitSafe(repoRoot) {
+  if (!fs.existsSync(path.join(repoRoot, ".git"))) return;
+  const status = git(repoRoot, ["status", "--porcelain"]);
+  if (status.stdout.trim())
+    throw new Error("repo alp-code còn thay đổi chưa commit — xử lý trước, hoặc dùng --force nếu thật sự muốn xoá");
+
+  const upstream = git(repoRoot, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], true);
+  if (upstream.status !== 0) return;
+  const ahead = git(repoRoot, ["rev-list", "--count", "@{u}..HEAD"]);
+  if (Number(ahead.stdout.trim()) > 0)
+    throw new Error("repo alp-code có commit chưa push — push/backup trước, hoặc dùng --force nếu thật sự muốn xoá");
+}
+
+function git(repoRoot, args, allowFailure = false) {
+  const r = spawnSync("git", ["-C", repoRoot, ...args], { encoding: "utf8" });
+  if (r.error) throw new Error(`không chạy được git: ${r.error.message}`);
+  if (!allowFailure && r.status !== 0)
+    throw new Error((r.stderr || "").trim() || `git ${args[0]} thất bại (exit ${r.status})`);
+  return r;
+}
+
+function registeredProjects(repoRoot, platform, env = process.env) {
+  const file = path.join(P.stateHome(env), "projects.json");
+  if (!fs.existsSync(file)) return [];
+  const projects = JSON.parse(fs.readFileSync(file, "utf8")).projects || [];
+  return [...new Map(projects.map((entry) => {
+    const resolved = path.resolve(entry.path);
+    return [platform === "win32" ? resolved.toLowerCase() : resolved, resolved];
+  })).values()];
+}
+
+function cleanupProjects(projects, say) {
+  for (const project of projects) {
+    if (!fs.existsSync(project)) {
+      say("ABSENT", `${project} — workspace không còn trên đĩa`);
+      continue;
+    }
+    try {
+      for (const file of [path.join(project, ".claude", "settings.local.json"), path.join(project, ".codex", "config.toml")]) {
+        if (!fs.existsSync(file)) continue;
+        const body = fs.readFileSync(file, "utf8");
+        if (!body.toLowerCase().includes("alp init")) { say("KEEP", `${file} — không phải file do alp init sinh`); continue; }
+        fs.rmSync(file);
+        say("REMOVED", file);
+        const backup = `${file}.alp-backup`;
+        if (fs.existsSync(backup)) { fs.renameSync(backup, file); say("RESTORED", file); }
+      }
+    } catch (e) {
+      say("WARN", `${project} — không gỡ hết config cục bộ: ${e.message}`);
+    }
+  }
+}
+
+/** `~/.alp` → `~/.alp.memory-backup-<stamp>`: cạnh state home, không nằm trong thứ vừa bị xoá. */
+function nextBackupPath(anchor, now) {
+  const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const base = `${anchor}.memory-backup-${stamp}`;
+  let candidate = base;
+  for (let i = 2; fs.existsSync(candidate); i++) candidate = `${base}-${i}`;
+  return candidate;
+}
+
+function isWithin(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+module.exports = {
+  uninstall,
+  assertInstallRoot,
+  assertGitSafe,
+  registeredProjects,
+  nextBackupPath,
+  isWithin,
+  removeOwnedState,
+  tarballHomeOf,
+  OWNED_STATE,
+};

package/scripts/lib/update-check-worker.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Detached child entrypoint for the background "is there a newer release" check. Spawned by
+// src/cli/update-check.ts with stdio:"ignore" and unref()'d — this process outlives the `alp`
+// invocation that spawned it and must never throw uncaught or hang the caller.
+"use strict";
+
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const { resolveLatestReleaseTag } = require("./update.cjs");
+const { FileUpdateCheckStore } = require(path.join(repoRoot, "dist", "src", "cli", "update-check.js"));
+
+process.on("unhandledRejection", () => process.exit(0));
+
+(async () => {
+  const resolved = await resolveLatestReleaseTag(repoRoot, { timeoutMs: 4000 }).catch(() => ({ ok: false }));
+  await new FileUpdateCheckStore()
+    .write({ checkedAt: Date.now(), latestTag: resolved.ok ? resolved.tag : null })
+    .catch(() => {});
+  process.exit(0);
+})();

package/scripts/lib/update.cjs

@@ -0,0 +1,395 @@
+// `alp update`, một đường cho mỗi kiểu cài. Kiểu cài quyết định cách cập nhật, và cả ba đường
+// đều KHÔNG build gì trên máy người dùng nữa:
+//
+//   npm      — `npm install -g alp-code@<version>`; npm lo cả code lẫn dependency.
+//   tarball  — tải bundle của GitHub Release, giải nén sang `versions/<tag>` rồi trỏ lại
+//              `current`. Thư mục cũ còn nguyên tới khi bản mới đứng được.
+//   dev      — clone của người phát triển: vẫn checkout tag rồi build tại chỗ, vì đó chính là
+//              thứ một dev clone dùng để làm việc.
+//
+// Không còn bước backup/restore memory quanh update: từ v0.9.0 memory và mọi state khác nằm ở
+// `~/.alp`, ngoài tầm với của thứ đang bị thay. Chép dữ liệu qua lại quanh một thao tác không
+// đụng tới nó chỉ thêm một đường có thể hỏng.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const semver = require("./semver-lite.cjs");
+const P = require("./install-paths.cjs");
+
+const REPO_SLUG = "phucanh08/alp-code";
+
+function assertCleanWorkingTree(repoRoot, env) {
+  const staged = gitLines(repoRoot, ["diff", "--cached", "--name-only"], env);
+  if (!staged.ok) return failure(`không kiểm tra được staged changes: ${staged.message}`);
+  if (staged.lines.length)
+    return failure(`repo có staged changes; không tự cất: ${staged.lines.join(", ")}`);
+
+  const dirty = gitLines(repoRoot, ["diff", "--name-only"], env);
+  if (!dirty.ok) return failure(`không kiểm tra được working tree: ${dirty.message}`);
+
+  if (dirty.lines.length) return failure(`repo có tracked changes; không tự cất: ${dirty.lines.join(", ")}`);
+  return { ok: true };
+}
+
+async function resolveLatestReleaseTag(repoRoot, options = {}) {
+  const repoSlug = options.repoSlug || REPO_SLUG;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (fetchImpl) {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), options.timeoutMs || 5000);
+      const response = await fetchImpl(`https://api.github.com/repos/${repoSlug}/releases/latest`, {
+        signal: controller.signal,
+        headers: { "User-Agent": "alp-code-updater" },
+      });
+      clearTimeout(timer);
+      if (response.ok) {
+        const body = await response.json();
+        if (body && typeof body.tag_name === "string" && semver.isValid(body.tag_name)) {
+          return { ok: true, tag: body.tag_name, source: "github-api" };
+        }
+      }
+    } catch {
+      /* fall through to git-based fallback */
+    }
+  }
+  // `git ls-remote` chỉ là lối thoát cho dev clone. Bản cài từ npm hay tarball không có `.git`
+  // nào cả, nên hỏi git ở đó chắc chắn hỏng — và hỏng bằng một thông báo của git, che mất lý
+  // do thật là không gọi được GitHub API.
+  const remote = options.remote || "origin";
+  if (!fs.existsSync(path.join(repoRoot, ".git")))
+    return { ok: false, message: "không hỏi được GitHub Releases (mạng?) và bản cài này không phải git clone để tra tag" };
+  const listed = gitText(repoRoot, ["ls-remote", "--tags", "--refs", remote], options.env || process.env);
+  if (!listed.ok) return { ok: false, message: `không lấy được danh sách tag: ${listed.message}` };
+  const tags = listed.text
+    .split(/\r?\n/)
+    .map((line) => line.split("refs/tags/")[1])
+    .filter(Boolean)
+    .filter((tag) => semver.isValid(tag));
+  if (!tags.length) return { ok: false, message: "không tìm thấy tag phiên bản (vX.Y.Z) trên remote" };
+  tags.sort(semver.compare);
+  return { ok: true, tag: tags[tags.length - 1], source: "git-ls-remote" };
+}
+
+/**
+ * Git and npm are chatty, and `alp update` is a one-line errand: say which version you moved
+ * to, not every object counted and every package linked. Output is captured by default so a
+ * successful run stays quiet — `commandFailure` reads the same captured streams, so a failure
+ * still reports exactly what the tool said. `verbose: true` puts the firehose back, which is
+ * what the installers want and what a broken build needs.
+ */
+function quietStdio(options) {
+  return options.stdio || (options.verbose ? "inherit" : ["ignore", "pipe", "pipe"]);
+}
+
+function packageVersion(repoRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version || null;
+  } catch {
+    return null;
+  }
+}
+
+async function checkoutLatestRelease(repoRoot, options = {}) {
+  const env = options.env || process.env;
+  const stdio = quietStdio(options);
+  const log = options.log || (() => {});
+
+  const clean = assertCleanWorkingTree(repoRoot, env);
+  if (!clean.ok) return clean;
+  log("CHECK", "tracked source clean; machine-local project registry is outside git");
+
+  const remote = options.remote || "origin";
+  const fetched = runGit(repoRoot, ["fetch", "--tags", "--force", remote], { env, stdio });
+  if (!succeeded(fetched)) return failure(commandFailure("git fetch --tags", fetched));
+
+  const resolved = options.pinTag
+    ? { ok: true, tag: options.pinTag.startsWith("v") ? options.pinTag : `v${options.pinTag}`, source: "pinned" }
+    : await (options.resolveLatestReleaseTag || resolveLatestReleaseTag)(repoRoot, options);
+  if (!resolved.ok) return failure(resolved.message);
+
+  log("CHECKOUT", `${resolved.tag} (${resolved.source})`);
+  const checkedOut = runGit(repoRoot, ["checkout", "--detach", resolved.tag], { env, stdio });
+  if (!succeeded(checkedOut)) return failure(commandFailure(`git checkout ${resolved.tag}`, checkedOut));
+  return { ok: true, status: 0, tag: resolved.tag, source: resolved.source, preserved: [] };
+}
+
+/**
+ * `alp update` — chọn đường theo kiểu cài rồi đi.
+ *
+ * `options.channel` chỉ để test ép nhánh; ngoài đời kiểu cài đọc được từ chính thư mục cài,
+ * vì cùng một cây file đi cả npm lẫn tarball nên chỉ vị trí mới phân biệt được chúng.
+ */
+async function updateInstallation(repoRoot, options = {}) {
+  const channel = options.channel || P.detectChannel(repoRoot);
+  if (channel === "npm") return updateNpmInstall(repoRoot, options);
+  if (channel === "tarball") return updateTarballInstall(repoRoot, options);
+  return updateDevClone(repoRoot, options);
+}
+
+/** Version đích cho một bản cài, sau khi hỏi GitHub Release (hoặc theo `--version` đã ghim). */
+async function resolveTarget(repoRoot, options) {
+  const from = packageVersion(repoRoot);
+  const resolved = options.pinTag
+    ? { ok: true, tag: normalizeTag(options.pinTag), source: "pinned" }
+    : await (options.resolveLatestReleaseTag || resolveLatestReleaseTag)(repoRoot, options);
+  if (!resolved.ok) return { ok: false, message: resolved.message };
+  return { ok: true, from, tag: resolved.tag, version: resolved.tag.replace(/^v/, ""), source: resolved.source };
+}
+
+function normalizeTag(tag) {
+  return String(tag).startsWith("v") ? String(tag) : `v${tag}`;
+}
+
+/**
+ * Chạy `ensure-state.cjs` bằng một tiến trình MỚI trên thư mục cài MỚI.
+ *
+ * Không gọi thẳng `ensureState()` trong tiến trình này được: code đang chạy đến từ thư mục vừa
+ * bị thay, `require` một file chưa nạp sẽ đọc trúng bản đã bị xoá hoặc bản nửa cũ nửa mới.
+ */
+function runEnsureState(root, options) {
+  const spawnProcess = options.spawnProcess || spawnSync;
+  const result = spawnProcess(process.execPath, [path.join(root, "scripts", "ensure-state.cjs"), "--quiet"], {
+    cwd: root,
+    env: options.env || process.env,
+    stdio: quietStdio(options),
+  });
+  return succeeded(result) ? { ok: true } : failure(commandFailure("ensure-state.cjs", result));
+}
+
+// ------------------------------------------------------------------ channel npm
+
+async function updateNpmInstall(repoRoot, options = {}) {
+  const target = await resolveTarget(repoRoot, options);
+  if (!target.ok) return failure(target.message);
+  if (target.from === target.version && !options.force)
+    return { ok: true, tag: target.tag, from: target.from, to: target.from, channel: "npm", unchanged: true };
+
+  (options.onCheckout || (() => {}))({ from: target.from, tag: target.tag });
+  const runCommand = options.runCommand || spawnCommand;
+  const installed = runCommand("npm", ["install", "--global", `alp-code@${target.version}`], {
+    env: options.env || process.env,
+    stdio: quietStdio(options),
+  });
+  if (!succeeded(installed)) {
+    const detail = commandFailure("npm install -g", installed);
+    return failure(/EACCES|permission denied/i.test(detail)
+      ? `npm không ghi được vào thư mục global: ${detail}\n         Sửa quyền (npm config set prefix ~/.npm-global) hoặc cài lại bằng installer tarball.`
+      : detail);
+  }
+
+  const ensured = runEnsureState(repoRoot, options);
+  if (!ensured.ok) return ensured;
+  return { ok: true, tag: target.tag, from: target.from, to: packageVersion(repoRoot) || target.version, channel: "npm" };
+}
+
+// -------------------------------------------------------------- channel tarball
+
+/** `~/.alp-code` suy từ thư mục cài: `<home>/versions/<tag>` hoặc chính nó nếu layout cũ. */
+function tarballHomeFor(repoRoot, env) {
+  const resolved = path.resolve(repoRoot);
+  const parent = path.dirname(resolved);
+  return path.basename(parent) === "versions" ? path.dirname(parent) : resolved;
+}
+
+function bundleAssetName(tag) {
+  return `alp-code-${tag}-bundle.tar.gz`;
+}
+
+function bundleUrl(tag, options = {}) {
+  return `https://github.com/${options.repoSlug || REPO_SLUG}/releases/download/${tag}/${bundleAssetName(tag)}`;
+}
+
+async function updateTarballInstall(repoRoot, options = {}) {
+  const target = await resolveTarget(repoRoot, options);
+  if (!target.ok) return failure(target.message);
+  if (target.from === target.version && !options.force)
+    return { ok: true, tag: target.tag, from: target.from, to: target.from, channel: "tarball", unchanged: true };
+
+  (options.onCheckout || (() => {}))({ from: target.from, tag: target.tag });
+  const home = options.tarballHome ? path.resolve(options.tarballHome) : tarballHomeFor(repoRoot, options.env || process.env);
+  const installed = await installBundle(home, target.tag, options);
+  if (!installed.ok) return installed;
+
+  const ensured = runEnsureState(installed.root, options);
+  if (!ensured.ok) return ensured;
+  pruneVersions(home, [path.basename(installed.root), path.basename(path.resolve(repoRoot))]);
+  return { ok: true, tag: target.tag, from: target.from, to: target.version, channel: "tarball", root: installed.root };
+}
+
+/**
+ * Tải bundle về, giải nén sang một thư mục MỚI, rồi mới trỏ `current` sang đó.
+ *
+ * Thứ tự này là điểm mấu chốt: bản đang chạy không bị đụng tới cho đến khi bản mới đã nằm đủ
+ * trên đĩa. Tải dở giữa chừng hay tar hỏng thì `current` vẫn trỏ vào bản cũ và người dùng vẫn
+ * còn một `alp` chạy được — thay tại chỗ thì hỏng giữa chừng là mất luôn cả hai.
+ */
+async function installBundle(home, tag, options = {}) {
+  const versions = path.join(home, "versions");
+  const destination = path.join(versions, tag);
+  const staging = path.join(versions, `.incoming-${tag}-${process.pid}`);
+  fs.mkdirSync(versions, { recursive: true });
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.mkdirSync(staging, { recursive: true });
+
+  const archive = path.join(versions, `.${tag}-${process.pid}.tar.gz`);
+  try {
+    const downloaded = await downloadFile(bundleUrl(tag, options), archive, options);
+    if (!downloaded.ok) return failure(downloaded.message);
+
+    const extracted = (options.runCommand || spawnCommand)("tar", ["-xzf", archive, "-C", staging], {
+      stdio: quietStdio(options),
+      env: options.env || process.env,
+    });
+    if (!succeeded(extracted)) return failure(commandFailure("tar -xzf", extracted));
+    if (!fs.existsSync(path.join(staging, "scripts", "alp.cjs")))
+      return failure(`bundle ${bundleAssetName(tag)} không đúng cấu trúc — thiếu scripts/alp.cjs`);
+
+    fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staging, destination);
+  } finally {
+    fs.rmSync(archive, { force: true });
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+
+  const pointed = pointCurrent(home, destination);
+  if (!pointed.ok) return pointed;
+  return { ok: true, root: destination };
+}
+
+/**
+ * `<home>/current` → version đang dùng, thay bằng rename nên không có khoảnh khắc nào nó
+ * không trỏ đi đâu cả. Windows dùng junction: symlink thư mục ở đó cần quyền admin hoặc
+ * Developer Mode, junction thì không cần gì.
+ */
+function pointCurrent(home, target) {
+  const link = path.join(home, "current");
+  const temporary = path.join(home, `.current-${process.pid}`);
+  const type = process.platform === "win32" ? "junction" : "dir";
+  try {
+    fs.rmSync(temporary, { recursive: true, force: true });
+    fs.symlinkSync(target, temporary, type);
+    fs.rmSync(link, { recursive: true, force: true });
+    fs.renameSync(temporary, link);
+    return { ok: true, link };
+  } catch (error) {
+    fs.rmSync(temporary, { recursive: true, force: true });
+    return failure(`không trỏ được ${link} sang ${target}: ${error.message}`);
+  }
+}
+
+/** Giữ bản đang chạy và bản vừa cài, dọn phần còn lại — đủ để lùi một bước, không hơn. */
+function pruneVersions(home, keep) {
+  const versions = path.join(home, "versions");
+  let entries;
+  try { entries = fs.readdirSync(versions); } catch { return; }
+  for (const entry of entries) {
+    if (keep.includes(entry)) continue;
+    if (entry.startsWith(".incoming-")) { fs.rmSync(path.join(versions, entry), { recursive: true, force: true }); continue; }
+    if (!semver.isValid(entry)) continue;
+    fs.rmSync(path.join(versions, entry), { recursive: true, force: true });
+  }
+}
+
+async function downloadFile(url, destination, options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (!fetchImpl) return { ok: false, message: "Node này không có fetch — cần Node >= 18" };
+  try {
+    const response = await fetchImpl(url, { headers: { "User-Agent": "alp-code-updater" }, redirect: "follow" });
+    if (!response.ok) return { ok: false, message: `tải ${url} thất bại (HTTP ${response.status})` };
+    fs.writeFileSync(destination, Buffer.from(await response.arrayBuffer()));
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: `tải ${url} thất bại: ${error.message}` };
+  }
+}
+
+// ------------------------------------------------------------------ channel dev
+
+async function updateDevClone(repoRoot, options = {}) {
+  const from = packageVersion(repoRoot);
+  const checkedOut = await checkoutLatestRelease(repoRoot, options);
+  if (!checkedOut.ok) return checkedOut;
+  (options.onCheckout || (() => {}))({ from, tag: checkedOut.tag });
+
+  const spawnProcess = options.spawnProcess || spawnSync;
+  const built = spawnProcess(process.execPath, [path.join(repoRoot, "scripts", "bootstrap.cjs"), "--no-path"], {
+    cwd: repoRoot,
+    env: options.env || process.env,
+    stdio: quietStdio(options),
+  });
+  return succeeded(built)
+    ? { ...checkedOut, from, to: packageVersion(repoRoot), channel: "dev" }
+    : failure(commandFailure("bootstrap.cjs", built));
+}
+
+function spawnCommand(command, args, options) {
+  const { spawnSyncCommand } = require("./delegation/command-runner.cjs");
+  return spawnSyncCommand(command, args, options);
+}
+
+function onlyWorkspaceChanged(base, current) {
+  const normalizedBase = normalizeNewlines(base);
+  const normalizedCurrent = normalizeNewlines(current);
+  const workspacePattern = /^workspaces:\s*$\n(?:^[ \t]+.*(?:\n|$))*/m;
+  if (!workspacePattern.test(normalizedBase) || !workspacePattern.test(normalizedCurrent)) return false;
+  return normalizedBase.replace(workspacePattern, "workspaces:\n") ===
+    normalizedCurrent.replace(workspacePattern, "workspaces:\n");
+}
+
+function gitLines(repoRoot, args, env) {
+  const result = gitText(repoRoot, args, env);
+  return result.ok
+    ? { ok: true, lines: result.text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean) }
+    : result;
+}
+
+function gitText(repoRoot, args, env) {
+  const result = runGit(repoRoot, args, {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  return succeeded(result)
+    ? { ok: true, text: String(result.stdout || "") }
+    : { ok: false, message: commandFailure(`git ${args.join(" ")}`, result) };
+}
+
+function runGit(repoRoot, args, options) {
+  return spawnSync("git", ["-C", repoRoot, ...args], options);
+}
+
+function commandFailure(command, result) {
+  return String(result?.stderr || result?.stdout || result?.error?.message || `${command} exit ${result?.status}`).trim();
+}
+
+function succeeded(result) {
+  return !result.error && result.status === 0;
+}
+
+function failure(message) {
+  return { ok: false, status: 1, message, preserved: [] };
+}
+
+function normalizeNewlines(text) {
+  return String(text).replace(/\r\n/g, "\n");
+}
+
+module.exports = {
+  onlyWorkspaceChanged,
+  packageVersion,
+  assertCleanWorkingTree,
+  resolveLatestReleaseTag,
+  checkoutLatestRelease,
+  updateInstallation,
+  updateNpmInstall,
+  updateTarballInstall,
+  updateDevClone,
+  installBundle,
+  pointCurrent,
+  pruneVersions,
+  tarballHomeFor,
+  bundleAssetName,
+  bundleUrl,
+};