@polymorphism-tech/morph-spec 4.19.0 → 4.21.0

package/src/dashboard/scanner/standards-scanner.js

@@ -0,0 +1,26 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function scanStandards(frameworkDir, agents) {
+  const standardsJsonPath = join(frameworkDir, 'standards', 'STANDARDS.json');
+  if (!existsSync(standardsJsonPath)) return { version: 'unknown', list: [] };
+  const sJson = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
+  const refMap = {};
+  for (const agent of agents) {
+    for (const std of agent.standards) {
+      if (!refMap[std.id]) refMap[std.id] = [];
+      refMap[std.id].push({ agentId: agent.id, scope: std.scope, priority: std.priority });
+    }
+  }
+  const list = sJson.standards.map(std => {
+    const mdPath = join(frameworkDir, 'standards', std.path);
+    return {
+      id: std.id, name: std.name, path: std.path, category: std.category,
+      subcategory: std.subcategory || null, tags: std.tags || [],
+      digest: std.digest || '', stacks: std.stacks || [],
+      content: existsSync(mdPath) ? readFileSync(mdPath, 'utf8') : '',
+      referencedBy: refMap[std.id] || [],
+    };
+  });
+  return { version: sJson.version, list };
+}

package/src/dashboard/scanner/state-scanner.js

@@ -0,0 +1,8 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function scanState(projectDir) {
+  const statePath = join(projectDir, '.morph', 'state.json');
+  if (!existsSync(statePath)) return null;
+  try { return JSON.parse(readFileSync(statePath, 'utf8')); } catch { return null; }
+}

package/src/dashboard/scanner/workflows-scanner.js

@@ -0,0 +1,18 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function scanWorkflows(frameworkDir) {
+  const dir = join(frameworkDir, 'workflows', 'configs');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
+    const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    return {
+      id: d.id, name: d.name, description: d.description || '',
+      criteria: d.criteria || {}, keywords: d.keywords || [],
+      phases: d.phases || { run: [], skip: [] },
+      pausePoints: d.pausePoints || [],
+      outputs: d.outputs || { required: [], optional: [], skip: [] },
+      priority: d.priority || 0,
+    };
+  });
+}

package/src/dashboard/vite-plugin-morph-data.js

@@ -0,0 +1,17 @@
+import { scanAll } from './scanner/index.js';
+
+const VIRTUAL_MODULE_ID = 'virtual:morph-data';
+const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_MODULE_ID;
+
+export default function morphDataPlugin(frameworkDir, projectDir) {
+  return {
+    name: 'vite-plugin-morph-data',
+    resolveId(id) { if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_ID; },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_ID) {
+        const data = scanAll(frameworkDir, projectDir);
+        return `export default ${JSON.stringify(data)}`;
+      }
+    },
+  };
+}

package/src/dashboard/vite.config.js

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import morphDataPlugin from './vite-plugin-morph-data.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const frameworkDir = resolve(__dirname, '..', '..', 'framework');
+const projectDir = process.env.MORPH_PROJECT_DIR || process.cwd();
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [
+    react(),
+    tailwindcss(),
+    morphDataPlugin(frameworkDir, projectDir),
+  ],
+  server: {
+    port: 3200,
+  },
+});

package/src/lib/checkpoints/checkpoint-hooks.js

@@ -48,7 +48,8 @@ export async function runCheckpointHooks(featureName, checkpointNum, opts = {})
       passed: valResult.passed,
       errors: valResult.errors,
       warnings: valResult.warnings,
-      details: valResult.results
+      details: valResult.results,
+      scores: valResult.scores || null
     };
     totalErrors += valResult.errors;
     totalWarnings += valResult.warnings;

package/src/lib/detectors/index.js

