pan-stack-cli 0.1.1 → 0.1.4

package/lib/git/git-grv.js

@@ -2,10 +2,9 @@
 /*
  * 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 path = require("path");
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
 const { ensureRepoExists, isGitRepo, listRemotesVerbose } = require("./helpers/git");
 
@@ -19,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);
@@ -28,8 +27,7 @@ function printRepoRemotes({ label, destination, dryRun }) {
   console.log("");
 }
 
-function showWorkspaceRootRemotes({ manifestPath, baseDir, dryRun }) {
-  const workspaceRoot = path.resolve(baseDir || path.dirname(manifestPath || ".project.yaml"));
+function showWorkspaceRootRemotes({ workspaceRoot, dryRun }) {
   if (!isGitRepo(workspaceRoot)) {
     return;
   }
@@ -47,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() {
@@ -64,16 +62,14 @@ function main() {
     return;
   }
 
-  const manifestPath = path.resolve(args.manifest || ".project.yaml");
-  const repos = loadManifestRepos({
-    manifestPath,
+  const { repos, workspaceRoot } = loadManifestRepos({
+    manifestPath: args.manifest,
     baseDir: args.baseDir,
   });
 
   if (!args.noWorkspace) {
     showWorkspaceRootRemotes({
-      manifestPath,
-      baseDir: args.baseDir,
+      workspaceRoot,
       dryRun: args.dryRun,
     });
   }

package/lib/git/git-gst.js

@@ -2,10 +2,9 @@
 /*
  * 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 path = require("path");
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
 const { ensureRepoExists, isGitRepo, runGitStatus } = require("./helpers/git");
 
@@ -22,8 +21,7 @@ function printRepoStatus({ label, destination, dryRun, gitArgs }) {
   console.log("");
 }
 
-function showWorkspaceRootStatus({ manifestPath, baseDir, dryRun, gitArgs }) {
-  const workspaceRoot = path.resolve(baseDir || path.dirname(manifestPath || ".project.yaml"));
+function showWorkspaceRootStatus({ workspaceRoot, dryRun, gitArgs }) {
   if (!isGitRepo(workspaceRoot)) {
     return;
   }
@@ -40,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() {
@@ -62,16 +60,14 @@ function main() {
   }
 
   const gitArgs = args.gitArgs || [];
-  const manifestPath = path.resolve(args.manifest || ".project.yaml");
-  const repos = loadManifestRepos({
-    manifestPath,
+  const { repos, workspaceRoot } = loadManifestRepos({
+    manifestPath: args.manifest,
     baseDir: args.baseDir,
   });
 
   if (!args.noWorkspace) {
     showWorkspaceRootStatus({
-      manifestPath,
-      baseDir: args.baseDir,
+      workspaceRoot,
       dryRun: args.dryRun,
       gitArgs,
     });

package/lib/git/git-pull.js

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

package/lib/git/git-push.js

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

package/lib/git/helpers/cli.js

@@ -1,5 +1,6 @@
 const path = require("path");
 const fs = require("fs");
+const { findNearestProjectManifest } = require("../../discover");
 const { parseManifest, manifestRepos, validateRepo } = require("./manifest");
 
 function parseCommonArgs(argv, extraFlags = {}) {
@@ -51,19 +52,61 @@ function looksLikeManifest(arg) {
   }
 }
 
-function loadManifestRepos({ manifestPath, baseDir }) {
-  const resolvedManifest = path.resolve(manifestPath || ".project.yaml");
-  if (!fs.existsSync(resolvedManifest)) {
-    throw new Error(`Manifest not found: ${manifestPath || ".project.yaml"}`);
+function resolveProjectWorkspace({
+  manifestPath = "",
+  baseDir = ".",
+  startDir = process.cwd(),
+}) {
+  const manifestName = manifestPath || ".project.yaml";
+  const cwdManifest = path.isAbsolute(manifestName)
+    ? manifestName
+    : path.resolve(startDir, manifestName);
+
+  let resolvedManifest = "";
+  let usedWalkUp = false;
+
+  if (fs.existsSync(cwdManifest)) {
+    resolvedManifest = cwdManifest;
+  } else {
+    const found = findNearestProjectManifest(startDir);
+    if (!found) {
+      const label = manifestPath || ".project.yaml";
+      throw new Error(
+        `Manifest not found: ${label} (walked up from ${startDir})`
+      );
+    }
+    resolvedManifest = found;
+    usedWalkUp = true;
+  }
+
+  const workspaceRoot = path.dirname(resolvedManifest);
+  let resolvedBaseDir;
+  if (baseDir === ".") {
+    resolvedBaseDir = usedWalkUp ? workspaceRoot : path.resolve(startDir, ".");
+  } else if (path.isAbsolute(baseDir)) {
+    resolvedBaseDir = baseDir;
+  } else {
+    resolvedBaseDir = path.resolve(startDir, baseDir);
   }
 
+  return {
+    manifestPath: resolvedManifest,
+    baseDir: resolvedBaseDir,
+    workspaceRoot,
+  };
+}
+
+function loadManifestRepos({ manifestPath, baseDir, startDir = process.cwd() }) {
+  const workspace = resolveProjectWorkspace({ manifestPath, baseDir, startDir });
+  const { manifestPath: resolvedManifest, baseDir: resolvedBaseDir, workspaceRoot } =
+    workspace;
+
   const data = parseManifest(resolvedManifest);
   const repos = manifestRepos(data);
   if (repos.length === 0) {
     throw new Error("No repositories found in manifest.");
   }
 
-  const resolvedBaseDir = path.resolve(baseDir);
   const results = [];
   for (const repo of repos) {
     try {
@@ -83,7 +126,12 @@ function loadManifestRepos({ manifestPath, baseDir }) {
     throw new Error("No valid repositories found in manifest.");
   }
 
-  return results;
+  return {
+    repos: results,
+    manifestPath: resolvedManifest,
+    baseDir: resolvedBaseDir,
+    workspaceRoot,
+  };
 }
 
 function printCommonOptions() {
@@ -92,12 +140,13 @@ function printCommonOptions() {
 
 options:
   -h, --help           show this help message and exit
-  --base-dir BASE_DIR  Base directory for relative repo paths. Default: current directory.
+  --base-dir BASE_DIR  Base directory for relative repo paths. Default: directory containing .project.yaml (walk-up from cwd when needed).
   --dry-run            Print commands only`;
 }
 
 module.exports = {
   parseCommonArgs,
+  resolveProjectWorkspace,
   loadManifestRepos,
   printCommonOptions,
 };

package/lib/git/helpers/git.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const { spawnOptions } = require("../../platform");
 
 function isGitRepo(directory) {
   return fs.existsSync(path.join(directory, ".git"));
@@ -14,7 +15,7 @@ function runGit(gitArgs, { cwd, dryRun, action, name }) {
   }
 
   console.log(`[${action}] ${name}: ${cwd}`);
-  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit", cwd });
+  const result = spawnSync(command[0], command.slice(1), spawnOptions({ stdio: "inherit", cwd }));
   return result.status ?? 1;
 }
 
@@ -31,10 +32,10 @@ function ensureRepoExists({ name, destination }) {
 }
 
 function listRemotesVerbose(directory) {
-  const result = spawnSync("git", ["remote", "-v"], {
+  const result = spawnSync("git", ["remote", "-v"], spawnOptions({
     cwd: directory,
     encoding: "utf8",
-  });
+  }));
   if (result.status !== 0) {
     return [];
   }
@@ -45,10 +46,10 @@ function listRemotesVerbose(directory) {
 }
 
 function runGitStatus(directory, gitArgs = []) {
-  const result = spawnSync("git", ["status", ...gitArgs], {
+  const result = spawnSync("git", ["status", ...gitArgs], spawnOptions({
     cwd: directory,
     stdio: "inherit",
-  });
+  }));
   return result.status ?? 1;
 }
 

package/lib/manifest.js

@@ -323,7 +323,7 @@ function getCommandDefinition(source, commandName, subArg) {
     const target = def.targets[targetName];
     if (!target) {
       const valid = Object.keys(def.targets).join(" | ");
-      throw new Error(`Target hợp lệ cho '${commandName}': ${valid}`);
+      throw new Error(`Valid targets for '${commandName}': ${valid}`);
     }
     return {
       ...target,

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.1",
-  "description": "CLI điều phối PAN Stack — git đa repo và lệnh dự án từ .project.yaml",
+  "version": "0.1.4",
+  "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.