pan-stack-cli 0.1.4 → 0.2.1

package/lib/ui/init.js

@@ -0,0 +1,252 @@
+// lib/ui/init.js — `pan ui init`: scaffold dự án panui mẫu.
+// Flow: chọn loại (web landing / mobile / cms) → chọn template → chọn bảng màu →
+// nhập tên/đường dẫn → (tồn tại→lỗi) → copy template + thay placeholder palette/tên.
+// KHÔNG cần auth/backend — thuần local.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { PALETTES, PALETTE_BY_ID, paletteReplacements } = require("./palettes");
+const { menuSelect } = require("../menu-prompt");
+const { t } = require("../i18n");
+const { getRegistryBaseUrl, fetchRegistry, downloadAndExtract } = require("../skill-registry-client");
+
+// Template pan-ui (landing-glass, mobile-app, ...) không còn bundle local — đăng ký trên registry
+// server với name prefix "pan-ui-" (xem apps/pan-agent-skill-registry/registry/templates/pan-ui/).
+
+const CATEGORY_LABEL = {
+  landing: "Web — Landing page",
+  mobile: "Mobile — Ứng dụng điện thoại",
+  cms: "CMS — Trang quản trị",
+};
+const CATEGORY_ORDER = ["landing", "mobile", "cms"];
+
+// Design System khai ở cấp app (field `designSystem` trong app.panui.yaml). shadcn = mặc định
+// (đứng đầu danh sách), antd = lựa chọn thứ hai. Thiếu field → renderer coi như shadcn.
+const DESIGN_SYSTEMS = [
+  { id: "shadcn", label: "shadcn ui (Recommended)" },
+  { id: "antd", label: "antd" },
+];
+
+const TEXT_EXT = new Set([".yaml", ".yml", ".html", ".htm", ".md", ".json", ".txt", ".css"]);
+
+/**
+ * Lấy danh sách template pan-ui từ registry server (KHÔNG tải zip — chỉ đọc metadata
+ * `extra.{category,label,platform}` + `description` để dựng picker). Cần server đang chạy
+ * (PAN_SKILL_REGISTRY_URL, mặc định localhost:4600) — xem apps/pan-agent-skill-registry.
+ * @returns {Promise<Array<{id, category, label, description, platform, item}>>}
+ */
+async function discoverTemplates() {
+  const baseUrl = getRegistryBaseUrl();
+  const items = await fetchRegistry(baseUrl);
+  return items
+    .filter((i) => i.type === "template" && i.name.startsWith("pan-ui-"))
+    .map((item) => ({
+      id: item.name.slice("pan-ui-".length),
+      category: (item.extra && item.extra.category) || "",
+      label: (item.extra && item.extra.label) || item.name,
+      description: item.description || "",
+      platform: item.extra && item.extra.platform,
+      item, // giữ nguyên để downloadAndExtract sau khi user chọn xong (tải NGAY 1 cái, không tải hết)
+    }));
+}
+
+/** Copy đệ quy src→dest; file text thì thay placeholder theo `replacements`. */
+function copyWithReplace(src, dest, replacements) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      if (name === "template.json") continue; // manifest không copy vào dự án
+      copyWithReplace(path.join(src, name), path.join(dest, name), replacements);
+    }
+    return;
+  }
+  const ext = path.extname(src).toLowerCase();
+  if (TEXT_EXT.has(ext)) {
+    let content = fs.readFileSync(src, "utf8");
+    for (const [token, value] of Object.entries(replacements)) {
+      content = content.split(token).join(value);
+    }
+    fs.writeFileSync(dest, content);
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Ghi field `designSystem: <ds>` cấp app vào app.panui.yaml của dự án vừa sinh.
+ * Nếu file đã có dòng `designSystem:` → thay giá trị; chưa có → chèn ngay sau dòng `app:`.
+ * Không tìm thấy file/anchor → bỏ qua im lặng (renderer mặc định shadcn).
+ */
+function applyDesignSystem(targetDir, ds) {
+  const file = path.join(targetDir, "app.panui.yaml");
+  if (!fs.existsSync(file)) return;
+  const content = fs.readFileSync(file, "utf8");
+  const lines = content.split("\n");
+  const dsIdx = lines.findIndex((l) => /^designSystem\s*:/.test(l));
+  if (dsIdx >= 0) {
+    lines[dsIdx] = `designSystem: ${ds}`;
+  } else {
+    const appIdx = lines.findIndex((l) => /^app\s*:/.test(l));
+    const at = appIdx >= 0 ? appIdx + 1 : 1; // sau `app:`, hoặc sau `panui:` nếu không có `app:`
+    lines.splice(at, 0, `designSystem: ${ds}`);
+  }
+  fs.writeFileSync(file, lines.join("\n"));
+}
+
+/** Chuẩn hóa tên nhập → { targetDir (tuyệt đối), projectName }. Cho tên đơn (pan-ui) hoặc path. */
+function resolveTarget(input) {
+  const raw = String(input || "").trim();
+  const value = raw || "pan-ui";
+  const targetDir = path.resolve(process.cwd(), value);
+  const projectName = path.basename(targetDir);
+  return { targetDir, projectName };
+}
+
+// Chọn 1 item; ưu tiên menu-prompt (hotkey b/x nhấn-1-phím) → @inquirer/prompts select với
+// item b/x ẩn ở cuối (không hotkey thật, vẫn chọn được bằng Enter) → lỗi nếu không có gì.
+async function pick(inq, { message, choices, hotkeys = [] }) {
+  try {
+    return await menuSelect({ message, choices, hotkeys });
+  } catch (err) {
+    if (String(err && err.message) !== "no-core") throw err;
+    if (!inq || typeof inq.select !== "function") {
+      throw new Error("Cần terminal tương tác (@inquirer/prompts) để chạy `pan ui init`.");
+    }
+    const extra = hotkeys.map((h) => ({ name: `${h.key}  ${h.label}`, value: h.value }));
+    const list = extra.length ? [...choices, { name: "──────────", disabled: true }, ...extra] : choices;
+    return inq.select({ message, choices: list, loop: false });
+  }
+}
+
+async function run(_args) {
+  const inq = await import("@inquirer/prompts").catch(() => null);
+
+  const baseUrl = getRegistryBaseUrl();
+  const templates = await discoverTemplates();
+  if (templates.length === 0) {
+    throw new Error(
+      `Không tìm thấy template pan-ui nào trên registry server (${baseUrl}). Kiểm tra server đang chạy và apps/pan-agent-skill-registry/registry/templates/pan-ui/ đã build chưa.`
+    );
+  }
+
+  const categories = CATEGORY_ORDER.filter((c) => templates.some((tpl) => tpl.category === c));
+
+  let designSystem = null;
+  let category = null;
+  let chosen = null;
+  let palette = null;
+
+  // Vòng lặp 4 cấp (Design System → loại → template → bảng màu); 'b' quay lại cấp trước, 'x' thoát hẳn.
+  designSystemLoop: for (;;) {
+    // 0) Design System — bước ĐẦU TIÊN. shadcn (Recommended) mặc định đứng đầu, antd thứ hai.
+    designSystem = await pick(inq, {
+      message: "Chọn Design System:",
+      choices: DESIGN_SYSTEMS.map((d) => ({ name: d.label, value: d.id })),
+      hotkeys: [{ key: "x", label: t("EXIT_LABEL"), value: "__exit__" }],
+    });
+    if (designSystem === "__exit__") {
+      console.log(t("EXITED"));
+      process.exit(0);
+    }
+
+  categoryLoop: for (;;) {
+    category = await pick(inq, {
+      message: "Loại dự án:",
+      choices: categories.map((c) => ({ name: CATEGORY_LABEL[c] || c, value: c })),
+      hotkeys: [
+        { key: "b", label: t("BACK_LABEL"), value: "__back__" },
+        { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+      ],
+    });
+    if (category === "__exit__") {
+      console.log(t("EXITED"));
+      process.exit(0);
+    }
+    if (category === "__back__") continue designSystemLoop;
+
+    const inCat = templates.filter((tpl) => tpl.category === category);
+
+    templateLoop: for (;;) {
+      const template = await pick(inq, {
+        message: "Chọn giao diện mẫu:",
+        choices: inCat.map((tpl) => ({
+          name: `${tpl.label}${tpl.description ? ` — ${tpl.description}` : ""}`,
+          value: tpl.id,
+        })),
+        hotkeys: [
+          { key: "b", label: t("BACK_LABEL"), value: "__back__" },
+          { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+        ],
+      });
+      if (template === "__exit__") {
+        console.log(t("EXITED"));
+        process.exit(0);
+      }
+      if (template === "__back__") continue categoryLoop;
+      chosen = inCat.find((tpl) => tpl.id === template);
+
+      for (;;) {
+        const paletteId = await pick(inq, {
+          message: "Bảng màu (chỉ đổi màu chủ đạo primary/accent...):",
+          choices: PALETTES.map((p) => ({ name: p.label, value: p.id })),
+          hotkeys: [
+            { key: "b", label: t("BACK_LABEL"), value: "__back__" },
+            { key: "x", label: t("EXIT_LABEL"), value: "__exit__" },
+          ],
+        });
+        if (paletteId === "__exit__") {
+          console.log(t("EXITED"));
+          process.exit(0);
+        }
+        if (paletteId === "__back__") continue templateLoop;
+        palette = PALETTE_BY_ID.get(paletteId);
+        break designSystemLoop;
+      }
+    }
+  }
+  }
+
+  if (!inq || typeof inq.input !== "function") {
+    throw new Error("Cần terminal tương tác (@inquirer/prompts) để chạy `pan ui init`.");
+  }
+
+  // 4) Tên / đường dẫn dự án.
+  const nameInput = await inq.input({
+    message: "Tên dự án hoặc đường dẫn lưu (vd: pan-ui, ./design/landing, /abs/duan):",
+    default: "pan-ui",
+  });
+  const { targetDir, projectName } = resolveTarget(nameInput);
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(
+      `Thư mục đã tồn tại: ${targetDir}\n→ Xóa thủ công (CLI không tự xóa) rồi chạy lại, hoặc chọn tên khác.`
+    );
+  }
+
+  // 5) Tải ĐÚNG 1 template đã chọn (zip) rồi scaffold: copy + thay placeholder (palette + tên dự án).
+  const replacements = {
+    ...paletteReplacements(palette),
+    __PROJECT_NAME__: projectName,
+  };
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "pan-ui-init-"));
+  try {
+    const extractedDir = await downloadAndExtract(baseUrl, chosen.item, stagingDir);
+    copyWithReplace(extractedDir, targetDir, replacements);
+  } finally {
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+  }
+
+  // Ghi Design System đã chọn vào app.panui.yaml cấp app.
+  applyDesignSystem(targetDir, designSystem);
+
+  const dsLabel = (DESIGN_SYSTEMS.find((d) => d.id === designSystem) || {}).label || designSystem;
+  console.log(`\n✓ Đã tạo dự án "${projectName}" (${dsLabel} · ${CATEGORY_LABEL[category]} · ${chosen.label} · màu ${palette.label.split(" —")[0]})`);
+  console.log(`  ${targetDir}`);
+  console.log("\nBước tiếp theo:");
+  console.log(`  • Xem thử:   pnpm --dir apps/pan-stack-design-system panui:gen ${targetDir} -o /tmp/preview && pan serve /tmp/preview`);
+  console.log("  • Sửa nội dung: mở app.panui.yaml + screens/ + components/*.html");
+  console.log("  • Đưa lên Pan Studio: pan ui login → (tạo dự án) → pan ui sync");
+}
+
+module.exports = { run, discoverTemplates, resolveTarget, applyDesignSystem, DESIGN_SYSTEMS };

