@polymorphism-tech/morph-spec 4.6.0 → 4.7.1

package/scripts/scan-nextjs.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * scan-nextjs.mjs - CLI scan for Next.js violations.
+ * Usage: node scripts/scan-nextjs.mjs [path] [--json]
+ * Exit: 0=clean, 1=errors, 2=scan failed
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateNextComponent } from '../src/lib/validators/nextjs/next-component-validator.js';
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const pathArg = args.find(a => !a.startsWith('--'));
+const targetPath = pathArg ? resolve(pathArg) : resolve('src');
+
+function checkUseEffectFetch(content, filePath) {
+  const issues = [];
+  if (/useEffect\s*\(\s*(?:async\s+)?\(\s*\)\s*=>/.test(content) && /\bfetch\s*\(/.test(content)) {
+    issues.push({
+      type: 'error',
+      message: "useEffect used for data fetching — use Server Components or TanStack Query (useQuery) instead",
+      suggestion: "Replace with a Server Component fetch or TanStack Query useQuery hook",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+function checkDefaultExport(content, filePath) {
+  const issues = [];
+  const fileName = filePath.split('/').pop() ?? '';
+  const SPECIAL = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx'];
+  if (!SPECIAL.includes(fileName) && /^export\s+default\s+/m.test(content) && fileName.endsWith('.tsx')) {
+    issues.push({
+      type: 'warning',
+      message: `Default export in '${fileName}' — prefer named exports for easier refactoring`,
+      suggestion: "Change to: export function ComponentName() {}",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+function findTsxFiles(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (['node_modules', '.next', 'dist', '.git'].includes(entry.name)) continue;
+    if (entry.isDirectory()) {
+      results.push(...findTsxFiles(fullPath));
+    } else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function main() {
+  if (!existsSync(targetPath)) {
+    const msg = `Error: Path does not exist: ${targetPath}`;
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: msg, exitCode: 2 }));
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  let files;
+  try {
+    files = findTsxFiles(targetPath);
+  } catch (err) {
+    const msg = `Error scanning directory: ${err.message}`;
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: msg, exitCode: 2 }));
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  const normalizedTarget = targetPath.replace(/\\/g, '/');
+
+  const allIssues = [];
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    const normalizedFile = filePath.replace(/\\/g, '/');
+    const relPath = normalizedFile.startsWith(normalizedTarget)
+      ? normalizedFile.slice(normalizedTarget.length).replace(/^\//, '')
+      : normalizedFile;
+
+    const issues = [
+      ...validateNextComponent(content, relPath),
+      ...checkUseEffectFetch(content, relPath),
+      ...checkDefaultExport(content, relPath),
+    ];
+    allIssues.push(...issues);
+  }
+
+  const errors = allIssues.filter(i => i.type === 'error');
+  const warnings = allIssues.filter(i => i.type === 'warning');
+
+  if (jsonMode) {
+    const out = JSON.stringify({
+      files: files.length,
+      issues: allIssues.map(i => ({
+        severity: i.type,
+        message: i.message,
+        file: i.file,
+        line: i.line ?? null,
+        suggestion: i.suggestion ?? null,
+      })),
+      errors: errors.length,
+      warnings: warnings.length,
+      exitCode: errors.length > 0 ? 1 : 0,
+    }, null, 2);
+    process.stdout.write(out + '\n');
+    process.exit(errors.length > 0 ? 1 : 0);
+  }
+
+  const displayPath = targetPath.replace(process.cwd().replace(/\\/g, '/'), '.').replace(/\\/g, '/');
+  console.log(`🔍 Scanning ${displayPath} (${files.length} file${files.length !== 1 ? "s" : ""})...`);
+  console.log("");
+
+  if (allIssues.length === 0) {
+    console.log(`✅ No issues found — ${files.length} file${files.length !== 1 ? "s" : ""} scanned`);
+    console.log(`Summary: ${files.length} files scanned | 0 issues (0 critical, 0 high, 0 medium)`);
+    process.exit(0);
+  }
+
+  if (errors.length > 0) {
+    console.log(`CRITICAL (${errors.length})`);
+    for (const issue of errors) {
+      const loc = issue.line ? `:${issue.line}` : "";
+      console.log(`  ${issue.file}${loc}  — ${issue.message}`);
+      if (issue.suggestion) console.log(`    → ${issue.suggestion}`);
+    }
+    console.log('');
+  }
+
+  if (warnings.length > 0) {
+    console.log(`HIGH/MEDIUM (${warnings.length})`);
+    for (const issue of warnings) {
+      console.log(`  ${issue.file}  — ${issue.message}`);
+    }
+    console.log('');
+  }
+
+  const cleanFiles = files.length - new Set(allIssues.map(i => i.file)).size;
+  if (cleanFiles > 0) {
+    console.log(`✅ No issues found in ${cleanFiles} file${cleanFiles !== 1 ? "s" : ""}`);
+  }
+
+  console.log(`Summary: ${files.length} files scanned | ${allIssues.length} issue${allIssues.length !== 1 ? "s" : ""} (${errors.length} critical, ${warnings.length} high/medium)`);
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();

package/src/commands/project/doctor.js

@@ -411,7 +411,58 @@ export async function doctorCommand(options = {}) {
   // Check agents.json
   const agentsPath = join(morphPath, 'framework', 'agents.json');
   if (await pathExists(agentsPath)) {
-    checks.push({ name: 'agents.json', status: 'ok' });
+    try {
+      const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const agentEntries = Object.entries(agentsData.agents || {})
+        .filter(([k]) => !k.startsWith('_comment'));
+      const actualCount = agentEntries.length;
+      const declaredCount = agentsData.total_agents;
+
+      // Check 1: total_agents matches actual count
+      if (actualCount !== declaredCount) {
+        checks.push({
+          name: 'agents.json count',
+          status: 'warn',
+          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
+        });
+        hasWarnings = true;
+      } else {
+        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
+      }
+
+      // Check 2: required tier-2 agents present
+      const requiredTier2 = ['standards-architect', 'dotnet-senior', 'infra-architect', 'domain-architect'];
+      const missingTier2 = requiredTier2.filter(id => !agentsData.agents[id]);
+      if (missingTier2.length > 0) {
+        checks.push({
+          name: 'agents.json required agents',
+          status: 'error',
+          msg: `Missing required agents: ${missingTier2.join(', ')}`
+        });
+        hasErrors = true;
+      } else {
+        checks.push({ name: 'agents.json required agents', status: 'ok' });
+      }
+
+      // Check 3: tier counts sum matches total
+      const tierCounts = [1, 2, 3, 4].map(t =>
+        agentEntries.filter(([, v]) => v.tier === t).length
+      );
+      const tierSum = tierCounts.reduce((a, b) => a + b, 0);
+      if (tierSum !== actualCount) {
+        checks.push({
+          name: 'agents.json tier counts',
+          status: 'warn',
+          msg: `Tier counts sum to ${tierSum} but total is ${actualCount}`
+        });
+        hasWarnings = true;
+      } else {
+        checks.push({ name: 'agents.json tier counts', status: 'ok' });
+      }
+    } catch {
+      checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
   } else {
     checks.push({ name: 'agents.json', status: 'missing' });
     hasErrors = true;

package/src/commands/project/init.js

@@ -181,7 +181,8 @@ Run \`morph-spec detect\` to analyze your project.
 
     // 9b2. Install tier-1/2 agents as native Claude Code subagents in .claude/agents/
     spinner.text = 'Installing native subagents to .claude/agents/...';
-    await installAgents(targetPath, frameworkDir);
+    const detectedStackForAgents = config.project.stack ?? null;
+    await installAgents(targetPath, frameworkDir, { projectStack: detectedStackForAgents });
 
     // 9b2b. Install level-2 domain agents as native Claude Code subagents in .claude/agents/
     await installDomainAgents(targetPath, frameworkDir);
@@ -286,6 +287,19 @@ Run \`morph-spec detect\` to analyze your project.
 
         if (structure?.stack && structure.stack !== 'unknown') {
           detectedStack = structure.stack;
+
+          // Persist detected stack to config.json
+          if (structure?.stack && structure.stack !== 'unknown') {
+            config.project.stack = structure.stack;
+          }
+          if (structure?.architecture && structure.architecture !== 'unknown') {
+            config.project.architecture = structure.architecture;
+          }
+          if (structure?.uiLibrary) {
+            config.project.uiLibrary = structure.uiLibrary;
+          }
+          await writeJson(configPath, config);
+
           spinner.stop();
           logger.blank();
           logger.header('Existing Project Detected');

package/src/commands/project/update.js

@@ -255,7 +255,12 @@ export async function updateCommand(options) {
 
     // Sync native subagents to .claude/agents/
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
-    await installAgents(targetPath, frameworkDir);
+    let projectStack = null;
+    try {
+      const cfg = await readJson(join(morphPath, 'config', 'config.json'));
+      projectStack = cfg?.project?.stack ?? null;
+    } catch { /* ignore — config may not exist yet */ }
+    await installAgents(targetPath, frameworkDir, { projectStack });
     await installDomainAgents(targetPath, frameworkDir);
 
     // Sync path-scoped rules to .claude/rules/

package/src/lib/standards/standards-context-injector.js

@@ -44,6 +44,11 @@ const AGENT_STANDARDS_MAP = {
     'backend/database/ef-core',
     'backend/api/rest'
   ],
+  'infra-architect': [
+    'core/architecture',
+    'core/coding'
+  ],
+  // Tier 3: Specialists - Infrastructure Squad
   'azure-architect': [
     'infrastructure/azure/azure', // Stack-specific
     'core/architecture',

package/src/lib/validators/nextjs/index.js

@@ -0,0 +1,6 @@
+/**
+ * Next.js Validators
+ *
+ * Validators specific to Next.js App Router patterns.
+ */
+export { validateNextComponent, validateNextComponentFiles } from './next-component-validator.js';

package/src/lib/validators/nextjs/next-component-validator.js

@@ -0,0 +1,181 @@
+import { glob } from 'glob';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Next.js Component Validator
+ *
+ * Validates .tsx files for:
+ * 1. Unnecessary 'use client' directives (no interactivity)
+ * 2. Missing 'use client' when React hooks are used
+ * 3. File naming convention (kebab-case)
+ *
+ * @module next-component-validator
+ */
+
+// ============================================
+// CONSTANTS
+// ============================================
+
+/** Hooks/patterns that require 'use client' */
+const CLIENT_HOOKS = ['useState', 'useEffect', 'useRef', 'useReducer', 'useCallback', 'useMemo', 'useContext'];
+
+/** Event handler patterns that indicate interactivity (hooks are checked via CLIENT_HOOKS) */
+const EVENT_HANDLER_PATTERNS = [
+  /\bonClick\b/,
+  /\bonChange\b/,
+  /\bonSubmit\b/,
+  /\bonFocus\b/,
+  /\bonBlur\b/,
+  /\bonKeyDown\b/,
+];
+
+/** Next.js special files exempt from naming checks */
+const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
+
+// ============================================
+// MAIN VALIDATION FUNCTION
+// ============================================
+
+/**
+ * @typedef {Object} ValidationIssue
+ * @property {'error' | 'warning' | 'info'} type
+ * @property {string} message
+ * @property {string} [suggestion]
+ * @property {string} file
+ * @property {number} [line]
+ */
+
+/**
+ * Validates a Next.js component file.
+ *
+ * @param {string} content - File content
+ * @param {string} filePath - Relative file path
+ * @returns {ValidationIssue[]}
+ */
+export function validateNextComponent(content, filePath) {
+  const issues = [];
+
+  // Only validate .tsx and .ts files
+  if (!filePath.endsWith('.tsx') && !filePath.endsWith('.ts')) {
+    return issues;
+  }
+
+  // Skip non-component utility files (no JSX, no hooks)
+  const hasJsx = /(?<![a-zA-Z0-9])<[A-Z][a-zA-Z]*[\s/>]|(?<![a-zA-Z0-9])<[a-z][a-z]+[\s>/]/.test(content);
+  const hasHooks = CLIENT_HOOKS.some(hook => content.includes(hook));
+
+  if (!hasJsx && !hasHooks) {
+    return issues;
+  }
+
+  const hasUseClient = /^'use client';?|^"use client";?/.test(content.trimStart());
+
+  // Check 1: use client present but no interactivity
+  if (hasUseClient) {
+    const hasEventHandlers = EVENT_HANDLER_PATTERNS.some(pattern => pattern.test(content));
+    const hasClientHooks = CLIENT_HOOKS.some(hook => new RegExp(`\\b${hook}\\b`).test(content));
+    if (!hasEventHandlers && !hasClientHooks) {
+      issues.push({
+        type: 'warning',
+        message: "'use client' directive present but no interactivity detected (no hooks, no event handlers)",
+        suggestion: "Remove 'use client' to make this a Server Component, or add interactive behavior",
+        file: filePath,
+      });
+    }
+  }
+
+  // Check 2: hooks used without use client
+  if (!hasUseClient) {
+    const usedHooks = CLIENT_HOOKS.filter(hook => new RegExp(`\\b${hook}\\b`).test(content));
+    if (usedHooks.length > 0) {
+      issues.push({
+        type: 'error',
+        message: `React hook(s) used (${usedHooks.join(', ')}) without 'use client' directive`,
+        suggestion: "Add 'use client' as the first line of the file",
+        file: filePath,
+        line: 1,
+      });
+    }
+  }
+
+  // Check 3: file naming convention (kebab-case)
+  const fileName = filePath.split('/').pop() ?? '';
+  const isSpecialFile = NEXTJS_SPECIAL_FILES.includes(fileName);
+
+  if (!isSpecialFile && fileName.endsWith('.tsx')) {
+    const baseName = fileName.replace('.tsx', '');
+    const hasUpperCase = /[A-Z]/.test(baseName);
+    if (hasUpperCase) {
+      issues.push({
+        type: 'warning',
+        message: `Component file '${fileName}' should use kebab-case naming`,
+        suggestion: `Rename to '${toKebabCase(baseName)}.tsx'`,
+        file: filePath,
+      });
+    }
+  }
+
+  return issues;
+}
+
+// ============================================
+// HELPERS
+// ============================================
+
+function toKebabCase(str) {
+  return str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+
+// ============================================
+// PROJECT-LEVEL SCANNER
+// ============================================
+
+/**
+ * Validates all Next.js component files in a project directory.
+ * Wraps validateNextComponent for use in validation-runner.js.
+ *
+ * @param {string} projectPath - Root path of the project
+ * @param {Object} _options - Validator options (unused, for interface compatibility)
+ * @returns {Promise<{ errors: number, warnings: number, issues: Array }>}
+ */
+export async function validateNextComponentFiles(projectPath, _options = {}) {
+  const result = { errors: 0, warnings: 0, issues: [] };
+
+  // Find all .tsx and .ts files under src/
+  const srcDir = join(projectPath, 'src');
+  const normalizedSrc = srcDir.replace(/\\/g, '/');
+  const pattern = normalizedSrc + '/**/*.{tsx,ts}';
+  const files = await glob(pattern, { ignore: ['**/node_modules/**', '**/.next/**'] });
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    // Make path relative for cleaner output
+    const normFilePath = filePath.replace(/\\/g, '/');
+    const relPath = normFilePath.replace(projectPath.replace(/\\/g, '/') + '/', '');
+    const fileIssues = validateNextComponent(content, relPath);
+
+    for (const issue of fileIssues) {
+      result.issues.push({
+        level: issue.type,
+        message: issue.message,
+        file: issue.file,
+        line: issue.line,
+        solution: issue.suggestion,
+      });
+      if (issue.type === 'error') result.errors++;
+      else if (issue.type === 'warning') result.warnings++;
+    }
+  }
+
+  return result;
+}

package/src/lib/validators/validation-runner.js

@@ -216,6 +216,11 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
       return await validateDesignSystem(projectPath, featureName, options);
     }
 
+    case 'nextjs-component': {
+      const { validateNextComponentFiles } = await import('./nextjs/next-component-validator.js');
+      return await validateNextComponentFiles(projectPath, options);
+    }
+
     default:
       if (options.verbose) {
         console.log(chalk.gray(`  Unknown validator: ${validatorId}`));

package/src/utils/agents-installer.js

@@ -17,8 +17,12 @@ import { join } from 'path';
  *
  * @param {string} projectDir - Target project directory
  * @param {string} frameworkDir - Path to morph-spec framework/ directory
+ * @param {object} options - Optional settings
+ * @param {string|null} options.projectStack - Detected project stack (e.g. 'nextjs', 'blazor')
  */
-export async function installAgents(projectDir, frameworkDir = 'framework') {
+export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
+  const { projectStack = null } = options;
+
   const agentsJsonPath = join(frameworkDir, 'agents.json');
   const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
 
@@ -33,7 +37,15 @@ export async function installAgents(projectDir, frameworkDir = 'framework') {
   const targetDir = join(projectDir, '.claude', 'agents');
   mkdirSync(targetDir, { recursive: true });
 
-  const eligible = agents.filter(a => a.tier === 1 || a.tier === 2);
+  const DOTNET_STACKS = ['dotnet', 'blazor', 'dotnet-api', 'fullstack'];
+  const eligible = agents.filter(a => {
+    if (a.tier !== 1 && a.tier !== 2) return false;
+    // Skip dotnet-senior for non-.NET projects
+    if (a.id === 'dotnet-senior' && projectStack && !DOTNET_STACKS.includes(projectStack)) {
+      return false;
+    }
+    return true;
+  });
 
   for (const agent of eligible) {
     const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');

package/.morph/.morphversion

@@ -1,5 +0,0 @@
-{
-  "morphVersion": "4.5.0",
-  "installedAt": "2026-02-23T16:14:25.956Z",
-  "cliVersion": "4.5.0"
-}

package/.morph/analytics/threads-log.jsonl

@@ -1,6 +0,0 @@
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T15:31:40.102Z"}
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T15:45:29.404Z"}
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T15:46:05.207Z"}
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T16:05:33.457Z"}
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T16:14:14.564Z"}
-{"type":"fusion_started","feature":"test-feature","data":{"count":3,"strategy":"best-of-n","agents":["fusion-agent-1","fusion-agent-2","fusion-agent-3"]},"timestamp":"2026-02-23T16:31:49.191Z"}

package/.morph/config/config.json

@@ -1,8 +0,0 @@
-{
-  "framework": "global",
-  "frameworkVersion": "4.5.0",
-  "project": {
-    "name": "morph-spec-framework",
-    "architecture": "unknown"
-  }
-}