pan-stack-cli 0.1.2 → 0.1.5

package/lib/platform.js

@@ -0,0 +1,140 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const WINDOWS_RESERVED_NAMES = new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9",
+]);
+
+function isWindows() {
+  return process.platform === "win32";
+}
+
+function splitEnvList(value) {
+  if (!value) {
+    return [];
+  }
+  // On Windows, do not split on ":" — drive letters use "C:".
+  const parts = isWindows() ? value.split(/[;,]/) : value.split(/[:;,]/);
+  return parts.map((part) => part.trim()).filter(Boolean);
+}
+
+function findBash() {
+  const candidates = isWindows()
+    ? [
+        process.env.PAN_GIT_BASH,
+        process.env.PAN_BASH,
+        process.env.GIT_BASH,
+        process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "bin", "bash.exe"),
+        process.env["ProgramFiles(x86)"] &&
+          path.join(process.env["ProgramFiles(x86)"], "Git", "bin", "bash.exe"),
+        process.env.LOCALAPPDATA &&
+          path.join(process.env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe"),
+      ]
+    : [process.env.PAN_BASH, process.env.BASH, "/usr/bin/bash", "/bin/bash"];
+
+  for (const candidate of candidates.filter(Boolean)) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** @deprecated use findBash */
+function findGitBash() {
+  return findBash();
+}
+
+function spawnOptions(extra = {}) {
+  return isWindows() ? { windowsHide: true, ...extra } : extra;
+}
+
+function normalizeShellEnv(env) {
+  if (!isWindows()) {
+    return env;
+  }
+
+  const normalized = { ...env };
+  for (const key of ["PAN_WORKSPACE_ROOT", "PAN_REPO_ROOT", "PAN_PROJECT_ROOT"]) {
+    if (typeof normalized[key] === "string") {
+      normalized[key] = normalized[key].replace(/\\/g, "/");
+    }
+  }
+  return normalized;
+}
+
+function runShellScript(script, { cwd, env, stdio = "inherit" } = {}) {
+  const shellEnv = normalizeShellEnv(env);
+  const bash = findBash();
+
+  if (!bash) {
+    const hint = isWindows()
+      ? "Install Git for Windows (https://git-scm.com/download/win) or set PAN_GIT_BASH / PAN_BASH to bash.exe."
+      : "Install bash or set PAN_BASH to its path.";
+    throw new Error(
+      `Shell commands in .pan.yaml require bash. ${hint} Alternatively, use 'exec' instead of 'shell'.`
+    );
+  }
+
+  return spawnSync(bash, ["-lc", script], spawnOptions({ cwd, env: shellEnv, stdio }));
+}
+
+function runExecLine(execLine, { cwd, env, stdio = "inherit" } = {}) {
+  return spawnSync(
+    execLine,
+    spawnOptions({ cwd, env: normalizeShellEnv(env), stdio, shell: true })
+  );
+}
+
+function validateFolderName(name) {
+  if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+    throw new Error(
+      "Invalid folder name. Use letters, numbers, dots, hyphens, or underscores."
+    );
+  }
+
+  if (isWindows()) {
+    if (/[<>:"/\\|?*]/.test(name)) {
+      throw new Error("Invalid folder name for Windows (<>:\"/\\|?* are not allowed).");
+    }
+    const base = name.replace(/\.+$/, "").toUpperCase();
+    if (WINDOWS_RESERVED_NAMES.has(base)) {
+      throw new Error(`Invalid folder name for Windows (reserved name: ${base}).`);
+    }
+  }
+}
+
+module.exports = {
+  isWindows,
+  splitEnvList,
+  findBash,
+  findGitBash,
+  spawnOptions,
+  normalizeShellEnv,
+  runShellScript,
+  runExecLine,
+  validateFolderName,
+};

package/lib/run-command.js

@@ -8,10 +8,11 @@ const {
   resolveCommandName,
 } = require("./manifest");
 const { sourceMatchesProject } = require("./discover");
+const { runShellScript, runExecLine, spawnOptions } = require("./platform");
 
 function needDir(dir) {
   if (!fs.existsSync(dir)) {
-    throw new Error(`Chưa có thư mục: ${dir} (chạy 'pan clone' trước?)`);
+    throw new Error(`Directory not found: ${dir} (run 'pan clone' first?)`);
   }
 }
 
@@ -46,12 +47,11 @@ function runExec(source, def, forwardedArgs) {
 
   const execLine = [def.exec, ...forwardedArgs].filter(Boolean).join(" ").trim();
   if (!execLine) {
-    throw new Error("Command thiếu 'exec' hoặc 'shell'.");
+    throw new Error("Command is missing 'exec' or 'shell'.");
   }
 
-  const result = spawnSync(execLine, {
+  const result = runExecLine(execLine, {
     cwd,
-    shell: true,
     stdio: "inherit",
     env: buildPanEnv(source, forwardedArgs),
   });
@@ -65,12 +65,17 @@ function runShell(source, def, forwardedArgs) {
     needDir(cwd);
   }
 
-  const result = spawnSync(def.shell, {
-    cwd,
-    shell: true,
-    stdio: "inherit",
-    env: buildPanEnv(source, forwardedArgs),
-  });
+  let result;
+  try {
+    result = runShellScript(def.shell, {
+      cwd,
+      stdio: "inherit",
+      env: buildPanEnv(source, forwardedArgs),
+    });
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
 
   process.exit(result.status ?? 1);
 }
@@ -88,7 +93,7 @@ function runProjectCommand(source, commandName, args) {
 
   const resolved = getCommandDefinition(source, commandName, subArg);
   if (!resolved) {
-    throw new Error(`Không tìm thấy lệnh '${commandName}' trong ${source.path}`);
+    throw new Error(`Command '${commandName}' not found in ${source.path}`);
   }
 
   if (resolved.shell) {
@@ -101,7 +106,7 @@ function runProjectCommand(source, commandName, args) {
     return;
   }
 
-  throw new Error(`Lệnh '${commandName}' thiếu 'exec' hoặc 'shell' trong ${source.path}`);
+  throw new Error(`Command '${commandName}' is missing 'exec' or 'shell' in ${source.path}`);
 }
 
 function sourceLabel(source) {
@@ -126,11 +131,11 @@ function promptProjectChoice(matches, commandName) {
     });
     console.log("");
 
-    rl.question("Chọn dự án (số): ", (answer) => {
+    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("Lựa chọn không hợp lệ."));
+        reject(new Error("Invalid choice."));
         return;
       }
       resolve(matches[choice - 1]);
@@ -149,7 +154,7 @@ async function runWithProjectResolution(
 
   if (matches.length === 0) {
     throw new Error(
-      `Không tìm thấy lệnh '${commandName}' trong bất kỳ .pan.yaml nào.`
+      `Command '${commandName}' not found in any .pan.yaml file.`
     );
   }
 
@@ -158,7 +163,7 @@ async function runWithProjectResolution(
     source = matches.find((item) => sourceMatchesProject(item, projectFlag));
     if (!source) {
       const names = matches.map((item) => sourceLabel(item)).join(", ");
-      throw new Error(`Không tìm thấy dự án '${projectFlag}'. Có: ${names}`);
+      throw new Error(`Project '${projectFlag}' not found. Available: ${names}`);
     }
   } else if (matches.length === 1) {
     source = matches[0];
@@ -176,7 +181,7 @@ async function runWithProjectResolution(
         (item, index) => `${index + 1}. ${sourceLabel(item)} (${item.root})`
       );
       throw new Error(
-        `Lệnh '${commandName}' trùng ở nhiều dự án. Dùng --project <tên>.\n${lines.join("\n")}`
+        `Command '${commandName}' is defined in multiple projects. Use --project <name>.\n${lines.join("\n")}`
       );
     }
   }
@@ -187,13 +192,13 @@ async function runWithProjectResolution(
 function runGitScript(scriptName, args) {
   const scriptPath = path.join(__dirname, "git", scriptName);
   if (!fs.existsSync(scriptPath)) {
-    throw new Error(`Không tìm thấy script: ${scriptPath}`);
+    throw new Error(`Script not found: ${scriptPath}`);
   }
 
-  const child = spawn(process.execPath, [scriptPath, ...args], {
+  const child = spawn(process.execPath, [scriptPath, ...args], spawnOptions({
     stdio: "inherit",
     env: process.env,
-  });
+  }));
 
   child.on("exit", (code) => {
     process.exit(code ?? 1);

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "pan-stack-cli",
-  "version": "0.1.2",
-  "description": "CLI điều phối PAN Stack — git đa repo và lệnh dự án từ .project.yaml",
+  "version": "0.1.5",
+  "description": "PAN Stack CLI — multi-repo git and project commands from .project.yaml",
   "license": "MIT",
   "bin": {
     "pan": "bin/pan.js"
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "templates"
   ],
   "engines": {
     "node": ">=18"

package/templates/workspace/.claude/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.codex/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.cursor/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.pan.yaml

@@ -0,0 +1,25 @@
+# Workspace-level commands. Per-repo commands live in apps/*/.pan.yaml
+commands:
+  install:
+    alias: i
+    description: Install dependencies across cloned repositories
+    shell: |
+      set -euo pipefail
+      root="${PAN_WORKSPACE_ROOT}"
+      for dir in apps/web apps/api; do
+        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir (run 'pan clone' first?)" >&2; exit 1; }
+        echo "-> install $dir"
+        (cd "$root/$dir" && npm install)
+      done
+      echo "Done."
+
+  test:
+    default: web
+    description: Run tests (web | api)
+    targets:
+      web:
+        cwd: apps/web
+        exec: npm test
+      api:
+        cwd: apps/api
+        exec: npm test

package/templates/workspace/.project.yaml

@@ -0,0 +1,15 @@
+project: __PROJECT_NAME__
+managed_by: your-team
+
+stack:
+  repo: repo_url_to_be_filled
+
+repositories:
+  - name: bookshop-web
+    description: Customer-facing web application
+    url: repo_url_to_be_filled
+    path: apps/web
+  - name: bookshop-api
+    description: REST API service
+    url: repo_url_to_be_filled
+    path: apps/api

package/templates/workspace/README.md

@@ -0,0 +1,35 @@
+# __PROJECT_NAME__
+
+PAN Stack workspace shell for the Bookshop example project.
+
+This repository is the **coordination layer** — not the product source tree. It holds
+agent skills, workspace manifests, and `pan` commands. Product code lives in the
+repositories listed in `.project.yaml`.
+
+## Layout
+
+```text
+__PROJECT_NAME__/
+  .project.yaml          # Workspace manifest (repository list)
+  .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 (after pan clone)
+    api/                 # bookshop-api (after pan clone)
+```
+
+## Quick start
+
+```bash
+# Edit repository URLs in .project.yaml, then:
+pan clone
+pan install
+pan test web
+```
+
+## Agent skills
+
+All three agent folders ship with the shared `writing-guidelines` skill. Add more
+skills under each `.claude`, `.cursor`, and `.codex` directory as your team grows.