pan-stack-cli 0.1.2 → 0.1.5

package/README.md

@@ -1,152 +1,217 @@
 # 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`:
+Global CLI for PAN Stack workspaces. Install once, use in any project that has
+`.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
+# or from source before npm publish:
+npm i -g /path/to/pan-stack-cli
 ```
 
-Sau đó gõ `pan` thay cho `./pan`.
+## What is PAN Stack?
+
+PAN Stack is a **workspace shell** for coding with AI agents — not a monorepo that
+contains every product repository. The stack repo holds:
+
+- Agent skills and prompts (`.claude`, `.cursor`, `.codex`)
+- Workspace manifests (`.project.yaml`, `.pan.yaml`)
+- Team docs and coordination files
 
-## Yêu cầu
+Product source code lives in separate repositories listed in `.project.yaml`. The
+`pan` CLI ties them together: clone all repos, run git ops across the workspace,
+and execute project commands defined in `.pan.yaml`.
+
+```text
+bookshop-stack/                 # PAN Stack workspace (shell)
+  .project.yaml                 # Which repos belong to this workspace
+  .pan.yaml                     # Workspace-level pan commands
+  .claude/skills/               # Claude Code skills
+  .cursor/skills/               # Cursor agent skills
+  .codex/skills/                # Codex agent skills
+  apps/
+    web/                        # bookshop-web (cloned product repo)
+    api/                        # bookshop-api (cloned product repo)
+```
+
+Run `pan create` to scaffold this layout with the shared `writing-guidelines`
+skill pre-installed for all three agent folders.
+
+## Requirements
 
 - 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, …)
+- Git (for `pan clone`, `pull`, `sync-main`, `fetch`, `push`, `grv`, `gst`)
 
-## Lệnh git (built-in)
+## Windows support
 
-Đọc `repositories` từ `.project.yaml` gần nhất (walk-up từ thư mục hiện tại):
+Built-in commands (`create`, `clone`, `pull`, `sync-main`, `push`, `fetch`, `grv`, `gst`) run on
+Windows, macOS, and Linux. Notes for Windows:
 
-| 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`) |
+- `shell:` blocks in `.pan.yaml` run through **bash** on all platforms (Git Bash on
+  Windows, system bash on macOS/Linux). Use `exec:` for simple one-liners (`npm test`)
+  when possible; those work without Bash.
+- Install **Git for Windows** if bash is not already on `PATH`.
+- Set `PAN_PROJECT_ROOTS` with **semicolon** separators (`C:\work\a;C:\work\b`).
+  Do not use `:` — it conflicts with drive letters.
+- Optional: set `PAN_GIT_BASH` to the full path of `bash.exe` if Git is installed in
+  a non-standard location.
 
-Tuỳ chọn git (forward xuống script):
+## Bootstrap a new workspace
 
-- `--base-dir DIR` — thư mục gốc cho path repo con (mặc định: thư mục chứa `.project.yaml`; tự walk-up từ cwd nếu không có ngay tại đó)
-- `--dry-run` — chỉ in lệnh
-- `[manifest]` — đường dẫn manifest (mặc định: `.project.yaml`)
+```bash
+mkdir ~/work && cd ~/work
+pan create                    # prompts for folder name
+# or
+pan create bookshop-stack     # non-interactive
 
-## Lệnh dự án (từ `.pan.yaml`)
+cd bookshop-stack
+# Edit .project.yaml — replace repo_url_to_be_filled with real URLs
+pan clone
+pan install
+```
 
-Hai lớp cấu hình:
+`pan create` fails if the target folder already exists.
 
-| 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 |
+## Configuration files
 
-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`).
+Two files drive the CLI. Keep responsibilities separate:
 
-### Schema `.pan.yaml` (repo con)
+| File | Role |
+|------|------|
+| `.project.yaml` | Workspace manifest — lists `repositories` (name, url, path). **No commands.** |
+| `.pan.yaml` | `pan` commands — at workspace root and/or inside each child repo |
 
-`cwd` / `exec` tương đối **root repo** (thư mục chứa file `.pan.yaml`):
+### `.project.yaml` example
 
 ```yaml
-commands:
-  be:
-    description: Deploy backend local
-    exec: scripts/deploy.sh
+project: bookshop-stack
+managed_by: your-team
+
+stack:
+  repo: https://github.com/example/bookshop-stack.git
+
+repositories:
+  - name: bookshop-web
+    description: Customer-facing web application
+    url: https://github.com/example/bookshop-web.git
+    path: apps/web
+  - name: bookshop-api
+    description: REST API service
+    url: https://github.com/example/bookshop-api.git
+    path: apps/api
+```
+
+### `.pan.yaml` — workspace root
+
+Orchestration commands. Paths are relative to the workspace root. Use
+`PAN_WORKSPACE_ROOT` in shell blocks:
 
