@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

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

@@ -1,17 +1,134 @@
-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)}`;
-      }
-    },
-  };
-}
+import { scanAll } from './scanner/index.js';
+import { classifyChange, watchTargets, isMorphDataReload } from './scanner/project-api.js';
+import { createPortfolio } from './scanner/portfolio.js';
+
+const VIRTUAL_MODULE_ID = 'virtual:morph-data';
+const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_MODULE_ID;
+const DEBOUNCE_MS = 300;
+const RESCAN_MS = 30_000;
+const WARM_GAP_MS = 400;
+const MAX_BODY = 64 * 1024;
+
+function readBody(req) {
+  return new Promise((resolveBody) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => { size += c.length; if (size <= MAX_BODY) chunks.push(c); });
+    req.on('end', () => {
+      try { resolveBody(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : null); } catch { resolveBody(null); }
+    });
+    req.on('error', () => resolveBody(null));
+  });
+}
+
+/**
+ * Two data paths:
+ *   - `virtual:morph-data` — the framework's knowledge (agents, phases, skills,
+ *     standards, rules, hooks, docs). Static for the life of the server.
+ *   - `/api/morph/*` — the portfolio (`/projects`) and each project's features
+ *     and activity (`/p/:id/…`), read on demand and pushed as `morph:changed`
+ *     over the HMR socket when a project's `.morph/` changes.
+ */
+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);
+        return `export default ${JSON.stringify(data)}`;
+      }
+    },
+    configureServer(server) {
+      const portfolio = createPortfolio({ launchDir: projectDir });
+      const push = (data) => server.ws.send({ type: 'custom', event: 'morph:changed', data });
+
+      // Vite reloads the whole page for any changed .html it watches, even when
+      // handleHotUpdate returns [] (vite 6: no module matched + .html = full
+      // reload). A project's .morph/ carries .html design sources, and an agent
+      // writing one reloaded the dashboard under the person reading it. The
+      // dashboard's own code never lives under .morph/.
+      const clientHot = server.environments?.client?.hot;
+      if (clientHot?.send) {
+        const send = clientHot.send.bind(clientHot);
+        clientHot.send = (payload, ...rest) => {
+          if (payload?.type === 'full-reload' && isMorphDataReload(payload.path)) return;
+          send(payload, ...rest);
+        };
+      }
+
+      const watched = new Set();
+      function watchNew() {
+        const fresh = portfolio.list().flatMap((p) => watchTargets(p.dir)).filter((p) => !watched.has(p));
+        for (const p of fresh) watched.add(p);
+        if (fresh.length) server.watcher.add(fresh);
+      }
+
+      // Read the projects in the background, one at a time, so neither the first
+      // page nor the portfolio waits for a large project. Reading one blocks the
+      // event loop for seconds, so each step waits WARM_GAP_MS first: the reads
+      // a push (or an add) just caused are served before the next block.
+      let warming = false;
+      function warmSoon() {
+        if (warming) return;
+        warming = true;
+        const step = () => {
+          const warmed = portfolio.warmNext();
+          if (!warmed) { warming = false; return; }
+          push({ scope: 'projects' });
+          setTimeout(step, WARM_GAP_MS);
+        };
+        setTimeout(step, WARM_GAP_MS);
+      }
+
+      server.middlewares.use('/api/morph', async (req, res) => {
+        const body = req.method === 'POST' ? await readBody(req) : null;
+        const { status, body: out } = portfolio.handle(req.method || 'GET', req.url || '/', body);
+        res.statusCode = status;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-store');
+        res.end(JSON.stringify(out));
+        // The portfolio's list changed: watch and read any project just added.
+        if (req.method !== 'GET' && status === 200) { watchNew(); push({ scope: 'projects' }); warmSoon(); }
+      });
+
+      watchNew();
+      warmSoon();
+      const rescan = setInterval(watchNew, RESCAN_MS);
+      rescan.unref?.();
+
+      const timers = new Map();
+      const changed = new Map(); // `${project}:${scope}` -> path -> watcher event, in the debounce window
+      const onFsEvent = (event, path) => {
+        const scope = classifyChange(path);
+        if (!scope) return;
+        const project = portfolio.ownerOf(path);
+        if (!project) return;
+        const key = `${project.id}:${scope}`;
+        if (!changed.has(key)) changed.set(key, new Map());
+        const seen = changed.get(key);
+        // A path added then changed in one window is still an add.
+        if (!seen.has(path) || seen.get(path) === 'change') seen.set(path, event);
+        clearTimeout(timers.get(key));
+        timers.set(key, setTimeout(() => {
+          timers.delete(key);
+          const paths = changed.get(key) || new Map();
+          changed.delete(key);
+          for (const [p, event] of paths) portfolio.invalidate(project, scope, p, event);
+          if (scope === 'features') watchNew();
+          push({ scope, project: project.id });
+          // A log append is tailed on read, so the portfolio can refresh now; a
+          // feature change is re-read in the background first, then pushed.
+          if (scope === 'activity') push({ scope: 'projects' });
+          else warmSoon();
+        }, DEBOUNCE_MS));
+      };
+      for (const evt of ['add', 'change', 'unlink', 'addDir', 'unlinkDir']) server.watcher.on(evt, (path) => onFsEvent(evt, path));
+      server.httpServer?.once('close', () => clearInterval(rescan));
+    },
+    // A changed `.morph/` file is data, not a module: never let it reach HMR.
+    handleHotUpdate(ctx) {
+      if (classifyChange(ctx.file)) return [];
+    },
+  };
+}

