pan-stack-cli 0.1.5 → 0.2.1

package/lib/run-command.js

@@ -1,18 +1,20 @@
 const fs = require("fs");
 const path = require("path");
 const { spawn, spawnSync } = require("child_process");
-const readline = require("readline");
 const {
   getCommandDefinition,
   commandBaseDir,
   resolveCommandName,
+  parseSequenceSteps,
 } = require("./manifest");
 const { sourceMatchesProject } = require("./discover");
 const { runShellScript, runExecLine, spawnOptions } = require("./platform");
+const { hasSelect, resolveChoices, runSelect, SELECT_BACK } = require("./select");
+const { t } = require("./i18n");
 
 function needDir(dir) {
   if (!fs.existsSync(dir)) {
-    throw new Error(`Directory not found: ${dir} (run 'pan clone' first?)`);
+    throw new Error(t("DIRECTORY_NOT_FOUND__DIR", { dir }));
   }
 }
 
@@ -27,7 +29,7 @@ function resolveCwd(source, cwd) {
   return path.resolve(base, cwd);
 }
 
-function buildPanEnv(source, forwardedArgs) {
+function buildPanEnv(source, forwardedArgs, selected, extraEnv) {
   const panEnv = {
     ...process.env,
     PAN_REPO_ROOT: source.root,
@@ -38,49 +40,149 @@ function buildPanEnv(source, forwardedArgs) {
   forwardedArgs.forEach((value, index) => {
     panEnv[`PAN_ARG_${index + 1}`] = value;
   });
+  // Kết quả picker (field select trong .pan.yaml) → script đọc qua $PAN_SELECTED (mỗi dòng 1 giá trị).
+  if (Array.isArray(selected)) {
+    panEnv.PAN_SELECTED = selected.join("\n");
+    panEnv.PAN_SELECTED_COUNT = String(selected.length);
+  }
+  // Biến riêng cho 1 bước trong `sequence` (vd "MODE=prod build-be") — đè lên env chung.
+  if (extraEnv && Object.keys(extraEnv).length) {
+    Object.assign(panEnv, extraEnv);
+  }
   return panEnv;
 }
 
-function runExec(source, def, forwardedArgs) {
+// Core chạy `exec:` — SYNC, KHÔNG process.exit (để sequence gọi lặp được). Trả {status}.
+function runExecCore(source, def, forwardedArgs, selected, extraEnv) {
   const cwd = resolveCwd(source, def.cwd);
   needDir(cwd);
 
   const execLine = [def.exec, ...forwardedArgs].filter(Boolean).join(" ").trim();
   if (!execLine) {
-    throw new Error("Command is missing 'exec' or 'shell'.");
+    throw new Error(t("COMMAND_MISSING_EXEC_OR_SHELL"));
   }
 
-  const result = runExecLine(execLine, {
+  return runExecLine(execLine, {
     cwd,
     stdio: "inherit",
-    env: buildPanEnv(source, forwardedArgs),
+    env: buildPanEnv(source, forwardedArgs, selected, extraEnv),
   });
-
-  process.exit(result.status ?? 1);
 }
 
-function runShell(source, def, forwardedArgs) {
+// Core chạy `shell:` — SYNC, KHÔNG process.exit (để sequence gọi lặp được). Trả {status}.
+function runShellCore(source, def, forwardedArgs, selected, extraEnv) {
   const cwd = resolveCwd(source, def.cwd || ".");
   if (def.cwd) {
     needDir(cwd);
   }
+  return runShellScript(def.shell, {
+    cwd,
+    stdio: "inherit",
+    env: buildPanEnv(source, forwardedArgs, selected, extraEnv),
+  });
+}
+
+function runExec(source, def, forwardedArgs, selected) {
+  const result = runExecCore(source, def, forwardedArgs, selected);
+  process.exit(result.status ?? 1);
+}
 
+function runShell(source, def, forwardedArgs, selected) {
   let result;
   try {
-    result = runShellScript(def.shell, {
-      cwd,
-      stdio: "inherit",
-      env: buildPanEnv(source, forwardedArgs),
-    });
+    result = runShellCore(source, def, forwardedArgs, selected);
   } catch (error) {
     console.error(error.message);
     process.exit(1);
   }
-
   process.exit(result.status ?? 1);
 }
 
-function runProjectCommand(source, commandName, args) {
+// Chạy 1 command def (đã resolve target nếu có) mà KHÔNG process.exit — dùng trong sequence.
+// Trả {status} (0 = ok). Ném lỗi nếu command thiếu cả exec/shell.
+async function runOneStepDef(source, commandName, resolved, extraEnv) {
+  let selected = await resolveSelection(source, resolved, []);
+  // Bước trong sequence không có "menu cha" để quay lại — 'b' ở đây coi như bước này không chọn gì.
+  if (selected === SELECT_BACK) selected = [];
+  if (selected && selected.length === 0) {
+    console.error(t("NOTHING_SELECTED_EXITING"));
+    return { status: 0, skipped: true };
+  }
+  if (resolved.shell) {
+    return runShellCore(source, resolved, [], selected, extraEnv);
+  }
+  if (resolved.exec) {
+    return runExecCore(source, resolved, [], selected, extraEnv);
+  }
+  throw new Error(
+    t("COMMAND_MISSING_EXEC_OR_SHELL_IN_SOURCE__COMMAND_PATH", { command: commandName, path: source.path })
+  );
+}
+
+// `sequence:` — chạy nhiều command ĐÃ khai báo trong CÙNG file .pan.yaml, TUẦN TỰ theo thứ tự,
+// dừng ngay khi 1 bước lỗi (trừ bước có "?" cuối tên lệnh → cảnh báo rồi chạy tiếp).
+async function runSequence(source, def, commandName) {
+  const steps = parseSequenceSteps(def.sequence);
+  if (steps.length === 0) {
+    throw new Error(`Command '${commandName}' has an empty sequence.`);
+  }
+
+  console.log(`▶ ${commandName}: ${steps.length} step(s)`);
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index];
+    if (!source.commands[step.name]) {
+      throw new Error(
+        `sequence step ${index + 1}/${steps.length} in '${commandName}': command '${step.name}' not found in ${source.path}`
+      );
+    }
+    const resolved = getCommandDefinition(source, step.name, step.target);
+    const label = step.target ? `${step.name}:${step.target}` : step.name;
+    const envHint = Object.keys(step.env).length ? ` (${Object.entries(step.env).map(([k, v]) => `${k}=${v}`).join(" ")})` : "";
+    console.log(`\n── [${index + 1}/${steps.length}] ${label}${envHint} ──`);
+
+    let result;
+    try {
+      result = await runOneStepDef(source, step.name, resolved, step.env);
+    } catch (error) {
+      result = { status: 1, error };
+    }
+
+    const status = result.status ?? 1;
+    if (status !== 0) {
+      if (step.optional) {
+        console.warn(`⚠️  [${index + 1}/${steps.length}] ${label} failed (exit ${status}) — optional, continuing.${result.error ? " " + result.error.message : ""}`);
+        continue;
+      }
+      if (result.error) console.error(result.error.message);
+      console.error(`✗ sequence '${commandName}' stopped at step ${index + 1}/${steps.length} (${label}), exit ${status}.`);
+      return status;
+    }
+  }
+  console.log(`\n✓ sequence '${commandName}' — ${steps.length} step(s) done.`);
+  return 0;
+}
+
+// Nếu command khai báo select (selectFrom/selectChoices) → render picker, trả mảng value.
+// 'all' arg / PAN_ALL=1 / non-TTY ⇒ chọn hết. Trả null nếu command không có select.
+async function resolveSelection(source, def, forwardedArgs) {
+  if (!hasSelect(def)) return null;
+  const cwd = resolveCwd(source, def.cwd || ".");
+  const env = buildPanEnv(source, forwardedArgs);
+  const choices = resolveChoices(def, { cwd, env });
+  const forceAll =
+    forwardedArgs.includes("all") || process.env.PAN_ALL === "1" || !process.stdin.isTTY;
+  return runSelect(
+    {
+      message: def.selectMessage || "Chọn:",
+      multi: def.selectMulti !== "false",
+      all: def.selectAll !== "false",
+      choices,
+    },
+    { forceAll }
+  );
+}
+
+async function runProjectCommand(source, commandName, args) {
   let subArg = "";
   let forwardedArgs = [...args];
 
@@ -93,20 +195,41 @@ function runProjectCommand(source, commandName, args) {
 
   const resolved = getCommandDefinition(source, commandName, subArg);
   if (!resolved) {
-    throw new Error(`Command '${commandName}' not found in ${source.path}`);
+    throw new Error(t("COMMAND_NOT_FOUND_IN_SOURCE__COMMAND_PATH", { command: commandName, path: source.path }));
+  }
+
+  if (resolved.sequence) {
+    const status = await runSequence(source, resolved, commandName);
+    process.exit(status);
+    return;
+  }
+
+  const selected = await resolveSelection(source, resolved, forwardedArgs);
+  // 'b' ở bước chọn (selectFrom/selectChoices) — KHÔNG thoát hẳn tiến trình: trả tín hiệu để
+  // caller (menu tương tác `pan` trống) quay lại bước chọn TRƯỚC đó thay vì chạy lệnh/thoát.
+  // Lời gọi trực tiếp không qua menu (`pan <command>` / runWithProjectResolution) không có "menu
+  // cha" để quay lại nên coi tín hiệu này như huỷ lệnh êm (xem runWithProjectResolution bên dưới).
+  if (selected === SELECT_BACK) {
+    return { backed: true };
+  }
+  if (selected && selected.length === 0) {
+    console.error(t("NOTHING_SELECTED_EXITING"));
+    process.exit(0);
   }
 
   if (resolved.shell) {
-    runShell(source, resolved, forwardedArgs);
+    runShell(source, resolved, forwardedArgs, selected);
     return;
   }
 
   if (resolved.exec) {
-    runExec(source, resolved, forwardedArgs);
+    runExec(source, resolved, forwardedArgs, selected);
     return;
   }
 
-  throw new Error(`Command '${commandName}' is missing 'exec' or 'shell' in ${source.path}`);
+  throw new Error(
+    t("COMMAND_MISSING_EXEC_OR_SHELL_IN_SOURCE__COMMAND_PATH", { command: commandName, path: source.path })
+  );
 }
 
 function sourceLabel(source) {
@@ -116,31 +239,26 @@ function sourceLabel(source) {
   return source.repoName || source.project;
 }
 
-function promptProjectChoice(matches, commandName) {
-  return new Promise((resolve, reject) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    console.log("");
-    matches.forEach((source, index) => {
-      const def = source.commands[commandName];
-      const desc = def?.description ? ` — ${def.description}` : "";
-      console.log(`  ${index + 1}. ${sourceLabel(source)} (${source.root})${desc}`);
-    });
-    console.log("");
-
-    rl.question("Pick a project (number): ", (answer) => {
-      rl.close();
-      const choice = Number.parseInt(answer, 10);
-      if (!Number.isFinite(choice) || choice < 1 || choice > matches.length) {
-        reject(new Error("Invalid choice."));
-        return;
-      }
-      resolve(matches[choice - 1]);
-    });
+async function promptProjectChoice(matches, commandName) {
+  const choices = matches.map((source) => {
+    const def = source.commands[commandName];
+    const desc = def?.description ? ` — ${def.description}` : "";
+    return { name: `${sourceLabel(source)}${desc}`, value: source };
   });
+  const picked = await runSelect(
+    {
+      message: t("COMMAND_MULTIPLE_PLACES_SELECT_PROJECT__COMMAND", { command: commandName }),
+      multi: false,
+      all: false,
+      choices,
+    },
+    { forceAll: false }
+  );
+  const source = Array.isArray(picked) ? picked[0] : picked;
+  if (!source || source === SELECT_BACK) {
+    throw new Error(t("NOTHING_SELECTED_EXITING"));
+  }
+  return source;
 }
 
 async function runWithProjectResolution(
@@ -153,9 +271,7 @@ async function runWithProjectResolution(
   const resolvedName = resolveCommandName(allSources, commandName);
 
   if (matches.length === 0) {
-    throw new Error(
-      `Command '${commandName}' not found in any .pan.yaml file.`
-    );
+    throw new Error(t("COMMAND_NOT_FOUND_ANYWHERE__COMMAND", { command: commandName }));
   }
 
   let source = null;
@@ -163,7 +279,7 @@ async function runWithProjectResolution(
     source = matches.find((item) => sourceMatchesProject(item, projectFlag));
     if (!source) {
       const names = matches.map((item) => sourceLabel(item)).join(", ");
-      throw new Error(`Project '${projectFlag}' not found. Available: ${names}`);
+      throw new Error(t("PROJECT_NOT_FOUND__PROJECT_NAMES", { project: projectFlag, names }));
     }
   } else if (matches.length === 1) {
     source = matches[0];
@@ -181,18 +297,23 @@ async function runWithProjectResolution(
         (item, index) => `${index + 1}. ${sourceLabel(item)} (${item.root})`
       );
       throw new Error(
-        `Command '${commandName}' is defined in multiple projects. Use --project <name>.\n${lines.join("\n")}`
+        t("COMMAND_MULTIPLE_PROJECTS__COMMAND_LINES", { command: commandName, lines: lines.join("\n") })
       );
     }
   }
 
-  runProjectCommand(source, resolvedName, args);
+  // Lời gọi trực tiếp (không qua menu tương tác) không có "bước trước" để quay lại — 'b' ở đây
+  // chỉ đơn giản là huỷ êm (giống 'không chọn gì'), KHÔNG lỗi.
+  const result = await runProjectCommand(source, resolvedName, args);
+  if (result && result.backed) {
+    console.log(t("NOTHING_SELECTED_EXITING"));
+  }
 }
 
 function runGitScript(scriptName, args) {
   const scriptPath = path.join(__dirname, "git", scriptName);
   if (!fs.existsSync(scriptPath)) {
-    throw new Error(`Script not found: ${scriptPath}`);
+    throw new Error(t("SCRIPT_NOT_FOUND__PATH", { path: scriptPath }));
   }
 
   const child = spawn(process.execPath, [scriptPath, ...args], spawnOptions({

package/lib/serve.js

@@ -0,0 +1,75 @@
+// pan serve — chạy static HTTP server cho 1 thư mục build (vd output `panui:gen`).
+// Bọc package `serve` (npm). Ưu tiên bin local (đã cài trong pan-stack-cli); nếu chưa có
+// thì fallback `npx --yes serve` (tự tải). SPA mode (-s) để refresh/route sâu vẫn trả index.html.
+const { spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+function printServeHelp() {
+  console.log(`usage: pan serve [dir] [options]
+
+Chạy static server cho thư mục build (mặc định thư mục hiện tại).
+Ví dụ:
+  pnpm panui:gen examples/blog-project -o panui-demo   # build web demo tĩnh
+  pan serve panui-demo                                 # xem demo (http://localhost:3000)
+  pan serve panui-demo -p 8080
+
+options:
+  -p, --port <port>   Cổng lắng nghe (mặc định 3000)
+  -h, --help          Hiện trợ giúp này`);
+}
+
+function parseServeArgs(args) {
+  let dir = ".";
+  let port = "";
+  let dirSet = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "-h" || a === "--help") {
+      printServeHelp();
+      process.exit(0);
+    } else if (a === "-p" || a === "--port") {
+      port = args[i + 1] || "";
+      i += 1;
+    } else if (a.startsWith("--port=")) {
+      port = a.slice("--port=".length);
+    } else if (!dirSet) {
+      dir = a;
+      dirSet = true;
+    }
+  }
+  return { dir, port };
+}
+
+/** Bin `serve` cài cục bộ trong pan-stack-cli (nếu có). */
+function localServeBin() {
+  const bin = path.join(__dirname, "..", "node_modules", ".bin", "serve");
+  return fs.existsSync(bin) ? bin : null;
+}
+
+function runServe(args) {
+  const { dir, port } = parseServeArgs(args);
+  const target = path.resolve(dir);
+  if (!fs.existsSync(target)) {
+    console.error(`\n✗ Không tồn tại thư mục: ${target}\n`);
+    process.exit(1);
+  }
+
+  // `serve <dir> -s [-l <port>]` — `-s` single-page (fallback index.html).
+  const serveArgs = [target, "-s"];
+  if (port) serveArgs.push("-l", String(port));
+
+  const local = localServeBin();
+  const cmd = local || "npx";
+  const spawnArgs = local ? serveArgs : ["--yes", "serve", ...serveArgs];
+
+  const child = spawn(cmd, spawnArgs, { stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`\n✗ Không chạy được 'serve': ${err.message}`);
+    console.error("  Cài: cd apps/pan-stack-tools/pan-stack-cli && pnpm install (hoặc dùng npx serve).\n");
+    process.exit(1);
+  });
+  child.on("close", (code) => process.exit(code || 0));
+}
+
+module.exports = { runServe };

package/lib/skill-registry-client.js

@@ -0,0 +1,173 @@
+// Client cho registry server pan-agent-skill-registry (apps/pan-agent-skill-registry):
+// gọi HTTP /api/registry + /api/packages/*.zip, quản lý lockfile local
+// <workspaceRoot>/.pan/skills-lock.json để biết cái gì đã cài (installed vs updatable).
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { isWindows } = require("./platform");
+
+const DEFAULT_REGISTRY_URL = "http://localhost:4600";
+const LOCK_RELATIVE_PATH = path.join(".pan", "skills-lock.json");
+
+function getRegistryBaseUrl() {
+  return (process.env.PAN_SKILL_REGISTRY_URL || DEFAULT_REGISTRY_URL).replace(/\/+$/, "");
+}
+
+function friendlyNetworkError(baseUrl, err) {
+  return new Error(
+    `✗ Không kết nối được tới registry server (${baseUrl}). Cần server đang chạy trước — xem apps/pan-agent-skill-registry/README.md.` +
+      (err && err.message ? ` (${err.message})` : "")
+  );
+}
+
+async function fetchJson(url) {
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    throw friendlyNetworkError(url, err);
+  }
+  if (!res.ok) {
+    throw new Error(`✗ Registry server trả lỗi HTTP ${res.status} cho ${url}`);
+  }
+  return res.json();
+}
+
+async function fetchRegistry(baseUrl = getRegistryBaseUrl()) {
+  const data = await fetchJson(`${baseUrl}/api/registry`);
+  return Array.isArray(data.items) ? data.items : [];
+}
+
+async function checkHealth(baseUrl = getRegistryBaseUrl()) {
+  try {
+    const data = await fetchJson(`${baseUrl}/health`);
+    return !!(data && data.ok);
+  } catch {
+    return false;
+  }
+}
+
+function lockPath(workspaceRoot) {
+  return path.join(workspaceRoot, LOCK_RELATIVE_PATH);
+}
+
+function loadLock(workspaceRoot) {
+  const p = lockPath(workspaceRoot);
+  if (!fs.existsSync(p)) {
+    return { installed: {} };
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (!raw || typeof raw !== "object") return { installed: {} };
+    if (!raw.installed || typeof raw.installed !== "object") raw.installed = {};
+    return raw;
+  } catch {
+    return { installed: {} };
+  }
+}
+
+function saveLock(workspaceRoot, lock) {
+  const dir = path.join(workspaceRoot, ".pan");
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(lockPath(workspaceRoot), JSON.stringify(lock, null, 2) + "\n", "utf8");
+}
+
+// @returns { notInstalled: item[], updatable: item[], upToDate: item[] }
+// (updatable/upToDate item objects are augmented with `oldVersion`).
+function diffRegistry(items, lock) {
+  const installed = (lock && lock.installed) || {};
+  const notInstalled = [];
+  const updatable = [];
+  const upToDate = [];
+  for (const item of items) {
+    const entry = installed[item.name];
+    if (!entry) {
+      notInstalled.push(item);
+    } else if (entry.version !== item.version) {
+      updatable.push({ ...item, oldVersion: entry.version });
+    } else {
+      upToDate.push(item);
+    }
+  }
+  return { notInstalled, updatable, upToDate };
+}
+
+function downloadToTemp(url) {
+  return new Promise((resolve, reject) => {
+    fetch(url)
+      .then(async (res) => {
+        if (!res.ok) {
+          reject(new Error(`✗ Tải zip thất bại (HTTP ${res.status}) từ ${url}`));
+          return;
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        const tmpFile = path.join(os.tmpdir(), `pan-skill-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`);
+        fs.writeFileSync(tmpFile, buf);
+        resolve(tmpFile);
+      })
+      .catch((err) => reject(friendlyNetworkError(url, err)));
+  });
+}
+
+function extractZip(zipFile, destDir) {
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+
+  if (isWindows()) {
+    try {
+      execFileSync(
+        "powershell",
+        ["-NoProfile", "-Command", `Expand-Archive -Force -Path '${zipFile}' -DestinationPath '${destDir}'`],
+        { stdio: "pipe" }
+      );
+      return;
+    } catch (err) {
+      throw new Error(
+        `✗ Không giải nén được (PowerShell Expand-Archive). Cần PowerShell khả dụng trên máy. (${err.message})`
+      );
+    }
+  }
+
+  try {
+    execFileSync("unzip", ["-o", "-q", zipFile, "-d", destDir], { stdio: "pipe" });
+  } catch (err) {
+    throw new Error(
+      `✗ Không giải nén được (thiếu lệnh 'unzip' hoặc file zip lỗi). Cài unzip rồi thử lại. (${err.message})`
+    );
+  }
+}
+
+// Tải zip của `item` (từ baseUrl + item.zip) và giải nén vào `<destDir>/<item.name>/`
+// (zip không có lớp thư mục bọc — ta tự tạo).
+async function downloadAndExtract(baseUrl, item, destDir) {
+  const zipUrl = `${baseUrl}${item.zip}`;
+  const tmpFile = await downloadToTemp(zipUrl);
+  try {
+    const target = path.join(destDir, item.name);
+    extractZip(tmpFile, target);
+    return target;
+  } finally {
+    try {
+      fs.unlinkSync(tmpFile);
+    } catch {
+      /* bỏ qua */
+    }
+  }
+}
+
+module.exports = {
+  DEFAULT_REGISTRY_URL,
+  getRegistryBaseUrl,
+  fetchRegistry,
+  checkHealth,
+  lockPath,
+  loadLock,
+  saveLock,
+  diffRegistry,
+  downloadAndExtract,
+};

package/lib/stats/aggregate.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const { canonicalEmail } = require("./identity");
+
+/**
+ * Gộp commit theo thành viên (email chuẩn) và theo dự án.
+ * (Commit đã được lọc theo range ở tầng git; range ở đây chỉ để chắc chắn.)
+ */
+function aggregate(commits, aliasMap = {}, range = {}) {
+  const { from = -Infinity, to = Infinity } = range;
+  const byEmail = new Map();
+
+  for (const c of commits) {
+    if (c.ts < from || c.ts > to) continue;
+    const email = canonicalEmail(c.email, aliasMap);
+    if (!byEmail.has(email)) {
+      byEmail.set(email, { email, name: c.name || email, commits: 0, additions: 0, deletions: 0, projects: new Map() });
+    }
+    const m = byEmail.get(email);
+    m.commits += 1;
+    m.additions += c.additions;
+    m.deletions += c.deletions;
+    if (c.name) m.name = c.name;
+
+    if (!m.projects.has(c.repoName)) {
+      m.projects.set(c.repoName, { name: c.repoName, commits: 0, additions: 0, deletions: 0 });
+    }
+    const p = m.projects.get(c.repoName);
+    p.commits += 1;
+    p.additions += c.additions;
+    p.deletions += c.deletions;
+  }
+
+  const members = [...byEmail.values()]
+    .map((m) => ({ ...m, projects: [...m.projects.values()].sort((a, b) => b.commits - a.commits) }))
+    .sort((a, b) => b.commits - a.commits);
+
+  const totals = members.reduce(
+    (acc, m) => {
+      acc.commits += m.commits;
+      acc.additions += m.additions;
+      acc.deletions += m.deletions;
+      return acc;
+    },
+    { members: members.length, commits: 0, additions: 0, deletions: 0 }
+  );
+
+  return { members, totals };
+}
+
+module.exports = { aggregate };

package/lib/stats/identity.js

@@ -0,0 +1,20 @@
+"use strict";
+
+const fs = require("fs");
+
+/** Đọc alias-map.json (email biến thể -> email chuẩn). Không có thì {}. */
+function loadAliasMap(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Chuẩn hoá email theo alias-map (fallback chính nó). */
+function canonicalEmail(email, aliasMap = {}) {
+  const key = (email || "").toLowerCase().trim();
+  return aliasMap[key] || key || "unknown@local";
+}
+
+module.exports = { loadAliasMap, canonicalEmail };