+```yaml
+commands:
   install:
     alias: i
-    description: Cài dependencies (pan i hoặc pan install)
+    description: Install dependencies across cloned repositories
     shell: |
       set -euo pipefail
-      pnpm install
+      root="${PAN_WORKSPACE_ROOT}"
+      for dir in apps/web apps/api; do
+        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir" >&2; exit 1; }
+        (cd "$root/$dir" && npm install)
+      done
 
-  lint:
-    shell: |
-      set -euo pipefail
-      pnpm lint
+  test:
+    default: web
+    description: Run tests (web | api)
+    targets:
+      web:
+        cwd: apps/web
+        exec: npm test
+      api:
+        cwd: apps/api
+        exec: npm test
 ```
 
-Alias: `alias: i` hoặc `aliases: i, ins` (cách nhau bằng dấu phẩy).
+### `.pan.yaml` — child repo
 
-### Schema `.pan.yaml` (workspace root)
-
-Lệnh orchestration — `cwd` tương đối workspace root; dùng `PAN_WORKSPACE_ROOT` trong shell:
+Place a `.pan.yaml` inside a cloned repo. `cwd` / `exec` are relative to that
+repo's root:
 
 ```yaml
 commands:
-  install:
-    shell: |
-      cd "${PAN_WORKSPACE_ROOT}/apps/frontend" && pnpm install
+  dev:
+    description: Start local dev server
+    exec: npm run dev
 
-  test:
-    default: fe
-    targets:
-      be:
-        cwd: apps/backend
-        exec: ./gradlew test
-      fe:
-        cwd: apps/frontend
-        exec: pnpm test
+  lint:
+    shell: |
+      set -euo pipefail
+      npm run lint
 ```
 
-### Biến môi trường
+Aliases: `alias: i` or `aliases: i, ins` (comma-separated).
 
-| 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 |
+## Built-in git commands
 
-### Nhiều repo trùng tên lệnh
+Read `repositories` from the nearest `.project.yaml` (walk-up from cwd):
 
-CLI quét workspace gần nhất (walk-up `.project.yaml`) rồi load mọi `.pan.yaml` con.
+| Command | Action |
+|---------|--------|
+| `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 |
+| `pan gst` | `git status` for workspace + each child repo |
 
-## Ví dụ (CSDL-CC)
+Git options:
 
-Trong repo `btp-csdl-cc` (đã có `.project.yaml`):
+- `--base-dir DIR` — base for relative repo paths (default: directory containing `.project.yaml`)
+- `--dry-run` — print commands only
+- `[manifest]` — manifest path (default: `.project.yaml`)
 
-```bash
-cd ~/work/btp/btp-csdl-cc
+Works from child repo directories — the CLI walks up to find `.project.yaml`.
 
-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
-```
+## Project commands
+
+The CLI loads **all** `.pan.yaml` files in the workspace (root + each
+`repositories[].path`). When the same command name appears in multiple repos,
+use `--project <name>` or pick interactively.
+
+### Environment variables
 
-## `./pan` ở root repo
+| Variable | Meaning |
+|----------|---------|
+| `PAN_WORKSPACE_ROOT` | Directory containing `.project.yaml` |
+| `PAN_REPO_ROOT` | Directory containing the active `.pan.yaml` |
+| `PAN_PROJECT_ROOT` | Alias of `PAN_WORKSPACE_ROOT` |
+| `PAN_ARG_1`, … | Arguments after the command name |
 
-Script `./pan` là shim mỏng:
+### Registry (optional)
 
-1. Dùng `pan` global nếu đã cài
-2. Fallback `node .pan/pan-stack-cli/bin/pan.js`
+- `PAN_PROJECT_ROOTS` — extra workspace roots (`;` on Windows, `:` or `;` on Unix)
+- `~/.pan/projects` — one workspace root per line
 
-## Cấu trúc package
+## Package layout
 
 ```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
