viepilot 1.6.1 → 1.8.1

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Planned
+
+ - None.
+
+### Added
+
+ - None yet.
+
+## [1.8.1] - 2026-04-01
+
+### Fixed
+
+- **M1.26 / Phase 30 (BUG-004) completed** — enforced vp-only namespace behavior across the framework: all `vp-*` skills include scope guard rules, core workflows default to `vp-*` routing only, and external skills are allowed only via explicit user opt-in.
+
+### Added
+
+- `tests/unit/vp-scope-policy-contracts.test.js` — regression tests to ensure all bundled skills/workflows retain the BUG-004 scope policy contract.
+
+### Documentation
+
+- `docs/skills-reference.md`, `docs/user/features/autonomous-mode.md`, `docs/user/features/debug-mode.md`, `docs/user/quick-start.md` — clarified default `vp-*` scope and added explicit opt-in examples for external skills.
+
+## [1.8.0] - 2026-04-01
+
+### Added
+
+- **M1.25 / Phase 29 (ENH-018) completed** — complexity-gated Mermaid architecture contract shipped: brainstorm inputs + crystallize matrix (`required|optional|N/A`) for six diagram types, architecture template sections with N/A rationale policy, and skill/workflow alignment across `vp-crystallize`, `vp-audit`, `vp-debug`, and `autonomous`.
+
+## [1.7.0] - 2026-04-01
+
+### Added
+
+- **M1.24 / Phase 28 (ENH-017) completed** — Node-native installer flow shipped: `lib/viepilot-install.cjs` (`buildInstallPlan`/`applyInstallPlan`), `bin/viepilot.cjs install` no longer spawns `bash`, `install.sh` now thin wrapper to Node, and Jest coverage for dry-run/apply/wrapper paths.
+
+### Documentation
+
+- `docs/troubleshooting.md`, `docs/dev/deployment.md` — updated install engine behavior (`npx viepilot install` Node-native, `install.sh` wrapper), Windows guidance, and reinstall semantics with `dev-install.sh`.
+
 ## [1.6.1] - 2026-04-01
 
 ### Enhanced
@@ -252,7 +290,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.1...HEAD
+[1.8.1]: https://github.com/0-CODE/viepilot/compare/v1.8.0...v1.8.1
+[1.8.0]: https://github.com/0-CODE/viepilot/compare/v1.7.0...v1.8.0
 [0.10.0]: https://github.com/0-CODE/viepilot/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/0-CODE/viepilot/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/0-CODE/viepilot/compare/v0.8.1...v0.8.2

package/bin/viepilot.cjs

@@ -5,9 +5,15 @@
  */
 
 const path = require('path');
-const { spawnSync } = require('child_process');
 const readline = require('readline');
 const fs = require('fs');
