pan-stack-cli 0.1.1 → 0.1.4

package/README.md

@@ -1,152 +1,216 @@
 # 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`, `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`, `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: `.`)
-- `--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 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, 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",
@@ -48,43 +50,45 @@ 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
   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 +123,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 +137,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,
@@ -12,15 +13,13 @@ const {
 } = require("./manifest");
 
 const BUILTIN_GIT_COMMANDS = new Set(["clone", "pull", "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");
@@ -64,12 +63,17 @@ function walkUpManifests(startDir) {
   return found;
 }
 
-function findNearestWorkspace(startDir = process.cwd()) {
+function findNearestProjectManifest(startDir = process.cwd()) {
   const walked = walkUpManifests(startDir);
-  if (walked.length === 0) {
+  return walked[0] || null;
+}
+
+function findNearestWorkspace(startDir = process.cwd()) {
+  const manifestPath = findNearestProjectManifest(startDir);
+  if (!manifestPath) {
     return null;
   }
-  return loadManifest(walked[0]);
+  return loadManifest(manifestPath);
 }
 
 function loadCommandSourcesForWorkspace(workspace) {
@@ -183,7 +187,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}` : "";
@@ -194,7 +198,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");
 }
 
@@ -202,15 +206,22 @@ 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,
   loadAllCommandSources,
   loadCommandSourcesForWorkspace,
   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`);
   }
@@ -47,7 +48,7 @@ function main() {
     return;
   }
 
-  const repos = loadManifestRepos({
+  const { repos } = loadManifestRepos({
     manifestPath: args.manifest,
     baseDir: args.baseDir,
   });

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

@@ -40,7 +40,7 @@ function main() {
     return;
   }
 
-  const repos = loadManifestRepos({
+  const { repos } = loadManifestRepos({
     manifestPath: args.manifest,
     baseDir: args.baseDir,
   });