@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/templates/integrations/neon-auth-config.cs

@@ -1,19 +1,4 @@
-// ==============================================================================
-// MORPH-SPEC - Neon Auth Configuration Template
-// Configuracao de autenticacao com Neon Auth (Better Auth) para .NET
-//
-// Neon Auth tokens are signed with EdDSA (Ed25519, JWK kty "OKP"). There is no
-// OIDC discovery document (/.well-known/openid-configuration) — only the raw
-// /.well-known/jwks.json — and Microsoft.IdentityModel.Tokens cannot verify
-// OKP/EdDSA signatures on its own. See:
-//   .morph/framework/standards/backend/integrations/neon-auth/neon-auth.md
-//   → "## .NET Backend Integration" for the full reference and rationale.
-//
-// NuGet (add both):
-//   <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.3" />
-//   <PackageReference Include="BouncyCastle.Cryptography" Version="2.6.2" /> <!-- pin >= 2.3.1, CVE-2024-30172 -->
-// ==============================================================================
-
+// Neon Auth signs with EdDSA (Ed25519), which Microsoft.IdentityModel cannot verify: needs BouncyCastle.Cryptography >= 2.3.1 (CVE-2024-30172).
 using System.Security.Claims;
 using System.Text;
 using Microsoft.AspNetCore.Authentication;
@@ -26,32 +11,14 @@ using Org.BouncyCastle.Crypto.Signers;
 
 namespace {{Namespace}}.Infrastructure.Auth;
 
-// ==============================================================================
-// OPTIONS
-// ==============================================================================
-
 public class NeonAuthOptions
 {
     public const string SectionName = "NeonAuth";
 
-    /// <summary>
-    /// Neon Auth Base URL (e.g., https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth).
-    /// MUST be present in appsettings.Development.json — it's a public value, not a secret.
-    /// Missing it produces the same symptom as a broken signature validator: every request
-    /// gets a bare 401 with nothing useful in the logs.
-    /// </summary>
+    // Public value, commit it in appsettings.Development.json: when missing, every request is a bare 401 with nothing in the logs.
     public string BaseUrl { get; set; } = string.Empty;
 }
 
-// ==============================================================================
-// JWKS PROVIDER (cached — Neon Auth has no OIDC discovery to piggyback on)
-// ==============================================================================
-
-/// <summary>
-/// Fetches and caches Neon Auth's raw JWKS. Cached for 15 minutes; a forced refresh
-/// happens once when an unknown `kid` is seen, to survive key rotation without
-/// waiting out the TTL.
-/// </summary>
 public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
 {
     private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
@@ -65,7 +32,7 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
         var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
         if (key is not null) return key;
 
-        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        // Unknown kid may be a key rotation: refresh once instead of waiting out the TTL.
         keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
         return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
     }
@@ -94,18 +61,8 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
     }
 }
 
-// ==============================================================================
-// SERVICE EXTENSIONS
-// ==============================================================================
-
 public static class NeonAuthServiceExtensions
 {
-    /// <summary>
-    /// Adds Neon Auth JWT Bearer authentication to the project. Validates EdDSA-signed
-    /// JWTs issued by Neon Auth via a manually-fetched, cached JWKS — see
-    /// NeonAuthJwksProvider above and the standard's "## .NET Backend Integration" section
-    /// for why options.Authority / the default IssuerSigningKeyResolver do not work here.
-    /// </summary>
     public static IServiceCollection AddNeonAuthentication(
         this IServiceCollection services,
         IConfiguration configuration)
@@ -116,9 +73,7 @@ public static class NeonAuthServiceExtensions
         services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
             .AddJwtBearer(options =>
             {
-                // Do NOT set options.Authority — Neon Auth serves no
-                // /.well-known/openid-configuration, so Authority-driven metadata refresh
-                // has nothing valid to fetch. ValidIssuer is set explicitly instead.
+                // No options.Authority: Neon Auth serves no /.well-known/openid-configuration to fetch.
                 options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuer = true,
@@ -126,16 +81,12 @@ public static class NeonAuthServiceExtensions
                     ValidateAudience = false,
                     ValidateLifetime = true,
                     NameClaimType = "sub",
-                    // Trust in the signing key is established entirely inside
-                    // SignatureValidator below (fetched from our own cached JWKS) —
-                    // this flag doesn't gate that path.
+                    // The key is trusted inside SignatureValidator below, not by this flag.
                     ValidateIssuerSigningKey = false,
                 };
             });
 