+const os = require('os');
+const { buildInstallPlan, applyInstallPlan, resolveViepilotPackageRoot } = require(path.join(
+  __dirname,
+  '..',
+  'lib',
+  'viepilot-install.cjs',
+));
 
 const TARGETS = [
   { id: 'claude-code', label: 'Claude Code' },
@@ -28,7 +34,7 @@ Usage:
 Install options:
   --target <id|id,id|all>   Target profile(s): claude-code,cursor-agent,cursor-ide
   --yes                      Non-interactive mode (skip confirmations)
-  --dry-run                  Print actions only, do not execute installers
+  --dry-run                  Print actions only (Node installer; no bash)
   --list-targets             Print supported targets and exit
   --help                     Show help
 
@@ -239,28 +245,48 @@ async function interactiveTargetSelection() {
   return runKeyboardSelector(TARGETS, 'multi', 'Select install targets');
 }
 
-function handlerForTarget(target) {
-  const root = path.join(__dirname, '..');
-  return {
-    script: path.join(root, 'install.sh'),
-    env: { VIEPILOT_AUTO_YES: '1', VIEPILOT_INSTALL_PROFILE: target },
+/**
+ * One install applies the same file bundle for every target id (profiles are informational).
+ * @param {string[]} selectedTargets
+ * @param {boolean} dryRun
+ * @returns {{ ok: boolean, code: number }}
+ */
+function runInstallViaNode(selectedTargets, dryRun) {
+  const fallbackRoot = path.join(__dirname, '..');
+  const pkgRoot = resolveViepilotPackageRoot(fallbackRoot) || fallbackRoot;
+  const profile = selectedTargets[0] || 'cursor-ide';
+  const env = {
+    ...process.env,
+    VIEPILOT_AUTO_YES: '1',
+    VIEPILOT_INSTALL_PROFILE: profile,
   };
-}
+  const wantPathShim = env.VIEPILOT_ADD_PATH === '1';
 
-function runInstaller(target, dryRun) {
-  const config = handlerForTarget(target);
-  const commandLabel = `${config.script} [profile=${target}]`;
-  if (dryRun) {
-    console.log(`[dry-run] ${commandLabel}`);
-    return { ok: true, target, dryRun: true };
+  let plan;
+  try {
+    plan = buildInstallPlan(pkgRoot, env, { wantPathShim });
+  } catch (err) {
+    console.error(err.message);
+    return { ok: false, code: 1 };
   }
 
-  const result = spawnSync('bash', [config.script], {
-    stdio: 'inherit',
-    env: { ...process.env, ...config.env },
-    cwd: path.join(__dirname, '..'),
-  });
-  return { ok: result.status === 0, target, code: result.status ?? 1 };
+  console.log('');
+  console.log('ViePilot install (Node — no bash required)');
+  console.log(`  Package: ${pkgRoot}`);
+  console.log(`  Targets (informational): ${selectedTargets.join(', ')}`);
+
+  const applied = applyInstallPlan(plan, { dryRun });
+  if (applied.logs.length > 0) {
+    console.log('');
+    console.log(applied.logs.join('\n'));
+  }
+  if (!applied.ok && applied.errors.length > 0) {
+    const first = applied.errors[0];
+    const msg = first.error && first.error.message ? first.error.message : String(first.error);
+    console.error(msg);
+  }
+
+  return { ok: applied.ok, code: applied.ok ? 0 : 1 };
 }
 
 async function installCommand(rawArgs) {
@@ -290,7 +316,13 @@ async function installCommand(rawArgs) {
   }
 
   console.log(`\nSelected targets: ${selectedTargets.join(', ')}`);
-  const results = selectedTargets.map((target) => runInstaller(target, options.dryRun));
+  const run = runInstallViaNode(selectedTargets, options.dryRun);
+  const results = selectedTargets.map((target) => ({
+    ok: run.ok,
+    target,
+    dryRun: options.dryRun,
+    code: run.code,
+  }));
   const failed = results.filter((r) => !r.ok);
 
   console.log('\nInstall summary:');
@@ -307,7 +339,7 @@ async function installCommand(rawArgs) {
 }
 
 function computeUninstallPaths(targets) {
-  const home = process.env.HOME || '';
+  const home = process.env.HOME || os.homedir() || '';
   const cursorSkills = path.join(home, '.cursor', 'skills');
   const vpRoot = path.join(home, '.cursor', 'viepilot');
   const paths = [];

package/docs/dev/deployment.md

@@ -24,11 +24,10 @@ cd viepilot
 ./install.sh
 ```
 
-`install.sh` copies:
+`install.sh` is a thin **bash** wrapper: optional **cloc** / **PATH** prompts, then **`node bin/viepilot.cjs install`** (same **Node** engine as `npx viepilot install`). It installs to:
 - `skills/vp-*/` → `~/.cursor/skills/`
-- `workflows/` → `~/.cursor/viepilot/workflows/`
-- `templates/` → `~/.cursor/viepilot/templates/`
-- `bin/vp-tools.cjs` → `~/.local/bin/vp-tools`
+- `workflows/`, `templates/`, `bin/`, `lib/` → `~/.cursor/viepilot/…`
+- Optional PATH symlinks (Unix) via `VIEPILOT_ADD_PATH=1`
 
 ### Method 3: Development Mode
 

package/docs/skills-reference.md

@@ -2,6 +2,14 @@
 
 Complete reference for all ViePilot skills.
 
+## ViePilot Scope Policy
+
+- **Default behavior**: ViePilot workflows and responses only use skills under `vp-*`.
+- **Out-of-scope by default**: skills outside the ViePilot namespace are ignored, even if present in the runtime environment.
+- **Explicit opt-in**: external skills are considered only when the user explicitly asks to expand beyond ViePilot scope.
+- **Routing fallback**: if an external skill is mentioned accidentally, prefer the closest built-in `vp-*` command instead.
+- **Opt-in example**: "Trong bước này, cho phép dùng thêm external skills ngoài ViePilot để tham khảo."
+
 ---
 
 ## /vp-brainstorm

package/docs/troubleshooting.md

@@ -68,6 +68,43 @@ chmod +x install.sh
 
 ---
 
+### `npx viepilot install` vs dev clone — upgrade / cài lại có “conflict” không?
+
+**Không có** giao diện merge từng file. Hành vi phụ thuộc **script nào** chạy:
+
+| Cách cài | Script | Trước khi ghi file mới |
+|----------|--------|-------------------------|
+| **`npx viepilot install`** (mọi `--target`) | **`bin/viepilot.cjs`** + `lib/viepilot-install.cjs` (Node, **không** bash) | **Không** xóa `~/.cursor/skills/vp-*` hay `~/.cursor/viepilot`; copy đè tương đương **`cp -r`**. File cùng tên bị ghi đè; file **chỉ còn ở bản cũ** có thể **vẫn nằm lại** (orphan). |
+| **`./install.sh`** từ clone / tarball | Thin **bash** wrapper → gọi `node bin/viepilot.cjs install` | Cùng engine Node như NPX; bash chỉ còn prompt (cloc, PATH) khi không `VIEPILOT_AUTO_YES=1`. |
+| **`./dev-install.sh`** từ clone repo | `dev-install.sh` | **Có** xóa sạch `vp-*` skills + **`rm -rf ~/.cursor/viepilot`** rồi cài lại → gần như cài mới hoàn toàn. |
+
+`npx viepilot install` chạy **trực tiếp** Node installer — **không** spawn `bash install.sh`. `install.sh` dùng khi bạn chạy tay từ repo và muốn prompt cloc/PATH giống trước.
+
+**Muốn cài sạch sau bản cũ** (tránh sót file):
+
+```bash
+npx viepilot uninstall --yes
+npx viepilot install --target cursor-agent --yes
+```
+
+(Chọn lại `--target` đúng profile bạn dùng.)
+
+---
+
+### Windows / đa OS: `install.sh` và `npx viepilot install` chạy thế nào?
+
+**`npx viepilot install`** dùng **Node** (`lib/viepilot-install.cjs`) — **không** cần Bash. **`./install.sh`** là wrapper Bash (prompt cloc/PATH) rồi gọi `node bin/viepilot.cjs install …`. **`dev-install.sh`** vẫn là Bash đầy đủ (xóa + copy).
+
+| OS | `npx viepilot install` | `./install.sh` |
+|----|------------------------|----------------|
+| **macOS**, **Linux** | Chỉ cần Node trên PATH | Bash → Node (cùng engine với NPX) |
+| **Windows (CMD/PowerShell)** | Chạy được với Node | Cần Git Bash / WSL cho file `.sh`, hoặc: `node bin\viepilot.cjs install --target cursor-agent --yes` |
+| **PATH `/usr/local/bin`** | Tùy chọn trong installer (Unix); Windows bỏ qua / PATH thủ công | |
+
+Với ViePilot **Node-native install**, lỗi **`bash: command not found`** khi chạy **`npx viepilot install`** không còn điển hình — nếu vẫn gặp trên bản cũ, hãy nâng ViePilot hoặc dùng `node bin/viepilot.cjs install …` từ source.
+
+---
+
 ### `vp-tools: command not found`
 
 **Cause**: ViePilot bin not in PATH.

package/docs/user/features/autonomous-mode.md

@@ -30,6 +30,12 @@ Mỗi task:
 /vp-auto --dry-run        # Preview, không execute
 ```
 
+## ViePilot Scope Policy (BUG-004)
+
+- Mặc định, `/vp-auto` chỉ route/gợi ý các skill thuộc namespace `vp-*`.
+- Nếu môi trường runtime có skills ngoài framework, workflow sẽ bỏ qua và ưu tiên skill ViePilot tương đương.
+- Chỉ khi bạn ghi rõ yêu cầu mở rộng (explicit opt-in), agent mới được phép dùng external skills.
+
 ### Doc-first gate (v0.8.2 / BUG-001)
 
 Workflow `autonomous.md` yêu cầu **ghi nhận kế hoạch trong file task** và **`PHASE-STATE` → `in_progress`** trước khi chỉnh sửa deliverable. Xem `workflows/autonomous.md` — *Pre-execution documentation gate*.

package/docs/user/features/debug-mode.md

@@ -75,3 +75,4 @@ Active debug sessions:
 - Mô tả problem cụ thể: "X happens when Y" thay vì "something is broken"
 - Một session per issue — không mix nhiều bugs
 - Dùng `/vp-debug continue` sau context reset để không mất progress
+- Theo policy BUG-004, `/vp-debug` mặc định chỉ dùng hệ skill `vp-*`; external skills chỉ dùng khi bạn explicit opt-in.

package/docs/user/quick-start.md

@@ -182,6 +182,14 @@ Hiển thị:
 
 ---
 
+## Skill Scope (BUG-004)
+
+- Theo mặc định, ViePilot chỉ dùng hệ lệnh/skill `vp-*` trong toàn bộ workflow.
+- Nếu bạn thấy đề cập skill ngoài framework, hãy coi đó là out-of-scope trừ khi bạn đã explicit opt-in.
+- Ví dụ opt-in hợp lệ: "Cho phép dùng thêm external skills ngoài ViePilot trong bước research này."
+
+---
+
 ## Next Steps
 
 - [Skills Reference](../skills-reference.md) — Chi tiết tất cả commands

package/install.sh

@@ -1,23 +1,22 @@
 #!/bin/bash
 
-# ViePilot Installation Script
-# Installs ViePilot skills and tools to Cursor/Claude environment
+# ViePilot installation — thin wrapper around the Node installer (bin/viepilot.cjs).
+# Implements prompts + optional cloc install here; file copy/symlink/chmod/path is in lib/viepilot-install.cjs.
 #
-# Optional: VIEPILOT_SYMLINK_SKILLS=1 — symlink skills/* into ~/.cursor/skills/ (absolute paths)
+# Optional: VIEPILOT_SYMLINK_SKILLS=1 — passed through to Node (symlink skills into ~/.cursor/skills/)
+# Optional: VIEPILOT_INSTALL_DRY_RUN=1 — runs `viepilot install --dry-run` (for CI/tests)
 
 set -e
 
-# Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
-NC='\033[0m' # No Color
+NC='\033[0m'
 
-# Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR" || exit 1
 
-# Default installation paths
 CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
 VIEPILOT_DIR="$HOME/.cursor/viepilot"
 AUTO_YES="${VIEPILOT_AUTO_YES:-0}"
@@ -30,7 +29,6 @@ echo " VIEPILOT INSTALLER"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo -e "${NC}"
 
-# Check if running from viepilot directory
 if [ ! -f "$SCRIPT_DIR/README.md" ] || [ ! -d "$SCRIPT_DIR/skills" ]; then
     echo -e "${RED}Error: Please run this script from the viepilot directory${NC}"
     exit 1
@@ -40,6 +38,7 @@ echo -e "${YELLOW}Installation paths:${NC}"
 echo "  Skills: $CURSOR_SKILLS_DIR"
 echo "  ViePilot: $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
+echo "  Engine: Node (bin/viepilot.cjs) — no bash copy logic"
 echo ""
 
 install_cloc_best_effort() {
@@ -86,7 +85,6 @@ install_cloc_best_effort() {
     fi
 }
 
-# Confirm installation
 if [ "$AUTO_YES" != "1" ]; then
     read -p "Continue with installation? (y/n) " -n 1 -r
     echo
@@ -99,105 +97,29 @@ else
 fi
 
 echo ""
-echo -e "${BLUE}Installing...${NC}"
-
-# Create directories
-echo "  Creating directories..."
-mkdir -p "$CURSOR_SKILLS_DIR"
-mkdir -p "$VIEPILOT_DIR/workflows"
-mkdir -p "$VIEPILOT_DIR/templates/project"
-mkdir -p "$VIEPILOT_DIR/templates/phase"
-mkdir -p "$VIEPILOT_DIR/bin"
-mkdir -p "$VIEPILOT_DIR/lib"
-mkdir -p "$VIEPILOT_DIR/ui-components"
-
-# Install skills (copy default; VIEPILOT_SYMLINK_SKILLS=1 for dev-style live links)
-echo "  Installing skills..."
-for skill_dir in "$SCRIPT_DIR/skills"/*; do
-    if [ -d "$skill_dir" ]; then
-        skill_name=$(basename "$skill_dir")
-        if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
-            if command -v realpath >/dev/null 2>&1; then
-                skill_abs=$(realpath "$skill_dir")
-            else
-                skill_abs=$(cd "$skill_dir" && pwd)
-            fi
-            ln -sfn "$skill_abs" "$CURSOR_SKILLS_DIR/$skill_name"
-            echo "    ✓ $skill_name (symlink)"
-        else
-            cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
-            echo "    ✓ $skill_name"
-        fi
-    fi
-done
-
-# Install workflows
-echo "  Installing workflows..."
-cp -r "$SCRIPT_DIR/workflows"/* "$VIEPILOT_DIR/workflows/"
-echo "    ✓ workflows"
-
-# Install templates
-echo "  Installing templates..."
-cp -r "$SCRIPT_DIR/templates/project"/* "$VIEPILOT_DIR/templates/project/"
-cp -r "$SCRIPT_DIR/templates/phase"/* "$VIEPILOT_DIR/templates/phase/"
-echo "    ✓ templates"
-
-# Install stock UI components
-echo "  Installing stock UI components..."
-if [ -d "$SCRIPT_DIR/ui-components" ]; then
-    cp -r "$SCRIPT_DIR/ui-components"/* "$VIEPILOT_DIR/ui-components/"
-    echo "    ✓ ui-components"
-fi
-
-# Install CLI tools
-echo "  Installing CLI tools..."
-cp "$SCRIPT_DIR/bin/vp-tools.cjs" "$VIEPILOT_DIR/bin/"
-cp "$SCRIPT_DIR/bin/viepilot.cjs" "$VIEPILOT_DIR/bin/"
-cp "$SCRIPT_DIR/lib/cli-shared.cjs" "$VIEPILOT_DIR/lib/"
-chmod +x "$VIEPILOT_DIR/bin/vp-tools.cjs"
-chmod +x "$VIEPILOT_DIR/bin/viepilot.cjs"
-echo "    ✓ vp-tools.cjs + viepilot.cjs + lib/cli-shared.cjs"
-
-echo "  Checking optional dependency for README metric sync..."
+echo -e "${BLUE}Preparing Node installer...${NC}"
 install_cloc_best_effort
 
-# Create symlink in PATH (optional)
 echo ""
 if [ "$AUTO_YES" != "1" ]; then
-    read -p "Add vp-tools + viepilot to PATH? (creates symlink in /usr/local/bin) (y/n) " -n 1 -r
+    read -p "Add vp-tools + viepilot to PATH? (symlinks via Node installer, often /usr/local/bin) (y/n) " -n 1 -r
     echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        export VIEPILOT_ADD_PATH=1
+    fi
 else
-    REPLY=$([ "$ADD_PATH_CHOICE" = "1" ] && echo "y" || echo "n")
-fi
-if [[ $REPLY =~ ^[Yy]$ ]]; then
-    if [ -w "/usr/local/bin" ]; then
-        ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
-        ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
-        echo "    ✓ vp-tools + viepilot added to PATH"
-    else
-        echo -e "${YELLOW}    Note: Need sudo to create symlink${NC}"
-        sudo ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
-        sudo ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
-        echo "    ✓ vp-tools + viepilot added to PATH"
+    if [ "$ADD_PATH_CHOICE" = "1" ]; then
+        export VIEPILOT_ADD_PATH=1
     fi
 fi
 
+export VIEPILOT_AUTO_YES=1
+
+NODE_ARGS=(install --target "$INSTALL_PROFILE" --yes)
+if [ "${VIEPILOT_INSTALL_DRY_RUN:-0}" = "1" ]; then
+    NODE_ARGS+=(--dry-run)
+fi
+
 echo ""
-echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo -e "${GREEN} INSTALLATION COMPLETE ✓${NC}"
-echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo ""
-echo "Installed:"
-echo "  - Skills: $CURSOR_SKILLS_DIR/vp-*"
-echo "  - Workflows: $VIEPILOT_DIR/workflows/"
-echo "  - Templates: $VIEPILOT_DIR/templates/"
-echo "  - CLI: $VIEPILOT_DIR/bin/vp-tools.cjs"
-echo ""
-echo "Quick Start:"
-echo "  1. Open your project in Cursor"
-echo "  2. Run: /vp-brainstorm"
-echo "  3. After brainstorm: /vp-crystallize"
-echo "  4. Start coding: /vp-auto"
-echo ""
-echo "Documentation: $SCRIPT_DIR/docs/getting-started.md"
-echo ""
+echo -e "${BLUE}Running: node bin/viepilot.cjs ${NODE_ARGS[*]}${NC}"
+exec node "$SCRIPT_DIR/bin/viepilot.cjs" "${NODE_ARGS[@]}"