mustard-claude 3.1.4 → 3.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustard-claude",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Framework-agnostic CLI for Claude Code project setup",
   "type": "module",
   "bin": {

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

@@ -140,9 +140,13 @@ Never search in:
 - `node_modules/`, `.next/`, `bin/`, `obj/`, `dist/`, `migrations/`
 ```
 
-**`.claude/entity-registry.json`** — empty skeleton:
+**`.claude/entity-registry.json`** — generate via registry scanner:
+```bash
+node .claude/scripts/sync-registry.js --force
+```
+If `sync-registry.js` fails or is not available, create empty skeleton:
 ```json
-{ "_patterns": {}, "_enums": {}, "e": {} }
+{ "_meta": { "version": "4.0" }, "_patterns": {}, "_enums": {}, "e": {} }
 ```
 
 **`{subproject}/CLAUDE.md`** — per subproject (skip if exists):
@@ -310,6 +314,31 @@ See `scan-format.md` §10 for decomposition rules, SKILL.md format, and descript
 Skills are generated ONLY in `{subproject}/.claude/skills/{skill-name}/` (NOT in root `.claude/skills/`).
 Mark all with `<!-- mustard:generated -->`. Overwrite on next scan.
 
+### 4.7. Generate Pattern Skills from Registry (OODA: Observe → Act)
+
+After agent-generated skills (4.6), run the registry-based skill generator to create structural pattern skills from `_patterns`:
+
+```bash
+node .claude/scripts/sync-registry.js --force
+node .claude/scripts/skill-generator.js --force
+```
+
+This generates skills that the agents in Step 3 may have missed — particularly:
+- `{role}-entity-creation` — entity folder, base class, interfaces, namespace
+- `{role}-enum-placement` — enum folder, decorators, NEVER inline in entities
+- `{role}-route-conventions` — route naming, auth pattern, CRUD standard
+- `{role}-service-pattern` — interface-first, base interface, DI
+- `{role}-repository-pattern` — base class, interface, DI
+- `{role}-dto-conventions` — folder, naming, validation pattern
+- `{role}-module-registration` — DI registration, route wiring
+
+These skills are derived from **detected patterns** (not hardcoded). They complement agent-generated skills by covering structural conventions that agents may not explicitly document.
+
+**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)
+
 ### 4. Update CLAUDE.md files
 
 After agents complete:
@@ -358,8 +387,9 @@ Include findings in scan output under a `## Security` section:
 5. Old files backed up in `_backup/`
 6. Each subproject's CLAUDE.md has `## Scan References`
 7. Root CLAUDE.md has `## Project Structure` with all subprojects
-8. `.claude/entity-registry.json` exists
-9. Each generated skill has valid YAML frontmatter (name + description)
+8. `.claude/entity-registry.json` exists and is v4.0
+9. Pattern skills generated from registry (entity-creation, enum-placement, route-conventions, etc.)
+10. Each generated skill has valid YAML frontmatter (name + description)
 10. Each skill's description is "pushy" — includes casual trigger phrases
 11. If security scan ran: findings summarized in `## Security` section of output
 

package/templates/scripts/registry/file-utils.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * file-utils.js
+ *
+ * Single Responsibility: file collection and path helpers shared across scanners.
+ * No scanning logic, no schema building — only filesystem utilities.
+ *
+ * Usage:
+ *   const { collectFiles, relativePath, readFileSafe } = require('./registry/file-utils');
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_IGNORE = [
+  'node_modules', 'bin', 'obj', 'dist', '.next',
+  '__pycache__', '.venv', 'venv', 'target', 'build',
+  '.git', 'migrations', 'Migrations',
+];
+
+// ---------------------------------------------------------------------------
+// collectFiles
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively collect all files with the given extension under a directory.
+ * Skips DEFAULT_IGNORE directories, dot-directories, and any extra ignore dirs.
+ *
+ * @param {string} dir - root directory to walk
+ * @param {string} extension - file extension including dot, e.g. '.cs', '.ts'
+ * @param {string[]} [ignore] - additional directory names to skip
+ * @returns {string[]} - absolute file paths
+ */
+function collectFiles(dir, extension, ignore = []) {
+  const allIgnore = new Set([...DEFAULT_IGNORE, ...ignore]);
+  const results = [];
+
+  function walk(currentDir) {
+    try {
+      const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (allIgnore.has(entry.name) || entry.name.startsWith('.')) continue;
+          walk(path.join(currentDir, entry.name));
+        } else if (entry.name.endsWith(extension)) {
+          results.push(path.join(currentDir, entry.name));
+        }
+      }
+    } catch { /* ignore permission errors */ }
+  }
+
+  walk(dir);
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// relativePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a relative path from a base directory, normalised with forward slashes.
+ *
+ * @param {string} base - absolute base directory
+ * @param {string} filePath - absolute file path
+ * @returns {string} - relative path with forward slashes
+ */
+function relativePath(base, filePath) {
+  return path.relative(base, filePath).replace(/\\/g, '/');
+}
+
+// ---------------------------------------------------------------------------
+// readFileSafe
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a file as UTF-8 string. Returns null on any error.
+ *
+ * @param {string} filePath - absolute path to file
+ * @returns {string|null}
+ */
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// inferCommonFolder
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the most common parent folder from a list of relative file paths.
+ * Useful for pattern inference (e.g., "most entities live in Domain/Entities/").
+ *
+ * @param {string[]} filePaths - relative paths (forward slashes)
+ * @returns {string|null} - most common parent folder with trailing slash, or null
+ */
+function inferCommonFolder(filePaths) {
+  if (!filePaths.length) return null;
+
+  const counts = new Map();
+  for (const fp of filePaths) {
+    const dir = path.dirname(fp).replace(/\\/g, '/');
+    counts.set(dir, (counts.get(dir) || 0) + 1);
+  }
+
+  let maxDir = null;
+  let maxCount = 0;
+  for (const [dir, count] of counts) {
+    if (count > maxCount) {
+      maxDir = dir;
+      maxCount = count;
+    }
+  }
+
+  return maxDir ? maxDir + '/' : null;
+}
+
+module.exports = { collectFiles, relativePath, readFileSafe, inferCommonFolder, DEFAULT_IGNORE };

