mustard-claude 3.1.24 → 3.1.26

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "mustard-claude",
-  "version": "3.1.24",
-  "description": "Framework-agnostic CLI for Claude Code project setup",
-  "type": "module",
-  "bin": {
-    "mustard": "./bin/mustard.js"
-  },
-  "main": "dist/cli.js",
-  "types": "dist/cli.d.ts",
-  "files": [
-    "bin/",
-    "dist/",
-    "templates/"
-  ],
-  "keywords": [
-    "claude",
-    "claude-code",
-    "ai",
-    "cli",
-    "scaffold"
-  ],
-  "author": "rubensrpj",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rubensrpj/mustard.git"
-  },
-  "homepage": "https://github.com/rubensrpj/mustard#readme",
-  "bugs": {
-    "url": "https://github.com/rubensrpj/mustard/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "inquirer": "^9.2.15",
-    "ora": "^8.0.1"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@types/inquirer": "^9.0.9",
-    "@types/node": "^25.2.1",
-    "rimraf": "^6.1.2",
-    "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "start": "node bin/mustard.js",
-    "build": "tsc",
-    "clean": "rimraf dist",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test",
-    "release": "npm version patch && npm run build && npm publish"
-  }
-}
+{
+  "name": "mustard-claude",
+  "version": "3.1.26",
+  "description": "Framework-agnostic CLI for Claude Code project setup",
+  "type": "module",
+  "bin": {
+    "mustard": "./bin/mustard.js"
+  },
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "start": "node bin/mustard.js",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "release": "npm version patch && npm run build && npm publish"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "cli",
+    "scaffold"
+  ],
+  "author": "rubensrpj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rubensrpj/mustard.git"
+  },
+  "homepage": "https://github.com/rubensrpj/mustard#readme",
+  "bugs": {
+    "url": "https://github.com/rubensrpj/mustard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^25.2.1",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/CLAUDE.md

@@ -46,6 +46,10 @@ node scripts/sync-detect.js --no-cache
 # Entity registry generation
 node scripts/sync-registry.js
 node scripts/sync-registry.js --force
+
+# Skill validation (runs automatically at end of skill-generator.js; also callable standalone)
+node scripts/skill-validate.js
+node scripts/skill-validate.js --json
 ```
 
 ## Guards

package/templates/commands/mustard/scan/SKILL.md

@@ -4,7 +4,16 @@
 
 ## Trigger
 
-`/scan` or `/scan <subproject>`
+`/scan`, `/scan <subproject>`, `/scan --force`, `/scan <subproject> --force`
+
+## Flags
+
+- `--force` — descarta tudo o que é `<!-- mustard:generated -->` e regera do zero. Semântica:
+  - Ignora o incremental skip do Step 1/C: **todos** os subprojetos são reprocessados, independente de hash match ou `gitDirty`.
+  - Bypassa o fast-path de §2.6 (Bootstrap): sempre regenera `.claude/CLAUDE.md` e afins.
+  - Repassa "FORCE MODE" aos Task agents do Step 3 (eles apagam `{subproject}/.claude/skills/*/` com header `mustard:generated` antes de regerar).
+  - Roda sempre os dois comandos de §4.7 (`sync-registry.js --force` + `skill-generator.js --force`), mesmo com registry já v4.0.
+  - Skills sem o header `mustard:generated` (user-authored) são **preservadas**.
 
 ## Execution Model
 
@@ -49,6 +58,7 @@ Parse JSON output → list of `{ name, path, role, agent, stackSummary, gitDirty
 4. **Hash mismatch OR gitDirty** → include in agent launch list (dirty files indicate changes the previous scan may not have captured)
 5. If ALL subprojects can be skipped → skip to step 4 (Update CLAUDE.md) + step 5 (Compile) directly
 6. **No old cache** → scan ALL subprojects (first run)
+7. **`--force` ativo** → ignore tudo acima: marque **todos** os subprojetos como `needs-rescan`, não compare hashes, não pule nada.
 
 **Module-level incremental** (when subproject hash changed):
 - Compare `moduleHashes[subproject][module]` with cached values
@@ -98,7 +108,7 @@ If `.claude/docs/` exists and contains `.md` files:
 
 ### 2.6. Bootstrap (if needed)
 
-**Fast-path**: If root `CLAUDE.md` exists AND `.claude/entity-registry.json` exists → skip to step 3 (Launch Agents).
+**Fast-path**: If root `CLAUDE.md` exists AND `.claude/entity-registry.json` exists AND `--force` is **not** active → skip to step 3 (Launch Agents).
 Bootstrap only runs on first scan or when foundational files are missing.
 
 Otherwise create foundational files:
@@ -202,6 +212,12 @@ Path: {path}
 Role: {role}
 Stack: {stackSummary}
 
+FORCE MODE (only when /scan was invoked with --force):
+- Before generating skills, scan {path}/.claude/skills/ and delete every subdirectory
+  whose SKILL.md contains "<!-- mustard:generated" (preserve user-authored skills that
+  lack that marker).
+- Also delete any pre-existing _backup/ under {path}/.claude/commands/ to avoid stacking stale backups.
+
 Tasks:
 1. Read existing knowledge from {path}/.claude/commands/ and {path}/CLAUDE.md
 2. Backup generated files to {path}/.claude/commands/_backup/
@@ -330,6 +346,8 @@ Mark all with `<!-- mustard:generated -->`. Overwrite on next scan.
 
 After agent-generated skills (4.6), run the registry-based skill generator to create structural pattern skills from `_patterns`:
 
+> With `--force`, **always** run both commands — even if `entity-registry.json` already exists at v4.0.
+
 ```bash
 node .claude/scripts/sync-registry.js --force
 node .claude/scripts/skill-generator.js --force
@@ -349,7 +367,7 @@ These skills are derived from **detected patterns** (not hardcoded). They comple
 **Skip conditions:**
 - `entity-registry.json` version < 4.0 → skip (registry not populated)
 - `skill-generator.js` not present → skip
-- Pattern skill already exists and was NOT generated by mustard → skip (user-edited)
+- Pattern skill already exists and was NOT generated by mustard → skip (user-edited, unless `--force` — but `skill-generator.js` already preserves user-authored skills by checking the `mustard:generated` header)
 
 ### 4. Update CLAUDE.md files
 

package/templates/scripts/_fence-languages.json

@@ -0,0 +1,57 @@
+{
+  ".cs":    "csharp",
+  ".ts":    "typescript",
+  ".tsx":   "typescript",
+  ".js":    "javascript",
+  ".jsx":   "javascript",
+  ".mjs":   "javascript",
+  ".dart":  "dart",
+  ".py":    "python",
+  ".java":  "java",
+  ".go":    "go",
+  ".rs":    "rust",
+  ".rb":    "ruby",
+  ".php":   "php",
+  ".kt":    "kotlin",
+  ".kts":   "kotlin",
+  ".ex":    "elixir",
+  ".exs":   "elixir",
+  ".swift": "swift",
+  ".elm":   "elm",
+  ".zig":   "zig",
+  ".cr":    "crystal",
+  ".gleam": "gleam",
+  ".erl":   "erlang",
+  ".hrl":   "erlang",
+  ".scala": "scala",
+  ".clj":   "clojure",
+  ".cljs":  "clojure",
+  ".hs":    "haskell",
+  ".ml":    "ocaml",
+  ".mli":   "ocaml",
+  ".lua":   "lua",
+  ".nim":   "nim",
+  ".v":     "v",
+  ".rkt":   "racket",
+  ".jl":    "julia",
+  ".r":     "r",
+  ".R":     "r",
+  ".sh":    "bash",
+  ".bash":  "bash",
+  ".zsh":   "bash",
+  ".ps1":   "powershell",
+  ".sql":   "sql",
+  ".proto": "protobuf",
+  ".tf":    "terraform",
+  ".yaml":  "yaml",
+  ".yml":   "yaml",
+  ".toml":  "toml",
+  ".json":  "json",
+  ".xml":   "xml",
+  ".html":  "html",
+  ".css":   "css",
+  ".scss":  "scss",
+  ".sass":  "sass",
+  ".vue":   "vue",
+  ".svelte":"svelte"
+}

package/templates/scripts/_skill-meta.json

@@ -1,16 +1,4 @@
 {
-  "stacks": {
-    "dotnet":     { "lang": "csharp",     "label": ".NET",               "signals": { "exts": [".csproj", ".sln"], "files": [] } },
-    "typescript": { "lang": "typescript", "label": "TypeScript/Node.js", "signals": { "exts": [],                  "files": ["package.json", "tsconfig.json"] } },
-    "dart":       { "lang": "dart",       "label": "Flutter/Dart",       "signals": { "exts": [],                  "files": ["pubspec.yaml"] } },
-    "php":        { "lang": "php",        "label": "Laravel/PHP",        "signals": { "exts": [],                  "files": ["composer.json", "artisan"] } },
-    "python":     { "lang": "python",     "label": "Python",             "signals": { "exts": [],                  "files": ["pyproject.toml", "manage.py", "setup.py", "requirements.txt"] } },
-    "java":       { "lang": "java",       "label": "Spring/Java",        "signals": { "exts": [],                  "files": ["pom.xml", "build.gradle", "build.gradle.kts"] } },
-    "go":         { "lang": "go",         "label": "Go",                 "signals": { "exts": [],                  "files": ["go.mod"] } },
-    "rust":       { "lang": "rust",       "label": "Rust",               "signals": { "exts": [],                  "files": ["Cargo.toml"] } },
-    "kotlin":     { "lang": "kotlin",     "label": "Kotlin/JVM",         "signals": { "exts": [".kt"],             "files": ["build.gradle.kts"] } },
-    "elixir":     { "lang": "elixir",     "label": "Elixir/Phoenix",     "signals": { "exts": [".ex", ".exs"],     "files": ["mix.exs"] } }
-  },
   "roles": {
     "api":      "backend",
     "ui":       "frontend",

package/templates/scripts/migrate-skill-paths.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * migrate-skill-paths.js
+ *
+ * One-shot migration helper for target projects that still have role-prefixed
+ * pattern skills (`frontend-*`, `backend-*`, `general-*`, plus any other agent
+ * prefix from `.claude/.detect-cache.json`) duplicated inside each
+ * `{subproject}/.claude/skills/`. Moves them to ROOT `{project}/.claude/skills/`
+ * (the current output location of `skill-generator.js`) and deletes the
+ * now-empty copies.
+ *
+ * SAFE BY DEFAULT: runs in dry-run unless `--apply` is passed.
+ *
+ * Usage (inside a Mustard-initialized project, NOT Mustard itself):
+ *   node .claude/scripts/migrate-skill-paths.js             # dry-run, prints plan
+ *   node .claude/scripts/migrate-skill-paths.js --apply     # actually move files
+ *
+ * Algorithm:
+ *   1. Read `.claude/.detect-cache.json` → list of subprojects & their agent prefixes.
+ *   2. For each subproject, scan `{sub}/.claude/skills/` for folders whose name
+ *      begins with one of the known agent prefixes (frontend-, backend-, general-,
+ *      api-, app-, database-, mobile-, …) — those are role skills in the wrong place.
+ *   3. For each such folder:
+ *        a. If ROOT/.claude/skills/{folder} already exists with identical content
+ *           → just delete the duplicate.
+ *        b. If ROOT missing or different → move the folder to ROOT (prefer the
+ *           freshest mtime if there is already one at ROOT).
+ *   4. Log every action. On --apply, perform the FS changes; otherwise just log.
+ *
+ * Non-goals:
+ *   - Does NOT touch subproject-short prefixed skills (e.g. `admin-auth-guard`,
+ *     `api-endpoint-wiring`) — those belong in their subproject.
+ *   - Does NOT run skill-generator.js — user does that separately post-migration.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const APPLY = args.includes('--apply');
+const TARGET_ROOT = (() => {
+  const idx = args.indexOf('--root');
+  if (idx !== -1 && args[idx + 1]) return path.resolve(args[idx + 1]);
+  return process.cwd();
+})();
+
+const DETECT_CACHE = path.join(TARGET_ROOT, '.claude', '.detect-cache.json');
+const ROOT_SKILLS = path.join(TARGET_ROOT, '.claude', 'skills');
+
+function readJsonSafe(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+function hasSameContent(a, b) {
+  try {
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch { return false; }
+}
+
+function folderChecksum(dir) {
+  // Cheap signature: sorted list of relative paths + SKILL.md first-300 bytes.
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .flatMap(e => e.isDirectory()
+        ? fs.readdirSync(path.join(dir, e.name), { withFileTypes: true }).map(f => `${e.name}/${f.name}`)
+        : [e.name]
+      ).sort().join('|');
+    const skillMd = path.join(dir, 'SKILL.md');
+    const head = fs.existsSync(skillMd) ? fs.readFileSync(skillMd).slice(0, 300).toString('utf-8') : '';
+    return `${entries}\n${head}`;
+  } catch { return ''; }
+}
+
+function main() {
+  const cache = readJsonSafe(DETECT_CACHE);
+  if (!cache) {
+    console.error(`No .detect-cache.json at ${DETECT_CACHE}. Run: node .claude/scripts/sync-detect.js`);
+    process.exit(1);
+  }
+
+  const subs = cache.subprojects || [];
+
+  // A folder is "role-shared" (belongs at ROOT) only if its name prefix matches
+  // THIS subproject's agent and the same agent occurs in 2+ subprojects. Skills
+  // whose prefix is the subproject's unique short-name stay per-subproject.
+  const agentCount = new Map();
+  for (const s of subs) {
+    const a = s.agent || s.role || 'general';
+    agentCount.set(a, (agentCount.get(a) || 0) + 1);
+  }
+
+  const actions = []; // { type, from, to? }
+
+  for (const sub of subs) {
+    const subSkills = path.join(TARGET_ROOT, sub.path, '.claude', 'skills');
+    if (!fs.existsSync(subSkills)) continue;
+    let entries;
+    try { entries = fs.readdirSync(subSkills, { withFileTypes: true }); } catch { continue; }
+
+    const agent = sub.agent || sub.role || 'general';
+    // Only migrate if this agent is shared across subs, OR if the folder name
+    // prefix is a well-known role keyword (frontend/backend/general). A unique
+    // subproject-short prefix (e.g. `admin-auth-guard` when only sialia-admin
+    // exists) stays with the subproject.
+    const wellKnownRole = ['frontend', 'backend', 'general', 'database', 'mobile'].includes(agent);
+    const sharedAgent = (agentCount.get(agent) || 0) > 1;
+    if (!wellKnownRole && !sharedAgent) continue;
+
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const folderName = e.name;
+      // Only match THIS subproject's own agent prefix.
+      if (!folderName.startsWith(agent + '-')) continue;
+
+      const fromDir = path.join(subSkills, folderName);
+      const toDir = path.join(ROOT_SKILLS, folderName);
+
+      if (!fs.existsSync(toDir)) {
+        actions.push({ type: 'move', from: fromDir, to: toDir, sub: sub.name });
+      } else if (folderChecksum(fromDir) === folderChecksum(toDir)) {
+        actions.push({ type: 'delete-dup', from: fromDir, sub: sub.name });
+      } else {
+        actions.push({ type: 'conflict', from: fromDir, to: toDir, sub: sub.name });
+      }
+    }
+  }
+
+  if (!actions.length) {
+    console.log('No role-prefixed skills found in any subproject. Nothing to migrate.');
+    return;
+  }
+
+  console.log(`\nPlanned actions${APPLY ? ' (APPLYING)' : ' (dry-run — pass --apply to execute)'}:\n`);
+  for (const a of actions) {
+    const relFrom = path.relative(TARGET_ROOT, a.from).replace(/\\/g, '/');
+    if (a.type === 'move') {
+      const relTo = path.relative(TARGET_ROOT, a.to).replace(/\\/g, '/');
+      console.log(`  [move]        ${relFrom}  →  ${relTo}`);
+    } else if (a.type === 'delete-dup') {
+      console.log(`  [delete-dup]  ${relFrom}  (identical copy already at ROOT)`);
+    } else {
+      const relTo = path.relative(TARGET_ROOT, a.to).replace(/\\/g, '/');
+      console.log(`  [conflict]    ${relFrom}  (ROOT has different content at ${relTo}) — manual review needed`);
+    }
+  }
+
+  if (!APPLY) {
+    console.log('\n(dry-run — no changes made. Re-run with --apply to execute.)');
+    return;
+  }
+
+  fs.mkdirSync(ROOT_SKILLS, { recursive: true });
+  let ok = 0, failed = 0, skipped = 0;
+  for (const a of actions) {
+    try {
+      if (a.type === 'move') {
+        // Re-check: an earlier action this run may have already placed a
+        // folder at `a.to` (common when 3 subs share the same agent prefix).
+        if (fs.existsSync(a.to)) {
+          if (folderChecksum(a.from) === folderChecksum(a.to)) {
+            fs.rmSync(a.from, { recursive: true, force: true });
+            ok++;
+          } else {
+            console.error(`  CONFLICT at ${a.to} — content differs, leaving ${a.from} in place`);
+            skipped++;
+          }
+        } else {
+          fs.renameSync(a.from, a.to);
+          ok++;
+        }
+      } else if (a.type === 'delete-dup') {
+        fs.rmSync(a.from, { recursive: true, force: true });
+        ok++;
+      } else {
+        skipped++;
+      }
+    } catch (err) {
+      console.error(`  FAILED on ${a.from}: ${err.message}`);
+      failed++;
+    }
+  }
+  console.log(`\nMigration done: ${ok} applied, ${skipped} skipped (conflict), ${failed} failed.`);
+}
+
+try { main(); } catch (err) {
+  console.error(`Fatal: ${err.message}`);
+  process.exit(1);
+}