-        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has
-        // already run, so this only *adds* the SignatureValidator to the
-        // TokenValidationParameters instance built above.
+        // Separate pass because the validator needs NeonAuthJwksProvider from DI.
         services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
             .Configure<NeonAuthJwksProvider>((options, jwks) =>
             {
@@ -143,8 +94,7 @@ public static class NeonAuthServiceExtensions
                 {
                     var jwt = new JsonWebToken(token);
 
-                    // Pin the algorithm — refuse anything that isn't EdDSA to block
-                    // alg-substitution attacks.
+                    // Pin the algorithm against alg-substitution attacks.
                     if (!string.Equals(jwt.Alg, "EdDSA", StringComparison.Ordinal))
                         throw new SecurityTokenInvalidSignatureException(
                             $"Unsupported alg '{jwt.Alg}' — Neon Auth tokens must be EdDSA.");
@@ -153,9 +103,7 @@ public static class NeonAuthServiceExtensions
                     if (string.IsNullOrEmpty(kid))
                         throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
 
-                    // Blocking call: JWKS is cached in-memory, so this is I/O-free on the hot
-                    // path. SignatureValidator has no async overload — only a cold-start /
-                    // key-rotation miss ever awaits real I/O here.
+                    // SignatureValidator has no async overload; the JWKS is cached, so only a cold miss blocks on I/O.
                     var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
                         ?? throw new SecurityTokenInvalidSignatureException(
                             $"No JWKS key found for kid '{kid}'.");
@@ -181,10 +129,7 @@ public static class NeonAuthServiceExtensions
                         throw new SecurityTokenInvalidSignatureException(
                             "Ed25519 signature verification failed.");
 
-                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET
-                    // Core 8+ uses JsonWebTokenHandler internally. Returning a
-                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with
-                    // IDX10506 ("SignatureValidator returned a token of an unexpected type").
+                    // Must be JsonWebToken: returning a JwtSecurityToken fails with IDX10506 on ASP.NET Core 8+.
                     return jwt;
                 };
             });
@@ -195,10 +140,6 @@ public static class NeonAuthServiceExtensions
     }
 }
 
-// ==============================================================================
-// USER CONTEXT SERVICE
-// ==============================================================================
-
 public interface ICurrentUserService
 {
     string? UserId { get; }
@@ -218,10 +159,6 @@ public class CurrentUserService(IHttpContextAccessor httpContextAccessor) : ICur
         httpContextAccessor.HttpContext?.User.Identity?.IsAuthenticated ?? false;
 }
 
-// ==============================================================================
-// MIDDLEWARE PIPELINE
-// ==============================================================================
-
 public static class NeonAuthMiddlewareExtensions
 {
     public static IApplicationBuilder UseNeonAuthentication(this IApplicationBuilder app)
@@ -231,36 +168,3 @@ public static class NeonAuthMiddlewareExtensions
         return app;
     }
 }
-
-// ==============================================================================
-// APPSETTINGS.DEVELOPMENT.JSON — mandatory, public value, safe to commit
-// ==============================================================================
-
-/*
-{
-  "NeonAuth": {
-    "BaseUrl": "https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth"
-  }
-}
-*/
-
-// ==============================================================================
-// PROGRAM.CS EXAMPLE
-// ==============================================================================
-
-/*
-var builder = WebApplication.CreateBuilder(args);
-
-// Add Neon Auth authentication (registers the JWKS provider + EdDSA signature validator)
-builder.Services.AddNeonAuthentication(builder.Configuration);
-builder.Services.AddHttpContextAccessor();
-builder.Services.AddScoped<ICurrentUserService, CurrentUserService>();
-
-var app = builder.Build();
-
-app.UseNeonAuthentication();
-
-app.MapControllers().RequireAuthorization();
-
-app.Run();
-*/

package/framework/templates/project/validate.js

