pan-stack-cli 0.1.4 → 0.1.5

package/README.md

@@ -40,11 +40,11 @@ skill pre-installed for all three agent folders.
 ## Requirements
 
 - Node.js 18+
-- Git (for `pan clone`, `pull`, `fetch`, `push`, `grv`, `gst`)
+- Git (for `pan clone`, `pull`, `sync-main`, `fetch`, `push`, `grv`, `gst`)
 
 ## Windows support
 
-Built-in commands (`create`, `clone`, `pull`, `push`, `fetch`, `grv`, `gst`) run on
+Built-in commands (`create`, `clone`, `pull`, `sync-main`, `push`, `fetch`, `grv`, `gst`) run on
 Windows, macOS, and Linux. Notes for Windows:
 
 - `shell:` blocks in `.pan.yaml` run through **bash** on all platforms (Git Bash on
@@ -158,6 +158,7 @@ Read `repositories` from the nearest `.project.yaml` (walk-up from cwd):
 |---------|--------|
 | `pan clone` | Clone all repositories in the manifest |
 | `pan pull` | Pull all cloned repositories |
+| `pan sync-main [repo\|all]` (`pan sm`) | Fetch + merge `origin/main` into current branch (interactive picker; conflict summary) |
 | `pan fetch` | Fetch all remotes |
 | `pan push` | Push all repos (`-u origin HEAD` by default) |
 | `pan grv` | `git remote -v` for workspace + each child repo |
@@ -202,7 +203,7 @@ pan-stack-cli/
     platform.js             # Windows/cross-platform helpers
     manifest.js             # YAML parsing
     run-command.js        # command execution
-    git/                  # clone, pull, push, fetch, grv, gst
+    git/                  # clone, pull, sync-main, push, fetch, grv, gst
   templates/workspace/    # pan create template
   references/             # npm publish docs
 ```

package/bin/pan.js

@@ -19,6 +19,8 @@ const GIT_SCRIPT_MAP = {
   push: "git-push.js",
   grv: "git-grv.js",
   gst: "git-gst.js",
+  "sync-main": "git-sync-main.js",
+  sm: "git-sync-main.js",
 };
 
 function parseGlobalArgs(argv) {
@@ -54,6 +56,7 @@ workspace commands (built-in):
   create  Scaffold a new PAN Stack workspace (prompts for folder name)
   clone   Clone all repositories from .project.yaml
   pull    Pull latest changes for all repositories
+  sync-main (sm)  Fetch origin/main and merge into current branch (pick repo or all)
   fetch   Fetch all remotes for all repositories
   push    Push all repositories and set upstream
   grv     List git remotes -v for workspace + child repos

package/lib/discover.js

@@ -12,7 +12,16 @@ const {
   cleanValue,
 } = require("./manifest");
 
-const BUILTIN_GIT_COMMANDS = new Set(["clone", "pull", "fetch", "push", "grv", "gst"]);
+const BUILTIN_GIT_COMMANDS = new Set([
+  "clone",
+  "pull",
+  "sync-main",
+  "sm",
+  "fetch",
+  "push",
+  "grv",
+  "gst",
+]);
 const BUILTIN_WORKSPACE_COMMANDS = new Set(["create", ...BUILTIN_GIT_COMMANDS]);
 
 function readProjectRoots() {

package/lib/git/git-clone.js

@@ -10,7 +10,7 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
-const { spawnOptions } = require("../../platform");
+const { spawnOptions } = require("../platform");
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
 
 function cloneRepo({ name, url, destination, dryRun }) {

package/lib/git/git-sync-main.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/*
+ * Sync origin/main (or --ref) into the current branch for selected PAN Stack repos.
+ *
+ * Fetches first, then merge (default) or rebase (--rebase). Interactive repo picker
+ * when TTY; pass repo name or "all" as first positional argument.
+ */
+
+const {
+  looksLikeManifest,
+  loadManifestRepos,
+  printCommonOptions,
+} = require("./helpers/cli");
+const colors = require("./helpers/colors");
+const { resolveTargets } = require("./helpers/repo-select");
+const {
+  ensureRepoExists,
+  runGit,
+  runGitCapture,
+  getCurrentBranch,
+  refExists,
+  listConflictedFiles,
+  isMergeOrRebaseInProgress,
+  countDirtyFiles,
+} = require("./helpers/git");
+
+const ICON = {
+  ok: "✅",
+  warn: "⚠️",
+  conflict: "⛔",
+  skip: "⏭️",
+  info: "ℹ️",
+};
+
+function printHelp() {
+  console.log(`usage: pan sync-main [repo|all] [options]   (alias: pan sm)
+
+Fetch remote main (or --ref) and merge into the current branch for workspace and/or child repos.
+
+positional:
+  repo|all           Repo name from .project.yaml, or "all". Interactive picker if omitted (TTY).
+
+${printCommonOptions()}
+  --ref REF            Remote-tracking ref to merge (default: origin/main)
+  --rebase             Use git rebase instead of merge
+  --no-workspace       Only manifest child repos (skip workspace stack root)`);
+}
+
+function parseSyncMainArgs(argv) {
+  const args = {
+    help: false,
+    manifest: "",
+    baseDir: ".",
+    dryRun: false,
+    ref: "origin/main",
+    rebase: false,
+    noWorkspace: false,
+    selection: "",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help") {
+      args.help = true;
+    } else if (arg === "--base-dir") {
+      args.baseDir = argv[++index] || ".";
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--ref") {
+      args.ref = argv[++index] || "origin/main";
+    } else if (arg === "--rebase") {
+      args.rebase = true;
+    } else if (arg === "--no-workspace") {
+      args.noWorkspace = true;
+    } else if (!arg.startsWith("-")) {
+      if (looksLikeManifest(arg) && !args.manifest) {
+        args.manifest = arg;
+      } else if (!args.selection) {
+        args.selection = arg;
+      } else {
+        throw new Error(`Unexpected argument: ${arg}`);
+      }
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+function printEarlyConflict({ name, branch, ref, files, mode }) {
+  const headline = colors.bold(
+    colors.red(`${ICON.conflict} [conflict] ${name} (${branch})`)
+  );
+  const detail = colors.yellow(
+    `${mode} ${ref} thất bại — ${files.length} file conflict`
+  );
+  console.log(`${headline} — ${detail}`);
+  for (const file of files.slice(0, 8)) {
+    console.log(colors.dim(`    • ${file}`));
+  }
+  if (files.length > 8) {
+    console.log(colors.dim(`    … và ${files.length - 8} file khác`));
+  }
+}
+
+function syncMainRepo({
+  name,
+  destination,
+  dryRun,
+  ref,
+  rebase,
+}) {
+  const result = {
+    name,
+    destination,
+    branch: "",
+    status: "skipped",
+    message: "",
+    conflictFiles: [],
+    mode: rebase ? "rebase" : "merge",
+  };
+
+  if (!ensureRepoExists({ name, destination })) {
+    result.message = "repo không tồn tại hoặc chưa clone";
+    return result;
+  }
+
+  const branch = getCurrentBranch(destination);
+  result.branch = branch || "(detached HEAD)";
+  if (!branch) {
+    result.message = "đang detached HEAD — bỏ qua";
+    console.log(`${ICON.skip} [skip] ${name}: ${result.message}`);
+    return result;
+  }
+
+  const inProgress = isMergeOrRebaseInProgress(destination);
+  if (inProgress) {
+    const files = listConflictedFiles(destination);
+    result.status = "conflict";
+    result.conflictFiles = files;
+    result.message = `đang dở ${inProgress} — cần resolve trước`;
+    printEarlyConflict({ name, branch, ref, files, mode: inProgress });
+    return result;
+  }
+
+  const dirtyCount = countDirtyFiles(destination);
+  if (dirtyCount > 0) {
+    console.log(
+      `${ICON.warn} ${colors.yellow(`[warn] ${name}: working tree có ${dirtyCount} thay đổi chưa commit`)}`
+    );
+  }
+
+  if (dryRun) {
+    console.log(
+      `[dry-run] (in ${destination}) git fetch origin && git ${rebase ? "rebase" : "merge"} ${ref}`
+    );
+    result.status = "dry-run";
+    result.message = "dry-run";
+    return result;
+  }
+
+  console.log(`[fetch] ${name}: ${destination}`);
+  const fetch = runGitCapture(["fetch", "origin"], { cwd: destination });
+  if (fetch.status !== 0) {
+    result.status = "error";
+    result.message = fetch.stderr || "git fetch origin thất bại";
+    console.log(`${ICON.warn} ${colors.yellow(`[warn] ${name}: ${result.message}`)}`);
+    return result;
+  }
+
+  if (!refExists(destination, ref)) {
+    result.status = "error";
+    result.message = `không tìm thấy ref ${ref} (chạy fetch trước?)`;
+    console.log(`${ICON.warn} ${colors.yellow(`[warn] ${name}: ${result.message}`)}`);
+    return result;
+  }
+
+  const gitArgs = rebase ? ["rebase", ref] : ["merge", "--no-edit", ref];
+  console.log(`[${result.mode}] ${name} (${branch}) ← ${ref}`);
+  const action = runGit(gitArgs, {
+    cwd: destination,
+    dryRun: false,
+    action: result.mode,
+    name,
+  });
+
+  const conflictFiles = listConflictedFiles(destination);
+  if (conflictFiles.length > 0 || action !== 0) {
+    result.status = "conflict";
+    result.conflictFiles = conflictFiles.length > 0 ? conflictFiles : ["(xem git status)"];
+    result.message = `${result.mode} conflict`;
+    printEarlyConflict({
+      name,
+      branch,
+      ref,
+      files: result.conflictFiles,
+      mode: result.mode,
+    });
+    return result;
+  }
+
+  result.status = "ok";
+  result.message = "đã cập nhật";
+  console.log(`${ICON.ok} ${colors.green(`[ok] ${name}: ${branch} đã sync ${ref}`)}`);
+  return result;
+}
+
+function printSummary(results, { ref, rebase }) {
+  const ok = results.filter((item) => item.status === "ok");
+  const conflicts = results.filter((item) => item.status === "conflict");
+  const errors = results.filter((item) => item.status === "error");
+  const skipped = results.filter(
+    (item) => item.status === "skipped" || item.status === "dry-run"
+  );
+
+  console.log("");
+  console.log(colors.bold("─── sync-main summary ───"));
+  console.log(
+    `${ICON.info} ref: ${ref} · mode: ${rebase ? "rebase" : "merge"} · repos: ${results.length}`
+  );
+  console.log(
+    `  ${ICON.ok} ok: ${ok.length} · ${ICON.conflict} conflict: ${conflicts.length} · ${ICON.warn} error: ${errors.length} · ${ICON.skip} skip: ${skipped.length}`
+  );
+
+  if (conflicts.length > 0) {
+    console.log("");
+    console.log(colors.bold(colors.red(`${ICON.conflict} CONFLICT — cần xử lý thủ công`)));
+    for (const item of conflicts) {
+      console.log(colors.yellow(`\n  ${item.name} (${item.branch})`));
+      console.log(colors.dim(`  ${item.destination}`));
+      for (const file of item.conflictFiles) {
+        console.log(`    • ${file}`);
+      }
+      const hint = item.mode === "rebase"
+        ? "git add <file>… && git rebase --continue   (hoặc git rebase --abort)"
+        : "git add <file>… && git commit";
+      console.log(colors.dim(`  → ${hint}`));
+    }
+  }
+
+  if (errors.length > 0) {
+    console.log("");
+    console.log(colors.bold(colors.yellow(`${ICON.warn} LỖI`)));
+    for (const item of errors) {
+      console.log(`  • ${item.name}: ${item.message}`);
+    }
+  }
+
+  if (conflicts.length > 0) {
+    console.log("");
+    console.log(
+      colors.bold(
+        colors.red(
+          `${ICON.conflict} Kết thúc với conflict — resolve từng repo ở trên rồi commit/rebase --continue`
+        )
+      )
+    );
+  } else if (errors.length > 0) {
+    console.log("");
+    console.log(
+      colors.bold(colors.yellow(`${ICON.warn} Kết thúc với lỗi — xem chi tiết ở trên`))
+    );
+  } else if (ok.length > 0) {
+    console.log("");
+    console.log(colors.green(`${ICON.ok} Tất cả repo đã chọn đã sync ${ref}`));
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseSyncMainArgs(argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const { repos, workspaceRoot } = loadManifestRepos({
+    manifestPath: args.manifest,
+    baseDir: args.baseDir,
+  });
+
+  const targets = await resolveTargets({
+    repos,
+    workspaceRoot,
+    includeWorkspace: !args.noWorkspace,
+    selection: args.selection,
+  });
+
+  console.log(
+    `${ICON.info} sync-main: ${targets.length} repo · ${args.rebase ? "rebase" : "merge"} ← ${args.ref}`
+  );
+
+  const results = [];
+  for (const target of targets) {
+    results.push(
+      syncMainRepo({
+        name: target.name,
+        destination: target.destination,
+        dryRun: args.dryRun,
+        ref: args.ref,
+        rebase: args.rebase,
+      })
+    );
+    console.log("");
+  }
+
+  printSummary(results, { ref: args.ref, rebase: args.rebase });
+
+  const hasConflict = results.some((item) => item.status === "conflict");
+  const hasError = results.some((item) => item.status === "error");
+  if (hasConflict || hasError) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/lib/git/helpers/cli.js

@@ -146,6 +146,7 @@ options:
 
 module.exports = {
   parseCommonArgs,
+  looksLikeManifest,
   resolveProjectWorkspace,
   loadManifestRepos,
   printCommonOptions,

package/lib/git/helpers/colors.js

@@ -0,0 +1,19 @@
+const supportsColor =
+  Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.FORCE_COLOR !== "0";
+
+function wrap(code, text) {
+  if (!supportsColor || text == null) {
+    return String(text ?? "");
+  }
+  return `\u001b[${code}m${text}\u001b[0m`;
+}
+
+module.exports = {
+  supportsColor,
+  bold: (text) => wrap("1", text),
+  red: (text) => wrap("31", text),
+  green: (text) => wrap("32", text),
+  yellow: (text) => wrap("33", text),
+  cyan: (text) => wrap("36", text),
+  dim: (text) => wrap("2", text),
+};

package/lib/git/helpers/git.js

@@ -53,9 +53,83 @@ function runGitStatus(directory, gitArgs = []) {
   return result.status ?? 1;
 }
 
+function runGitCapture(gitArgs, { cwd } = {}) {
+  const result = spawnSync("git", gitArgs, spawnOptions({
+    cwd,
+    encoding: "utf8",
+  }));
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim(),
+  };
+}
+
+function getCurrentBranch(directory) {
+  const branch = runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: directory });
+  if (branch.status !== 0) {
+    return "";
+  }
+  if (branch.stdout === "HEAD") {
+    return "";
+  }
+  return branch.stdout;
+}
+
+function refExists(directory, ref) {
+  const result = runGitCapture(["rev-parse", "--verify", ref], { cwd: directory });
+  return result.status === 0;
+}
+
+function listConflictedFiles(directory) {
+  const result = runGitCapture(
+    ["diff", "--name-only", "--diff-filter=U"],
+    { cwd: directory }
+  );
+  if (result.status !== 0) {
+    return [];
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function isMergeOrRebaseInProgress(directory) {
+  const merge = runGitCapture(["rev-parse", "-q", "--verify", "MERGE_HEAD"], {
+    cwd: directory,
+  });
+  if (merge.status === 0) {
+    return "merge";
+  }
+  const rebaseMerge = fs.existsSync(path.join(directory, ".git", "rebase-merge"));
+  const rebaseApply = fs.existsSync(path.join(directory, ".git", "rebase-apply"));
+  if (rebaseMerge || rebaseApply) {
+    return "rebase";
+  }
+  return "";
+}
+
+function countDirtyFiles(directory) {
+  const result = runGitCapture(["status", "--porcelain"], { cwd: directory });
+  if (result.status !== 0) {
+    return 0;
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean).length;
+}
+
 module.exports = {
   isGitRepo,
   runGit,
+  runGitCapture,
+  getCurrentBranch,
+  refExists,
+  listConflictedFiles,
+  isMergeOrRebaseInProgress,
+  countDirtyFiles,
   ensureRepoExists,
   listRemotesVerbose,
   runGitStatus,

package/lib/git/helpers/repo-select.js

@@ -0,0 +1,97 @@
+const readline = require("readline");
+const { isGitRepo } = require("./git");
+
+function buildTargets({ repos, workspaceRoot, includeWorkspace }) {
+  const targets = [];
+  if (includeWorkspace && isGitRepo(workspaceRoot)) {
+    targets.push({
+      name: "workspace",
+      destination: workspaceRoot,
+      label: "workspace (stack root)",
+    });
+  }
+  for (const repo of repos) {
+    targets.push({
+      name: repo.name,
+      destination: repo.destination,
+      label: repo.name,
+    });
+  }
+  return targets;
+}
+
+function findTargetByName(targets, name) {
+  const needle = String(name || "").trim();
+  if (!needle) {
+    return [];
+  }
+  return targets.filter((target) => target.name === needle);
+}
+
+function promptRepoChoice(targets) {
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    console.log("");
+    console.log("Chọn repo để sync-main:");
+    console.log(`  1. all (${targets.length} repo)`);
+    targets.forEach((target, index) => {
+      console.log(`  ${index + 2}. ${target.label}`);
+      console.log(`     ${target.destination}`);
+    });
+    console.log("");
+
+    rl.question("Nhập số (1 = all): ", (answer) => {
+      rl.close();
+      const choice = Number.parseInt(String(answer).trim(), 10);
+      if (!Number.isFinite(choice) || choice < 1 || choice > targets.length + 1) {
+        reject(new Error("Lựa chọn không hợp lệ."));
+        return;
+      }
+      if (choice === 1) {
+        resolve(targets);
+        return;
+      }
+      resolve([targets[choice - 2]]);
+    });
+  });
+}
+
+async function resolveTargets({
+  repos,
+  workspaceRoot,
+  includeWorkspace,
+  selection,
+}) {
+  const targets = buildTargets({ repos, workspaceRoot, includeWorkspace });
+  if (targets.length === 0) {
+    throw new Error("Không có repo git nào để sync-main.");
+  }
+
+  const picked = String(selection || "").trim();
+  if (picked === "all") {
+    return targets;
+  }
+  if (picked) {
+    const matches = findTargetByName(targets, picked);
+    if (matches.length === 0) {
+      const names = targets.map((target) => target.name).join(", ");
+      throw new Error(`Repo '${picked}' không có trong manifest. Có: ${names}`);
+    }
+    return matches;
+  }
+
+  if (process.stdin.isTTY) {
+    return promptRepoChoice(targets);
+  }
+
+  return targets;
+}
+
+module.exports = {
+  buildTargets,
+  resolveTargets,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-stack-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "PAN Stack CLI — multi-repo git and project commands from .project.yaml",
   "license": "MIT",
   "bin": {