package/templates/scripts/registry/pluralize.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * pluralize.js
+ *
+ * Single Responsibility: English pluralization helpers for converting
+ * snake_case plural database table names to PascalCase singular entity names.
+ *
+ * Previously inlined in sync-registry.js. Extracted here so scanners can
+ * reuse without depending on the top-level CLI script.
+ *
+ * Usage:
+ *   const { snakeToPascalSingular, singularize, snakeToPascal } = require('./registry/pluralize');
+ */
+
+// ---------------------------------------------------------------------------
+// IRREGULAR_PLURALS
+// ---------------------------------------------------------------------------
+
+/**
+ * Lookup for common irregular plurals.
+ * Key: lowercase plural form (snake_case table name or single word)
+ * Value: PascalCase singular entity name
+ */
+const IRREGULAR_PLURALS = {
+  people: 'Person',
+  children: 'Child',
+  men: 'Man',
+  women: 'Woman',
+  mice: 'Mouse',
+  geese: 'Goose',
+  teeth: 'Tooth',
+  feet: 'Foot',
+  data: 'Datum',
+  indices: 'Index',
+  matrices: 'Matrix',
+  vertices: 'Vertex',
+  analyses: 'Analysis',
+  bases: 'Base',
+  crises: 'Crisis',
+  diagnoses: 'Diagnosis',
+  hypotheses: 'Hypothesis',
+  parentheses: 'Parenthesis',
+  theses: 'Thesis',
+  criteria: 'Criterion',
+  phenomena: 'Phenomenon',
+  media: 'Medium',
+  statuses: 'Status',
+  addresses: 'Address',
+};
+
+// ---------------------------------------------------------------------------
+// singularize
+// ---------------------------------------------------------------------------
+
+/**
+ * Singularize a single lowercase English word using simple heuristics.
+ *
+ * Examples:
+ *   companies -> company
+ *   addresses -> address
+ *   boxes     -> box
+ *   contracts -> contract
+ *   queue     -> queue  (already singular)
+ *
+ * @param {string} word - lowercase word
+ * @returns {string} - singular form (lowercase)
+ */
+function singularize(word) {
+  // Check irregular
+  if (IRREGULAR_PLURALS[word]) {
+    return IRREGULAR_PLURALS[word].toLowerCase();
+  }
+
+  // Already-singular indicators
+  if (
+    word.endsWith('ss') ||
+    word.endsWith('us') ||
+    word.endsWith('is') ||
+    word === 'queue'
+  ) {
+    return word;
+  }
+
+  // -ies -> -y (companies -> company, categories -> category)
+  if (word.endsWith('ies')) {
+    return word.slice(0, -3) + 'y';
+  }
+
+  // -sses -> -ss (addresses -> address)
+  if (word.endsWith('sses')) {
+    return word.slice(0, -2);
+  }
+
+  // -es after sh, ch, x, z -> remove -es (boxes -> box, churches -> church)
+  if (
+    word.endsWith('shes') ||
+    word.endsWith('ches') ||
+    word.endsWith('xes') ||
+    word.endsWith('zes')
+  ) {
+    return word.slice(0, -2);
+  }
+
+  // Generic -s removal (contracts -> contract)
+  if (word.endsWith('s') && !word.endsWith('ss')) {
+    return word.slice(0, -1);
+  }
+
+  return word;
+}
+
+// ---------------------------------------------------------------------------
+// snakeToPascalSingular
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a snake_case plural table name to PascalCase singular entity name.
+ *
+ * Examples:
+ *   contracts          -> Contract
+ *   partner_types      -> PartnerType
+ *   people             -> Person
+ *   companies          -> Company
+ *   product_categories -> ProductCategory
+ *   email_queue        -> EmailQueue  (already singular)
+ *
+ * @param {string} snakePlural - snake_case plural name (e.g., 'partner_types')
+ * @returns {string} - PascalCase singular entity name
+ */
+function snakeToPascalSingular(snakePlural) {
+  // Check irregular lookup for the full compound name
+  if (IRREGULAR_PLURALS[snakePlural]) {
+    return IRREGULAR_PLURALS[snakePlural];
+  }
+
+  // Split by underscore; singularize only the LAST part (the noun)
+  const parts = snakePlural.split('_');
+  const result = parts.map((part, idx) => {
+    const word = idx === parts.length - 1 ? singularize(part) : part;
+    return word.charAt(0).toUpperCase() + word.slice(1);
+  });
+
+  return result.join('');
+}
+
+// ---------------------------------------------------------------------------
+// snakeToPascal
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a snake_case name to PascalCase (no singularization).
+ *
+ * Example:
+ *   contract_status -> ContractStatus
+ *
+ * @param {string} snakeName
+ * @returns {string}
+ */
+function snakeToPascal(snakeName) {
+  return snakeName
+    .split('_')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+module.exports = { snakeToPascalSingular, singularize, snakeToPascal, IRREGULAR_PLURALS };

package/templates/scripts/registry/scanner-contract.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * scanner-contract.js
+ *
+ * Base contract for all stack scanners (Interface Segregation + Liskov Substitution).
+ * Every scanner extends ScannerContract and implements detect() and optionally
+ * the scan* methods. Each method has a single responsibility.
+ *
+ * Usage:
+ *   const { ScannerContract } = require('./scanner-contract');
+ *   class MyScanner extends ScannerContract { ... }
+ */
+
+// ---------------------------------------------------------------------------
+// JSDoc typedefs
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} EntityInfo
+ * @property {string} file - relative path from subproject root
+ * @property {string} [namespace]
+ * @property {string} [baseClass]
+ * @property {string[]} [interfaces]
+ * @property {string[]} [decorators] - class-level decorators/attributes
+ * @property {string[]} [refs] - referenced entities (FK/navigation)
+ * @property {string[]} [sub] - child/collection entities
+ * @property {string[]} [enums] - enum types used
+ * @property {string[]} [properties] - key property names with types
+ */
+
+/**
+ * @typedef {Object} EnumInfo
+ * @property {string[]} values
+ * @property {string} file - relative path
+ * @property {string} [namespace]
+ * @property {string[]} [decorators] - enum-level decorators
+ * @property {string[]} [valueDecorators] - decorators found on values (e.g., Description, Display)
+ * @property {string} [valueConvention] - UPPER_CASE | PascalCase | camelCase
+ */
+
+/**
+ * @typedef {Object} InterfaceInfo
+ * @property {string} file
+ * @property {string} [namespace]
+ * @property {string[]} [methods]
+ * @property {string[]} [extends] - parent interfaces
+ * @property {string[]} [implementedBy] - known implementing classes
+ */
+
+/**
+ * @typedef {Object} RouteInfo
+ * @property {string} file
+ * @property {string} prefix - route group prefix (e.g., /contracts)
+ * @property {Object[]} endpoints - { method, path, name, auth }
+ */
+
+/**
+ * @typedef {Object} DtoInfo
+ * @property {string} file
+ * @property {string} [namespace]
+ * @property {string} [entity] - linked entity name
+ * @property {string} [validationPattern] - FluentValidation, Zod, class-validator, etc.
+ */
+
+/**
+ * @typedef {Object} ServiceInfo
+ * @property {string} file
+ * @property {string} [interface] - interface it implements
+ * @property {string} [entity] - linked entity name
+ * @property {string[]} [dependencies] - injected interfaces
+ */
+
+/**
+ * @typedef {Object} RepoInfo
+ * @property {string} file
+ * @property {string} [interface]
+ * @property {string} [entity]
+ * @property {string} [baseClass]
+ */
+
+// ---------------------------------------------------------------------------
+// ScannerContract
+// ---------------------------------------------------------------------------
+
+/**
+ * Base contract for stack scanners (Interface Segregation + Liskov Substitution).
+ * Every scanner implements detect() and scan(). Each method has a single responsibility.
+ */
+class ScannerContract {
+  /**
+   * @param {string} subprojectPath - absolute path to subproject root
+   * @param {Object} subprojectMeta - metadata from sync-detect.js output
+   */
+  constructor(subprojectPath, subprojectMeta) {
+    if (new.target === ScannerContract) {
+      throw new Error('ScannerContract is abstract — extend it');
+    }
+    this.subprojectPath = subprojectPath;
+    this.meta = subprojectMeta;
+  }
+
+  /**
+   * Detect if this scanner applies to the subproject.
+   * @returns {boolean}
+   */
+  detect() { throw new Error('detect() not implemented'); }
+
+  /**
+   * Detect the architecture pattern used in the project.
+   * @returns {string} - e.g., 'solid', 'layered', 'minimal', 'mvvm', 'mvc'
+   */
+  detectArchitecture() { return 'unknown'; }
+
+  /**
+   * Scan entities (models, domain objects).
+   * @returns {Map<string, EntityInfo>}
+   */
+  scanEntities() { return new Map(); }
+
+  /**
+   * Scan enums/value types.
+   * @returns {Map<string, EnumInfo>}
+   */
+  scanEnums() { return new Map(); }
+
+  /**
+   * Scan interfaces/contracts.
+   * @returns {Map<string, InterfaceInfo>}
+   */
+  scanInterfaces() { return new Map(); }
+
+  /**
+   * Scan routes/endpoints.
+   * @returns {Map<string, RouteInfo>}
+   */
+  scanRoutes() { return new Map(); }
+
+  /**
+   * Scan DTOs/schemas/view models.
+   * @returns {Map<string, DtoInfo>}
+   */
+  scanDtos() { return new Map(); }
+
+  /**
+   * Scan services.
+   * @returns {Map<string, ServiceInfo>}
+   */
+  scanServices() { return new Map(); }
+
+  /**
+   * Scan repositories.
+   * @returns {Map<string, RepoInfo>}
+   */
+  scanRepositories() { return new Map(); }
+
+  /**
+   * Infer structural patterns from all scanned data.
+   * Called AFTER all scan methods. Receives the results.
+   * @param {{ entities: Map, enums: Map, interfaces: Map, routes: Map, dtos: Map, services: Map, repositories: Map }} scanResults
+   * @returns {Object} - patterns object for _patterns.{stack}
+   */
+  inferPatterns(scanResults) { return {}; } // eslint-disable-line no-unused-vars
+
+  /**
+   * Run the full scan pipeline.
+   * Calls all scan* methods in order, then inferPatterns, then returns the combined result.
+   * @returns {{ entities: Map, enums: Map, interfaces: Map, routes: Map, dtos: Map, services: Map, repositories: Map, patterns: Object }}
+   */
+  scan() {
+    const entities = this.scanEntities();
+    const enums = this.scanEnums();
+    const interfaces = this.scanInterfaces();
+    const routes = this.scanRoutes();
+    const dtos = this.scanDtos();
+    const services = this.scanServices();
+    const repositories = this.scanRepositories();
+    const architecture = this.detectArchitecture();
+
+    const scanResults = { entities, enums, interfaces, routes, dtos, services, repositories };
+    const patterns = this.inferPatterns(scanResults);
+    patterns.architecture = architecture;
+
+    return { ...scanResults, patterns };
+  }
+}
+
+module.exports = { ScannerContract };

