@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/src/harmony/sync.js

@@ -0,0 +1,458 @@
+/**
+ * Harmony Sync — Unified Setup / Sync Engine
+ *
+ * Generates aligned configs for ALL active platforms from a shared canonical
+ * understanding. Ensures instructions, MCP servers, and trust posture are
+ * consistent across Claude, Codex, Gemini, Copilot, and Cursor.
+ *
+ * Uses managed blocks from each platform's patch module so hand-authored
+ * content is always preserved.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { buildCanonicalModel, PLATFORM_SIGNATURES } = require('./canon');
+
+// ─── Managed block markers (imported from platform patch modules) ───────────
+
+const MANAGED_MARKERS = {
+  claude: {
+    start: '<!-- nerviq:managed:start -->',
+    end: '<!-- nerviq:managed:end -->',
+  },
+  codex: {
+    start: '<!-- nerviq:managed:start -->',
+    end: '<!-- nerviq:managed:end -->',
+  },
+  gemini: {
+    start: '<!-- nerviq:managed:start -->',
+    end: '<!-- nerviq:managed:end -->',
+  },
+  copilot: {
+    start: '<!-- nerviq:managed:start -->',
+    end: '<!-- nerviq:managed:end -->',
+  },
+  cursor: {
+    // Cursor uses MDC format but managed blocks are still HTML-comment-based for .mdc
+    start: '<!-- nerviq:managed:start -->',
+    end: '<!-- nerviq:managed:end -->',
+  },
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function ensureDir(dirPath) {
+  try {
+    fs.mkdirSync(dirPath, { recursive: true });
+  } catch {
+    // Already exists or not writable
+  }
+}
+
+/**
+ * Extract managed block from content.
+ */
+function extractManagedBlock(content, startMarker, endMarker) {
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return { before: content, managed: null, after: '' };
+  }
+
+  return {
+    before: content.substring(0, startIdx),
+    managed: content.substring(startIdx + startMarker.length, endIdx).trim(),
+    after: content.substring(endIdx + endMarker.length),
+  };
+}
+
+/**
+ * Upsert a managed block within content.
+ */
+function upsertManagedBlock(content, newManaged, startMarker, endMarker) {
+  const { before, managed, after } = extractManagedBlock(content, startMarker, endMarker);
+
+  if (managed !== null) {
+    return `${before}${startMarker}\n${newManaged}\n${endMarker}${after}`;
+  }
+
+  const separator = content.endsWith('\n') ? '\n' : '\n\n';
+  return `${content}${separator}${startMarker}\n${newManaged}\n${endMarker}\n`;
+}
+
+// ─── Instruction content builders ───────────────────────────────────────────
+
+/**
+ * Build a shared instruction block that should appear on every platform.
+ * Derived from the canonical model's shared understanding.
+ */
+function buildSharedInstructionBlock(model) {
+  const lines = [];
+
+  lines.push(`## Harmony-Managed Instructions`);
+  lines.push(`<!-- Synced by nerviq harmony. Do not edit this block manually. -->`);
+  lines.push('');
+
+  // Project identity
+  lines.push(`Project: ${model.projectName}`);
+  if (model.stacks.length > 0) {
+    lines.push(`Stacks: ${model.stacks.join(', ')}`);
+  }
+  lines.push('');
+
+  // Shared instructions (if any were found across platforms)
+  if (model.sharedInstructions.length > 0) {
+    lines.push('### Shared Guidelines');
+    for (const instruction of model.sharedInstructions.slice(0, 20)) {
+      lines.push(instruction);
+    }
+    lines.push('');
+  }
+
+  // MCP servers (unified list)
+  const mcpNames = Object.keys(model.mcpServers);
+  if (mcpNames.length > 0) {
+    lines.push('### Available MCP Servers');
+    for (const name of mcpNames) {
+      const server = model.mcpServers[name];
+      lines.push(`- ${name} (on: ${server.platforms.join(', ')})`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Platform-specific file generators ──────────────────────────────────────
+
+/**
+ * Generate the instruction file path for a platform.
+ */
+function getInstructionPath(platform) {
+  switch (platform) {
+    case 'claude': return 'CLAUDE.md';
+    case 'codex': return 'AGENTS.md';
+    case 'gemini': return 'GEMINI.md';
+    case 'copilot': return '.github/copilot-instructions.md';
+    case 'cursor': return '.cursorrules';
+    default: return null;
+  }
+}
+
+/**
+ * Generate MCP config content for a platform based on the unified MCP server list.
+ */
+function buildMcpConfig(platform, mcpServers) {
+  // Filter to servers that should be on this platform
+  const servers = {};
+  for (const [name, server] of Object.entries(mcpServers)) {
+    servers[name] = {
+      command: server.command || 'npx',
+      args: server.args || [],
+    };
+  }
+
+  if (Object.keys(servers).length === 0) return null;
+
+  if (platform === 'claude') {
+    // Claude settings.json format
+    return { mcpServers: servers };
+  }
+
+  if (platform === 'cursor' || platform === 'copilot') {
+    // mcp.json format
+    return { mcpServers: servers };
+  }
+
+  if (platform === 'gemini') {
+    // Gemini settings.json format
+    return { mcpServers: servers };
+  }
+
+  return null;
+}
+
+/**
+ * Get the MCP config file path for a platform.
+ */
+function getMcpConfigPath(platform) {
+  switch (platform) {
+    case 'claude': return '.claude/settings.json';
+    case 'gemini': return '.gemini/settings.json';
+    case 'copilot': return '.vscode/mcp.json';
+    case 'cursor': return '.cursor/mcp.json';
+    default: return null;
+  }
+}
+
+// ─── Trust alignment recommendations ────────────────────────────────────────
+
+/**
+ * Recommend a unified trust posture across all platforms.
+ * Strategy: use the most restrictive trust level present.
+ */
+function recommendTrustPosture(model) {
+  const TRUST_LEVELS = {
+    'locked-down': 0,
+    'default': 1,
+    'unknown': 1,
+    'safe-write': 2,
+    'standard': 2,
+    'no-sandbox': 3,
+    'full-auto': 4,
+    'bypass': 4,
+    'unrestricted': 5,
+  };
+
+  const postures = Object.values(model.trustPosture);
+  if (postures.length === 0) return 'safe-write';
+
+  // Find the most restrictive (lowest) trust level
+  let minLevel = Infinity;
+  let minPosture = 'default';
+  for (const posture of postures) {
+    const level = TRUST_LEVELS[posture] ?? 1;
+    if (level < minLevel) {
+      minLevel = level;
+      minPosture = posture;
+    }
+  }
+
+  return minPosture;
+}
+
+// ─── Main sync functions ────────────────────────────────────────────────────
+
+/**
+ * Generate harmony sync operations from a canonical model.
+ *
+ * For each active platform:
+ *   - Generate/update instruction file with shared managed block
+ *   - Ensure shared MCP servers exist on all platforms that support MCP
+ *   - Report trust posture alignment recommendations
+ *
+ * @param {object} canonicalModel - Output of buildCanonicalModel()
+ * @param {object} [options] - { syncMcp: true, syncInstructions: true, dryRun: false }
+ * @returns {object} { files, summary, warnings }
+ */
+function generateHarmonySync(canonicalModel, options = {}) {
+  const {
+    syncMcp = true,
+    syncInstructions = true,
+  } = options;
+
+  const model = canonicalModel;
+  const files = [];
+  const warnings = [];
+
+  const sharedBlock = buildSharedInstructionBlock(model);
+  const recommendedTrust = recommendTrustPosture(model);
+
+  for (const ap of model.activePlatforms) {
+    const platform = ap.platform;
+
+    // ── Instruction file sync ──
+    if (syncInstructions) {
+      const instrPath = getInstructionPath(platform);
+      if (instrPath) {
+        const fullPath = path.join(model.dir, instrPath);
+        const existingContent = safeReadFile(fullPath);
+        const markers = MANAGED_MARKERS[platform];
+
+        if (existingContent) {
+          // Patch existing file with managed block
+          const updated = upsertManagedBlock(
+            existingContent,
+            sharedBlock,
+            markers.start,
+            markers.end,
+          );
+
+          if (updated !== existingContent) {
+            files.push({
+              platform,
+              path: instrPath,
+              action: 'patch',
+              content: updated,
+              preview: `Update managed block in ${instrPath}`,
+            });
+          }
+        } else {
+          // Create new instruction file with managed block
+          const newContent = `# ${platform === 'codex' ? 'AGENTS' : platform.charAt(0).toUpperCase() + platform.slice(1)} Instructions\n\n` +
+            `${markers.start}\n${sharedBlock}\n${markers.end}\n`;
+
+          files.push({
+            platform,
+            path: instrPath,
+            action: 'create',
+            content: newContent,
+            preview: `Create ${instrPath} with harmony-managed content`,
+          });
+        }
+      }
+    }
+
+    // ── MCP server sync ──
+    if (syncMcp && Object.keys(model.mcpServers).length > 0) {
+      const mcpPath = getMcpConfigPath(platform);
+      if (!mcpPath) continue;  // Codex doesn't support MCP config
+
+      const fullMcpPath = path.join(model.dir, mcpPath);
+      const existingMcp = safeReadFile(fullMcpPath);
+      const mcpConfig = buildMcpConfig(platform, model.mcpServers);
+
+      if (!mcpConfig) continue;
+
+      if (existingMcp) {
+        // Merge: add missing servers, don't overwrite existing
+        let existingJson;
+        try {
+          existingJson = JSON.parse(existingMcp);
+        } catch {
+          warnings.push(`Cannot parse ${mcpPath} — skipping MCP sync for ${platform}`);
+          continue;
+        }
+
+        const existingServers = existingJson.mcpServers || existingJson.servers || {};
+        const newServers = mcpConfig.mcpServers || {};
+        let added = 0;
+
+        for (const [name, config] of Object.entries(newServers)) {
+          if (!existingServers[name]) {
+            existingServers[name] = config;
+            added++;
+          }
+        }
+
+        if (added > 0) {
+          // Preserve the original key name (mcpServers or servers)
+          const serverKey = existingJson.servers ? 'servers' : 'mcpServers';
+          existingJson[serverKey] = existingServers;
+
+          files.push({
+            platform,
+            path: mcpPath,
+            action: 'patch',
+            content: JSON.stringify(existingJson, null, 2) + '\n',
+            preview: `Add ${added} MCP server(s) to ${mcpPath}`,
+          });
+        }
+      } else {
+        // Create new MCP config
+        files.push({
+          platform,
+          path: mcpPath,
+          action: 'create',
+          content: JSON.stringify(mcpConfig, null, 2) + '\n',
+          preview: `Create ${mcpPath} with ${Object.keys(mcpConfig.mcpServers || {}).length} MCP server(s)`,
+        });
+      }
+    }
+  }
+
+  // Trust posture warnings
+  const trustValues = Object.values(model.trustPosture);
+  const uniqueTrust = new Set(trustValues);
+  if (uniqueTrust.size > 1) {
+    warnings.push(
+      `Trust posture varies across platforms. Recommended baseline: "${recommendedTrust}". ` +
+      `Current: ${Object.entries(model.trustPosture).map(([p, t]) => `${p}=${t}`).join(', ')}. ` +
+      `Trust alignment must be applied manually per platform.`
+    );
+  }
+
+  // Summary
+  const creates = files.filter(f => f.action === 'create').length;
+  const patches = files.filter(f => f.action === 'patch').length;
+  const summary = {
+    totalFiles: files.length,
+    creates,
+    patches,
+    platforms: [...new Set(files.map(f => f.platform))],
+    recommendedTrust,
+  };
+
+  return { files, summary, warnings };
+}
+
+/**
+ * Preview sync operations without writing.
+ *
+ * @param {string} dir - Project root directory
+ * @param {object} [options] - Same as generateHarmonySync options
+ * @returns {object} Sync plan (files, summary, warnings)
+ */
+function previewHarmonySync(dir, options = {}) {
+  const model = buildCanonicalModel(dir);
+  return generateHarmonySync(model, options);
+}
+
+/**
+ * Apply harmony sync — write all generated files to disk.
+ *
+ * @param {string} dir - Project root directory
+ * @param {object} [options] - { syncMcp, syncInstructions, dryRun }
+ * @returns {object} { applied, skipped, warnings }
+ */
+function applyHarmonySync(dir, options = {}) {
+  const { dryRun = false } = options;
+  const model = buildCanonicalModel(dir);
+  const sync = generateHarmonySync(model, options);
+
+  if (dryRun) {
+    return {
+      applied: [],
+      skipped: sync.files.map(f => f.path),
+      warnings: sync.warnings,
+      plan: sync,
+    };
+  }
+
+  const applied = [];
+  const skipped = [];
+
+  for (const file of sync.files) {
+    const fullPath = path.join(dir, file.path);
+
+    try {
+      // Ensure parent directory exists
+      ensureDir(path.dirname(fullPath));
+
+      fs.writeFileSync(fullPath, file.content, 'utf8');
+      applied.push({
+        platform: file.platform,
+        path: file.path,
+        action: file.action,
+      });
+    } catch (err) {
+      skipped.push({
+        platform: file.platform,
+        path: file.path,
+        reason: err.message,
+      });
+    }
+  }
+
+  return {
+    applied,
+    skipped,
+    warnings: sync.warnings,
+    summary: sync.summary,
+  };
+}
+
+module.exports = {
+  generateHarmonySync,
+  applyHarmonySync,
+  previewHarmonySync,
+};