start-vibing-stacks 2.6.0 → 2.7.0

package/dist/index.js

@@ -24,6 +24,7 @@ const PKG_VERSION = JSON.parse(readFileSync(join(CLI_ROOT, 'package.json'), 'utf
 // CLI Arguments
 // =============================================================================
 const args = process.argv.slice(2);
+const SUBCOMMAND = args[0] && !args[0].startsWith('-') ? args[0] : null;
 const FLAGS = {
     force: args.includes('--force'),
     noClaude: args.includes('--no-claude'),
@@ -31,6 +32,7 @@ const FLAGS = {
     noInstall: args.includes('--no-install'),
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
+    apply: args.includes('--apply'),
 };
 if (FLAGS.version) {
     console.log(PKG_VERSION);
@@ -40,10 +42,16 @@ if (FLAGS.help) {
     console.log(ui.LOGO);
     console.log(`
   ${chalk.bold('Usage:')}
-    npx start-vibing-stacks [options]
+    npx start-vibing-stacks [command] [options]
+
+  ${chalk.bold('Commands:')}
+    (default)         Setup or resume current project
+    migrate           Compare installed vs bundled skill/agent versions
+                      Add --apply to update outdated/missing items
 
   ${chalk.bold('Options:')}
-    --force           Overwrite existing configuration
+    --force           Overwrite existing configuration (default command)
+    --apply           Apply updates (migrate command)
     --no-claude       Skip Claude Code installation
     --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation
@@ -57,6 +65,12 @@ if (FLAGS.help) {
   `);
     process.exit(0);
 }
+// Subcommand: migrate
+if (SUBCOMMAND === 'migrate') {
+    const { runMigrate } = await import('./migrate.js');
+    await runMigrate(process.cwd(), { apply: FLAGS.apply });
+    process.exit(0);
+}
 const AVAILABLE_STACKS = [
     { id: 'php', name: 'PHP 8.3+', icon: '🐘', available: true },
     { id: 'nodejs', name: 'Node.js / TypeScript', icon: '📦', available: true },

package/dist/migrate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Start Vibing Stacks — Migrate
+ *
+ * Compares the SKILL.md / agent / hook versions installed in .claude/
+ * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ *
+ * Reports outdated, missing, and modified items. Optionally upgrades.
+ *
+ * Skill version contract:
+ *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
+ *   No frontmatter = treated as "v0" / pre-versioning.
+ */
+export interface MigrateItem {
+    kind: 'skill' | 'agent' | 'hook';
+    name: string;
+    source: string;
+    target: string;
+    bundledVersion: string;
+    installedVersion: string | null;
+    status: 'missing' | 'outdated' | 'current' | 'ahead' | 'modified-no-version';
+}
+export interface MigrateOptions {
+    apply: boolean;
+    scope?: 'skills' | 'agents' | 'hooks' | 'all';
+}
+export declare function planMigration(projectDir: string, opts: MigrateOptions): MigrateItem[];
+export declare function runMigrate(projectDir: string, opts: MigrateOptions): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,217 @@
+/**
+ * Start Vibing Stacks — Migrate
+ *
+ * Compares the SKILL.md / agent / hook versions installed in .claude/
+ * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ *
+ * Reports outdated, missing, and modified items. Optionally upgrades.
+ *
+ * Skill version contract:
+ *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
+ *   No frontmatter = treated as "v0" / pre-versioning.
+ */
+import { existsSync, readFileSync, copyFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { join, relative, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import * as semver from 'semver';
+import * as ui from './ui.js';
+const __m_filename = fileURLToPath(import.meta.url);
+const __m_dirname = dirname(__m_filename);
+const CLI_ROOT = resolve(__m_dirname, '..');
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
+const VERSION_RE = /^version:\s*["']?([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?)["']?\s*$/m;
+function parseVersion(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const content = readFileSync(file, 'utf8');
+        const fm = FRONTMATTER_RE.exec(content);
+        if (!fm)
+            return null;
+        const v = VERSION_RE.exec(fm[1] ?? '');
+        return v?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function statusOf(bundled, installed) {
+    if (installed === null)
+        return 'modified-no-version';
+    const cmp = semver.compare(installed, bundled);
+    if (cmp < 0)
+        return 'outdated';
+    if (cmp > 0)
+        return 'ahead';
+    return 'current';
+}
+function listSubdirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter(n => {
+            try {
+                return statSync(join(dir, n)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function listFiles(dir, suffix) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter(n => n.endsWith(suffix));
+    }
+    catch {
+        return [];
+    }
+}
+function listSkillSources(stack, frontendSkillsDir) {
+    const out = [];
+    const sharedDir = join(CLI_ROOT, 'stacks', '_shared', 'skills');
+    const stackDir = join(CLI_ROOT, 'stacks', stack, 'skills');
+    const frontendDir = frontendSkillsDir
+        ? join(CLI_ROOT, 'stacks', 'frontend', frontendSkillsDir, 'skills')
+        : null;
+    for (const dir of [sharedDir, stackDir, frontendDir].filter(Boolean)) {
+        for (const entry of listSubdirs(dir)) {
+            const skillPath = join(dir, entry, 'SKILL.md');
+            if (existsSync(skillPath))
+                out.push({ source: skillPath, name: entry });
+        }
+    }
+    return out;
+}
+function listAgentSources() {
+    const dir = join(CLI_ROOT, 'stacks', '_shared', 'agents');
+    return listFiles(dir, '.md').map(n => ({ source: join(dir, n), name: n }));
+}
+function listHookSources() {
+    const dir = join(CLI_ROOT, 'stacks', '_shared', 'hooks');
+    return listFiles(dir, '.ts').map(n => ({ source: join(dir, n), name: n }));
+}
+function loadProjectConfig(projectDir) {
+    const path = join(projectDir, '.claude', 'config', 'active-project.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function planMigration(projectDir, opts) {
+    const config = loadProjectConfig(projectDir);
+    if (!config) {
+        ui.error('No .claude/config/active-project.json found. Run `npx start-vibing-stacks` first.');
+        return [];
+    }
+    const items = [];
+    const scope = opts.scope ?? 'all';
+    if (scope === 'all' || scope === 'skills') {
+        for (const { source, name } of listSkillSources(config.stack, config.frontendSkillsDir)) {
+            const target = join(projectDir, '.claude', 'skills', name, 'SKILL.md');
+            const bundledVersion = parseVersion(source);
+            if (!bundledVersion)
+                continue;
+            const installedVersion = parseVersion(target);
+            const status = !existsSync(target)
+                ? 'missing'
+                : statusOf(bundledVersion, installedVersion);
+            items.push({ kind: 'skill', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    if (scope === 'all' || scope === 'agents') {
+        for (const { source, name } of listAgentSources()) {
+            const target = join(projectDir, '.claude', 'agents', name);
+            const bundledVersion = parseVersion(source);
+            if (!bundledVersion)
+                continue;
+            const installedVersion = parseVersion(target);
+            const status = !existsSync(target)
+                ? 'missing'
+                : statusOf(bundledVersion, installedVersion);
+            items.push({ kind: 'agent', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    if (scope === 'all' || scope === 'hooks') {
+        for (const { source, name } of listHookSources()) {
+            const target = join(projectDir, '.claude', 'hooks', name);
+            const bundledVersion = '0.0.0';
+            const installedVersion = existsSync(target) ? '0.0.0' : null;
+            const status = !existsSync(target) ? 'missing' : 'current';
+            items.push({ kind: 'hook', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    return items;
+}
+function applyOne(item) {
+    mkdirSync(dirname(item.target), { recursive: true });
+    copyFileSync(item.source, item.target);
+}
+export async function runMigrate(projectDir, opts) {
+    ui.header('🔄 Start Vibing — Migrate');
+    const items = planMigration(projectDir, opts);
+    if (items.length === 0) {
+        ui.info('Nothing to migrate.');
+        return;
+    }
+    const grouped = {
+        missing: [], outdated: [], current: [], ahead: [], 'modified-no-version': [],
+    };
+    for (const it of items)
+        grouped[it.status].push(it);
+    const summary = (label, list) => {
+        if (list.length === 0)
+            return;
+        console.log(`\n  ${label} (${list.length}):`);
+        for (const it of list.slice(0, 30)) {
+            const v = it.installedVersion ?? '–';
+            console.log(`    ${it.kind.padEnd(5)} ${it.name.padEnd(32)} installed=${v.padEnd(8)} bundled=${it.bundledVersion}`);
+        }
+        if (list.length > 30)
+            console.log(`    ... and ${list.length - 30} more`);
+    };
+    summary('MISSING', grouped.missing);
+    summary('OUTDATED', grouped.outdated);
+    summary('AHEAD (installed newer than bundled — kept)', grouped.ahead);
+    summary('UNVERSIONED (manual review)', grouped['modified-no-version']);
+    summary('CURRENT', grouped.current);
+    const upgradable = [...grouped.missing, ...grouped.outdated];
+    if (upgradable.length === 0) {
+        console.log('');
+        ui.success('Everything up to date.');
+        return;
+    }
+    if (!opts.apply) {
+        console.log('');
+        ui.info(`Run with --apply to install/update ${upgradable.length} item(s).`);
+        return;
+    }
+    console.log('');
+    for (const it of upgradable) {
+        try {
+            applyOne(it);
+            ui.success(`updated ${it.kind} ${it.name} (${it.installedVersion ?? '–'} → ${it.bundledVersion})`);
+        }
+        catch (err) {
+            ui.warn(`failed ${it.kind} ${it.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    console.log('');
+    ui.success(`Migration complete: ${upgradable.length} item(s) updated.`);
+    if (grouped['modified-no-version'].length > 0) {
+        console.log('');
+        ui.warn(`${grouped['modified-no-version'].length} unversioned local item(s) skipped — review manually.`);
+        for (const it of grouped['modified-no-version'].slice(0, 10)) {
+            console.log(`    ${relative(projectDir, it.target)}`);
+        }
+    }
+}

package/dist/setup.js

@@ -169,6 +169,16 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = `Imported ${config.standardsReview.patterns.length} project standards`;
             }
         }
+        // 11d. Copy CI workflow templates (only when target dir is empty or --force)
+        const stackWorkflowsDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'workflows');
+        if (existsSync(stackWorkflowsDir)) {
+            const ghWorkflowsDir = join(projectDir, '.github', 'workflows');
+            const targetIsEmpty = !existsSync(ghWorkflowsDir);
+            if (targetIsEmpty || options.force) {
+                copyDirRecursive(stackWorkflowsDir, ghWorkflowsDir, options.force);
+                spinner.text = 'Installed CI workflow templates';
+            }
+        }
         // 12. Copy commands
         const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
         if (existsSync(sharedCommandsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/agents/claude-md-compactor.md

@@ -1,5 +1,6 @@
 ---
 name: claude-md-compactor
+version: 1.0.0
 description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars OR auto memory MEMORY.md exceeds 200 lines. Compacts while preserving critical knowledge by offloading to topic files."
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob

package/stacks/_shared/agents/commit-manager.md

@@ -1,5 +1,6 @@
 ---
 name: commit-manager
+version: 1.0.0
 description: "AUTOMATICALLY invoke as FINAL AGENT when implementation is complete. Creates conventional commits, merges to main."
 model: haiku
 tools: Read, Write, Edit, Bash, Grep, Glob

package/stacks/_shared/agents/documenter.md

@@ -1,5 +1,6 @@
 ---
 name: documenter
+version: 1.0.0
 description: "AUTOMATICALLY invoke AFTER any code implementation. Creates/updates domain documentation. PROACTIVELY runs after implementation."
 model: sonnet
 tools: Read, Write, Edit, Grep, Glob, Bash

package/stacks/_shared/agents/domain-updater.md

@@ -1,5 +1,6 @@
 ---
 name: domain-updater
+version: 1.0.0
 description: "AUTOMATICALLY invoke BEFORE commit-manager at session end. Records problems, solutions, and learnings in domain docs."
 model: haiku
 tools: Read, Write, Edit, Bash, Grep, Glob

package/stacks/_shared/agents/research-web.md

@@ -1,5 +1,6 @@
 ---
 name: research-web
+version: 1.0.0
 description: "AUTOMATICALLY invoke BEFORE implementing any new feature or technology. Triggers: new feature, new technology, 'search', 'find info'. Web research specialist."
 model: sonnet
 tools: WebSearch, WebFetch, Read, Write

package/stacks/_shared/agents/security-auditor.md

@@ -0,0 +1,168 @@
+---
+name: security-auditor
+version: 1.0.0
+description: "AUTOMATICALLY invoke when code touches auth, sessions, user data, passwords, tokens, API routes, database queries, cookies, or env vars. VETO POWER — blocks insecure code. Runs AFTER tester, BEFORE quality-gate."
+model: sonnet
+tools: Read, Grep, Glob, Bash
+skills: security-baseline, secrets-management
+---
+
+# Security Auditor Agent
+
+You audit code for security flaws. **You have VETO power** — when violations are found you block the workflow and require fixes.
+
+## When You Run
+
+After implementation and tester, **before** quality-gate and commit-manager. Always run when modified files include:
+
+- Auth, session, login, register, password, token, JWT
+- Route Handlers, Server Actions, controllers, API endpoints
+- Database queries, ORM models
+- Cookie / header / CORS / CSP configuration
+- File uploads
+- Anything reading `process.env` / `os.environ` / `$_ENV` / `env()`
+
+## Step 1 — Read Stack Context
+
+```bash
+cat .claude/config/active-project.json
+```
+
+Branch logic on `stack`:
+- `nodejs` → load `api-security-node` skill
+- `python` → load `api-security-python` skill
+- `php` → load `api-security` skill
+- always → `security-baseline`, `secrets-management`
+
+## Step 2 — Identify Modified Files
+
+```bash
+git diff --name-only --diff-filter=AM HEAD
+git diff --name-only --cached --diff-filter=AM
+```
+
+Read each modified source file.
+
+## Step 3 — Run the Audit Matrix
+
+Apply each check below. **One violation = block.**
+
+### A. Authn / Session
+
+| Check | Pattern that fails |
+|---|---|
+| User ID from session, not body | `req.body.userId`, `request.json()["user_id"]`, `$request->input('user_id')` used for ownership |
+| Auth gate before logic | Route handler with no `auth()` / `Depends(current_user)` / `auth:sanctum` middleware |
+| Algorithm pinned on JWT | `jwt.verify(token)` without `algorithms` array |
+| Token in HttpOnly cookie | `localStorage.setItem('token', ...)` or token rendered into HTML |
+
+### B. Authz
+
+| Check | Pattern that fails |
+|---|---|
+| Object-level scope | `Model.findById(id)` with no `where userId = session.user.id` |
+| Role check on server | Role check only in client/UI |
+| Mass assignment guard | `User.create(req.body)` without allowlist / Zod `.strict()` / Pydantic `extra="forbid"` / `$fillable` |
+
+### C. Input Validation
+
+| Check | Pattern that fails |
+|---|---|
+| Schema at boundary | Route handler reads `req.body` / `request.json()` without Zod / Pydantic / FormRequest |
+| Strict mode | Schema present but allows extra keys |
+| Mongo operator injection | `User.findOne({ email: req.body.email })` without coercing email to string |
+| SQL bindings | f-string / template-literal SQL: `f"... {x} ..."`, `\`SELECT ... ${x}\``, `"... $x ..."` |
+
+### D. Secrets / Env
+
+Run secrets scan:
+
+```bash
+# Quick high-signal grep
+git diff --cached -U0 \
+  | grep -E '(api[_-]?key|secret|token|password|bearer|aws_|private_key)' \
+  | grep -vE '\.env\.example|TEMPLATE|placeholder|example|<your|YOUR_|XXXX'
+```
+
+Also check:
+- No `NEXT_PUBLIC_` containing `SECRET|TOKEN|PRIVATE|PASSWORD|CREDENTIAL`
+- No hardcoded connection string with embedded password
+- `.env` is in `.gitignore`
+- `.env.example` exists if any env var is read
+
+### E. Cookies
+
+| Check | Required |
+|---|---|
+| `httpOnly: true` | yes |
+| `secure: true` in prod | yes |
+| `sameSite` set | `lax` or `strict` |
+
+### F. CORS / Headers
+
+- No `origin: '*'` or `allow_origins=["*"]` combined with `credentials: true` / `allow_credentials=True`
+- Security headers configured (Helmet / middleware): HSTS, CSP, X-Content-Type-Options, Referrer-Policy
+
+### G. Rate Limiting
+
+- Auth endpoints (`/login`, `/register`, `/password/reset`) have a rate limiter
+- Webhook endpoints reject requests without verified signature
+
+### H. Logging
+
+- No `console.log(req.body)` / `print(request.json())` / `Log::info($request->all())`
+- No `console.log(token)` / logging of cookies, headers, or `Authorization`
+- No PII (email, phone, full name) in logs without redaction
+
+### I. SSRF
+
+- User-supplied URLs are validated against an allowlist OR private IP ranges are blocked
+
+### J. Webhook Verification
+
+- Stripe / GitHub / GitHub App webhooks call `constructEvent` / signature verifier **before** parsing body
+
+## Step 4 — Report
+
+If everything passes, output:
+
+```
+✅ Security audit passed.
+Files audited: <n>
+Checks: A-J all green.
+```
+
+If violations are found, output:
+
+```
+🛑 SECURITY AUDIT BLOCKED
+
+<n> violation(s) found:
+
+1. [HIGH] <file>:<line>
+   Issue: <one line>
+   Fix: <one line>
+   Reference: security-baseline §A01 (or whichever)
+
+2. [MEDIUM] ...
+```
+
+Severity:
+- **CRITICAL** — RCE, SQLi, missing auth, secret in commit. Block immediately.
+- **HIGH** — Authz bypass, missing CSRF, unsafe cookie. Block.
+- **MEDIUM** — Missing rate limit, weak headers. Block.
+- **LOW** — Minor logging concern. Warn, allow.
+
+## Rules
+
+1. **VETO POWER** — `domain-updater` and `commit-manager` MUST NOT run while you have unresolved CRITICAL/HIGH/MEDIUM findings.
+2. **READ THE CODE** — never approve based on file names alone.
+3. **NO FALSE NEGATIVES > FALSE POSITIVES** — when in doubt, flag and explain.
+4. **CITE THE FIX** — every finding has a one-line fix and a skill reference.
+5. **RE-RUN AFTER FIXES** — never trust "I fixed it" without re-reading the file.
+
+## See Also
+
+- Skill `security-baseline` — universal OWASP rules
+- Skill `secrets-management` — env hygiene
+- Stack-specific skill: `api-security-node` / `api-security-python` / PHP `api-security`

package/stacks/_shared/agents/tester.md

@@ -1,5 +1,6 @@
 ---
 name: tester
+version: 1.0.0
 description: "AUTOMATICALLY invoke AFTER implementing any function or utility. Creates tests using the stack-appropriate framework."
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob