start-vibing-stacks 2.24.0 → 2.25.2

package/README.md

@@ -6,7 +6,7 @@ Multi-stack AI workflow for **Claude Code** & **Cursor**. One command installs a
 npx start-vibing-stacks
 ```
 
-> Latest: **v2.24.0** — `migrate` is now smart and complete. Versioned hooks (`// @sv-version`), versioned commands, idempotent `settings.json` patcher, runtime dirs auto-creation, `.gitignore` update — all reachable via `npx start-vibing-stacks migrate --apply`. New `--force-hooks` flag overwrites legacy hooks (no `@sv-version`) with timestamped `.bak` backup. v2.23.0 → multi-instance coordination layer.
+> Latest: **v2.25.0** — `--force-hooks` (alias `--force-legacy`) now also covers legacy commands (`commands/*.md` without `version:` frontmatter), not just hooks. Single command rebuilds installs older than v2.23.0. v2.24.0 → smart migrate (versioned hooks/commands, idempotent `settings.json`, runtime dirs, `.gitignore`). v2.23.0 → multi-instance coordination layer.
 
 ---
 
@@ -133,7 +133,8 @@ Single-host coordination only. It does **not** replace `git` for cross-machine c
 npx start-vibing-stacks                                # setup or resume current project
 npx start-vibing-stacks migrate                        # dry run: skills + agents + hooks + commands + settings.json + runtime dirs
 npx start-vibing-stacks migrate --apply                # apply (idempotent; preserves customizations)
-npx start-vibing-stacks migrate --apply --force-hooks  # also overwrite legacy hooks (no @sv-version) — creates .bak
+npx start-vibing-stacks migrate --apply --force-legacy # also overwrite legacy hooks AND commands (no version) — creates .bak
+npx start-vibing-stacks migrate --apply --force-hooks  # alias for --force-legacy (back-compat)
 
 # flags: --force --no-claude --no-mcp --no-install --help --version
 ```
@@ -145,7 +146,7 @@ npx start-vibing-stacks migrate --apply --force-hooks  # also overwrite legacy h
 - **Runtime artefacts** — `.claude/state/{sessions,inbox,file-touches}/_archive` auto-created; `_state.README.md` staged.
 - **`.gitignore`** — `.claude/state/` appended if not already covered.
 
-Legacy hooks without `@sv-version` (anything older than v2.24.0) are reported as `needs-update-legacy` and skipped by default. Pass `--force-hooks` to overwrite them — each gets a timestamped `.bak`.
+Legacy files without versioning — hooks without `// @sv-version` AND commands without `version:` frontmatter (anything installed before the versioning landed) — are reported as `needs-update-legacy` and skipped by default. Pass `--force-legacy` (or its alias `--force-hooks`) to overwrite them — each gets a timestamped `.bak`. Skills and agents are intentionally **not** covered because users customize them; they stay in `modified-no-version` (advisory only).
 
 Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
 

package/dist/index.js