package/lib/ui/login.js

@@ -0,0 +1,128 @@
+// lib/ui/login.js — device-flow auth (§4.3, OD-U1): POST /auth/device/start, mở browser
+// verificationUriComplete, poll /auth/device/poll mỗi `interval`s, lưu credential.
+const os = require("os");
+const { spawn } = require("child_process");
+const { createApiClient } = require("./api");
+const { getApiConfig, saveCredential, loadCredential, isExpired } = require("./config");
+const { findWorkspaceRoot } = require("./workspace");
+
+/**
+ * Mở browser theo OS. Không throw — trả false nếu không mở được (fallback in URL).
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+function openBrowser(url) {
+  return new Promise((resolve) => {
+    let cmd;
+    let args;
+    if (process.platform === "darwin") {
+      cmd = "open";
+      args = [url];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      args = ["/c", "start", '""', url];
+    } else {
+      cmd = "xdg-open";
+      args = [url];
+    }
+    try {
+      const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+      child.on("error", () => resolve(false));
+      child.unref();
+      resolve(true);
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function run(args = []) {
+  const force = args.includes("--force") || args.includes("-f");
+
+  const workspaceRoot = findWorkspaceRoot() || process.cwd();
+  const { apiUrl } = getApiConfig(workspaceRoot);
+
+  // Đã có key CÒN HẠN cho đúng apiUrl này → báo info + hướng dẫn thay vì âm thầm login lại đè key.
+  const existing = loadCredential(apiUrl);
+  if (existing && !isExpired(existing) && !force) {
+    const email = (existing.user && existing.user.email) || "?";
+    const expDate = existing.expiresAt ? new Date(existing.expiresAt).toLocaleString() : "?";
+    console.log(`✓ Đã đăng nhập ${email} tại ${apiUrl} (key hết hạn ${expDate}).`);
+    console.log("");
+    console.log("Muốn đổi tài khoản / đăng nhập lại?");
+    console.log("  pan ui logout           # đăng xuất trước, rồi 'pan ui login' lại");
+    console.log("  pan ui login --force    # đăng nhập lại ngay, ghi đè key hiện tại");
+    return;
+  }
+
+  const api = createApiClient({ apiUrl });
+
+  console.log(`Đăng nhập Pan Studio (${apiUrl})...`);
+  const start = await api.deviceStart({
+    clientName: `pan-cli@${os.hostname()}`,
+    scope: "WRITE",
+  });
+  const { deviceCode, userCode, verificationUriComplete, interval, expiresIn } = start;
+
+  if (!deviceCode || !verificationUriComplete) {
+    throw new Error(
+      "Phản hồi /auth/device/start không hợp lệ (thiếu deviceCode/verificationUriComplete) — kiểm tra backend."
+    );
+  }
+
+  console.log(`Mã đăng nhập: ${userCode}`);
+  console.log(`Mở trình duyệt tại: ${verificationUriComplete}`);
+  const opened = await openBrowser(verificationUriComplete);
+  if (!opened) {
+    console.log(
+      "Không tự mở được trình duyệt — hãy dán URL trên vào trình duyệt và làm theo hướng dẫn."
+    );
+  }
+
+  const intervalMs = Math.max(1, Number(interval) || 4) * 1000;
+  const deadline = Date.now() + Math.max(1, Number(expiresIn) || 600) * 1000;
+
+  console.log("Đang chờ xác nhận trên trình duyệt...");
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let poll;
+    try {
+      poll = await api.devicePoll(deviceCode);
+    } catch (err) {
+      console.log(`\nLỗi khi kiểm tra trạng thái: ${err.message}`);
+      continue;
+    }
+
+    if (poll.status === "approved") {
+      if (!poll.token) {
+        throw new Error(
+          "Trạng thái approved nhưng thiếu token trong phản hồi — không thể lưu credential."
+        );
+      }
+      saveCredential(apiUrl, {
+        token: poll.token,
+        tokenType: poll.tokenType || "pmcp",
+        expiresAt: poll.expiresAt,
+        user: poll.user,
+      });
+      const email = poll.user && poll.user.email;
+      const expDate = poll.expiresAt ? new Date(poll.expiresAt).toLocaleString() : "?";
+      console.log(`\nĐã đăng nhập ${email || ""} — key hết hạn ${expDate}.`);
+      return;
+    }
+    if (poll.status === "denied") {
+      throw new Error("Yêu cầu đăng nhập đã bị từ chối trên trình duyệt.");
+    }
+    if (poll.status === "expired") {
+      throw new Error("Yêu cầu đăng nhập đã hết hạn — chạy lại `pan ui login`.");
+    }
+    process.stdout.write(".");
+  }
+  throw new Error("Hết thời gian chờ xác nhận đăng nhập — chạy lại `pan ui login`.");
+}
+
+module.exports = { run };

package/lib/ui/logout.js

@@ -0,0 +1,22 @@
+// lib/ui/logout.js — xóa credential local (~/.pan/credentials.json) cho API hiện tại.
+const { createApiClient } = require("./api");
+const { getApiConfig, loadCredential, clearCredential } = require("./config");
+const { findWorkspaceRoot } = require("./workspace");
+
+async function run(_args) {
+  const workspaceRoot = findWorkspaceRoot() || process.cwd();
+  const { apiUrl } = getApiConfig(workspaceRoot);
+
+  const cred = loadCredential(apiUrl);
+  if (!cred) {
+    console.log(`Chưa đăng nhập Pan Studio (${apiUrl}) — không có gì để đăng xuất.`);
+    return;
+  }
+
+  clearCredential(apiUrl);
+  const email = cred.user && cred.user.email;
+  console.log(`Đã đăng xuất${email ? ` ${email}` : ""} khỏi ${apiUrl}.`);
+  console.log("Key local đã xóa. (Token trên backend vẫn còn hạn — thu hồi tại UI/mcp-tokens nếu cần.)");
+}
+
+module.exports = { run };

package/lib/ui/palettes.js

@@ -0,0 +1,103 @@
+// lib/ui/palettes.js — bảng màu cho `pan ui init` scaffold.
+// Mục tiêu: chỉ đổi màu chủ đạo (primary/secondary/accent...) — panui theme + inline HTML
+// của template dùng placeholder __PRIMARY__ / __PRIMARY_DARK__ / ... init thay bằng hex bên dưới.
+//
+// theme app.panui.yaml chỉ nhận primary/sidebar/accent; các sắc còn lại (primaryDark, secondary,
+// primarySoft, onPrimary) dùng cho gradient/nền trong HTML inline (html-ui) của template landing.
+
+/** @typedef {{ id, label, primary, primaryDark, secondary, accent, sidebar, primarySoft, onPrimary }} Palette */
+
+/** Danh sách placeholder init sẽ thay trong MỌI file template. */
+const PALETTE_TOKENS = [
+  "primary",
+  "primaryDark",
+  "secondary",
+  "accent",
+  "sidebar",
+  "primarySoft",
+  "onPrimary",
+];
+
+/** @type {Palette[]} */
+const PALETTES = [
+  {
+    id: "indigo",
+    label: "Indigo — Xanh tím than (mặc định, hiện đại)",
+    primary: "#4f46e5",
+    primaryDark: "#4338ca",
+    secondary: "#0ea5e9",
+    accent: "#f59e0b",
+    sidebar: "#1e1b4b",
+    primarySoft: "#eef2ff",
+    onPrimary: "#ffffff",
+  },
+  {
+    id: "emerald",
+    label: "Emerald — Xanh lá (tươi, tin cậy)",
+    primary: "#059669",
+    primaryDark: "#047857",
+    secondary: "#14b8a6",
+    accent: "#f59e0b",
+    sidebar: "#064e3b",
+    primarySoft: "#ecfdf5",
+    onPrimary: "#ffffff",
+  },
+  {
+    id: "rose",
+    label: "Rose — Đỏ hồng (nổi bật, năng lượng)",
+    primary: "#e11d48",
+    primaryDark: "#be123c",
+    secondary: "#f43f5e",
+    accent: "#fb7185",
+    sidebar: "#4c0519",
+    primarySoft: "#fff1f2",
+    onPrimary: "#ffffff",
+  },
+  {
+    id: "violet",
+    label: "Violet — Tím (sáng tạo, cao cấp)",
+    primary: "#7c3aed",
+    primaryDark: "#6d28d9",
+    secondary: "#a855f7",
+    accent: "#ec4899",
+    sidebar: "#2e1065",
+    primarySoft: "#f5f3ff",
+    onPrimary: "#ffffff",
+  },
+  {
+    id: "amber",
+    label: "Amber — Cam hổ phách (ấm, thân thiện)",
+    primary: "#ea580c",
+    primaryDark: "#c2410c",
+    secondary: "#f59e0b",
+    accent: "#fbbf24",
+    sidebar: "#431407",
+    primarySoft: "#fff7ed",
+    onPrimary: "#ffffff",
+  },
+  {
+    id: "graphite",
+    label: "Graphite — Xám than (tối giản, sang trọng)",
+    primary: "#0f172a",
+    primaryDark: "#020617",
+    secondary: "#334155",
+    accent: "#38bdf8",
+    sidebar: "#020617",
+    primarySoft: "#f1f5f9",
+    onPrimary: "#ffffff",
+  },
+];
+
+const PALETTE_BY_ID = new Map(PALETTES.map((p) => [p.id, p]));
+
+/** Bản đồ placeholder `__TOKEN__` → hex cho 1 palette (dùng khi thay thế template). */
+function paletteReplacements(palette) {
+  const map = {};
+  for (const token of PALETTE_TOKENS) {
+    const upper = token.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase();
+    map[`__${upper}__`] = palette[token];
+  }
+  return map; // vd { "__PRIMARY__": "#4f46e5", "__PRIMARY_DARK__": "#4338ca", ... }
+}
+
+module.exports = { PALETTES, PALETTE_BY_ID, PALETTE_TOKENS, paletteReplacements };

package/lib/ui/published-html.js

@@ -0,0 +1,24 @@
+// lib/ui/published-html.js — GATE sync (§4.6, OD-U2) rồi POST /projects/:id/export/html,
+// poll export/versions tới done, in URL công khai <apiBase>/p/<urlPublicPrefix>.
+const { ensureSynced, pollExportDone } = require("./export-gate");
+
+async function run(_args) {
+  const { api, project, backend } = await ensureSynced();
+
+  console.log(`Đang build & publish HTML cho '${project.name || project.id}'...`);
+  await api.exportHtml(backend.id);
+  console.log("Đang chờ build hoàn tất...");
+  const version = await pollExportDone(api, backend.id);
+
+  const prefix = project.urlPublicPrefix || (version && version.urlPublicPrefix);
+  if (!prefix) {
+    console.log(
+      "\nBuild xong nhưng không xác định được urlPublicPrefix — kiểm tra thủ công trên `GET /projects/:id`."
+    );
+    return;
+  }
+  const url = `${backend.apiUrl}/p/${prefix}`;
+  console.log(`\nĐã publish: ${url}`);
+}
+
+module.exports = { run };

package/lib/ui/sync.js

@@ -0,0 +1,137 @@
+// lib/ui/sync.js — push local→backend + diff + cảnh báo tên/id dự án + xác nhận (§4.5,
+// OD-U3). Xuất thêm `resolveProject`/`diffProject`/`pushDiff` để published-html.js và
+// gen-react-web-code.js tái dùng làm GATE (§4.6, OD-U2) qua lib/ui/export-gate.js.
+const fs = require("fs");
+const path = require("path");
+const { createApiClient } = require("./api");
+const { getApiConfig, loadCredential, isExpired } = require("./config");
+const {
+  findWorkspaceRoot,
+  scanPanuiProjects,
+  selectProject,
+  readBackendId,
+} = require("./workspace");
+const { computeDiff, isDiffClean, printDiff } = require("./diff");
+
+async function loadInquirer() {
+  const inq = await import("@inquirer/prompts").catch(() => null);
+  if (!inq) {
+    throw new Error("Cần TTY (@inquirer/prompts) cho lệnh này.");
+  }
+  return inq;
+}
+
+function toList(res) {
+  if (Array.isArray(res)) return res;
+  if (res && Array.isArray(res.items)) return res.items;
+  if (res && Array.isArray(res.data)) return res.data;
+  return [];
+}
+
+/**
+ * Monorepo scan (§4.7) → chọn dự án panui → đọc backend.id. Thiếu backend.id → gợi ý clone.
+ * @returns {Promise<{ projectDir: string, appYamlPath: string, backend: {id:string, apiUrl:string} }>}
+ */
+async function resolveProject() {
+  const workspaceRoot = findWorkspaceRoot() || process.cwd();
+  const candidates = scanPanuiProjects(workspaceRoot);
+  const picked = await selectProject(candidates);
+  const backend = readBackendId(picked.appYamlPath);
+  if (!backend || !backend.id || !backend.apiUrl) {
+    throw new Error(
+      `Dự án '${picked.name}' chưa liên kết backend (thiếu backend.id/apiUrl trong app.panui.yaml) — chạy \`pan ui clone\` để tạo liên kết.`
+    );
+  }
+  return { projectDir: picked.dir, appYamlPath: picked.appYamlPath, backend };
+}
+
+/**
+ * Chạy diff local↔backend cho 1 dự án đã resolve (yêu cầu credential hợp lệ).
+ * @param {{ projectDir: string, backend: {id:string, apiUrl:string} }} resolved
+ * @returns {Promise<{ api, project, backend, projectDir, diff }>}
+ */
+async function diffProject({ projectDir, backend }) {
+  const cred = loadCredential(backend.apiUrl);
+  if (!cred || isExpired(cred)) {
+    throw new Error("Chưa đăng nhập hoặc key đã hết hạn — chạy `pan ui init` trước.");
+  }
+  const api = createApiClient({ apiUrl: backend.apiUrl, token: cred.token });
+  const project = await api.getProject(backend.id);
+  const treeRes = await api.listFiles(backend.id);
+  const backendFiles = toList(treeRes);
+  const diff = await computeDiff(projectDir, backendFiles, async (relPath) => {
+    const res = await api.getContent(backend.id, relPath);
+    return typeof res === "string" ? res : res && res.content;
+  });
+  return { api, project, backend, projectDir, diff };
+}
+
+/**
+ * Đẩy thay đổi lên backend theo kết quả diffProject(). Hỏi riêng trước khi xóa.
+ * @param {{ api, backend, projectDir, diff }} state
+ */
+async function pushDiff({ api, backend, projectDir, diff }) {
+  for (const relPath of [...diff.added, ...diff.changed]) {
+    const content = fs.readFileSync(path.join(projectDir, relPath), "utf8");
+    await api.putFile(backend.id, {
+      path: relPath,
+      content,
+      editNote: "pan-cli sync",
+    });
+    console.log(`  đã đẩy: ${relPath}`);
+  }
+
+  if (diff.removed.length) {
+    const inq = await loadInquirer();
+    const ok = await inq.confirm({
+      message: `Xóa ${diff.removed.length} file trên backend không còn ở local?`,
+      default: false,
+    });
+    if (ok) {
+      for (const relPath of diff.removed) {
+        await api.deleteFile(backend.id, relPath);
+        console.log(`  đã xóa: ${relPath}`);
+      }
+    } else {
+      console.log("Bỏ qua xóa file trên backend.");
+    }
+  }
+}
+
+async function run(_args) {
+  const resolved = await resolveProject();
+  const state = await diffProject(resolved);
+  const { project, backend, diff } = state;
+
+  const inq = await loadInquirer();
+  console.log(
+    `Đồng bộ lên dự án '${project.name || project.id}' (id ${backend.id}) — đúng dự án?`
+  );
+  const proceed = await inq.confirm({ message: "Tiếp tục?", default: false });
+  if (!proceed) {
+    console.log("Đã hủy.");
+    return;
+  }
+
+  if (isDiffClean(diff)) {
+    console.log("Không có thay đổi để đồng bộ — local đã khớp backend.");
+    return;
+  }
+
+  console.log("Thay đổi phát hiện:");
+  printDiff(diff);
+
+  const ok = await inq.confirm({
+    message: "Đẩy các thay đổi trên lên backend?",
+    default: false,
+  });
+  if (!ok) {
+    console.log("Đã hủy.");
+    return;
+  }
+
+  await pushDiff(state);
+  console.log("Đồng bộ hoàn tất.");
+}
+
+module.exports = { run, resolveProject, diffProject, pushDiff };