package/src/lib/detectors/claude-config-detector.js

@@ -15,13 +15,12 @@ import { homedir } from 'os';
  * Detect Claude Code configuration for a project.
  *
  * @param {string} targetPath - Root path of the project
- * @returns {{ plugins: string[], mcpServers: Array<{name: string, config: Object}>, superpowers: boolean, customSkills: string[], customCommands: string[], hooks: string[] }}
+ * @returns {{ plugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
  */
 export function detectClaudeConfig(targetPath) {
   const result = {
     plugins: [],
     mcpServers: [],
-    superpowers: false,
     customSkills: [],
     customCommands: [],
     hooks: [],
@@ -86,7 +85,6 @@ export function detectClaudeConfig(targetPath) {
         const pluginsData = JSON.parse(readFileSync(pluginsPath, 'utf8'));
         const plugins = pluginsData.plugins || {};
         result.plugins = Object.keys(plugins);
-        result.superpowers = 'superpowers@claude-plugins-official' in plugins;
       } catch { /* invalid JSON */ }
     }
 
@@ -166,7 +164,7 @@ export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
 /**
  * Format a human-readable one-liner summary of detected config.
  *
- * @param {{ plugins: string[], mcpServers: Array<{name: string}>, superpowers: boolean }} config
+ * @param {{ plugins: string[], mcpServers: Array<{name: string}> }} config
  * @returns {string}
  */
 export function formatConfigSummary(config) {
@@ -177,8 +175,5 @@ export function formatConfigSummary(config) {
   if (config.plugins.length > 0) {
     parts.push(`Plugins: ${config.plugins.length}`);
   }
-  if (config.superpowers) {
-    parts.push('superpowers: yes');
-  }
   return parts.join(' | ') || 'No Claude config detected';
 }

package/src/lib/detectors/index.js

@@ -2,7 +2,7 @@
  * @fileoverview Project Detector
  *
  * Scans a project directory for stack, architecture, UI library, and integrations.
- * Used by mcp-setup, morph-init, and session-start hooks.
+ * Used by `morph-spec init`, `mcp setup` and the test-node fallback (test-nodes.js).
  *
  * @module detectors/index
  */
@@ -106,6 +106,10 @@ export function detectProject(targetPath, opts = {}) {
         if (content.includes('Hangfire')) {
           if (!structure.integrations.includes('hangfire')) structure.integrations.push('hangfire');
         }
+        // Same heuristic as the package.json side (`pg`/`postgres` → neon).
+        if (content.includes('Npgsql')) {
+          if (!structure.integrations.includes('neon')) structure.integrations.push('neon');
+        }
       } catch { /* ignore */ }
     }
 

package/src/lib/evaluator-report.js

@@ -349,3 +349,25 @@ export function mediaProofScore(proofScores) {
   const value = proofScores?.media;
   return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+
+/**
+ * Os dois vereditos do relatório lidos de um TEXTO já em mãos — o score
+ * composto vigente e os Proof-Scores vigentes, pela mesma regra append-only
+ * (o último token vale) dos leitores por `cwd` acima.
+ *
+ * Existe para quem tem o relatório fora do caminho canônico — o dashboard lê
+ * features arquivadas em `.morph/archive/{f}/4-review/` —, sem que ele
+ * precise de uma segunda cópia dos regexes.
+ *
+ * @param {string} text
+ * @returns {{ score: number|undefined, proofScores: Record<string, number>|undefined }}
+ */
+export function evaluatorVerdictFromText(text) {
+  if (typeof text !== 'string') return { score: undefined, proofScores: undefined };
+  const scores = compositeScoresIn(text);
+  const lines = [...text.matchAll(PROOF_SCORES_RE)];
+  return {
+    score: scores.length === 0 ? undefined : scores[scores.length - 1],
+    proofScores: lines.length === 0 ? undefined : parseProofScores(lines[lines.length - 1][1]),
+  };
+}

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

@@ -1,209 +1,208 @@
-/**
- * Settings Generator
- *
- * Generates .claude/settings.local.json for projects based on detected
- * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
- * to track managed entries for safe reset.
- */
-
-import { join } from 'path';
-import { existsSync } from 'fs';
-import { readFile, writeFile, mkdir } from 'fs/promises';
-
-const MORPH_MANAGED_KEY = '_morph_managed';
-
-/**
- * Generate and merge settings for a project
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
- * @returns {Promise<Object>} Generated settings summary
- */
-export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
-  const claudeDir = join(targetPath, '.claude');
-  const settingsPath = join(claudeDir, 'settings.local.json');
-
-  // Read existing settings
-  const existing = await readSettingsSafe(settingsPath);
-
-  // Build stack-based permissions
-  const stack = morphConfig?.project?.architecture || 'unknown';
-  const permissions = buildPermissions(stack, detectedConfig);
-
-  // Build generated settings
-  const generated = {};
-
-  if (permissions.length > 0) {
-    generated.permissions = permissions;
-  }
-
-  // Track what we manage
-  const managed = {
-    permissions_added: permissions,
-    mcps_detected: detectedConfig.mcpServers.map(s => s.name),
-    plugins_detected: detectedConfig.plugins.map(p => p.name),
-    generated_at: new Date().toISOString()
-  };
-
-  // Merge without overwriting user config
-  const merged = mergeSettings(existing, generated);
-  merged[MORPH_MANAGED_KEY] = managed;
-
-  // Ensure directory exists
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
-
-  await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
-
-  return {
-    settingsPath,
-    permissionsAdded: permissions.length,
-    managed
-  };
-}
-
-/**
- * Build permission rules based on detected stack
- * @param {string} stack - Detected project stack
- * @param {Object} detectedConfig - Detected Claude config
- * @returns {Array<string>} Permission patterns
- */
-export function buildPermissions(stack, detectedConfig = {}) {
-  const permissions = [];
-
-  // Stack-based permissions
-  const stackPermissions = {
-    nodejs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    typescript: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)', 'Bash(tsc:*)'],
-    nextjs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    react: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    vue: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
-    dotnet: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
-    python: ['Bash(python:*)', 'Bash(pip:*)', 'Bash(pytest:*)'],
-    go: ['Bash(go:*)']
-  };
-
-  if (stackPermissions[stack]) {
-    permissions.push(...stackPermissions[stack]);
-  }
-
-  // morph-spec CLI always needs node/npx
-  if (!permissions.includes('Bash(npx:*)')) {
-    permissions.push('Bash(npx:*)');
-  }
-
-  return permissions;
-}
-
-/**
- * Deep merge settings without overwriting user entries
- * @param {Object} existing - Current settings.local.json
- * @param {Object} generated - Generated settings to merge
- * @returns {Object} Merged settings
- */
-export function mergeSettings(existing, generated) {
-  const result = { ...existing };
-
-  for (const [key, value] of Object.entries(generated)) {
-    if (key === MORPH_MANAGED_KEY) continue;
-
-    if (Array.isArray(value) && Array.isArray(result[key])) {
-      // Merge arrays without duplicates
-      const set = new Set(result[key]);
-      for (const item of value) {
-        set.add(item);
-      }
-      result[key] = [...set];
-    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      // Recursively merge objects
-      result[key] = mergeSettings(result[key] || {}, value);
-    } else if (!(key in result)) {
-      // Only add new keys, never overwrite existing
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Remove only morph-spec managed entries from settings
- * @param {string} settingsPath - Path to settings.local.json
- * @returns {Promise<Object>} Summary of what was removed
- */
-export async function resetMorphSettings(settingsPath) {
-  if (!existsSync(settingsPath)) {
-    return { removed: false, reason: 'file not found' };
-  }
-
-  const settings = await readSettingsSafe(settingsPath);
-  const managed = settings[MORPH_MANAGED_KEY];
-
-  if (!managed) {
-    return { removed: false, reason: 'no _morph_managed section found' };
-  }
-
-  // Remove managed permissions
-  if (managed.permissions_added && Array.isArray(settings.permissions)) {
-    settings.permissions = settings.permissions.filter(
-      p => !managed.permissions_added.includes(p)
-    );
-    if (settings.permissions.length === 0) {
-      delete settings.permissions;
-    }
-  }
-
-  // Remove the managed marker itself
-  delete settings[MORPH_MANAGED_KEY];
-
-  // Write back
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-
-  return {
-    removed: true,
-    permissionsRemoved: managed.permissions_added || [],
-    previouslyGenerated: managed.generated_at
-  };
-}
-
-/**
- * Save integrations.json with detected config
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- */
-export async function saveIntegrations(targetPath, detectedConfig) {
-  const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
-  const integrationsDir = join(targetPath, '.morph', 'config');
-
-  if (!existsSync(integrationsDir)) {
-    await mkdir(integrationsDir, { recursive: true });
-  }
-
-  const integrations = {
-    version: '1.0.0',
-    detectedAt: new Date().toISOString(),
-    plugins: detectedConfig.plugins,
-    mcpServers: detectedConfig.mcpServers,
-    superpowers: detectedConfig.superpowers,
-    customSkills: detectedConfig.customSkills.length,
-    customCommands: detectedConfig.customCommands.length,
-    hooks: detectedConfig.hooks.length
-  };
-
-  await writeFile(integrationsPath, JSON.stringify(integrations, null, 2) + '\n', 'utf-8');
-  return integrationsPath;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-async function readSettingsSafe(settingsPath) {
-  try {
-    if (!existsSync(settingsPath)) return {};
-    return JSON.parse(await readFile(settingsPath, 'utf-8'));
-  } catch {
-    return {};
-  }
-}
+/**
+ * Settings Generator
+ *
+ * Generates .claude/settings.local.json for projects based on detected
+ * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
+ * to track managed entries for safe reset.
+ */
+
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+
+const MORPH_MANAGED_KEY = '_morph_managed';
+
+/**
+ * Generate and merge settings for a project
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
+ * @returns {Promise<Object>} Generated settings summary
+ */
+export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings
+  const existing = await readSettingsSafe(settingsPath);
+
+  // Build stack-based permissions
+  const stack = morphConfig?.project?.architecture || 'unknown';
+  const permissions = buildPermissions(stack, detectedConfig);
+
+  // Build generated settings
+  const generated = {};
+
+  if (permissions.length > 0) {
+    generated.permissions = permissions;
+  }
+
+  // Track what we manage
+  const managed = {
+    permissions_added: permissions,
+    mcps_detected: detectedConfig.mcpServers.map(s => s.name),
+    plugins_detected: detectedConfig.plugins.map(p => p.name),
+    generated_at: new Date().toISOString()
+  };
+
+  // Merge without overwriting user config
+  const merged = mergeSettings(existing, generated);
+  merged[MORPH_MANAGED_KEY] = managed;
+
+  // Ensure directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+
+  return {
+    settingsPath,
+    permissionsAdded: permissions.length,
+    managed
+  };
+}
+
+/**
+ * Build permission rules based on detected stack
+ * @param {string} stack - Detected project stack
+ * @param {Object} detectedConfig - Detected Claude config
+ * @returns {Array<string>} Permission patterns
+ */
+export function buildPermissions(stack, detectedConfig = {}) {
+  const permissions = [];
+
+  // Stack-based permissions
+  const stackPermissions = {
+    nodejs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    typescript: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)', 'Bash(tsc:*)'],
+    nextjs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    react: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    vue: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    dotnet: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
+    python: ['Bash(python:*)', 'Bash(pip:*)', 'Bash(pytest:*)'],
+    go: ['Bash(go:*)']
+  };
+
+  if (stackPermissions[stack]) {
+    permissions.push(...stackPermissions[stack]);
+  }
+
+  // morph-spec CLI always needs node/npx
+  if (!permissions.includes('Bash(npx:*)')) {
+    permissions.push('Bash(npx:*)');
+  }
+
+  return permissions;
+}
+
+/**
+ * Deep merge settings without overwriting user entries
+ * @param {Object} existing - Current settings.local.json
+ * @param {Object} generated - Generated settings to merge
+ * @returns {Object} Merged settings
+ */
+export function mergeSettings(existing, generated) {
+  const result = { ...existing };
+
+  for (const [key, value] of Object.entries(generated)) {
+    if (key === MORPH_MANAGED_KEY) continue;
+
+    if (Array.isArray(value) && Array.isArray(result[key])) {
+      // Merge arrays without duplicates
+      const set = new Set(result[key]);
+      for (const item of value) {
+        set.add(item);
+      }
+      result[key] = [...set];
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Recursively merge objects
+      result[key] = mergeSettings(result[key] || {}, value);
+    } else if (!(key in result)) {
+      // Only add new keys, never overwrite existing
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove only morph-spec managed entries from settings
+ * @param {string} settingsPath - Path to settings.local.json
+ * @returns {Promise<Object>} Summary of what was removed
+ */
+export async function resetMorphSettings(settingsPath) {
+  if (!existsSync(settingsPath)) {
+    return { removed: false, reason: 'file not found' };
+  }
+
+  const settings = await readSettingsSafe(settingsPath);
+  const managed = settings[MORPH_MANAGED_KEY];
+
+  if (!managed) {
+    return { removed: false, reason: 'no _morph_managed section found' };
+  }
+
+  // Remove managed permissions
+  if (managed.permissions_added && Array.isArray(settings.permissions)) {
+    settings.permissions = settings.permissions.filter(
+      p => !managed.permissions_added.includes(p)
+    );
+    if (settings.permissions.length === 0) {
+      delete settings.permissions;
+    }
+  }
+
+  // Remove the managed marker itself
+  delete settings[MORPH_MANAGED_KEY];
+
+  // Write back
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return {
+    removed: true,
+    permissionsRemoved: managed.permissions_added || [],
+    previouslyGenerated: managed.generated_at
+  };
+}
+
+/**
+ * Save integrations.json with detected config
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ */
+export async function saveIntegrations(targetPath, detectedConfig) {
+  const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
+  const integrationsDir = join(targetPath, '.morph', 'config');
+
+  if (!existsSync(integrationsDir)) {
+    await mkdir(integrationsDir, { recursive: true });
+  }
+
+  const integrations = {
+    version: '1.0.0',
+    detectedAt: new Date().toISOString(),
+    plugins: detectedConfig.plugins,
+    mcpServers: detectedConfig.mcpServers,
+    customSkills: detectedConfig.customSkills.length,
+    customCommands: detectedConfig.customCommands.length,
+    hooks: detectedConfig.hooks.length
+  };
+
+  await writeFile(integrationsPath, JSON.stringify(integrations, null, 2) + '\n', 'utf-8');
+  return integrationsPath;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+async function readSettingsSafe(settingsPath) {
+  try {
+    if (!existsSync(settingsPath)) return {};
+    return JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}