@@ -33,7 +33,7 @@ const FLAGS = {
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
     apply: args.includes('--apply'),
-    forceHooks: args.includes('--force-hooks'),
+    forceHooks: args.includes('--force-hooks') || args.includes('--force-legacy'),
 };
 if (FLAGS.version) {
     console.log(PKG_VERSION);
@@ -53,7 +53,9 @@ if (FLAGS.help) {
   ${chalk.bold('Options:')}
     --force           Overwrite existing configuration (default command)
     --apply           Apply updates (migrate command)
-    --force-hooks     Overwrite legacy hooks without @sv-version (migrate; creates .bak)
+    --force-legacy    Overwrite legacy hooks (no @sv-version) AND legacy commands
+                      (no version: frontmatter) — each gets a timestamped .bak
+    --force-hooks     Alias for --force-legacy (kept for back-compat)
     --no-claude       Skip Claude Code installation
     --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation

package/dist/migrate.js

@@ -187,7 +187,20 @@ export function planMigration(projectDir, opts) {
             if (!bundledVersion)
                 continue;
             const installedVersion = parseFrontmatterVersion(target);
-            const status = !existsSync(target) ? 'missing' : statusFromSemver(bundledVersion, installedVersion);
+            let status;
+            if (!existsSync(target)) {
+                status = 'missing';
+            }
+            else if (installedVersion === null) {
+                // Commands are canonical infra files (slash-command routes). When the
+                // installed copy lacks `version:` frontmatter it predates versioned
+                // commands — treat as legacy so `--force-hooks` can heal it (same
+                // .bak machinery as legacy hooks). Skills/agents stay manual-review.
+                status = 'needs-update-legacy';
+            }
+            else {
+                status = statusFromSemver(bundledVersion, installedVersion);
+            }
             items.push({ kind: 'command', name, source, target, bundledVersion, installedVersion, status });
         }
     }
@@ -363,7 +376,7 @@ export async function runMigrate(projectDir, opts) {
     };
     summary('MISSING', grouped.missing);
     summary('OUTDATED', grouped.outdated);
-    summary('NEEDS UPDATE — legacy hooks (no @sv-version tag)', grouped['needs-update-legacy']);
+    summary('NEEDS UPDATE — legacy (hooks without @sv-version, commands without version: frontmatter)', grouped['needs-update-legacy']);
     summary('AHEAD (installed newer than bundled — kept)', grouped.ahead);
     summary('UNVERSIONED (manual review)', grouped['modified-no-version']);
     summary('CURRENT', grouped.current);
@@ -415,8 +428,9 @@ export async function runMigrate(projectDir, opts) {
             todo.push('runtime artefacts');
         ui.info(`Run with --apply to update: ${todo.join(' + ')}.`);
         if (grouped['needs-update-legacy'].length > 0 && !opts.forceHooks) {
-            ui.info(`${grouped['needs-update-legacy'].length} legacy hook(s) without @sv-version detected. ` +
-                `Use --force-hooks to update them with a .bak backup.`);
+            ui.info(`${grouped['needs-update-legacy'].length} legacy file(s) detected (hooks without @sv-version, ` +
+                `commands without \`version:\` frontmatter). Use --force-legacy (alias --force-hooks) to ` +
+                `update them with a .bak backup.`);
         }
         return;
     }
@@ -453,7 +467,7 @@ export async function runMigrate(projectDir, opts) {
         ui.success('gitignore: appended .claude/state/');
     console.log('');
     ui.success(`Migration complete: ${updated} file(s), ${settingsApply.added.length} settings entry(ies)` +
-        (legacyUpdated > 0 ? `, ${legacyUpdated} legacy hook(s) overwritten with backup` : ''));
+        (legacyUpdated > 0 ? `, ${legacyUpdated} legacy file(s) overwritten with backup` : ''));
     if (grouped['modified-no-version'].length > 0) {
         console.log('');
         ui.warn(`${grouped['modified-no-version'].length} unversioned local skill/agent/command(s) skipped — review manually.`);
@@ -463,8 +477,9 @@ export async function runMigrate(projectDir, opts) {
     }
     if (grouped['needs-update-legacy'].length > 0 && !opts.forceHooks) {
         console.log('');
-        ui.warn(`${grouped['needs-update-legacy'].length} legacy hook(s) without @sv-version were skipped. ` +
-            `Re-run with --force-hooks to update them (each gets a .bak backup).`);
+        ui.warn(`${grouped['needs-update-legacy'].length} legacy file(s) skipped (hooks without @sv-version, ` +
+            `commands without \`version:\` frontmatter). Re-run with --force-legacy ` +
+            `(alias --force-hooks) to update them (each gets a .bak backup).`);
         for (const it of grouped['needs-update-legacy'].slice(0, 10)) {
             console.log(`    ${relative(projectDir, it.target)}`);
         }

package/package.json

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

package/stacks/_shared/commands/validate.md

@@ -1,28 +1,113 @@
 ---
 name: validate
-description: Run the full quality gate (typecheck → lint → test → build) using the stack's commands from active-project.json.
-version: 1.0.0
+description: Run the full quality gate (typecheck → lint → test → build) using THIS project's `active-project.json#qualityGates`. Per-stack reference is below.
+version: 1.1.0
 ---
 
 # /validate — Run Full Validation
 
-Read the quality gates from `.claude/config/active-project.json#qualityGates` and run them in order. Stop at the first failure.
+## How it works (canonical — always use this)
+
+1. **Read the gates from `.claude/config/active-project.json#qualityGates`.** This is the **only** source of truth — it was populated at install time from the active stack and reflects this project's actual tooling.
+2. Run each gate in `order` ascending; stop at the first failure that has `required: true`.
+3. If a gate has `appliesTo: ["nextjs", ...]`, only run it when `framework` in `active-project.json` matches.
 
 ```bash
-jq -r '.qualityGates' .claude/config/active-project.json
+jq -r '.qualityGates | sort_by(.order) | .[] | "\(.order). \(.name) (required=\(.required)): \(.command)"' .claude/config/active-project.json
+```
+
+`commit-manager` refuses to commit while `/validate` is failing.
+
+---
+
+## Per-stack reference (suggested — only used if `active-project.json` is missing or corrupted)
+
+This block exists so the model has a stack-aware fallback. **Do not pick from here when `active-project.json#qualityGates` is present and valid** — that JSON always wins.
+
+```json
+{
+  "python": {
+    "_default": {
+      "typecheck": "mypy .",
+      "lint":      "ruff check .",
+      "format":    "ruff format .",
+      "test":      "pytest --tb=short",
+      "serve":     "uvicorn app.main:app --reload"
+    },
+    "frameworks": {
+      "fastapi":  { "test": "pytest --tb=short" },
+      "django":   { "test": "python manage.py test", "migrate": "python manage.py migrate" },
+      "flask":    { "test": "pytest --tb=short" },
+      "scripts":  { "test": "pytest --tb=short" }
+    },
+    "_runOrder": ["typecheck", "lint", "test"]
+  },
+
+  "nodejs": {
+    "_default": {
+      "typecheck": "bun run typecheck",
+      "lint":      "bun run lint",
+      "format":    "bun run format",
+      "test":      "bun run test",
+      "build":     "bun run build",
+      "serve":     "bun run dev"
+    },
+    "frameworks": {
+      "nextjs": {
+        "_extra": [
+          { "name": "RouteSlugs",   "command": "node scripts/check-route-slugs.mjs",   "order": 4, "required": true,  "why": "next build does not catch dynamic-route slug mismatch" },
+          { "name": "BuildScripts", "command": "node scripts/check-build-scripts.mjs", "order": 5, "required": true,  "why": "Vercel/Docker strip devDeps; scripts.build calling tsx/ts-node/vitest crash exit 127" }
+        ]
+      },
+      "nuxt":     { "build": "bun run build" },
+      "astro":    { "build": "bun run build" },
+      "express":  { "test": "bun run test" },
+      "fastify":  { "test": "bun run test" },
+      "vanilla":  { "test": "bun run test" }
+    },
+    "_runOrder": ["typecheck", "lint", "test", "_extra", "build"]
+  },
+
+  "php": {
+    "_default": {
+      "static":    "vendor/bin/phpstan analyse --level=6",
+      "test":      "vendor/bin/phpunit",
+      "format":    "vendor/bin/php-cs-fixer fix",
+      "serve":     "php artisan serve"
+    },
+    "frameworks": {
+      "laravel-octane": {
+        "serve": "php artisan octane:start --watch",
+        "_extraIfFrontend": ["typecheck", "lint", "viteManifest"]
+      },
+      "laravel":        { "_extraIfFrontend": ["typecheck", "lint", "viteManifest"] }
+    },
+    "_frontendChecks": {
+      "typecheck":    "npx tsc --noEmit",
+      "lint":         "npx eslint resources/js/",
+      "viteManifest": "node scripts/check-vite-manifest.mjs"
+    },
+    "_runOrder": ["static", "test", "typecheck", "lint", "viteManifest"]
+  }
+}
 ```
 
-Execution order (each step blocks the next):
+### How to read this fallback
+
+- `_default` — commands that always apply within the stack.
+- `frameworks.<framework>` — overrides or extras gated by `framework` in `active-project.json`.
+- `_extra` — additional gates with explicit `order` (PHP/Next.js use this for stack-specific static checks like vite-manifest, route-slugs, build-scripts).
+- `_runOrder` — order to chain when no `qualityGates` is available.
 
-| # | Gate | Typical commands |
-|---|---|---|
-| 1 | **Typecheck** | `npx tsc --noEmit` · `mypy .` · `vendor/bin/phpstan analyse` |
-| 2 | **Lint** | `npx eslint .` · `ruff check .` · `vendor/bin/pint --test` |
-| 3 | **Unit tests** | `npx vitest run` · `pytest` · `vendor/bin/phpunit` |
-| 4 | **E2E** (only if configured) | `npx playwright test` |
-| 5 | **Build** | `npm run build` · `composer dump-autoload --optimize` |
+If `.claude/config/active-project.json#qualityGates` is missing, **do not silently fall back** — instead:
+
+1. Print a warning: `WARN: active-project.json#qualityGates missing — using fallback for stack=<X>, framework=<Y>`.
+2. Run the fallback in `_runOrder`.
+3. Recommend the user re-run `npx start-vibing-stacks` (or `migrate --apply`) to repair the config.
+
+---
 
-Output format (one line per gate):
+## Output format
 
 ```
 typecheck: PASS  (1.4s)
@@ -34,4 +119,4 @@ build:     PASS  (3.1s)
 ✅ All gates passed — safe to invoke commit-manager
 ```
 
-If any gate fails, print the failure output and exit non-zero. `commit-manager` will refuse to commit while validation is failing.
+If any required gate fails, print its full output and exit non-zero. Optional gates (`required: false`) print a warning but do not block.