@@ -30,7 +30,7 @@ export function detectProject(targetPath, opts = {}) {
   try {
     // ── Package.json analysis ──────────────────────────────────────────────
     // Collect deps from root and common monorepo subfolders
-    const pkgLocations = ['.', 'src/frontend', 'frontend', 'apps/web', 'packages/app'];
+    const pkgLocations = ['.', 'src/frontend', 'src/web', 'frontend', 'apps/web', 'packages/app'];
     const allDeps = {};
     let rootPkg = null;
     let scripts = [];

package/src/lib/generators/recap-generator.js

@@ -179,6 +179,21 @@ function buildRecapMarkdown(data) {
     md += `> Verify actual build status with the commands in the section below.\n\n`;
   }
 
+  // Score Breakdown (when rubric scoring is available)
+  if (validationResult.scores) {
+    const scores = validationResult.scores;
+    md += `### Quality Score: ${scores.score}/10\n\n`;
+    md += `| Category | Score | Weight | Status |\n|----------|-------|--------|--------|\n`;
+    const approveThreshold = scores.approveThreshold ?? 8.0;
+    for (const [category, data] of Object.entries(scores.breakdown)) {
+      if (category === '_unmapped') continue;
+      const pct = Math.round(data.weight * 100);
+      const status = data.score >= approveThreshold ? 'Pass' : data.score >= 6 ? 'Needs work' : 'Critical';
+      md += `| ${category} | ${Math.round(data.score * 10) / 10}/10 | ${pct}% | ${status} |\n`;
+    }
+    md += `\n`;
+  }
+
   // Suggested Quality Verification
   const agents = agentsSummary;
   const hasNextjs = agents.some(a => ['nextjs-expert', 'css-specialist', 'ui-designer'].includes(a));

package/src/lib/installers/mcp-installer.js

@@ -7,7 +7,7 @@
  */
 
 import { join } from 'path';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
 import { execSync } from 'child_process';
 import { installMcpServers } from '../../utils/claude-settings-manager.js';
 
@@ -173,6 +173,145 @@ export function installCompanionSkills(mcpsInstalled, exec = execSync) {
   return results;
 }
 
+/**
+ * Generate the Stitch OAuth proxy template script.
+ * @param {string} gcpProject - GCP project ID for x-goog-user-project header
+ * @returns {string} CJS proxy script content
+ */
+export function getStitchProxyTemplate(gcpProject) {
+  return `/**
+ * Stitch MCP OAuth Proxy
+ * Generated by morph-spec mcp setup stitch
+ *
+ * Bridges stdio JSON-RPC to https://stitch.googleapis.com/mcp
+ * using gcloud application-default credentials (OAuth2 bearer token).
+ */
+const { execSync } = require('child_process');
+const https = require('https');
+
+const GCP_PROJECT = '${gcpProject}';
+const STITCH_HOST = 'stitch.googleapis.com';
+const STITCH_PATH = '/mcp';
+const TOKEN_TTL_MS = 50 * 60 * 1000; // 50 minutes
+
+let cachedToken = null;
+let tokenExpiresAt = 0;
+
+function getAccessToken() {
+  if (cachedToken && Date.now() < tokenExpiresAt) return cachedToken;
+  try {
+    cachedToken = execSync('gcloud auth application-default print-access-token', {
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    tokenExpiresAt = Date.now() + TOKEN_TTL_MS;
+    return cachedToken;
+  } catch (err) {
+    process.stderr.write('[stitch-proxy] Failed to get access token. Run: gcloud auth application-default login\\n');
+    throw err;
+  }
+}
+
+function clearTokenCache() {
+  cachedToken = null;
+  tokenExpiresAt = 0;
+}
+
+function sendRequest(body) {
+  return new Promise((resolve, reject) => {
+    const token = getAccessToken();
+    const data = JSON.stringify(body);
+    const options = {
+      hostname: STITCH_HOST,
+      path: STITCH_PATH,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        'Authorization': \`Bearer \${token}\`,
+        'x-goog-user-project': GCP_PROJECT,
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let responseData = '';
+      res.on('data', (chunk) => { responseData += chunk; });
+      res.on('end', () => {
+        if (res.statusCode === 401) {
+          // Token expired — retry once with fresh token
+          clearTokenCache();
+          const retryToken = getAccessToken();
+          options.headers['Authorization'] = \`Bearer \${retryToken}\`;
+          const retryData = JSON.stringify(body);
+          options.headers['Content-Length'] = Buffer.byteLength(retryData);
+          const retryReq = https.request(options, (retryRes) => {
+            let retryResponse = '';
+            retryRes.on('data', (chunk) => { retryResponse += chunk; });
+            retryRes.on('end', () => resolve(retryResponse));
+          });
+          retryReq.on('error', reject);
+          retryReq.write(retryData);
+          retryReq.end();
+        } else {
+          resolve(responseData);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+// Buffer stdin and split on newlines (JSON-RPC messages)
+let buffer = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk;
+  const lines = buffer.split('\\n');
+  buffer = lines.pop(); // keep incomplete line in buffer
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const request = JSON.parse(line);
+      const response = await sendRequest(request);
+      process.stdout.write(response + '\\n');
+    } catch (err) {
+      const errorResponse = JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32603, message: err.message || 'Proxy error' }
+      });
+      process.stdout.write(errorResponse + '\\n');
+    }
+  }
+});
+
+process.stderr.write(\`[stitch-proxy] Ready — GCP project: \${GCP_PROJECT}\\n\`);
+`;
+}
+
+/**
+ * Generate and write the Stitch OAuth proxy script to the target project.
+ * @param {string} targetPath - Project root directory
+ * @param {string} gcpProject - GCP project ID
+ * @returns {{ proxyPath: string }} Path to the generated proxy script
+ */
+export function generateStitchProxy(targetPath, gcpProject) {
+  const claudeDir = join(targetPath, '.claude');
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+
+  const proxyPath = join(claudeDir, 'stitch-proxy.cjs');
+  writeFileSync(proxyPath, getStitchProxyTemplate(gcpProject), 'utf-8');
+
+  return { proxyPath };
+}
+
 /**
  * Install a single MCP with provided credentials
  * @param {string} targetPath - Project root directory

package/src/lib/validators/score-aggregator.js

@@ -0,0 +1,244 @@
+/**
+ * MORPH-SPEC Score Aggregator
+ *
+ * Converts pass/fail validator results into weighted scores using rubric definitions.
+ * Produces prioritized feedback for the retry loop.
+ *
+ * @module score-aggregator
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Fallback rubric when none is configured or found. */
+const FALLBACK_RUBRIC = {
+  id: 'fallback',
+  version: '1.0.0',
+  categories: {
+    general: {
+      weight: 1.0,
+      validators: [],
+      description: 'All validators (fallback — no rubric configured)'
+    }
+  },
+  thresholds: { approve: 8.0, retry: 6.0 }
+};
+
+/**
+ * Load a rubric by ID from the project or framework directory.
+ *
+ * Search order:
+ *   1. .morph/framework/rubrics/{rubricId}.json  (installed in project)
+ *   2. npm package path  (node_modules/@polymorphism-tech/morph-spec/framework/rubrics/)
+ *   3. Local dev path  (framework/rubrics/ relative to this module)
+ *
+ * @param {string} projectPath - Project root
+ * @param {string} rubricId - Rubric identifier (e.g. 'default', 'frontend', 'backend')
+ * @returns {Object} Parsed rubric object
+ */
+export function loadRubric(projectPath, rubricId = 'default') {
+  const filename = `${rubricId}.json`;
+
+  const candidates = [
+    join(projectPath, '.morph', 'framework', 'rubrics', filename),
+    join(projectPath, 'node_modules', '@polymorphism-tech', 'morph-spec', 'framework', 'rubrics', filename),
+    join(__dirname, '..', '..', '..', 'framework', 'rubrics', filename)
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        return JSON.parse(readFileSync(candidate, 'utf8'));
+      } catch {
+        // Corrupted file — try next candidate
+      }
+    }
+  }
+
+  return FALLBACK_RUBRIC;
+}
+
+/**
+ * Score a single validator result.
+ *
+ * Scoring formula:
+ *   - Base score: 10
+ *   - Each error:   -2  (min 0)
+ *   - Each warning: -1  (min 0)
+ *
+ * @param {Object} validatorResult - { passed: boolean, issues?: Array, error?: string }
+ * @returns {number} Score 0–10
+ */
+export function scoreValidator(validatorResult) {
+  if (!validatorResult) return 10; // Validator didn't run — assume clean
+
+  // Validator threw an error — can't assess
+  if (validatorResult.error) return 5;
+
+  const errors = (validatorResult.issues || []).filter(i => i.level === 'error').length;
+  const warnings = (validatorResult.issues || []).filter(i => i.level === 'warning').length;
+
+  return Math.max(0, 10 - (errors * 2) - (warnings * 1));
+}
+
+/**
+ * Build a reverse map: validatorId → category name.
+ * Validators not mapped to any category go into '_unmapped'.
+ *
+ * @param {Object} rubric
+ * @returns {Map<string, string>}
+ */
+function buildValidatorCategoryMap(rubric) {
+  const map = new Map();
+  for (const [categoryName, category] of Object.entries(rubric.categories)) {
+    for (const validatorId of category.validators || []) {
+      map.set(validatorId, categoryName);
+    }
+  }
+  return map;
+}
+
+/**
+ * Aggregate validator results into weighted scores using a rubric.
+ *
+ * @param {Object} validationResult - From validation-runner.js: { passed, errors, warnings, issues, results }
+ * @param {Object} rubric - Loaded rubric object
+ * @param {Object} [configOverrides] - Optional threshold overrides from config.json
+ * @param {number} [configOverrides.approve] - Override approve threshold
+ * @param {number} [configOverrides.retry] - Override retry threshold
+ * @returns {{
+ *   score: number,
+ *   action: 'approve' | 'retry' | 'escalate',
+ *   breakdown: Object,
+ *   priorityFixes: Array<{ category: string, score: number, weight: number, deficit: number, issues: Array }>
+ * }}
+ */
+export function aggregateScores(validationResult, rubric, configOverrides = {}) {
+  const results = validationResult.results || {};
+  const validatorCategoryMap = buildValidatorCategoryMap(rubric);
+
+  // Collect scores per category
+  const breakdown = {};
+  const unmappedScores = [];
+
+  for (const [categoryName, category] of Object.entries(rubric.categories)) {
+    const mappedValidators = (category.validators || []).filter(v => results[v] !== undefined);
+    const scores = mappedValidators.map(v => scoreValidator(results[v]));
+
+    breakdown[categoryName] = {
+      score: scores.length > 0 ? scores.reduce((a, b) => a + b, 0) / scores.length : 10,
+      weight: category.weight,
+      validators: mappedValidators,
+      issues: mappedValidators.flatMap(v => (results[v]?.issues || []))
+    };
+  }
+
+  // Handle validators not mapped to any rubric category
+  for (const [validatorId, result] of Object.entries(results)) {
+    if (!validatorCategoryMap.has(validatorId)) {
+      unmappedScores.push(scoreValidator(result));
+    }
+  }
+
+  // Handle unmapped validators
+  if (unmappedScores.length > 0) {
+    const unmappedIds = Object.keys(results).filter(id => !validatorCategoryMap.has(id));
+    if (Object.keys(breakdown).length === 0) {
+      // No categories at all — put everything in 'general'
+      breakdown.general = {
+        score: unmappedScores.reduce((a, b) => a + b, 0) / unmappedScores.length,
+        weight: 1.0,
+        validators: unmappedIds,
+        issues: unmappedIds.flatMap(id => results[id]?.issues || [])
+      };
+    } else {
+      // Categories exist but some validators aren't mapped — add as low-weight 'other'
+      const unmappedAvg = unmappedScores.reduce((a, b) => a + b, 0) / unmappedScores.length;
+      breakdown._unmapped = {
+        score: unmappedAvg,
+        weight: 0.05,
+        validators: unmappedIds,
+        issues: unmappedIds.flatMap(id => results[id]?.issues || [])
+      };
+    }
+  }
+
+  // Calculate weighted final score
+  const totalWeight = Object.values(breakdown).reduce((sum, cat) => sum + cat.weight, 0);
+  const weightedScore = totalWeight > 0
+    ? Object.values(breakdown).reduce((sum, cat) => sum + (cat.score * cat.weight), 0) / totalWeight
+    : 10;
+
+  // Round to 1 decimal
+  const score = Math.round(weightedScore * 10) / 10;
+
+  // Determine action
+  const approveThreshold = configOverrides.approve ?? rubric.thresholds?.approve ?? 8.0;
+  const retryThreshold = configOverrides.retry ?? rubric.thresholds?.retry ?? 6.0;
+
+  let action;
+  if (score >= approveThreshold) {
+    action = 'approve';
+  } else if (score >= retryThreshold) {
+    action = 'retry';
+  } else {
+    action = 'escalate';
+  }
+
+  // Build priority fixes — sorted by impact (weight * deficit from 10)
+  const priorityFixes = Object.entries(breakdown)
+    .filter(([, cat]) => cat.issues.length > 0)
+    .map(([categoryName, cat]) => ({
+      category: categoryName,
+      score: Math.round(cat.score * 10) / 10,
+      weight: cat.weight,
+      deficit: Math.round((10 - cat.score) * cat.weight * 10) / 10,
+      issues: cat.issues
+    }))
+    .sort((a, b) => b.deficit - a.deficit);
+
+  return { score, action, breakdown, priorityFixes, approveThreshold };
+}
+
+/**
+ * Format score breakdown as a human-readable string for hook injection.
+ *
+ * @param {Object} scoreResult - From aggregateScores()
+ * @param {number} [approveThreshold] - For display
+ * @returns {string}
+ */
+export function formatScoreBreakdown(scoreResult, approveThreshold = 8.0) {
+  const lines = [];
+
+  lines.push(`Score: ${scoreResult.score}/10 (threshold: ${approveThreshold})`);
+  lines.push('');
+
+  if (scoreResult.priorityFixes.length > 0) {
+    lines.push('Priority fixes (by impact):');
+    for (let i = 0; i < scoreResult.priorityFixes.length; i++) {
+      const fix = scoreResult.priorityFixes[i];
+      const topIssue = fix.issues[0];
+      const issueText = topIssue
+        ? `${topIssue.message}${topIssue.file ? ` (${topIssue.file}${topIssue.line ? ':' + topIssue.line : ''})` : ''}`
+        : 'Issues detected';
+      lines.push(`${i + 1}. [${fix.category}: ${fix.score}/10] ${issueText}`);
+      // Show additional issues count if more than 1
+      if (fix.issues.length > 1) {
+        lines.push(`   ... and ${fix.issues.length - 1} more issue(s) in this category`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('Score breakdown:');
+  for (const [category, data] of Object.entries(scoreResult.breakdown)) {
+    const pct = Math.round(data.weight * 100);
+    const indicator = data.score >= approveThreshold ? '\u2713' : data.score >= 6 ? '\u2193 needs work' : '\u2193\u2193 critical';
+    lines.push(`  ${category}: ${Math.round(data.score * 10) / 10}/10 (weight ${pct}%) ${indicator}`);
+  }
+
+  return lines.join('\n');
+}

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

@@ -13,6 +13,7 @@ import chalk from 'chalk';
 import { loadState } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../core/paths/output-schema.js';
 import { getStackProfile } from '../stack/stack-profile.js';
+import { aggregateScores, loadRubric } from './score-aggregator.js';
 
 /** Validators that only make sense for .NET projects. */
 const DOTNET_ONLY_VALIDATORS = new Set([
@@ -172,6 +173,17 @@ export async function runValidation(projectPath, featureName, options = {}) {
     ? `✅ All validations passed (${result.warnings} warnings)`
     : `❌ ${result.errors} error(s), ${result.warnings} warning(s)`;
 
+  // Score aggregation — layered on top of pass/fail
+  try {
+    const rubricId = readRubricConfig(projectPath);
+    const rubric = loadRubric(projectPath, rubricId);
+    const thresholdOverrides = readThresholdConfig(projectPath);
+    result.scores = aggregateScores(result, rubric, thresholdOverrides);
+  } catch {
+    // Score aggregation is non-blocking — if it fails, pass/fail still works
+    result.scores = null;
+  }
+
   return result;
 }
 
@@ -303,3 +315,35 @@ export function formatValidationResults(result) {
 
   console.log('');
 }
+
+/**
+ * Read rubric ID from project config.
+ * @param {string} projectPath
+ * @returns {string}
+ */
+function readRubricConfig(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return 'default';
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    return config.validation?.rubric ?? 'default';
+  } catch {
+    return 'default';
+  }
+}
+
+/**
+ * Read threshold overrides from project config.
+ * @param {string} projectPath
+ * @returns {Object} { approve?: number, retry?: number }
+ */
+function readThresholdConfig(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return {};
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    return config.validation?.thresholds ?? {};
+  } catch {
+    return {};
+  }
+}

package/src/scripts/setup-infra.js

@@ -227,6 +227,14 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await copyDirectory(hooksSrc, hooksDest);
   }
 
+  // --- 7b. Copy framework/rubrics → .morph/framework/rubrics ---
+  log('Step 7b: Copying rubrics...');
+  const rubricsSrc = join(FRAMEWORK_DIR, 'rubrics');
+  const rubricsDest = join(frameworkDestDir, 'rubrics');
+  if (await pathExists(rubricsSrc)) {
+    await copyDirectory(rubricsSrc, rubricsDest);
+  }
+
   // --- 8. Copy framework/agents.json → .morph/framework/agents.json ---
   log('Step 8: Copying agents.json...');
   const agentsSrc = join(FRAMEWORK_DIR, 'agents.json');