+pan-stack-cli/
+  bin/pan.js              # CLI entry
+  lib/
+    create.js             # pan create scaffold
+    discover.js             # workspace discovery
+    platform.js             # Windows/cross-platform helpers
+    manifest.js             # YAML parsing
+    run-command.js        # command execution
+    git/                  # clone, pull, sync-main, push, fetch, grv, gst
+  templates/workspace/    # pan create template
+  references/             # npm publish docs
 ```
 
-## Phát triển local
+## Local development
 
-Cài global từ source (khuyên dùng trước publish): [references/npm-development.md](references/npm-development.md).
+Install globally from source: [references/npm-development.md](references/npm-development.md).
 
-## Publish npm
+## Publish to npm
 
-Xem [references/npm-release.md](references/npm-release.md).
+See [references/npm-release.md](references/npm-release.md).

package/bin/pan.js

@@ -6,9 +6,11 @@ const {
   findSourcesWithCommand,
   formatProjectList,
   isBuiltinGitCommand,
+  isBuiltinWorkspaceCommand,
 } = require("../lib/discover");
 const { listCommands } = require("../lib/manifest");
 const { runWithProjectResolution, runGitScript, sourceLabel } = require("../lib/run-command");
+const { runCreate } = require("../lib/create");
 
 const GIT_SCRIPT_MAP = {
   clone: "git-clone.js",
@@ -17,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) {
@@ -48,43 +52,46 @@ function parseGlobalArgs(argv) {
 function printUsage() {
   console.log(`usage: pan <command> [options] [-- args...]
 
-repo commands (built-in):
+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 (URL đầy đủ) cho workspace + repo con
-  gst     Git status cho workspace + repo con (forward args: pan gst -sb)
+  grv     List git remotes -v for workspace + child repos
+  gst     Git status for workspace + child repos (e.g. pan gst -sb)
 
 project commands:
-  Gom từ .pan.yaml (workspace root + từng repo con trong .project.yaml)
+  Loaded from .pan.yaml (workspace root + each repo in .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
+  --project NAME   Pick a repo when multiple .pan.yaml files define the same command
+  --base-dir DIR   (git commands) base directory for child repo paths
+  --dry-run        (git commands) print commands only
+  -h, --help       Show help
 
 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
+  PAN_PROJECT_ROOTS   Semicolon-separated workspace roots (; on Windows, : or ; on Unix)
+  ~/.pan/projects     One workspace root per line
 
 examples:
+  pan create
+  pan create bookshop-stack
   pan clone
   pan grv
-  pan be
   pan test fe
-  pan test --project csdl-cc-b-frontend-e2e
+  pan test --project bookshop-web
 `);
 }
 
 function printAllCommands(sources) {
   if (sources.length === 0) {
-    console.log("Chưa tìm thấy .pan.yaml (workspace hoặc repo con).");
+    console.log("No .pan.yaml found (workspace or child repos).");
     return;
   }
 
-  console.log("Lệnh đã load:");
+  console.log("Loaded commands:");
   for (const source of sources) {
     const commands = listCommands(source);
     if (commands.length === 0) {
@@ -119,6 +126,11 @@ async function main() {
 
   const { command, args, project } = parsed;
 
+  if (command === "create") {
+    await runCreate(args);
+    return;
+  }
+
   if (isBuiltinGitCommand(command)) {
     const gitArgs = [...args];
     if (command === "push" && !gitArgs.includes("--set-upstream")) {
@@ -128,6 +140,10 @@ async function main() {
     return;
   }
 
+  if (isBuiltinWorkspaceCommand(command)) {
+    throw new Error(`Unknown built-in command: ${command}`);
+  }
+
   const allSources = loadAllCommandSources();
   const matches = findSourcesWithCommand(command);
   if (matches.length > 1 && !project && process.stdin.isTTY) {

package/lib/create.js

@@ -0,0 +1,87 @@
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { validateFolderName } = require("./platform");
+
+const TEMPLATE_ROOT = path.join(__dirname, "..", "templates", "workspace");
+
+function promptFolderName() {
+  return new Promise((resolve, reject) => {
+    if (!process.stdin.isTTY) {
+      reject(new Error("Folder name required: pan create <folder-name>"));
+      return;
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question("Workspace folder name: ", (answer) => {
+      rl.close();
+      const name = answer.trim();
+      if (!name) {
+        reject(new Error("Folder name cannot be empty."));
+        return;
+      }
+      resolve(name);
+    });
+  });
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function applyPlaceholders(targetDir, folderName) {
+  const files = [".project.yaml", "README.md"];
+  for (const relativePath of files) {
+    const filePath = path.join(targetDir, relativePath);
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+    const content = fs.readFileSync(filePath, "utf8");
+    fs.writeFileSync(filePath, content.replaceAll("__PROJECT_NAME__", folderName));
+  }
+}
+
+async function runCreate(args = []) {
+  let folderName = args[0]?.trim();
+  if (!folderName) {
+    folderName = await promptFolderName();
+  }
+
+  validateFolderName(folderName);
+
+  const targetDir = path.resolve(process.cwd(), folderName);
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Folder already exists: ${targetDir}`);
+  }
+
+  if (!fs.existsSync(TEMPLATE_ROOT)) {
+    throw new Error(`Template not found: ${TEMPLATE_ROOT}`);
+  }
+
+  copyDir(TEMPLATE_ROOT, targetDir);
+  applyPlaceholders(targetDir, folderName);
+
+  console.log(`Created PAN Stack workspace: ${targetDir}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${folderName}`);
+  console.log("  # Edit .project.yaml with your repository URLs");
+  console.log("  pan clone");
+}
+
+module.exports = {
+  runCreate,
+};

