pan-stack-cli 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# pan-stack-cli
+
+CLI toàn cục cho PAN Stack workspace — thay script `./pan` ở root dự án.
+
+Cài một lần, dùng ở mọi dự án có `.project.yaml`:
+
+```bash
+npm i -g pan-stack-cli
+# hoặc từ source (trước khi publish npm):
+npm i -g /path/to/.pan/pan-stack-cli
+```
+
+Sau đó gõ `pan` thay cho `./pan`.
+
+## Yêu cầu
+
+- Node.js 18+
+- Git (cho `pan clone`, `pull`, `fetch`, `push`, `grv`, `gst`)
+- Công cụ riêng từng lệnh dự án (pnpm, docker, curl, …)
+
+## Lệnh git (built-in)
+
+Đọc `repositories` từ `.project.yaml` gần nhất (walk-up từ thư mục hiện tại):
+
+| Lệnh | Việc |
+|------|------|
+| `pan clone` | Clone tất cả repo trong manifest |
+| `pan pull` | Pull tất cả repo đã clone |
+| `pan fetch` | Fetch all remotes |
+| `pan push` | Push và set upstream (`-u origin HEAD`) |
+| `pan grv` | `git remote -v` — URL đầy đủ cho workspace + từng repo con |
+| `pan gst` | `git status` cho workspace + từng repo con (vd `pan gst -sb`) |
+
+Tuỳ chọn git (forward xuống script):
+
+- `--base-dir DIR` — thư mục gốc cho path repo con (mặc định: `.`)
+- `--dry-run` — chỉ in lệnh
+- `[manifest]` — đường dẫn manifest (mặc định: `.project.yaml`)
+
+## Lệnh dự án (từ `.pan.yaml`)
+
+Hai lớp cấu hình:
+
+| File | Vai trò |
+|------|---------|
+| `.project.yaml` | Workspace: danh sách repo (`repositories`) — **không** chứa `commands` |
+| `.pan.yaml` | Lệnh `pan` — đặt ở workspace root và/hoặc từng repo con |
+
+CLI load **tất cả** `.pan.yaml` trong workspace (root + mỗi `repositories[].path`). Lệnh trùng tên → hỏi chọn repo (`--project`) hoặc tự chọn nếu arg khớp `targets` (vd `pan test fe`).
+
+### Schema `.pan.yaml` (repo con)
+
+`cwd` / `exec` tương đối **root repo** (thư mục chứa file `.pan.yaml`):
+
+```yaml
+commands:
+  be:
+    description: Deploy backend local
+    exec: scripts/deploy.sh
+
+  lint:
+    shell: |
+      set -euo pipefail
+      pnpm lint
+```
+
+### Schema `.pan.yaml` (workspace root)
+
+Lệnh orchestration — `cwd` tương đối workspace root; dùng `PAN_WORKSPACE_ROOT` trong shell:
+
+```yaml
+commands:
+  install:
+    shell: |
+      cd "${PAN_WORKSPACE_ROOT}/apps/frontend" && pnpm install
+
+  test:
+    default: fe
+    targets:
+      be:
+        cwd: apps/backend
+        exec: ./gradlew test
+      fe:
+        cwd: apps/frontend
+        exec: pnpm test
+```
+
+### Biến môi trường
+
+| Biến | Ý nghĩa |
+|------|---------|
+| `PAN_WORKSPACE_ROOT` | Thư mục chứa `.project.yaml` |
+| `PAN_REPO_ROOT` | Thư mục chứa `.pan.yaml` đang chạy |
+| `PAN_PROJECT_ROOT` | Alias của `PAN_WORKSPACE_ROOT` |
+| `PAN_ARG_1`, … | Args sau tên lệnh |
+
+### Nhiều repo trùng tên lệnh
+
+CLI quét workspace gần nhất (walk-up `.project.yaml`) rồi load mọi `.pan.yaml` con.
+
+## Ví dụ (CSDL-CC)
+
+Trong repo `btp-csdl-cc` (đã có `.project.yaml`):
+
+```bash
+cd ~/work/btp/btp-csdl-cc
+
+pan clone
+pan install
+pan be                    # deploy backend :8080
+pan fe                    # Vite :5173
+pan faker                 # pan-faker :8090
+pan test fe               # vitest
+pan demo uc2              # use case demo qua faker
+pan status
+pan down                  # docker compose down (giữ volume)
+pan reset -y              # xoá volume + deploy lại
+```
+
+## `./pan` ở root repo
+
+Script `./pan` là shim mỏng:
+
+1. Dùng `pan` global nếu đã cài
+2. Fallback `node .pan/pan-stack-cli/bin/pan.js`
+
+## Cấu trúc package
+
+```text
+.pan/pan-stack-cli/
+  bin/pan.js           # entry CLI
+  lib/                 # manifest, discover, run-command, git/
+  lib/git/             # git-clone, pull, fetch, push, grv, gst (+ helpers)
+  references/          # hướng dẫn publish npm
+```
+
+## Phát triển local
+
+Cài global từ source (khuyên dùng trước publish): [references/npm-development.md](references/npm-development.md).
+
+## Publish npm
+
+Xem [references/npm-release.md](references/npm-release.md).

