pan-stack-cli 0.1.5 → 0.2.1

package/lib/language.js

@@ -0,0 +1,121 @@
+// `pan language [<code>]` — đổi ngôn ngữ CLI bằng cách ghi `language: <code>` vào .project.yaml
+// gần nhất (walk-up từ cwd, giống findNearestProjectManifest). Chưa có key → thêm; đã có → update.
+// Không truyền code → menu tương tác (danh sách ngôn ngữ available), theo đúng quy ước chung của
+// mọi menu trong pan: ↑↓ di chuyển, Enter chọn, x thoát hẳn, b quay lại (không đổi gì).
+const fs = require("fs");
+const { findNearestProjectManifest } = require("./discover");
+const { loadInquirer } = require("./select");
+const { menuSelect } = require("./menu-prompt");
+const { helpTheme } = require("./inquirer-theme");
+const { t, lang, setLangOverride, availableLangs } = require("./i18n");
+const LANGUAGE_NAMES = require("./languages");
+
+function isCancelError(err) {
+  const s = String((err && (err.name + " " + err.message)) || "");
+  return /ExitPromptError|force closed|SIGINT|cancel/i.test(s);
+}
+
+function langLabel(code) {
+  return (LANGUAGE_NAMES[code] && LANGUAGE_NAMES[code].name) || code;
+}
+
+const TOP_LEVEL_LANGUAGE_RE = /^language\s*:.*$/m;
+const TOP_LEVEL_MANAGED_BY_RE = /^managed_by\s*:.*$/m;
+const TOP_LEVEL_PROJECT_RE = /^project\s*:.*$/m;
+
+function upsertLanguageLine(content, code) {
+  const newLine = `language: ${code}`;
+  if (TOP_LEVEL_LANGUAGE_RE.test(content)) {
+    return content.replace(TOP_LEVEL_LANGUAGE_RE, newLine);
+  }
+  const anchorRe = TOP_LEVEL_MANAGED_BY_RE.test(content) ? TOP_LEVEL_MANAGED_BY_RE : TOP_LEVEL_PROJECT_RE;
+  if (anchorRe.test(content)) {
+    return content.replace(anchorRe, (line) => `${line}\n${newLine}`);
+  }
+  // Không có project:/managed_by: (manifest lạ) → chèn lên đầu file.
+  return `${newLine}\n${content}`;
+}
+
+// @returns mã ngôn ngữ được chọn, hoặc "__exit__"/"__back__"/null (không chọn được gì — thiếu
+// TTY/dependency picker, caller tự in usage).
+async function promptLangChoice() {
+  const langs = availableLangs();
+  const current = lang();
+  const choices = langs.map((code) => ({
+    name: code === current ? `${langLabel(code)} (${code}) — hiện tại` : `${langLabel(code)} (${code})`,
+    value: code,
+    short: code,
+  }));
+  const hotkeys = [
+    { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+    { key: "b", label: t("BACK_LABEL"), value: "__back__" },
+  ];
+
+  try {
+    // Ưu tiên menu-prompt (phím tắt x/b nhấn-1-phím); thiếu @inquirer/core → fallback
+    // @inquirer/prompts select với item ẩn cuối danh sách cho x/b (vẫn chọn được bằng Enter).
+    try {
+      return await menuSelect({ message: t("LANGUAGE_SELECT_PROMPT"), choices, hotkeys, pageSize: 10 });
+    } catch (err) {
+      if (String(err && err.message) !== "no-core") throw err;
+      const inq = await loadInquirer();
+      if (!inq || typeof inq.select !== "function" || !process.stdin.isTTY) {
+        return null;
+      }
+      return await inq.select({
+        message: t("LANGUAGE_SELECT_PROMPT"),
+        choices: [
+          ...choices,
+          new inq.Separator(),
+          { name: `b  ${t("BACK_LABEL")}`, value: "__back__", short: "b" },
+          { name: `x  ${t("EXIT_LABEL")}`, value: "__exit__", short: "x" },
+        ],
+        pageSize: 10,
+        loop: false,
+        theme: helpTheme(false),
+      });
+    }
+  } catch (err) {
+    if (isCancelError(err)) return "__exit__";
+    throw err;
+  }
+}
+
+async function runLanguage(args) {
+  const manifestPath = findNearestProjectManifest(process.cwd());
+  let code = (args[0] || "").trim().toLowerCase();
+
+  if (!code) {
+    if (manifestPath) {
+      console.log(t("LANGUAGE_CURRENT__LANG_PATH", { lang: lang(), path: manifestPath }));
+    } else {
+      console.log(t("LANGUAGE_CURRENT_NO_PROJECT__LANG", { lang: lang() }));
+    }
+    console.log(t("LANGUAGE_AVAILABLE__LANGS", { langs: availableLangs().map((c) => `${c} (${langLabel(c)})`).join(", ") }));
+    code = await promptLangChoice();
+    if (code === "__exit__") {
+      process.exit(0);
+    }
+    if (!code || code === "__back__") {
+      console.log(t("LANGUAGE_USAGE"));
+      return;
+    }
+  }
+
+  const langs = availableLangs();
+  if (!langs.includes(code)) {
+    throw new Error(t("LANGUAGE_UNKNOWN__LANG_AVAILABLE", { lang: code, available: langs.join(", ") }));
+  }
+
+  if (!manifestPath) {
+    throw new Error(t("LANGUAGE_NO_PROJECT_YAML"));
+  }
+
+  const content = fs.readFileSync(manifestPath, "utf8");
+  const updated = upsertLanguageLine(content, code);
+  fs.writeFileSync(manifestPath, updated, "utf8");
+  setLangOverride(code);
+  console.log(t("LANGUAGE_SET__LANG_PATH", { lang: code, path: manifestPath }));
+}
+
+module.exports = { runLanguage };

package/lib/languages.js

@@ -0,0 +1,14 @@
+// Định nghĩa NGÔN NGỮ available của pan CLI — nguồn duy nhất cho tên hiển thị (dùng bởi
+// `pan language`/`pan lang` menu chọn ngôn ngữ). Danh sách mã hợp lệ thực tế lấy từ
+// `Object.keys(messages.js)` (xem lib/i18n.js#availableLangs) — file này chỉ cung cấp
+// tên người-đọc-được cho từng mã.
+//
+// Thêm ngôn ngữ mới:
+//   1. Thêm 1 object con trong lib/messages.js (vd `ja: { ... }`) — copy đủ key từ `en`.
+//   2. Thêm 1 dòng ở đây (mã → tên hiển thị) để menu `pan language` in đúng tên.
+// Thiếu dòng ở đây (mã có trong messages.js nhưng chưa khai ở đây) → menu vẫn hiện, chỉ
+// dùng luôn mã (vd "ja") làm tên hiển thị thay vì tên đầy đủ.
+module.exports = {
+  en: { code: "en", name: "English" },
+  vi: { code: "vi", name: "Tiếng Việt" },
+};

package/lib/manifest.js

@@ -1,5 +1,6 @@
 const fs = require("fs");
 const path = require("path");
+const { t } = require("./i18n");
 
 const PLACEHOLDER_VALUES = new Set(["", "repo_url_to_be_filled", "pan_stack_repo_url"]);
 
@@ -46,6 +47,8 @@ function parseManifest(manifestPath) {
     const body = blockLines.join("\n");
     if (blockMode === "command-shell") {
       currentCommand.shell = body;
+    } else if (blockMode === "command-sequence") {
+      currentCommand.sequence = body;
     } else if (blockMode === "target-shell" && currentCommand.targets[currentTargetName]) {
       currentCommand.targets[currentTargetName].shell = body;
     }
@@ -140,6 +143,12 @@ function parseManifest(manifestPath) {
           blockLines = [];
           continue;
         }
+        if (key === "sequence" && (value === "|" || value === ">")) {
+          blockMode = "command-sequence";
+          blockIndent = indent + 2;
+          blockLines = [];
+          continue;
+        }
         if (key === "targets") {
           currentCommand.targets = currentCommand.targets || {};
           continue;
@@ -213,23 +222,51 @@ function validateRepo(repo) {
   const repoPath = cleanValue(repo.path) || name;
 
   if (!name) {
-    throw new Error("Repository entry is missing 'name'.");
+    throw new Error(t("REPO_MISSING_NAME"));
   }
   if (PLACEHOLDER_VALUES.has(url)) {
-    throw new Error(`Repository '${name}' is missing a real url.`);
+    throw new Error(t("REPO_MISSING_URL__NAME", { name }));
   }
   if (!repoPath) {
-    throw new Error(`Repository '${name}' is missing 'path'.`);
+    throw new Error(t("REPO_MISSING_PATH__NAME", { name }));
   }
   return { name, url, repoPath };
 }
 
+const LOCAL_MANIFEST_FILE = ".project.local.yaml";
+
+function localManifestPath(manifestPath) {
+  return path.join(path.dirname(manifestPath), LOCAL_MANIFEST_FILE);
+}
+
+/**
+ * Parse `.project.yaml` rồi GỘP THÊM `repositories:` từ `.project.local.yaml` cùng thư mục
+ * (nếu có) — file cá nhân, KHÔNG commit (gitignore), chỉ cần có field `repositories:`. Dùng để
+ * mỗi người tự thêm repo riêng (thử nghiệm, fork cá nhân…) mà không đụng `.project.yaml` chung.
+ * Mọi lệnh đọc repo (clone/pull/push/fetch/grv/gst/sync-main/mr/checkout/stats/pan.yaml sources)
+ * đều đi qua đây (loadManifest / loadManifestRepos) nên tự động thấy repo local, không cần sửa
+ * riêng từng lệnh.
+ */
+function parseManifestWithLocal(manifestPath) {
+  const data = parseManifest(manifestPath);
+  const localPath = localManifestPath(manifestPath);
+  if (fs.existsSync(localPath)) {
+    const localData = parseManifest(localPath);
+    const localRepos = Array.isArray(localData.repositories) ? localData.repositories : [];
+    if (localRepos.length) {
+      data.repositories = [...(data.repositories || []), ...localRepos];
+      console.error(`ℹ️  +${localRepos.length} repo từ ${LOCAL_MANIFEST_FILE}`);
+    }
+  }
+  return data;
+}
+
 function loadManifest(manifestPath) {
   const resolved = path.resolve(manifestPath);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`Manifest not found: ${manifestPath}`);
+    throw new Error(t("MANIFEST_NOT_FOUND__PATH", { path: manifestPath }));
   }
-  const data = parseManifest(resolved);
+  const data = parseManifestWithLocal(resolved);
   return {
     path: resolved,
     root: path.dirname(resolved),
@@ -246,7 +283,7 @@ const PAN_CONFIG_FILE = ".pan.yaml";
 function loadPanConfig(configPath, meta = {}) {
   const resolved = path.resolve(configPath);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`Config not found: ${configPath}`);
+    throw new Error(t("CONFIG_NOT_FOUND__PATH", { path: configPath }));
   }
   const data = parseManifest(resolved);
   const root = path.dirname(resolved);
@@ -323,7 +360,7 @@ function getCommandDefinition(source, commandName, subArg) {
     const target = def.targets[targetName];
     if (!target) {
       const valid = Object.keys(def.targets).join(" | ");
-      throw new Error(`Valid targets for '${commandName}': ${valid}`);
+      throw new Error(t("VALID_TARGETS__COMMAND_VALID", { command: commandName, valid }));
     }
     return {
       ...target,
@@ -336,13 +373,74 @@ function getCommandDefinition(source, commandName, subArg) {
 }
 
 function listCommands(source) {
-  return Object.entries(source.commands || {}).map(([name, def]) => ({
-    name,
-    aliases: commandAliases(def),
-    description: def.description || "",
-    hasTargets: Boolean(def.targets),
-    targets: def.targets ? Object.keys(def.targets) : [],
-  }));
+  return Object.entries(source.commands || {})
+    .map(([name, def]) => ({
+      name,
+      aliases: commandAliases(def),
+      description: def.description || "",
+      hasTargets: Boolean(def.targets),
+      targets: def.targets ? Object.keys(def.targets) : [],
+      hasSequence: Boolean(def.sequence),
+    }))
+    // Sort A-Z theo tên lệnh — dễ dò trong menu tương tác (`pan` trống) và list help (`pan -h`),
+    // thay vì theo thứ tự khai báo trong .pan.yaml (khó đoán khi file có nhiều lệnh).
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Parse field `sequence` của 1 command → danh sách step chạy TUẦN TỰ theo thứ tự.
+ * 2 cách viết:
+ *   sequence: build-fe, build-be              # 1 dòng, phân tách bởi ,
+ *   sequence: |                               # nhiều dòng (khuyến nghị khi cần set biến)
+ *     build-fe
+ *     MODE=prod build-be:dev
+ *     build-extra?                            # dấu ? cuối = optional (lỗi vẫn chạy tiếp bước sau)
+ * Mỗi dòng: [KEY=VAL ...] tênLệnh[:target][?]
+ *   • tênLệnh phải là 1 command KHÁC đã khai báo trong CÙNG file .pan.yaml này.
+ *   • `:target` chọn target nếu lệnh đó có `targets:`.
+ *   • `KEY=VAL` (đặt trước tên lệnh, cách nhau bởi khoảng trắng) → biến môi trường CHỈ áp dụng
+ *     cho riêng bước đó (không ảnh hưởng các bước khác).
+ *   • `?` cuối tên lệnh → bước lỗi (exit code != 0) KHÔNG dừng cả sequence, chỉ cảnh báo rồi
+ *     chạy tiếp bước sau. Không có `?` → lỗi là DỪNG NGAY (không chạy bước còn lại).
+ */
+function parseSequenceSteps(raw) {
+  const text = String(raw || "");
+  const lines = text.includes("\n") ? text.split(/\r?\n/) : text.split(",");
+  const steps = [];
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const tokens = line.split(/\s+/).filter(Boolean);
+    const env = {};
+    let ref = null;
+    for (const token of tokens) {
+      const match = ref === null && token.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (match) {
+        env[match[1]] = cleanValue(match[2]);
+        continue;
+      }
+      if (ref !== null) {
+        throw new Error(`Invalid sequence step: "${line}" (expected "[KEY=VAL ...] commandName[:target][?]")`);
+      }
+      ref = token;
+    }
+    if (!ref) {
+      continue;
+    }
+    let optional = false;
+    if (ref.endsWith("?")) {
+      optional = true;
+      ref = ref.slice(0, -1);
+    }
+    const [name, target = ""] = ref.split(":");
+    if (!name) {
+      throw new Error(`Invalid sequence step: "${line}" — missing command name.`);
+    }
+    steps.push({ raw: line, name, target, env, optional });
+  }
+  return steps;
 }
 
 function commandBaseDir(source) {
@@ -352,8 +450,10 @@ function commandBaseDir(source) {
 module.exports = {
   PLACEHOLDER_VALUES,
   PAN_CONFIG_FILE,
+  LOCAL_MANIFEST_FILE,
   cleanValue,
   parseManifest,
+  parseManifestWithLocal,
   loadManifest,
   loadPanConfig,
   manifestRepos,
@@ -361,6 +461,7 @@ module.exports = {
   commandAliases,
   resolveCommandName,
   getCommandDefinition,
+  parseSequenceSteps,
   listCommands,
   commandBaseDir,
 };

package/lib/menu-prompt.js

@@ -0,0 +1,201 @@
+// Custom @inquirer prompt: danh sách chọn (↑↓/Enter, gõ chữ lọc) + PHÍM TẮT NHẤN-1-PHÍM chạy ngay
+// (vd h/v/b/x). Dùng @inquirer/core (dynamic ESM từ CJS). Thiếu core → menuSelect throw 'no-core'
+// để caller fallback sang @inquirer/prompts select.
+let cachePrompt = null;
+
+async function buildMenuPrompt() {
+  if (cachePrompt) return cachePrompt;
+  const core = await import("@inquirer/core").catch(() => null);
+  if (!core) return null;
+  const {
+    createPrompt, useState, useKeypress, usePrefix, usePagination, useMemo,
+    isEnterKey, isUpKey, isDownKey, Separator, makeTheme,
+  } = core;
+
+  cachePrompt = createPrompt((config, done) => {
+    const { message, choices, hotkeys = [], pageSize = 15, footer = "" } = config;
+    const theme = makeTheme(config.theme);
+    const [status, setStatus] = useState("idle");
+    const prefix = usePrefix({ status, theme });
+    const items = useMemo(() => choices, [choices]);
+    const firstSel = items.findIndex((it) => !Separator.isSeparator(it));
+    const [active, setActive] = useState(firstSel < 0 ? 0 : firstSel);
+
+    useKeypress((key, rl) => {
+      if (status !== "idle") return;
+      if (isEnterKey(key)) {
+        const it = items[active];
+        if (it && !Separator.isSeparator(it) && !it.disabled) {
+          setStatus("done");
+          done(it.value);
+        }
+      } else if (isUpKey(key) || isDownKey(key)) {
+        rl.clearLine(0);
+        const dir = isUpKey(key) ? -1 : 1;
+        let n = active;
+        do {
+          n = (n + dir + items.length) % items.length;
+        } while (Separator.isSeparator(items[n]) && n !== active);
+        setActive(n);
+      } else if (key.name && hotkeys.some((h) => h.key === key.name)) {
+        // PHÍM TẮT: nhấn 1 phím → chạy ngay.
+        setStatus("done");
+        done(hotkeys.find((h) => h.key === key.name).value);
+      } else {
+        // type-ahead: nhảy tới item tên bắt đầu bằng ký tự đang gõ.
+        const term = String(rl.line || "").toLowerCase();
+        if (term) {
+          const idx = items.findIndex(
+            (it) => !Separator.isSeparator(it) && String(it.name).toLowerCase().startsWith(term)
+          );
+          if (idx >= 0) setActive(idx);
+        }
+      }
+    });
+
+    const activeItem = items[active] || {};
+    if (status === "done") {
+      return `${prefix} ${message} ${activeItem.name || ""}`.trim();
+    }
+
+    const page = usePagination({
+      items,
+      active,
+      renderItem({ item, isActive }) {
+        if (Separator.isSeparator(item)) return `  ${item.separator || "──────────"}`;
+        const cursor = isActive ? "❯" : " ";
+        const line = ` ${cursor} ${item.name}`;
+        return isActive ? `\x1b[36m${line}\x1b[39m` : line;
+      },
+      pageSize,
+      loop: false,
+    });
+
+    const desc = activeItem.description ? `\x1b[2m  ${activeItem.description}\x1b[22m` : "";
+    const hk = hotkeys.length
+      ? "  " + hotkeys.map((h) => `\x1b[1m${h.key}\x1b[22m ${h.label}`).join(" · ")
+      : "";
+    const help = footer || hk ? `\x1b[2m${footer}\x1b[22m${hk}` : "";
+    return [`${prefix} ${message}`, page, desc, help].filter(Boolean).join("\n");
+  });
+  return cachePrompt;
+}
+
+async function menuSelect(config) {
+  const prompt = await buildMenuPrompt();
+  if (!prompt) throw new Error("no-core");
+  return prompt(config);
+}
+
+// Multi-select với phím tắt (x thoát, b quay lại...) — trả:
+//   { action: 'submit', values: string[] } khi Enter
+//   { action: <hotkey.value> } khi bấm hotkey
+let cachePromptCheckbox = null;
+
+async function buildMenuCheckbox() {
+  if (cachePromptCheckbox) return cachePromptCheckbox;
+  const core = await import("@inquirer/core").catch(() => null);
+  if (!core) return null;
+  const {
+    createPrompt, useState, useKeypress, usePrefix, usePagination, useMemo,
+    isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, makeTheme,
+  } = core;
+
+  cachePromptCheckbox = createPrompt((config, done) => {
+    const { message, choices, hotkeys = [], pageSize = 15, footer = "" } = config;
+    const theme = makeTheme(config.theme);
+    const [status, setStatus] = useState("idle");
+    const prefix = usePrefix({ status, theme });
+    const items = useMemo(() => choices, [choices]);
+    const firstSel = items.findIndex((it) => !Separator.isSeparator(it));
+    const [active, setActive] = useState(firstSel < 0 ? 0 : firstSel);
+    const [checked, setChecked] = useState(new Set());
+
+    function toggle(i) {
+      const it = items[i];
+      if (!it || Separator.isSeparator(it) || it.disabled) return;
+      const next = new Set(checked);
+      if (next.has(i)) next.delete(i);
+      else next.add(i);
+      setChecked(next);
+    }
+
+    useKeypress((key, rl) => {
+      if (status !== "idle") return;
+      if (isEnterKey(key)) {
+        setStatus("done");
+        const values = [];
+        items.forEach((it, i) => {
+          if (!Separator.isSeparator(it) && !it.disabled && checked.has(i)) values.push(it.value);
+        });
+        done({ action: "submit", values });
+      } else if (isSpaceKey && isSpaceKey(key)) {
+        rl.clearLine(0);
+        toggle(active);
+      } else if (key.name === "space") {
+        rl.clearLine(0);
+        toggle(active);
+      } else if (isUpKey(key) || isDownKey(key)) {
+        rl.clearLine(0);
+        const dir = isUpKey(key) ? -1 : 1;
+        let n = active;
+        do {
+          n = (n + dir + items.length) % items.length;
+        } while (Separator.isSeparator(items[n]) && n !== active);
+        setActive(n);
+      } else if (key.name === "a") {
+        // toggle-all: nếu chưa đủ → chọn hết; đã đủ → bỏ hết
+        const selectable = items.map((it, i) => ({ it, i })).filter(({ it }) => !Separator.isSeparator(it) && !it.disabled);
+        const allChecked = selectable.every(({ i }) => checked.has(i));
+        const next = new Set();
+        if (!allChecked) selectable.forEach(({ i }) => next.add(i));
+        setChecked(next);
+      } else if (key.name === "i") {
+        // invert
+        const next = new Set();
+        items.forEach((it, i) => {
+          if (!Separator.isSeparator(it) && !it.disabled && !checked.has(i)) next.add(i);
+        });
+        setChecked(next);
+      } else if (key.name && hotkeys.some((h) => h.key === key.name)) {
+        setStatus("done");
+        done({ action: hotkeys.find((h) => h.key === key.name).value });
+      }
+    });
+
+    if (status === "done") {
+      return `${prefix} ${message}`.trim();
+    }
+
+    const page = usePagination({
+      items,
+      active,
+      renderItem({ item, index, isActive }) {
+        if (Separator.isSeparator(item)) return `  ${item.separator || "──────────"}`;
+        const box = checked.has(index) ? "◉" : "◯";
+        const cursor = isActive ? "❯" : " ";
+        const line = ` ${cursor} ${box} ${item.name}`;
+        return isActive ? `\x1b[36m${line}\x1b[39m` : line;
+      },
+      pageSize,
+      loop: false,
+    });
+
+    const baseHelp = "space chọn · a chọn tất cả · i đảo";
+    const hk = hotkeys.length
+      ? "  " + hotkeys.map((h) => `\x1b[1m${h.key}\x1b[22m ${h.label}`).join(" · ")
+      : "";
+    const enterTip = `  \x1b[1mEnter\x1b[22m \x1b[2mxác nhận\x1b[22m`;
+    const help = `\x1b[2m${footer || baseHelp}\x1b[22m${hk}${enterTip}`;
+    return [`${prefix} ${message}`, page, help].filter(Boolean).join("\n");
+  });
+  return cachePromptCheckbox;
+}
+
+async function menuCheckbox(config) {
+  const prompt = await buildMenuCheckbox();
+  if (!prompt) throw new Error("no-core");
+  return prompt(config);
+}
+
+module.exports = { menuSelect, buildMenuPrompt, menuCheckbox, buildMenuCheckbox };

package/lib/menu.js

@@ -0,0 +1,134 @@
+// Menu tương tác khi gõ `pan` trống (TTY): chọn DỰ ÁN → chọn LỆNH → chạy — khỏi nhớ lệnh.
+// Ưu tiên custom prompt (menu-prompt) có PHÍM TẮT nhấn-1-phím (h/v/b/x); thiếu @inquirer/core →
+// fallback @inquirer/prompts select (phím tắt thành item chọn). Chuỗi theo ngôn ngữ (i18n, mặc định en).
+const path = require("path");
+const { loadAllCommandSources } = require("./discover");
+const { listCommands } = require("./manifest");
+const { runProjectCommand, sourceLabel } = require("./run-command");
+const { loadInquirer } = require("./select");
+const { menuSelect, buildMenuPrompt } = require("./menu-prompt");
+const { helpTheme } = require("./inquirer-theme");
+const { t } = require("./i18n");
+
+function isCancel(err) {
+  const s = String((err && (err.name + " " + err.message)) || "");
+  return /ExitPromptError|force closed|SIGINT|cancel/i.test(s);
+}
+
+// Chọn 1 item; hotkeys hiện ở footer (custom prompt) hoặc thành item cuối (fallback select).
+async function pick({ message, choices, hotkeys = [] }) {
+  try {
+    return await menuSelect({ message, choices, hotkeys });
+  } catch (err) {
+    if (String(err && err.message) !== "no-core") throw err;
+    const inq = await loadInquirer();
+    if (!inq || typeof inq.select !== "function") return "__exit__";
+    const extra = hotkeys.map((h) => ({ name: `${h.key}  ${h.label}`, value: h.value }));
+    const list = extra.length ? [...choices, new inq.Separator(), ...extra] : choices;
+    return inq.select({ message, choices: list, pageSize: 20, loop: false, theme: helpTheme(false) });
+  }
+}
+
+async function runInteractiveMenu({ printUsage, version } = {}) {
+  // Có ít nhất 1 backend picker? (core hoặc prompts). Không → trả false để caller in usage.
+  const core = await buildMenuPrompt();
+  const inqMod = await loadInquirer();
+  if (!core && (!inqMod || typeof inqMod.select !== "function")) return false;
+
+  // Sort A-Z theo tên hiển thị — dễ dò khi .project.yaml có nhiều repo/project.
+  const sources = loadAllCommandSources()
+    .filter((s) => listCommands(s).length > 0)
+    .sort((a, b) => sourceLabel(a).localeCompare(sourceLabel(b)));
+  if (sources.length === 0) {
+    // Không có .pan.yaml (project commands) — KHÔNG coi là lỗi/dead-end: các lệnh git
+    // built-in (pull/push/fetch/checkout/...) vẫn dùng được nhờ fallback quét git repo
+    // con quanh cwd (xem lib/git/helpers/cli.js). In gợi ý rồi để caller in usage đầy đủ.
+    console.log(t("NO_PAN_YAML_WITH_COMMANDS"));
+    console.log(t("NO_PAN_YAML_BUT_GIT_STILL_WORKS"));
+    return false;
+  }
+
+  try {
+    for (;;) {
+      // ── Tầng 1: dự án ──
+      const proj = await pick({
+        message: t("MENU_SELECT_PROJECT"),
+        choices: sources.map((s, i) => ({
+          name: sourceLabel(s),
+          value: i,
+          description: `${listCommands(s).length} ${t("COMMANDS_LABEL")} · ${s.root}`,
+        })),
+        hotkeys: [
+          { key: "h", label: t("HELP_LABEL"), value: "__help__" },
+          { key: "v", label: t("VERSION_LABEL"), value: "__version__" },
+          { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+        ],
+      });
+      if (proj === "__exit__") return true;
+      if (proj === "__version__") {
+        console.log(`pan-stack-cli ${version || "?"}`);
+        continue;
+      }
+      if (proj === "__help__") {
+        if (typeof printUsage === "function") printUsage();
+        continue;
+      }
+      const source = sources[proj];
+
+      // ── Tầng 2: lệnh ──
+      const cmds = listCommands(source);
+      const cmd = await pick({
+        message: `[${sourceLabel(source)}] ${t("MENU_SELECT_COMMAND")}`,
+        choices: cmds.map((c) => ({
+          name:
+            c.name +
+            (c.aliases && c.aliases.length ? ` (${c.aliases.join(", ")})` : "") +
+            (c.hasTargets ? ` [${c.targets.join("|")}]` : ""),
+          value: c.name,
+          description: c.description || "",
+        })),
+        hotkeys: [
+          { key: "b", label: t("BACK_LABEL"), value: "__back__" },
+          { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+        ],
+      });
+      if (cmd === "__exit__") return true;
+      if (cmd === "__back__") continue;
+
+      // ── Tầng 3: target (nếu có) ──
+      const def = source.commands[cmd];
+      const args = [];
+      if (def && def.targets && Object.keys(def.targets).length > 0) {
+        const targets = Object.keys(def.targets);
+        const tgt = await pick({
+          message: t("SELECT_TARGET__CMD", { cmd }),
+          choices: [
+            ...targets.map((x) => ({ name: x, value: x })),
+            { name: t("DEFAULT_LABEL"), value: "__default__" },
+          ],
+          hotkeys: [{ key: "b", label: t("BACK_LABEL"), value: "__back__" }],
+        });
+        if (tgt === "__back__") continue;
+        if (tgt !== "__default__") args.push(tgt);
+      }
+
+      console.error(`\n▶ pan ${cmd}${args.length ? " " + args.join(" ") : ""}  (${path.basename(source.root)})\n`);
+      // runProjectCommand tự process.exit() khi lệnh THẬT chạy xong — chỉ trả về (không exit) khi
+      // user bấm 'b' ở bước chọn (selectFrom/selectChoices) bên trong lệnh đó. Lúc đó `continue`
+      // để quay lại Tầng 1 (chọn dự án) thay vì thoát hẳn CLI, đúng quy ước 'b' = quay lại.
+      const result = await runProjectCommand(source, cmd, args);
+      if (result && result.backed) {
+        continue;
+      }
+      return true;
+    }
+  } catch (err) {
+    if (isCancel(err)) {
+      console.error("\n" + t("EXITED"));
+      return true;
+    }
+    throw err;
+  }
+}
+
+module.exports = { runInteractiveMenu };