package/lib/discover.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { splitEnvList } = require("./platform");
 const {
   PAN_CONFIG_FILE,
   loadManifest,
@@ -11,16 +12,23 @@ 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() {
   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));
-    }
+  for (const part of splitEnvList(fromEnv)) {
+    roots.push(path.resolve(part));
   }
 
   const registry = path.join(os.homedir(), ".pan", "projects");
@@ -188,7 +196,7 @@ function findSourcesWithCommand(commandName, startDir = process.cwd()) {
 }
 
 function formatProjectList(matches, commandName) {
-  const lines = [`Lệnh '${commandName}' có ở nhiều nơi:`];
+  const lines = [`Command '${commandName}' is defined in multiple places:`];
   matches.forEach((source, index) => {
     const def = source.commands[commandName];
     const desc = def?.description ? ` — ${def.description}` : "";
@@ -199,7 +207,7 @@ function formatProjectList(matches, commandName) {
     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>.");
+  lines.push("Pick a number, or rerun with --project <repo-name>.");
   return lines.join("\n");
 }
 
@@ -207,8 +215,13 @@ function isBuiltinGitCommand(name) {
   return BUILTIN_GIT_COMMANDS.has(name);
 }
 
+function isBuiltinWorkspaceCommand(name) {
+  return BUILTIN_WORKSPACE_COMMANDS.has(name);
+}
+
 module.exports = {
   BUILTIN_GIT_COMMANDS,
+  BUILTIN_WORKSPACE_COMMANDS,
   PAN_CONFIG_FILE,
   findNearestProjectManifest,
   findNearestWorkspace,
@@ -217,6 +230,7 @@ module.exports = {
   findSourcesWithCommand,
   formatProjectList,
   isBuiltinGitCommand,
+  isBuiltinWorkspaceCommand,
   getCommandDefinition,
   sourceMatchesProject,
 };

package/lib/git/git-clone.js

@@ -10,6 +10,7 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const { spawnOptions } = require("../platform");
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
 
 function cloneRepo({ name, url, destination, dryRun }) {
@@ -26,7 +27,7 @@ function cloneRepo({ name, url, destination, dryRun }) {
   }
 
   console.log(`[clone] ${name}: ${url} -> ${destination}`);
-  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+  const result = spawnSync(command[0], command.slice(1), spawnOptions({ stdio: "inherit" }));
   if (result.status !== 0) {
     console.log(`[warn] ${name}: clone failed, check repo access or url`);
   }

package/lib/git/git-grv.js

@@ -2,7 +2,7 @@
 /*
  * 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).
+ * oh-my-zsh-style alias for grv — full remote URLs (fetch/push).
  */
 
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
@@ -18,7 +18,7 @@ function printRepoRemotes({ label, destination, dryRun }) {
   console.log(destination);
   const lines = listRemotesVerbose(destination);
   if (lines.length === 0) {
-    console.log("(không có remote)");
+    console.log("(no remotes)");
   } else {
     for (const line of lines) {
       console.log(line);
@@ -45,7 +45,7 @@ function printHelp() {
 List git remotes with full URLs (git remote -v) for each repository.
 
 ${printCommonOptions()}
-  --no-workspace       Skip workspace root (chỉ repo trong manifest)`);
+  --no-workspace       Skip workspace root (manifest repos only)`);
 }
 
 function main() {

package/lib/git/git-gst.js

@@ -2,7 +2,7 @@
 /*
  * Git status for PAN Stack project repositories.
  *
- * Alias tương đương gst trong oh-my-zsh — chạy git status trên workspace + repo con.
+ * oh-my-zsh-style alias for gst — git status on workspace + child repos.
  */
 
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
@@ -38,10 +38,10 @@ function printHelp() {
   console.log(`usage: git-gst.js [--base-dir BASE_DIR] [--dry-run] [--no-workspace] [manifest] [git status args...]
 
 Run git status for workspace root and each repository in the manifest.
-Extra args are forwarded to git status (vd: -s, -sb).
+Extra args are forwarded to git status (e.g. -s, -sb).
 
 ${printCommonOptions()}
-  --no-workspace       Skip workspace root (chỉ repo trong manifest)`);
+  --no-workspace       Skip workspace root (manifest repos only)`);
 }
 
 function main() {