package/bin/pan.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+const {
+  findNearestWorkspace,
+  loadAllCommandSources,
+  findSourcesWithCommand,
+  formatProjectList,
+  isBuiltinGitCommand,
+} = require("../lib/discover");
+const { listCommands } = require("../lib/manifest");
+const { runWithProjectResolution, runGitScript, sourceLabel } = require("../lib/run-command");
+
+const GIT_SCRIPT_MAP = {
+  clone: "git-clone.js",
+  pull: "git-pull.js",
+  fetch: "git-fetch-all.js",
+  push: "git-push.js",
+  grv: "git-grv.js",
+  gst: "git-gst.js",
+};
+
+function parseGlobalArgs(argv) {
+  const result = {
+    help: false,
+    project: "",
+    command: "",
+    args: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help" || arg === "help") {
+      result.help = true;
+    } else if (arg === "--project") {
+      result.project = argv[++index] || "";
+    } else if (arg.startsWith("--project=")) {
+      result.project = arg.slice("--project=".length);
+    } else if (!result.command) {
+      result.command = arg;
+    } else {
+      result.args.push(arg);
+    }
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`usage: pan <command> [options] [-- args...]
+
+repo commands (built-in):
+  clone   Clone all repositories from .project.yaml
+  pull    Pull latest changes for all repositories
+  fetch   Fetch all remotes for all repositories
+  push    Push all repositories and set upstream
+  grv     List git remotes -v (URL đầy đủ) cho workspace + repo con
+  gst     Git status cho workspace + repo con (forward args: pan gst -sb)
+
+project commands:
+  Gom từ .pan.yaml (workspace root + từng repo con trong .project.yaml)
+
+options:
+  --project NAME   Chọn repo khi nhiều .pan.yaml có cùng lệnh
+  --base-dir DIR   (git commands) thư mục gốc repo con
+  --dry-run        (git commands) chỉ in lệnh
+  -h, --help       Hiện trợ giúp
+
+env:
+  PAN_PROJECT_ROOTS   Danh sách root workspace (phân cách bằng , hoặc ;)
+  ~/.pan/projects     Mỗi dòng một workspace root
+
+examples:
+  pan clone
+  pan grv
+  pan be
+  pan test fe
+  pan test --project csdl-cc-b-frontend-e2e
+`);
+}
+
+function printAllCommands(sources) {
+  if (sources.length === 0) {
+    console.log("Chưa tìm thấy .pan.yaml (workspace hoặc repo con).");
+    return;
+  }
+
+  console.log("Lệnh đã load:");
+  for (const source of sources) {
+    const commands = listCommands(source);
+    if (commands.length === 0) {
+      continue;
+    }
+    console.log(`\n  [${sourceLabel(source)}] ${source.root}`);
+    for (const command of commands) {
+      const targetHint = command.hasTargets
+        ? ` [${command.targets.join("|")}]`
+        : "";
+      const desc = command.description ? ` — ${command.description}` : "";
+      console.log(`    ${command.name}${targetHint}${desc}`);
+    }
+  }
+}
+
+async function main() {
+  const parsed = parseGlobalArgs(process.argv.slice(2));
+
+  if (parsed.help || !parsed.command) {
+    printUsage();
+    const workspace = findNearestWorkspace();
+    if (workspace) {
+      console.log("");
+      console.log(`Workspace: ${workspace.project} (${workspace.root})`);
+      printAllCommands(loadAllCommandSources());
+    }
+    return;
+  }
+
+  const { command, args, project } = parsed;
+
+  if (isBuiltinGitCommand(command)) {
+    const gitArgs = [...args];
+    if (command === "push" && !gitArgs.includes("--set-upstream")) {
+      gitArgs.unshift("--set-upstream");
+    }
+    runGitScript(GIT_SCRIPT_MAP[command], gitArgs);
+    return;
+  }
+
+  const matches = findSourcesWithCommand(command);
+  if (matches.length > 1 && !project && process.stdin.isTTY) {
+    console.log(formatProjectList(matches, command));
+  }
+
+  await runWithProjectResolution(matches, command, args, project);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/lib/discover.js

@@ -0,0 +1,206 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const {
+  PAN_CONFIG_FILE,
+  loadManifest,
+  loadPanConfig,
+  getCommandDefinition,
+  validateRepo,
+  cleanValue,
+} = require("./manifest");
+
+const BUILTIN_GIT_COMMANDS = new Set(["clone", "pull", "fetch", "push", "grv", "gst"]);
+
+function readProjectRoots() {
+  const roots = [];
+  const fromEnv = process.env.PAN_PROJECT_ROOTS || "";
+  for (const part of fromEnv.split(/[:;,]/)) {
+    const trimmed = part.trim();
+    if (trimmed) {
+      roots.push(path.resolve(trimmed));
+    }
+  }
+
+  const registry = path.join(os.homedir(), ".pan", "projects");
+  if (fs.existsSync(registry)) {
+    const content = fs.readFileSync(registry, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        continue;
+      }
+      roots.push(path.resolve(trimmed));
+    }
+  }
+
+  return [...new Set(roots)];
+}
+
+function manifestPathInDir(dir) {
+  const candidate = path.join(dir, ".project.yaml");
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function walkUpManifests(startDir) {
+  const found = [];
+  let current = path.resolve(startDir);
+  const seen = new Set();
+
+  while (true) {
+    const manifestPath = manifestPathInDir(current);
+    if (manifestPath && !seen.has(manifestPath)) {
+      seen.add(manifestPath);
+      found.push(manifestPath);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  return found;
+}
+
+function findNearestWorkspace(startDir = process.cwd()) {
+  const walked = walkUpManifests(startDir);
+  if (walked.length === 0) {
+    return null;
+  }
+  return loadManifest(walked[0]);
+}
+
+function loadCommandSourcesForWorkspace(workspace) {
+  const sources = [];
+  const workspaceRoot = workspace.root;
+  const workspacePan = path.join(workspaceRoot, PAN_CONFIG_FILE);
+
+  if (fs.existsSync(workspacePan)) {
+    sources.push(
+      loadPanConfig(workspacePan, {
+        workspaceRoot,
+        project: workspace.project,
+        repoName: workspace.project,
+        scope: "workspace",
+      })
+    );
+  }
+
+  for (const repo of workspace.repositories) {
+    try {
+      const { name, repoPath } = validateRepo(repo);
+      const repoDir = path.resolve(workspaceRoot, repoPath);
+      const repoPan = path.join(repoDir, PAN_CONFIG_FILE);
+      if (!fs.existsSync(repoPan)) {
+        continue;
+      }
+      sources.push(
+        loadPanConfig(repoPan, {
+          workspaceRoot,
+          project: name,
+          repoName: name,
+          scope: "repo",
+        })
+      );
+    } catch {
+      // skip invalid repo entries
+    }
+  }
+
+  return sources;
+}
+
+function collectWorkspaces(startDir = process.cwd()) {
+  const workspaces = new Map();
+
+  for (const manifestPath of walkUpManifests(startDir)) {
+    try {
+      const workspace = loadManifest(manifestPath);
+      workspaces.set(workspace.root, workspace);
+    } catch {
+      // ignore
+    }
+  }
+
+  for (const root of readProjectRoots()) {
+    const manifestPath = manifestPathInDir(root);
+    if (!manifestPath) {
+      continue;
+    }
+    try {
+      const workspace = loadManifest(manifestPath);
+      workspaces.set(workspace.root, workspace);
+    } catch {
+      // ignore
+    }
+  }
+
+  return [...workspaces.values()];
+}
+
+function loadAllCommandSources(startDir = process.cwd()) {
+  const sources = [];
+  const seen = new Set();
+
+  for (const workspace of collectWorkspaces(startDir)) {
+    for (const source of loadCommandSourcesForWorkspace(workspace)) {
+      const key = source.path;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      sources.push(source);
+    }
+  }
+
+  return sources;
+}
+
+function sourceMatchesProject(source, projectFlag) {
+  const flag = projectFlag.trim();
+  return (
+    source.project === flag ||
+    source.repoName === flag ||
+    path.basename(source.root) === flag
+  );
+}
+
+function findSourcesWithCommand(commandName, startDir = process.cwd()) {
+  return loadAllCommandSources(startDir).filter(
+    (source) => source.commands[commandName]
+  );
+}
+
+function formatProjectList(matches, commandName) {
+  const lines = [`Lệnh '${commandName}' có ở nhiều nơi:`];
+  matches.forEach((source, index) => {
+    const def = source.commands[commandName];
+    const desc = def?.description ? ` — ${def.description}` : "";
+    const label =
+      source.scope === "workspace"
+        ? `${source.project} (workspace)`
+        : source.repoName || source.project;
+    lines.push(`  ${index + 1}. ${label} (${source.root})${desc}`);
+  });
+  lines.push("");
+  lines.push("Chọn số thứ tự, hoặc chạy lại với --project <tên-repo>.");
+  return lines.join("\n");
+}
+
+function isBuiltinGitCommand(name) {
+  return BUILTIN_GIT_COMMANDS.has(name);
+}
+
+module.exports = {
+  BUILTIN_GIT_COMMANDS,
+  PAN_CONFIG_FILE,
+  findNearestWorkspace,
+  loadAllCommandSources,
+  loadCommandSourcesForWorkspace,
+  findSourcesWithCommand,
+  formatProjectList,
+  isBuiltinGitCommand,
+  getCommandDefinition,
+  sourceMatchesProject,
+};

package/lib/git/git-clone.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/*
+ * Clone PAN Stack project repositories from a small clone manifest.
+ *
+ * The parser intentionally supports only the manifest shape documented in
+ * PAN_STACK.md. It avoids external dependencies so the script can run anywhere
+ * Node.js and Git are available.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
+
+function cloneRepo({ name, url, destination, dryRun }) {
+  if (fs.existsSync(destination)) {
+    console.log(`[skip] ${name}: ${destination} already exists`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const command = ["git", "clone", url, destination];
+  if (dryRun) {
+    console.log(`[dry-run] ${command.join(" ")}`);
+    return;
+  }
+
+  console.log(`[clone] ${name}: ${url} -> ${destination}`);
+  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+  if (result.status !== 0) {
+    console.log(`[warn] ${name}: clone failed, check repo access or url`);
+  }
+}
+
+function printHelp() {
+  console.log(`usage: git-clone.js [--base-dir BASE_DIR] [--dry-run] [manifest]
+
+Clone repositories from a PAN Stack clone manifest.
+
+${printCommonOptions()}`);
+}
+
+function main() {
+  const args = parseCommonArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const repos = loadManifestRepos({
+    manifestPath: args.manifest,
+    baseDir: args.baseDir,
+  });
+
+  for (const repo of repos) {
+    cloneRepo({
+      name: repo.name,
+      url: repo.url,
+      destination: repo.destination,
+      dryRun: args.dryRun,
+    });
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/lib/git/git-fetch-all.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/*
+ * Fetch all remotes for PAN Stack project repositories from a clone manifest.
+ *
+ * Skips repositories that do not exist or are not git checkouts. Failures warn
+ * and continue so one broken repo does not block the rest.
+ */
+
+const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
+const { ensureRepoExists, runGit } = require("./helpers/git");
+
+function fetchRepo({ name, destination, dryRun }) {
+  if (!ensureRepoExists({ name, destination })) {
+    return;
+  }
+
+  const status = runGit(["fetch", "--all"], {
+    cwd: destination,
+    dryRun,
+    action: "fetch",
+    name,
+  });
+  if (status !== 0) {
+    console.log(`[warn] ${name}: fetch failed, check remote access`);
+  }
+}
+
+function printHelp() {
+  console.log(`usage: git-fetch-all.js [--base-dir BASE_DIR] [--dry-run] [manifest]
+
+Fetch all remotes for repositories listed in a PAN Stack clone manifest.
+
+${printCommonOptions()}`);
+}
+
+function main() {
+  const args = parseCommonArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const repos = loadManifestRepos({
+    manifestPath: args.manifest,
+    baseDir: args.baseDir,
+  });
+
+  for (const repo of repos) {
+    fetchRepo({
+      name: repo.name,
+      destination: repo.destination,
+      dryRun: args.dryRun,
+    });
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/lib/git/git-grv.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/*
+ * List git remotes (git remote -v) for PAN Stack project repositories.
+ *
+ * Alias tương đương grv trong oh-my-zsh — hiển thị URL đầy đủ (fetch/push).
+ */
+
+const path = require("path");
+const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
+const { ensureRepoExists, isGitRepo, listRemotesVerbose } = require("./helpers/git");
+
+function printRepoRemotes({ label, destination, dryRun }) {
+  if (dryRun) {
+    console.log(`[dry-run] (in ${destination}) git remote -v`);
+    return;
+  }
+
+  console.log(`== ${label} ==`);
+  console.log(destination);
+  const lines = listRemotesVerbose(destination);
+  if (lines.length === 0) {
+    console.log("(không có remote)");
+  } else {
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
+  console.log("");
+}
+
+function showWorkspaceRootRemotes({ manifestPath, baseDir, dryRun }) {
+  const workspaceRoot = path.resolve(baseDir || path.dirname(manifestPath || ".project.yaml"));
+  if (!isGitRepo(workspaceRoot)) {
+    return;
+  }
+
+  printRepoRemotes({
+    label: "workspace",
+    destination: workspaceRoot,
+    dryRun,
+  });
+}
+
+function printHelp() {
+  console.log(`usage: git-grv.js [--base-dir BASE_DIR] [--dry-run] [--no-workspace] [manifest]
+
+List git remotes with full URLs (git remote -v) for each repository.
+
+${printCommonOptions()}
+  --no-workspace       Skip workspace root (chỉ repo trong manifest)`);
+}
+
+function main() {
+  const args = parseCommonArgs(process.argv.slice(2), {
+    defaults: { noWorkspace: false },
+    handlers: {
+      "--no-workspace": (parsed) => {
+        parsed.noWorkspace = true;
+      },
+    },
+  });
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const manifestPath = path.resolve(args.manifest || ".project.yaml");
+  const repos = loadManifestRepos({
+    manifestPath,
+    baseDir: args.baseDir,
+  });
+
+  if (!args.noWorkspace) {
+    showWorkspaceRootRemotes({
+      manifestPath,
+      baseDir: args.baseDir,
+      dryRun: args.dryRun,
+    });
+  }
+
+  for (const repo of repos) {
+    if (!ensureRepoExists({ name: repo.name, destination: repo.destination })) {
+      continue;
+    }
+    printRepoRemotes({
+      label: repo.name,
+      destination: repo.destination,
+      dryRun: args.dryRun,
+    });
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}