@@ -1,120 +1,97 @@
-#!/usr/bin/env node
-/**
- * bin/validate.js — generated by morph-spec setup-infra
- *
- * Thin validator entry-point called by morph-spec validate-completion hook:
- *   node bin/validate.js <validator> [--json]
- *
- * Supported validators: architecture, nextjs-component,
- *   packages, design-system, ui-contrast, css
- *
- * Exits 0 on pass, 1 on validation errors.
- * --json flag prints structured JSON to stdout.
- */
-
-const validator = process.argv[2];
-const isJson = process.argv.includes('--json');
-
-if (!validator) {
-  console.error('Usage: node bin/validate.js <validator> [--json]');
-  process.exit(1);
-}
-
-const { execSync } = await import('child_process');
-const { existsSync } = await import('fs');
-const { join } = await import('path');
-
-const cwd = process.cwd();
-
-const results = {
-  validator,
-  errors: 0,
-  warnings: 0,
-  passed: true,
-  issues: [],
-};
-
-/**
- * Run a shell command and capture output.
- * Returns { success, stdout, stderr }.
- */
-function runCommand(cmd, options = {}) {
-  try {
-    const stdout = execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'], ...options }).toString();
-    return { success: true, stdout, stderr: '' };
-  } catch (err) {
-    return {
-      success: false,
-      stdout: err.stdout?.toString() || '',
-      stderr: err.stderr?.toString() || err.message,
-    };
-  }
-}
-
-// ── Stack detection ───────────────────────────────────────────────────────────
-
-const hasFrontend = existsSync(join(cwd, 'src/frontend')) || existsSync(join(cwd, 'frontend'));
-const hasBackend  = existsSync(join(cwd, 'src/backend'))  || existsSync(join(cwd, 'backend'));
-const hasSln      = existsSync(join(cwd, 'src/backend/backend.sln')) ||
-                    existsSync(join(cwd, 'src/backend/Backend.sln'));
-
-const frontendDir = existsSync(join(cwd, 'src/frontend')) ? 'src/frontend' : 'frontend';
-const backendDir  = existsSync(join(cwd, 'src/backend'))  ? 'src/backend'  : 'backend';
-
-// ── Validator dispatch ────────────────────────────────────────────────────────
-
-switch (validator) {
-  case 'architecture': {
-    if (hasBackend && hasSln) {
-      const slnFile = hasSln ? (
-        existsSync(join(cwd, 'src/backend/backend.sln')) ? 'backend.sln' : 'Backend.sln'
-      ) : '.';
-      const result = runCommand(`dotnet build ${slnFile} --no-restore -warnaserror`, { cwd: join(cwd, backendDir) });
-      if (!result.success) {
-        results.errors++;
-        results.passed = false;
-        results.issues.push({ level: 'error', message: `dotnet build failed: ${result.stderr.split('\n')[0]}` });
-      }
-    }
-    break;
-  }
-
-  case 'nextjs-component':
-  case 'packages':
-  case 'design-system': {
-    if (hasFrontend) {
-      const result = runCommand('npx tsc --noEmit', { cwd: join(cwd, frontendDir) });
-      if (!result.success) {
-        results.errors++;
-        results.passed = false;
-        results.issues.push({ level: 'error', message: `TypeScript errors found. Run: npx tsc --noEmit` });
-      }
-    }
-    break;
-  }
-
-  case 'ui-contrast':
-  case 'css': {
-    // CSS/contrast validators are visual — report as informational
-    results.issues.push({ level: 'info', message: `${validator} requires manual review` });
-    break;
-  }
-
-  default:
-    results.issues.push({ level: 'warning', message: `Unknown validator: ${validator}` });
-    break;
-}
-
-// ── Output ────────────────────────────────────────────────────────────────────
-
-if (isJson) {
-  console.log(JSON.stringify(results, null, 2));
-} else {
-  const icon = results.passed ? '✅' : '❌';
-  console.log(`${icon} Validator: ${validator} — ${results.passed ? 'PASSED' : `FAILED (${results.errors} errors)`}`);
-  for (const issue of results.issues) {
-    console.log(`  [${issue.level}] ${issue.message}`);
-  }
-}
-
-process.exit(results.passed ? 0 : 1);
+#!/usr/bin/env node
+
+const validator = process.argv[2];
+const isJson = process.argv.includes('--json');
+
+if (!validator) {
+  console.error('Usage: node bin/validate.js <validator> [--json]');
+  process.exit(1);
+}
+
+const { execSync } = await import('child_process');
+const { existsSync } = await import('fs');
+const { join } = await import('path');
+
+const cwd = process.cwd();
+
+const results = {
+  validator,
+  errors: 0,
+  warnings: 0,
+  passed: true,
+  issues: [],
+};
+
+function runCommand(cmd, options = {}) {
+  try {
+    const stdout = execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'], ...options }).toString();
+    return { success: true, stdout, stderr: '' };
+  } catch (err) {
+    return {
+      success: false,
+      stdout: err.stdout?.toString() || '',
+      stderr: err.stderr?.toString() || err.message,
+    };
+  }
+}
+
+const hasFrontend = existsSync(join(cwd, 'src/frontend')) || existsSync(join(cwd, 'frontend'));
+const hasBackend  = existsSync(join(cwd, 'src/backend'))  || existsSync(join(cwd, 'backend'));
+const hasSln      = existsSync(join(cwd, 'src/backend/backend.sln')) ||
+                    existsSync(join(cwd, 'src/backend/Backend.sln'));
+
+const frontendDir = existsSync(join(cwd, 'src/frontend')) ? 'src/frontend' : 'frontend';
+const backendDir  = existsSync(join(cwd, 'src/backend'))  ? 'src/backend'  : 'backend';
+
+switch (validator) {
+  case 'architecture': {
+    if (hasBackend && hasSln) {
+      const slnFile = hasSln ? (
+        existsSync(join(cwd, 'src/backend/backend.sln')) ? 'backend.sln' : 'Backend.sln'
+      ) : '.';
+      const result = runCommand(`dotnet build ${slnFile} --no-restore -warnaserror`, { cwd: join(cwd, backendDir) });
+      if (!result.success) {
+        results.errors++;
+        results.passed = false;
+        results.issues.push({ level: 'error', message: `dotnet build failed: ${result.stderr.split('\n')[0]}` });
+      }
+    }
+    break;
+  }
+
+  case 'nextjs-component':
+  case 'packages':
+  case 'design-system': {
+    if (hasFrontend) {
+      const result = runCommand('npx tsc --noEmit', { cwd: join(cwd, frontendDir) });
+      if (!result.success) {
+        results.errors++;
+        results.passed = false;
+        results.issues.push({ level: 'error', message: `TypeScript errors found. Run: npx tsc --noEmit` });
+      }
+    }
+    break;
+  }
+
+  case 'ui-contrast':
+  case 'css': {
+    results.issues.push({ level: 'info', message: `${validator} requires manual review` });
+    break;
+  }
+
+  default:
+    results.issues.push({ level: 'warning', message: `Unknown validator: ${validator}` });
+    break;
+}
+
+if (isJson) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  const icon = results.passed ? '✅' : '❌';
+  console.log(`${icon} Validator: ${validator} — ${results.passed ? 'PASSED' : `FAILED (${results.errors} errors)`}`);
+  for (const issue of results.issues) {
+    console.log(`  [${issue.level}] ${issue.message}`);
+  }
+}
+
+process.exit(results.passed ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.37.1",
+  "version": "8.40.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",
@@ -20,7 +20,6 @@
     "morph",
     "polymorphism"
   ],
