alp-code 0.9.0

package/scripts/lib/install-paths.cjs

@@ -0,0 +1,154 @@
+// install-paths.cjs — một chỗ duy nhất trả lời "alp-code để thứ gì ở đâu".
+//
+// VÌ SAO TỒN TẠI: từ v0.9.0 thư mục cài là một ARTIFACT DÙNG MỘT LẦN. `npm i -g alp-code`
+// xoá sạch package dir cũ rồi giải nén bản mới; installer tarball giải nén vào
+// `versions/<tag>` rồi trỏ lại symlink `current`. Bất cứ thứ gì của người dùng nằm trong đó
+// đều biến mất ở lần update kế tiếp — nên KHÔNG có gì của người dùng được nằm trong đó nữa.
+//
+// Ranh giới:
+//   · thư mục cài  — code đã build, hooks, skills, scaffold. Chỉ đọc, thay được bất cứ lúc nào.
+//   · `~/.alp`     — memory, identity docs, execution/delegation state, preferences. Không ai
+//                    thay hộ, không ai xoá hộ.
+//
+// Đây đúng là mô hình `npm i -g @anthropic-ai/claude-code` + `~/.claude` mà Claude Code và
+// Codex CLI dùng, và là lý do cả hai bỏ được bước build ở máy người dùng.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/** Thư mục cài mặc định của channel tarball — cũng là chỗ các bản < v0.9.0 clone về. */
+const LEGACY_INSTALL_HOME = ".alp-code";
+
+function homeDir(env) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  if (!home) throw new Error("không xác định được HOME/USERPROFILE");
+  return home;
+}
+
+/** `~/.alp` — gốc của mọi state cục bộ. `ALP_STATE_HOME` để test và cài song song. */
+function stateHome(env = process.env) {
+  return env.ALP_STATE_HOME ? path.resolve(env.ALP_STATE_HOME) : path.join(homeDir(env), ".alp");
+}
+
+/**
+ * Gốc memory. `ALP_MEMORY_ROOT` vẫn thắng — doctor, adapter và test đã dựa vào nó từ trước,
+ * và đó là đường duy nhất để chạy một ALP cô lập hoàn toàn.
+ */
+function memoryRoot(env = process.env) {
+  return env.ALP_MEMORY_ROOT ? path.resolve(env.ALP_MEMORY_ROOT) : path.join(stateHome(env), "memory");
+}
+
+/** `~/.alp/agents/<role>.md` — cache identity phẳng cho SessionStart hook. */
+function agentsDir(env = process.env) {
+  return path.join(stateHome(env), "agents");
+}
+
+/** `~/.alp/hooks/` — forwarder có đường dẫn ỔN ĐỊNH; xem `hookForwarderPath`. */
+function hooksDir(env = process.env) {
+  return path.join(stateHome(env), "hooks");
+}
+
+function executionsDir(env = process.env) {
+  return path.join(stateHome(env), "executions");
+}
+
+/**
+ * Đường dẫn hook mà `alp init` ghi vào `<project>/.claude/settings.local.json`.
+ *
+ * KHÔNG BAO GIỜ trỏ thẳng vào thư mục cài. Cấu hình đó nằm trong project của người dùng và
+ * sống lâu hơn mọi bản cài: đổi channel (tarball → npm), gỡ rồi cài lại chỗ khác, hay chỉ là
+ * lên version với tarball `versions/<tag>` mới — tất cả đều làm một đường dẫn tuyệt đối tới
+ * thư mục cài chết câm, và người dùng chỉ thấy phiên `claude` mất identity mà không rõ vì sao.
+ */
+function hookForwarderPath(name, env = process.env) {
+  return path.join(hooksDir(env), `${name}.cjs`);
+}
+
+/** Bản ghi bản cài hiện hành. Forwarder đọc file này để tìm thư mục cài. */
+function installRecordPath(env = process.env) {
+  return path.join(stateHome(env), "install.json");
+}
+
+function readInstallRecord(env = process.env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(installRecordPath(env), "utf8"));
+    return typeof parsed?.root === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeInstallRecord(record, env = process.env) {
+  const file = installRecordPath(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Channel của một thư mục cài, suy ra từ CHÍNH nó chứ không từ marker ghi lúc đóng gói:
+ * cùng một cây file được `npm publish` và được nén vào tarball, nên nội dung không phân biệt
+ * được hai bản cài — chỉ vị trí mới phân biệt được.
+ *
+ *   dev      — có `.git` và `src/`: bản clone của người phát triển, vẫn build tại chỗ.
+ *   npm      — nằm dưới một `node_modules/`: npm sở hữu thư mục này.
+ *   tarball  — còn lại: artifact giải nén, thường là `~/.alp-code/versions/<tag>`.
+ */
+function detectChannel(root) {
+  const resolved = path.resolve(root);
+  if (fs.existsSync(path.join(resolved, ".git")) && fs.existsSync(path.join(resolved, "src")))
+    return "dev";
+  if (resolved.split(path.sep).includes("node_modules")) return "npm";
+  return "tarball";
+}
+
+/** Gốc cài mặc định cho channel tarball: `~/.alp-code`, với `current` trỏ vào version đang dùng. */
+function tarballHome(env = process.env) {
+  return env.ALP_HOME ? path.resolve(env.ALP_HOME) : path.join(homeDir(env), LEGACY_INSTALL_HOME);
+}
+
+function tarballCurrentLink(env = process.env) {
+  return path.join(tarballHome(env), "current");
+}
+
+function tarballVersionsDir(env = process.env) {
+  return path.join(tarballHome(env), "versions");
+}
+
+/**
+ * Những chỗ memory có thể còn nằm lại từ bản < v0.9.0, theo thứ tự ưu tiên di trú.
+ * `root` là thư mục cài hiện tại; bản cũ thì chính nó là repo clone chứa `memory/`.
+ */
+function legacyMemoryRoots(root, env = process.env) {
+  const candidates = [
+    path.join(path.resolve(root), "memory"),
+    path.join(tarballHome(env), "memory"),
+    path.join(homeDir(env), LEGACY_INSTALL_HOME, "memory"),
+  ];
+  const previous = readInstallRecord(env);
+  if (previous?.root) candidates.push(path.join(previous.root, "memory"));
+  return [...new Set(candidates)];
+}
+
+module.exports = {
+  LEGACY_INSTALL_HOME,
+  stateHome,
+  memoryRoot,
+  agentsDir,
+  hooksDir,
+  executionsDir,
+  hookForwarderPath,
+  installRecordPath,
+  readInstallRecord,
+  writeInstallRecord,
+  detectChannel,
+  tarballHome,
+  tarballCurrentLink,
+  tarballVersionsDir,
+  legacyMemoryRoots,
+};

package/scripts/lib/release-manifest.cjs

@@ -0,0 +1,42 @@
+// release-manifest.cjs — hợp đồng nội dung của artifact phát hành.
+//
+// `files` trong package.json chỉ là CÁCH thực hiện hợp đồng này, và nó im lặng khi sai: một
+// dấu `!` đặt lệch chỗ cắt mất nguyên một thư mục mà `npm pack` vẫn chạy xanh. Danh sách ở đây
+// là thứ được kiểm lại — bởi `pack-release.cjs` lúc dựng artifact, và bởi
+// `test-pack-release.cjs` ở mỗi lần chạy test, để phát hiện trước khi tới ngày phát hành.
+
+"use strict";
+
+/** Không có đủ những file này thì bản cài không chạy được mà không build lại. */
+const REQUIRED = [
+  "package.json",
+  "LICENSE",
+  "dist/src/cli/alp.js",
+  "dist/src/agents/registry.js",
+  "dist/src/runtime/claude-adapter.js",
+  "dist/src/runtime/codex-adapter.js",
+  "scripts/alp.cjs",
+  "scripts/doctor.cjs",
+  "scripts/ensure-state.cjs",
+  "scripts/lib/install-paths.cjs",
+  "scripts/lib/state.cjs",
+  "scripts/lib/update.cjs",
+  "scripts/lib/uninstall.cjs",
+  "hooks/session-boot.cjs",
+  "scaffold/memory/INDEX.md",
+  "alp.config.yaml",
+];
+
+/** Nguồn, test và memory của maintainer không được đi theo artifact ra ngoài. */
+const FORBIDDEN = [/^src\//, /^test\//, /^dist\/test\//, /^memory\//, /^\.git\//, /^scripts\/test-/];
+
+/** @returns {{missing: string[], leaked: string[]}} */
+function verifyEntries(entries) {
+  const present = new Set(entries);
+  return {
+    missing: REQUIRED.filter((file) => !present.has(file)),
+    leaked: entries.filter((entry) => FORBIDDEN.some((pattern) => pattern.test(entry))),
+  };
+}
+
+module.exports = { REQUIRED, FORBIDDEN, verifyEntries };

package/scripts/lib/semver-lite.cjs

@@ -0,0 +1,20 @@
+// Minimal vX.Y.Z / X.Y.Z parsing and comparison — no pre-release/build-metadata support,
+// which is all alp-code's release tags need.
+
+function parse(tag) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(tag).trim());
+  return match && { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+function compare(a, b) {
+  const parsedA = parse(a);
+  const parsedB = parse(b);
+  if (!parsedA || !parsedB) throw new Error(`invalid semver tag: ${JSON.stringify(!parsedA ? a : b)}`);
+  return parsedA.major - parsedB.major || parsedA.minor - parsedB.minor || parsedA.patch - parsedB.patch;
+}
+
+function isValid(tag) {
+  return parse(tag) !== null;
+}
+
+module.exports = { parse, compare, isValid };

package/scripts/lib/state.cjs

@@ -0,0 +1,274 @@
+// state.cjs — dựng và giữ `~/.alp`, phần dữ liệu KHÔNG đi theo thư mục cài.
+//
+// Chạy được ở mọi channel và chạy được nhiều lần: installer gọi nó sau khi giải nén, và
+// `scripts/alp.cjs` gọi lại ở mỗi lần chạy lệnh. Đó là chủ ý — bản cài npm không có bước
+// bootstrap nào bảo đảm sẽ chạy (`npm i -g --ignore-scripts` là chuyện bình thường), nên
+// điều kiện tiên quyết phải tự dựng lấy ở lần dùng đầu tiên thay vì trông vào một bước cài.
+//
+// LUẬT DUY NHẤT: hàm ở đây chỉ biết TẠO cái còn thiếu và DI TRÚ cái nằm sai chỗ. Không hàm
+// nào ghi đè nội dung đã có — memory mất là mất thật, remote không có bản sao để lấy lại.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const P = require("./install-paths.cjs");
+const D = require("./delegation/config.cjs");
+
+/**
+ * @param {{ root: string, env?: NodeJS.ProcessEnv, version?: string }} options
+ * @returns {{ stateHome: string, memoryRoot: string, channel: string, log: Array<{level: string, text: string}> }}
+ */
+function ensureState(options) {
+  const root = path.resolve(options.root);
+  const env = options.env || process.env;
+  const log = [];
+  const say = (level, text) => log.push({ level, text });
+
+  const stateHome = P.stateHome(env);
+  mkdirPrivate(stateHome);
+
+  const channel = P.detectChannel(root);
+  const memoryRoot = ensureMemory(root, env, say);
+  ensureExecutions(env, say);
+  ensureDelegation(root, env, channel, say);
+  mkdirPrivate(P.agentsDir(env));
+
+  P.writeInstallRecord(
+    { root, channel, version: options.version ?? readVersion(root), updatedAt: new Date().toISOString() },
+    env,
+  );
+  say("OK", `install record ${P.installRecordPath(env)} → ${channel} ${root}`);
+
+  writeHookForwarders(root, env, say);
+  repairProjectHooks(env, say);
+
+  return { stateHome, memoryRoot, channel, log };
+}
+
+// ---------------------------------------------------------------------- memory
+
+/**
+ * `~/.alp/memory`, di trú từ chỗ cũ nếu cần rồi bù những file khung còn thiếu.
+ *
+ * Trước v0.9.0 memory nằm trong `<thư mục cài>/memory`. Chỗ đó giờ là artifact bị thay
+ * nguyên khối mỗi lần update, nên để nguyên là hẹn ngày mất dữ liệu — di trú là bắt buộc,
+ * không phải dọn dẹp cho gọn.
+ */
+function ensureMemory(root, env, say) {
+  const target = P.memoryRoot(env);
+
+  // "Chưa có memory ở chỗ mới" không phải là "thư mục chưa tồn tại": `alp doctor` và
+  // MarkdownFileStore đều tạo sẵn thư mục và ghi vào đó một file index ẩn chỉ để kiểm tra
+  // quyền ghi. Nếu coi đó là đã có dữ liệu thì di trú không bao giờ chạy, và người dùng lên
+  // v0.9.0 xong mở ra thấy memory rỗng trong khi bản cũ vẫn nằm nguyên chỗ cũ.
+  if (isEmptyish(target)) {
+    const legacy = P.legacyMemoryRoots(root, env).find(
+      (candidate) => candidate !== target && isDirectory(candidate) && !isEmptyish(candidate),
+    );
+    if (legacy) {
+      fs.rmSync(target, { recursive: true, force: true });
+      movePath(legacy, target);
+      leaveBreadcrumb(legacy, target);
+      say("MOVED", `memory ${legacy} → ${target}`);
+    }
+  }
+
+  mkdirPrivate(target);
+  const seed = path.join(root, "scaffold", "memory");
+  if (!fs.existsSync(seed)) throw new Error(`thiếu ${seed} — bản cài hỏng, không dựng lại memory được`);
+
+  const made = [];
+  copyMissing(seed, target, target, made);
+  for (const directory of [
+    path.join(target, "shared", "decisions"),
+    path.join(target, "shared", "people"),
+    path.join(target, "shared", "reference"),
+    path.join(target, "private"),
+  ]) {
+    if (fs.existsSync(directory)) continue;
+    fs.mkdirSync(directory, { recursive: true });
+    made.push(`${path.relative(target, directory)}/`);
+  }
+
+  if (made.length) for (const entry of made) say("WROTE", path.join(target, entry));
+  else say("OK", `memory ${target} đã đủ khung — không đụng vào nội dung`);
+  return target;
+}
+
+/**
+ * Một dòng để lại chỗ cũ. Với dev clone, `memory/` biến mất khỏi repo là chuyện đủ lạ để
+ * người dùng đi tìm; với bản cài thì thư mục này sắp bị xoá và dòng chữ vô hại.
+ */
+function leaveBreadcrumb(from, to) {
+  try {
+    fs.writeFileSync(
+      `${from}.moved-to.txt`,
+      `memory/ đã chuyển sang ${to} (alp-code >= v0.9.0).\nThư mục cài giờ là artifact thay được, không giữ dữ liệu người dùng.\n`,
+      "utf8",
+    );
+  } catch { /* breadcrumb là tiện ích, không phải điều kiện thành công */ }
+}
+
+// ------------------------------------------------------------------ state khác
+
+function ensureExecutions(env, say) {
+  const root = P.executionsDir(env);
+  mkdirPrivate(root);
+  say("OK", `execution state ${root}`);
+}
+
+/**
+ * State delegation. Mặc định cũ băm theo đường dẫn thư mục cài — hợp lý khi thư mục cài là
+ * một clone cố định, vô nghĩa khi nó là artifact có thể nằm ở `versions/<tag>` khác nhau mỗi
+ * bản. Bản cài dùng một thư mục chung; dev clone giữ nguyên khoá băm cũ để không mất state.
+ */
+function ensureDelegation(root, env, channel, say) {
+  let config;
+  try { config = D.loadDelegationConfig(root, env); }
+  catch (error) { throw new Error(`delegation config không hợp lệ: ${error.message}`); }
+
+  if (channel !== "dev" && !fs.existsSync(config.stateDir)) {
+    const legacy = D.legacyStateDir(root, env);
+    if (legacy !== config.stateDir && isDirectory(legacy)) {
+      movePath(legacy, config.stateDir);
+      say("MOVED", `delegation state ${legacy} → ${config.stateDir}`);
+    }
+  }
+
+  mkdirPrivate(config.stateDir);
+  say("OK", `delegation state ${config.stateDir}`);
+}
+
+// --------------------------------------------------------------- hook forwarder
+
+/**
+ * Sinh `~/.alp/hooks/<tên>.cjs` cho mọi hook trong thư mục cài.
+ *
+ * Forwarder tồn tại vì `<project>/.claude/settings.local.json` do `alp init` ghi phải trỏ tới
+ * một đường dẫn KHÔNG đổi. Nó nằm trong repo của người dùng, sống lâu hơn mọi bản cài, và
+ * không có bước nào đi sửa lại nó khi ALP lên version hay đổi channel.
+ *
+ * Ghi đè vô điều kiện: đây là file do ALP sinh, không phải dữ liệu người dùng, và nội dung
+ * phải luôn khớp bản cài hiện hành.
+ */
+function writeHookForwarders(root, env, say) {
+  const source = path.join(root, "hooks");
+  if (!isDirectory(source)) throw new Error(`thiếu ${source} — bản cài hỏng`);
+  const directory = P.hooksDir(env);
+  mkdirPrivate(directory);
+
+  const names = fs.readdirSync(source).filter((name) => name.endsWith(".cjs"));
+  for (const name of names) {
+    fs.writeFileSync(path.join(directory, name), forwarderSource(name), { encoding: "utf8", mode: 0o700 });
+  }
+  say("OK", `hook forwarder ${directory} (${names.join(", ")})`);
+}
+
+function forwarderSource(name) {
+  return `#!/usr/bin/env node
+// Sinh bởi alp-code — ĐỪNG SỬA TAY. Đường dẫn ổn định để cấu hình hook trong project của bạn
+// sống sót qua đổi version và đổi channel cài; nó chỉ đọc bản cài hiện hành rồi gọi hook thật.
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+
+const record = path.join(__dirname, "..", "install.json");
+let root;
+try {
+  root = JSON.parse(fs.readFileSync(record, "utf8")).root;
+} catch (error) {
+  process.stderr.write(\`alp-code: không đọc được \${record}: \${error.message}\\n\`);
+  process.exit(0);
+}
+
+if (!process.env.ALP_REPO_ROOT) process.env.ALP_REPO_ROOT = root;
+require(path.join(root, "hooks", ${JSON.stringify(name)}));
+`;
+}
+
+/**
+ * Sửa lại hook path trong những project đã `alp init` trước v0.9.0.
+ *
+ * Chúng đang trỏ thẳng vào thư mục cài cũ. Nếu bản cài đó bị npm thay hoặc bị gỡ, phiên
+ * `claude` mở tay trong project sẽ mất identity mà không báo gì rõ ràng — hỏng câm, đúng
+ * kiểu repo này tránh. Chỉ đụng vào file mang marker `alp init`; file của người dùng thì thôi.
+ */
+function repairProjectHooks(env, say) {
+  const forwarder = P.hookForwarderPath("session-boot", env);
+  const registry = path.join(P.stateHome(env), "projects.json");
+  let projects;
+  try { projects = JSON.parse(fs.readFileSync(registry, "utf8")).projects || []; }
+  catch { return; }
+
+  const repaired = [];
+  for (const entry of projects) {
+    const file = path.join(String(entry.path || ""), ".claude", "settings.local.json");
+    let parsed;
+    try { parsed = JSON.parse(fs.readFileSync(file, "utf8")); }
+    catch { continue; }
+    if (parsed.$generatedBy !== "alp init") continue;
+
+    const hooks = parsed.hooks?.SessionStart?.[0]?.hooks?.[0];
+    if (!hooks || typeof hooks.command !== "string") continue;
+    const command = `${JSON.stringify(process.execPath)} ${JSON.stringify(forwarder)}`;
+    if (hooks.command === command) continue;
+
+    hooks.command = command;
+    try {
+      fs.writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+      repaired.push(file);
+    } catch { /* project chỉ đọc hoặc đã bị xoá — không đáng làm hỏng cả bước cài */ }
+  }
+  if (repaired.length) say("FIXED", `hook path trong ${repaired.length} project → ${forwarder}`);
+}
+
+// ------------------------------------------------------------------- tiện ích
+
+function mkdirPrivate(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") { try { fs.chmodSync(directory, 0o700); } catch { /* không sở hữu */ } }
+}
+
+function isDirectory(candidate) {
+  try { return fs.statSync(candidate).isDirectory(); } catch { return false; }
+}
+
+/** Không có gì ngoài file ẩn (index cache dựng lại được) — tức là chưa có dữ liệu thật. */
+function isEmptyish(directory) {
+  try { return !fs.readdirSync(directory).some((entry) => !entry.startsWith(".")); }
+  catch { return true; }
+}
+
+/** rename khi cùng volume, cp+rm khi khác volume (EXDEV) — `~` và thư mục cài không chắc cùng đĩa. */
+function movePath(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  try {
+    fs.renameSync(from, to);
+    return;
+  } catch (error) {
+    if (error.code !== "EXDEV") throw error;
+  }
+  fs.cpSync(from, to, { recursive: true });
+  fs.rmSync(from, { recursive: true, force: true });
+}
+
+function copyMissing(sourceDir, destinationDir, base, made) {
+  fs.mkdirSync(destinationDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const source = path.join(sourceDir, entry.name);
+    const destination = path.join(destinationDir, entry.name);
+    if (entry.isDirectory()) copyMissing(source, destination, base, made);
+    else if (!fs.existsSync(destination)) {
+      fs.copyFileSync(source, destination);
+      made.push(path.relative(base, destination));
+    }
+  }
+}
+
+function readVersion(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version || null; }
+  catch { return null; }
+}
+
+module.exports = { ensureState, ensureMemory, writeHookForwarders, repairProjectHooks, movePath };