package/templates/scripts/registry/scanner-loader.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * scanner-loader.js
+ *
+ * Dependency Inversion: sync-registry.js depends on this loader, not on concrete scanners.
+ * Open/Closed: adding a new stack scanner = dropping a new file in scanners/, zero other changes.
+ *
+ * Usage:
+ *   const { loadScanner, detectStack } = require('./registry/scanner-loader');
+ *   const scanner = loadScanner(subprojectPath, subprojectMeta);
+ *   if (scanner) { const result = scanner.scan(); }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCANNERS_DIR = path.join(__dirname, 'scanners');
+
+// ---------------------------------------------------------------------------
+// Stack detection signals
+// Each key is the stack ID that maps to a scanner file: {stackId}-scanner.js
+// ---------------------------------------------------------------------------
+
+const STACK_SIGNALS = {
+  dotnet: { files: ['*.csproj', '*.sln'], dirs: [] },
+  typescript: { files: ['package.json', 'tsconfig.json'], dirs: [] },
+  dart: { files: ['pubspec.yaml'], dirs: ['lib'] },
+  php: { files: ['composer.json', 'artisan'], dirs: [] },
+  python: { files: ['pyproject.toml', 'setup.py', 'requirements.txt', 'manage.py'], dirs: [] },
+  java: { files: ['pom.xml', 'build.gradle', 'build.gradle.kts'], dirs: [] },
+  go: { files: ['go.mod'], dirs: [] },
+  rust: { files: ['Cargo.toml'], dirs: [] },
+};
+
+// ---------------------------------------------------------------------------
+// detectStack
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect which stack a subproject uses via file-presence heuristics.
+ * Iterates STACK_SIGNALS in definition order (most specific first).
+ *
+ * @param {string} subprojectPath - absolute path to subproject root
+ * @returns {string|null} - stack ID (e.g., 'dotnet') or null if unrecognised
+ */
+function detectStack(subprojectPath) {
+  for (const [stackId, signals] of Object.entries(STACK_SIGNALS)) {
+    for (const pattern of signals.files) {
+      // Handle glob-like patterns (*.ext) — match any file with that extension
+      if (pattern.startsWith('*')) {
+        const ext = pattern.slice(1); // e.g., '.csproj'
+        try {
+          const entries = fs.readdirSync(subprojectPath);
+          if (entries.some(e => e.endsWith(ext))) return stackId;
+        } catch { /* ignore unreadable dirs */ }
+      } else {
+        if (fs.existsSync(path.join(subprojectPath, pattern))) return stackId;
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// loadScanner
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the appropriate scanner class for a subproject and return an instance,
+ * or null if no scanner is available or detect() returns false.
+ *
+ * Resolution order:
+ *   1. Use subprojectMeta.stack if provided
+ *   2. Fall back to detectStack()
+ *   3. Look for scanners/{stackId}-scanner.js
+ *   4. Instantiate and call detect() — return null if detect() is false
+ *
+ * @param {string} subprojectPath - absolute path to subproject root
+ * @param {Object} subprojectMeta - metadata from sync-detect.js output
+ * @returns {import('./scanner-contract').ScannerContract|null}
+ */
+function loadScanner(subprojectPath, subprojectMeta) {
+  const stackId = subprojectMeta.stack || detectStack(subprojectPath);
+  if (!stackId) return null;
+
+  const scannerFile = path.join(SCANNERS_DIR, `${stackId}-scanner.js`);
+  if (!fs.existsSync(scannerFile)) return null;
+
+  try {
+    const ScannerClass = require(scannerFile);
+    const scanner = new ScannerClass(subprojectPath, subprojectMeta);
+    if (scanner.detect()) return scanner;
+  } catch (err) {
+    process.stderr.write(`[scanner-loader] Failed to load ${stackId} scanner: ${err.message}\n`);
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// listAvailableScanners
+// ---------------------------------------------------------------------------
+
+/**
+ * List all scanner files currently present in the scanners/ directory.
+ * Useful for diagnostics and --list-scanners flag.
+ * @returns {string[]} - array of stack IDs with scanners installed
+ */
+function listAvailableScanners() {
+  try {
+    return fs.readdirSync(SCANNERS_DIR)
+      .filter(f => f.endsWith('-scanner.js'))
+      .map(f => f.replace('-scanner.js', ''));
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { detectStack, loadScanner, listAvailableScanners, STACK_SIGNALS };