-  "main": "src/index.js",
   "bin": {
     "morph-spec": "bin/morph-spec.js"
   },
@@ -49,6 +48,7 @@
     "freshness": "node scripts/check-freshness.js",
     "verify": "npm run generate:check && npm run generate-standards:check && npm run validate && npm run freshness && npm test",
     "test": "node scripts/run-tests.mjs",
+    "test:changed": "node scripts/test-changed.mjs",
     "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node scripts/run-tests.mjs",
     "test:coverage:summary": "c8 --reporter=text-summary node scripts/run-tests.mjs",
     "docs": "jsdoc -c jsdoc.json",

package/src/commands/dashboard/dashboard.js

@@ -1,53 +1,80 @@
-import { spawn } from 'child_process';
-import { existsSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import chalk from 'chalk';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-export async function dashboardCommand(options = {}) {
-  const port = options.port || '3200';
-  const dashboardDir = resolve(__dirname, '..', '..', 'dashboard');
-  const nodeModules = resolve(dashboardDir, 'node_modules');
-
-  // Check if dashboard dependencies are installed
-  if (!existsSync(nodeModules)) {
-    console.log(chalk.yellow('Installing dashboard dependencies...'));
-    const install = spawn('npm', ['install'], {
-      cwd: dashboardDir,
-      stdio: 'inherit',
-      shell: true,
-    });
-    await new Promise((res, rej) => {
-      install.on('close', (code) => (code === 0 ? res() : rej(new Error(`npm install failed with code ${code}`))));
-    });
-  }
-
-  console.log(chalk.cyan(`\n  Starting morph-spec dashboard at http://localhost:${port}\n`));
-
-  const env = {
-    ...process.env,
-    MORPH_PROJECT_DIR: process.cwd(),
-  };
-
-  const viteArgs = ['vite', '--port', port];
-  if (options.open !== false) viteArgs.push('--open');
-
-  const vite = spawn('npx', viteArgs, {
-    cwd: dashboardDir,
-    stdio: 'inherit',
-    shell: true,
-    env,
-  });
-
-  vite.on('error', (err) => {
-    console.error(chalk.red(`Failed to start dashboard: ${err.message}`));
-    process.exit(1);
-  });
-
-  process.on('SIGINT', () => {
-    vite.kill();
-    process.exit(0);
-  });
-}
+import { spawn } from 'child_process';
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { registerProject } from '../../lib/projects/registry.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Where the hash of the package.json that produced node_modules is kept. */
+export const DEPS_STAMP = '.morph-deps-stamp';
+
+/** Hash of the dashboard's package.json — the dependency set it declares. */
+export function depsHash(dashboardDir) {
+  return createHash('sha256').update(readFileSync(join(dashboardDir, 'package.json'))).digest('hex');
+}
+
+/**
+ * Does the dashboard need an `npm install`? Not only when node_modules is
+ * missing: an install made before a dependency was added fails at import time,
+ * so node_modules must have been produced by THIS package.json.
+ */
+export function needsInstall(dashboardDir) {
+  const stamp = join(dashboardDir, 'node_modules', DEPS_STAMP);
+  if (!existsSync(stamp)) return true;
+  try {
+    return readFileSync(stamp, 'utf8').trim() !== depsHash(dashboardDir);
+  } catch {
+    return true;
+  }
+}
+
+export async function dashboardCommand(options = {}) {
+  const port = options.port || '3200';
+  const dashboardDir = resolve(__dirname, '..', '..', 'dashboard');
+
+  if (needsInstall(dashboardDir)) {
+    console.log(chalk.yellow('Installing dashboard dependencies...'));
+    const install = spawn('npm', ['install'], {
+      cwd: dashboardDir,
+      stdio: 'inherit',
+      shell: true,
+    });
+    await new Promise((res, rej) => {
+      install.on('close', (code) => (code === 0 ? res() : rej(new Error(`npm install failed with code ${code}`))));
+    });
+    writeFileSync(join(dashboardDir, 'node_modules', DEPS_STAMP), depsHash(dashboardDir));
+  }
+
+  // Opening the dashboard in a project puts it in the portfolio.
+  registerProject(process.cwd(), 'dashboard');
+
+  console.log(chalk.cyan(`\n  Starting morph-spec dashboard at http://localhost:${port}\n`));
+
+  const env = {
+    ...process.env,
+    MORPH_PROJECT_DIR: process.cwd(),
+  };
+
+  const viteArgs = ['vite', '--port', port];
+  if (options.open !== false) viteArgs.push('--open');
+
+  const vite = spawn('npx', viteArgs, {
+    cwd: dashboardDir,
+    stdio: 'inherit',
+    shell: true,
+    env,
+  });
+
+  vite.on('error', (err) => {
+    console.error(chalk.red(`Failed to start dashboard: ${err.message}`));
+    process.exit(1);
+  });
+
+  process.on('SIGINT', () => {
+    vite.kill();
+    process.exit(0);
+  });
+}

package/src/commands/graph/affected.js

@@ -9,7 +9,7 @@
  * @module graph-affected
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
+import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, affected } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob — o grafo é um subconjunto estrito do grep, então cair para grep não perde recall.';
@@ -79,11 +79,12 @@ export async function graphAffectedCommand(symbol, options = {}) {
   console.log(chalk.green(`\n✅ ${symbol} — ${consumers.length} consumidor(es)`));
   console.log(chalk.gray(`   declarado em ${resolved.node.source_file}`));
   if (freshness.state === 'stale') {
-    console.log(chalk.yellow('   ⚠ grafo stale (o rebuild do hook é assíncrono) — confirme no código antes de agir'));
+    console.log(chalk.yellow(`   ⚠ grafo stale, confirme no código antes de agir — ${describeStale(projectPath, freshness)}`));
   }
   for (const c of consumers) {
     const loc = c.source_location ? `:${c.source_location}` : '';
-    console.log(`   ${chalk.cyan(c.relation.padEnd(14))} ${c.source_file}${loc}  ${chalk.gray(c.label)}`);
+    const test = c.test ? chalk.gray(' [teste]') : '';
+    console.log(`   ${chalk.cyan(c.relation.padEnd(14))} ${c.source_file}${loc}  ${chalk.gray(c.label)}${test}`);
   }
   console.log('');
 }