@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/src/lib/context/context-bundler.js

@@ -0,0 +1,240 @@
+/**
+ * Context Bundler — Checkpoint compression (180K → 15K)
+ *
+ * Compresses checkpoint state into a compact bundle for session resumption.
+ * Saves bundles to .morph/bundles/{bundleId}.json
+ *
+ * A bundle contains:
+ *   - decisions[]: key architectural decisions made
+ *   - artifacts[]: paths to important generated files
+ *   - nextSteps[]: what to implement next
+ *   - metadata: original vs bundled token counts
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+const BUNDLES_DIR = join(process.cwd(), '.morph/bundles');
+
+// ============================================================================
+// Bundle Creation
+// ============================================================================
+
+/**
+ * Create a context bundle from checkpoint data
+ * @param {Object} opts
+ * @param {string} opts.feature - Feature name
+ * @param {number} opts.checkpointNum - Checkpoint number this bundle captures
+ * @param {Array} opts.decisions - Key decisions made: [{ id, title, summary }]
+ * @param {Array} opts.artifacts - Important file paths: [{ path, description }]
+ * @param {Array} opts.nextSteps - Next tasks to implement: [string]
+ * @param {number} [opts.originalTokens=180000] - Estimated original context size
+ * @param {Object} [opts.meta] - Additional metadata
+ * @returns {Object} Bundle object with ID
+ */
+export function createBundle({
+  feature,
+  checkpointNum,
+  decisions = [],
+  artifacts = [],
+  nextSteps = [],
+  originalTokens = 180000,
+  meta = {}
+}) {
+  const bundleId = `${feature}-cp${checkpointNum}-${randomUUID().substring(0, 8)}`;
+  const now = new Date().toISOString();
+
+  // Estimate bundle size (decisions + artifacts + nextSteps summary)
+  const bundledContent = JSON.stringify({ decisions, artifacts, nextSteps, meta });
+  const bundledTokens = Math.round(bundledContent.length / 4); // ~4 chars/token
+
+  const bundle = {
+    bundleId,
+    feature,
+    checkpointNum,
+    createdAt: now,
+    decisions,
+    artifacts,
+    nextSteps,
+    meta,
+    tokenMetrics: {
+      originalTokens,
+      bundledTokens,
+      compressionRatio: Math.round(originalTokens / Math.max(bundledTokens, 1)),
+      savingsTokens: originalTokens - bundledTokens
+    },
+    resumeInstructions: buildResumeInstructions(feature, checkpointNum, decisions, nextSteps)
+  };
+
+  return bundle;
+}
+
+/**
+ * Save a bundle to disk
+ * @param {Object} bundle - Bundle object (from createBundle)
+ * @returns {string} Path to saved bundle file
+ */
+export function saveBundle(bundle) {
+  if (!existsSync(BUNDLES_DIR)) {
+    mkdirSync(BUNDLES_DIR, { recursive: true });
+  }
+
+  const filePath = join(BUNDLES_DIR, `${bundle.bundleId}.json`);
+  writeFileSync(filePath, JSON.stringify(bundle, null, 2), 'utf8');
+
+  // Also update feature state with bundle reference
+  try {
+    const statePath = join(process.cwd(), '.morph/state.json');
+    if (existsSync(statePath)) {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      if (state.features?.[bundle.feature]) {
+        state.features[bundle.feature].contextBundles = state.features[bundle.feature].contextBundles || [];
+        state.features[bundle.feature].contextBundles.push({
+          bundleId: bundle.bundleId,
+          checkpointNum: bundle.checkpointNum,
+          createdAt: bundle.createdAt,
+          originalTokens: bundle.tokenMetrics.originalTokens,
+          bundledTokens: bundle.tokenMetrics.bundledTokens,
+          path: filePath
+        });
+        state.metadata = state.metadata || {};
+        state.metadata.lastUpdated = new Date().toISOString();
+        writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+  } catch {
+    // Non-fatal if state update fails
+  }
+
+  return filePath;
+}
+
+/**
+ * Load a bundle from disk
+ * @param {string} bundleId - Bundle ID
+ * @returns {Object|null} Bundle object or null if not found
+ */
+export function loadBundle(bundleId) {
+  const filePath = join(BUNDLES_DIR, `${bundleId}.json`);
+
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all bundles, optionally filtered by feature
+ * @param {string} [feature] - Filter by feature name
+ * @returns {Array} Array of bundle summaries
+ */
+export function listBundles(feature = null) {
+  if (!existsSync(BUNDLES_DIR)) return [];
+
+  const files = readdirSync(BUNDLES_DIR).filter(f => f.endsWith('.json'));
+  const bundles = [];
+
+  for (const file of files) {
+    try {
+      const bundle = JSON.parse(readFileSync(join(BUNDLES_DIR, file), 'utf8'));
+      if (!feature || bundle.feature === feature) {
+        bundles.push({
+          bundleId: bundle.bundleId,
+          feature: bundle.feature,
+          checkpointNum: bundle.checkpointNum,
+          createdAt: bundle.createdAt,
+          originalTokens: bundle.tokenMetrics?.originalTokens,
+          bundledTokens: bundle.tokenMetrics?.bundledTokens,
+          compressionRatio: bundle.tokenMetrics?.compressionRatio,
+          nextStepsCount: bundle.nextSteps?.length || 0
+        });
+      }
+    } catch {
+      // Skip malformed files
+    }
+  }
+
+  return bundles.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+}
+
+/**
+ * Get the latest bundle for a feature at or before a checkpoint number
+ * @param {string} feature - Feature name
+ * @param {number} [checkpointNum] - Target checkpoint (latest if not specified)
+ * @returns {Object|null} Bundle or null
+ */
+export function getLatestBundle(feature, checkpointNum = Infinity) {
+  const bundles = listBundles(feature)
+    .filter(b => b.checkpointNum <= checkpointNum)
+    .sort((a, b) => b.checkpointNum - a.checkpointNum);
+
+  if (bundles.length === 0) return null;
+  return loadBundle(bundles[0].bundleId);
+}
+
+// ============================================================================
+// Session Replay
+// ============================================================================
+
+/**
+ * Generate minimal context for session replay from a bundle
+ * @param {Object} bundle - Bundle object
+ * @returns {string} Compact context string (~15K tokens) for session resumption
+ */
+export function generateResumeContext(bundle) {
+  const lines = [];
+  lines.push(`# Session Resume — ${bundle.feature} @ Checkpoint ${bundle.checkpointNum}`);
+  lines.push(`> Bundle ID: ${bundle.bundleId} | Created: ${bundle.createdAt}`);
+  lines.push(`> Context compression: ${bundle.tokenMetrics?.originalTokens?.toLocaleString()} → ${bundle.tokenMetrics?.bundledTokens?.toLocaleString()} tokens`);
+  lines.push('');
+
+  if (bundle.decisions?.length > 0) {
+    lines.push('## Key Decisions Made');
+    for (const d of bundle.decisions) {
+      lines.push(`- **${d.id || ''}${d.id ? ':' : ''} ${d.title}** — ${d.summary}`);
+      if (d.fullPath) lines.push(`  *(Full: ${d.fullPath})*`);
+    }
+    lines.push('');
+  }
+
+  if (bundle.artifacts?.length > 0) {
+    lines.push('## Created Artifacts');
+    for (const a of bundle.artifacts) {
+      lines.push(`- \`${a.path}\` — ${a.description || ''}`);
+    }
+    lines.push('');
+  }
+
+  if (bundle.nextSteps?.length > 0) {
+    lines.push('## Next Steps (continue from here)');
+    bundle.nextSteps.forEach((step, i) => {
+      lines.push(`${i + 1}. ${step}`);
+    });
+    lines.push('');
+  }
+
+  lines.push(bundle.resumeInstructions || '');
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function buildResumeInstructions(feature, checkpointNum, decisions, nextSteps) {
+  return `## Resume Instructions
+
+1. Load minimal standards: run \`morph-spec prime feature\`
+2. Read spec: \`.morph/project/outputs/${feature}/spec.md\` (key sections only)
+3. Check tasks: \`morph-spec state get ${feature}\`
+4. Continue from: ${nextSteps[0] || `task after checkpoint ${checkpointNum}`}
+
+> This bundle was created at checkpoint ${checkpointNum}. All decisions above are final.`;
+}

package/src/lib/context/context-optimizer.js

@@ -0,0 +1,212 @@
+/**
+ * Context Optimizer — Selective context loading strategy
+ *
+ * Provides intelligent recommendations for reducing context window usage:
+ * - selectStandards: pick only relevant standards for a feature type
+ * - selectTemplates: pick only relevant templates
+ * - suggestOptimizations: compare current vs optimal context, return savings
+ *
+ * Connects to standards resolver and template registry.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const STANDARDS_DIR = join(process.cwd(), 'framework/standards');
+const TEMPLATES_REGISTRY = join(process.cwd(), 'framework/templates/REGISTRY.json');
+
+// Average token cost estimates per file type
+const TOKEN_ESTIMATES = {
+  standard_file: 2000,
+  template_file: 1500,
+  claude_md: 23000,
+  spec_file: 8000,
+  decisions_file: 3000
+};
+
+// Feature type → relevant standards mapping
+const STANDARDS_BY_FEATURE_TYPE = {
+  backend: [
+    'coding.md', 'architecture.md', 'dotnet10-compatibility.md',
+    'integration/api/rest-design.md'
+  ],
+  frontend: [
+    'coding.md', 'blazor-components.md', 'blazor-state.md',
+    'css-architecture.md', 'css-design-system.md'
+  ],
+  database: [
+    'coding.md', 'ef-core.md', 'architecture.md'
+  ],
+  infrastructure: [
+    'azure.md', 'bicep.md', 'devops.md'
+  ],
+  authentication: [
+    'coding.md', 'architecture.md', 'dotnet10-compatibility.md',
+    'integration/api/rest-design.md'
+  ],
+  fullstack: [
+    'coding.md', 'architecture.md', 'blazor-components.md',
+    'ef-core.md', 'dotnet10-compatibility.md'
+  ],
+  observability: [
+    'observability/monitoring.md', 'observability/logging.md',
+    'observability/tracing.md', 'observability/metrics.md'
+  ],
+  event_driven: [
+    'integration/event-driven/service-bus.md',
+    'integration/event-driven/cqrs.md'
+  ]
+};
+
+// ============================================================================
+// Standards Selection
+// ============================================================================
+
+/**
+ * Select minimal relevant standards for a given feature type
+ * @param {string} featureType - Feature type keyword
+ * @param {Object} [opts]
+ * @param {string[]} [opts.extraKeywords] - Additional keywords for selection
+ * @returns {Object} { selected: string[], skipped: string[], estimatedTokens: number }
+ */
+export function selectStandards(featureType, { extraKeywords = [] } = {}) {
+  const typeKey = detectFeatureCategory(featureType, extraKeywords);
+  const selected = STANDARDS_BY_FEATURE_TYPE[typeKey] || STANDARDS_BY_FEATURE_TYPE.fullstack;
+
+  // Check which selected files actually exist
+  const existing = selected.filter(f => {
+    const fullPath = join(STANDARDS_DIR, f);
+    return existsSync(fullPath);
+  });
+
+  // Estimate all standard files count for skipped calculation
+  const allStandards = getAllStandardsCount();
+  const skippedCount = allStandards - existing.length;
+
+  return {
+    selected: existing,
+    skipped: skippedCount,
+    featureType: typeKey,
+    estimatedTokens: existing.length * TOKEN_ESTIMATES.standard_file,
+    fullLoadTokens: allStandards * TOKEN_ESTIMATES.standard_file,
+    savings: skippedCount * TOKEN_ESTIMATES.standard_file
+  };
+}
+
+/**
+ * Select relevant templates for a feature type
+ * @param {string} featureType - Feature type keyword
+ * @returns {Object} { selected: string[], estimatedTokens: number }
+ */
+export function selectTemplates(featureType) {
+  const TEMPLATES_BY_TYPE = {
+    backend: ['dotnet-backend-service', 'dotnet-repository', 'dotnet-api-contracts'],
+    frontend: ['dotnet-blazor-component', 'dotnet-design-system'],
+    database: ['dotnet-migration', 'sql-migration'],
+    infrastructure: ['azure-container-app', 'azure-key-vault', 'azure-main-bicep'],
+    fullstack: ['dotnet-backend-service', 'dotnet-blazor-component', 'dotnet-migration']
+  };
+
+  const typeKey = detectFeatureCategory(featureType, []);
+  const selected = TEMPLATES_BY_TYPE[typeKey] || TEMPLATES_BY_TYPE.fullstack;
+
+  // Load registry to get full template count
+  let totalTemplates = 50;
+  try {
+    const registry = JSON.parse(readFileSync(TEMPLATES_REGISTRY, 'utf8'));
+    totalTemplates = (registry.templates || []).length;
+  } catch {
+    // Use estimate
+  }
+
+  return {
+    selected,
+    skipped: totalTemplates - selected.length,
+    estimatedTokens: selected.length * TOKEN_ESTIMATES.template_file,
+    fullLoadTokens: totalTemplates * TOKEN_ESTIMATES.template_file,
+    savings: (totalTemplates - selected.length) * TOKEN_ESTIMATES.template_file
+  };
+}
+
+/**
+ * Suggest context optimizations based on current vs optimal load
+ * @param {Object} current - Current context state
+ * @param {number} current.totalTokens - Current token count
+ * @param {number} current.standardsCount - Number of standards currently loaded
+ * @param {number} current.templatesCount - Number of templates currently loaded
+ * @param {string} featureType - Feature type for optimal selection
+ * @returns {Object} Optimization suggestions with savings estimates
+ */
+export function suggestOptimizations(current, featureType) {
+  const optimalStandards = selectStandards(featureType);
+  const optimalTemplates = selectTemplates(featureType);
+  const suggestions = [];
+
+  // Claude.md optimization
+  if (current.totalTokens > 50000) {
+    suggestions.push({
+      type: 'priming_file',
+      title: 'Use priming file instead of full CLAUDE.md',
+      description: 'Replace 23K token CLAUDE.md with a 500-token priming file',
+      savings: TOKEN_ESTIMATES.claude_md - 500,
+      priority: 'high',
+      command: 'morph-spec prime feature'
+    });
+  }
+
+  // Standards optimization
+  if (current.standardsCount > optimalStandards.selected.length + 3) {
+    suggestions.push({
+      type: 'standards_subset',
+      title: `Load only ${optimalStandards.selected.length} relevant standards`,
+      description: `Currently loading ${current.standardsCount} standards. Only ${optimalStandards.selected.length} are needed for ${featureType} features.`,
+      savings: optimalStandards.savings,
+      priority: 'medium',
+      selectedStandards: optimalStandards.selected
+    });
+  }
+
+  // Context bundle for large sessions
+  if (current.totalTokens > 100000) {
+    suggestions.push({
+      type: 'context_bundle',
+      title: 'Create context bundle checkpoint',
+      description: 'Compress current context (180K → ~15K tokens) for session resume',
+      savings: current.totalTokens - 15000,
+      priority: 'critical',
+      command: 'morph-spec bundle create'
+    });
+  }
+
+  const totalSavings = suggestions.reduce((sum, s) => sum + s.savings, 0);
+  const optimizedTokens = Math.max(current.totalTokens - totalSavings, 5000);
+
+  return {
+    currentTokens: current.totalTokens,
+    optimizedTokens,
+    totalSavings,
+    savingsPercent: Math.round(totalSavings / current.totalTokens * 100),
+    suggestions: suggestions.sort((a, b) => b.savings - a.savings)
+  };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function detectFeatureCategory(featureType, extraKeywords) {
+  const text = (featureType + ' ' + extraKeywords.join(' ')).toLowerCase();
+
+  if (/auth|login|jwt|oauth|identity/.test(text)) return 'authentication';
+  if (/blazor|frontend|ui|component|razor/.test(text)) return 'frontend';
+  if (/migration|ef.core|database|entity/.test(text)) return 'database';
+  if (/bicep|azure|infra|container|devops/.test(text)) return 'infrastructure';
+  if (/service.bus|cqrs|event.sourcing|pub.sub/.test(text)) return 'event_driven';
+  if (/monitor|logging|trace|metric|appinsight/.test(text)) return 'observability';
+  if (/api|endpoint|controller|rest/.test(text)) return 'backend';
+  return 'fullstack';
+}
+
+function getAllStandardsCount() {
+  return 30; // Known approximate count
+}