@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/src/lib/tracking/artifact-trail.js

@@ -0,0 +1,202 @@
+/**
+ * Artifact Trail — Debugging trail system
+ *
+ * Creates checkpoint artifact directories and saves:
+ * - Intermediate files (spec drafts, contract drafts)
+ * - Agent reasoning logs
+ * - Validator output logs
+ * - Failure artifacts on checkpoint failure
+ *
+ * Structure:
+ *   .morph/features/{feature}/artifacts/
+ *     checkpoint-{n}/
+ *       spec-draft.md
+ *       contracts-draft.cs
+ *       agent-reasoning.json
+ *       validator-output.json
+ *     checkpoint-{n}/failures/
+ *       failure-detail.json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const BASE_DIR = join(process.cwd(), '.morph/features');
+
+// ============================================================================
+// Path Helpers
+// ============================================================================
+
+function artifactsDir(feature) {
+  return join(BASE_DIR, feature, 'artifacts');
+}
+
+function checkpointDir(feature, checkpointNum) {
+  return join(artifactsDir(feature), `checkpoint-${checkpointNum}`);
+}
+
+function failuresDir(feature, checkpointNum) {
+  return join(checkpointDir(feature, checkpointNum), 'failures');
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+// ============================================================================
+// Checkpoint Artifacts
+// ============================================================================
+
+/**
+ * Initialize a checkpoint artifact directory
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @returns {string} Path to checkpoint directory
+ */
+export function initCheckpointArtifacts(feature, checkpointNum) {
+  const dir = checkpointDir(feature, checkpointNum);
+  ensureDir(dir);
+
+  const manifest = {
+    feature,
+    checkpointNum,
+    createdAt: new Date().toISOString(),
+    files: []
+  };
+
+  writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  return dir;
+}
+
+/**
+ * Save an intermediate artifact file to a checkpoint directory
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {string} filename - File name (e.g., 'spec-draft.md')
+ * @param {string} content - File content
+ * @returns {string} Full path to saved file
+ */
+export function saveArtifact(feature, checkpointNum, filename, content) {
+  const dir = ensureDir(checkpointDir(feature, checkpointNum));
+  const filePath = join(dir, filename);
+
+  writeFileSync(filePath, content, 'utf8');
+
+  // Update manifest
+  const manifestPath = join(dir, 'manifest.json');
+  if (existsSync(manifestPath)) {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest.files.includes(filename)) {
+      manifest.files.push(filename);
+      manifest.updatedAt = new Date().toISOString();
+      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    }
+  }
+
+  return filePath;
+}
+
+/**
+ * Save agent reasoning log
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} reasoning - Agent reasoning data
+ */
+export function saveAgentReasoning(feature, checkpointNum, reasoning) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    ...reasoning
+  };
+  saveArtifact(feature, checkpointNum, 'agent-reasoning.json', JSON.stringify(entry, null, 2));
+}
+
+/**
+ * Save validator output log
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} validatorOutput - Validator results
+ */
+export function saveValidatorOutput(feature, checkpointNum, validatorOutput) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    ...validatorOutput
+  };
+  saveArtifact(feature, checkpointNum, 'validator-output.json', JSON.stringify(entry, null, 2));
+}
+
+// ============================================================================
+// Failure Artifacts
+// ============================================================================
+
+/**
+ * Save failure artifacts when a checkpoint fails
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} failure - Failure details
+ * @param {string} failure.reason - Failure reason
+ * @param {Array} failure.errors - Array of error objects
+ * @param {number} failure.attemptNumber - Which retry attempt (1-3)
+ */
+export function saveFailureArtifacts(feature, checkpointNum, failure) {
+  const dir = ensureDir(failuresDir(feature, checkpointNum));
+  const filename = `failure-attempt-${failure.attemptNumber || 1}.json`;
+
+  const entry = {
+    feature,
+    checkpointNum,
+    timestamp: new Date().toISOString(),
+    ...failure
+  };
+
+  writeFileSync(join(dir, filename), JSON.stringify(entry, null, 2), 'utf8');
+  return join(dir, filename);
+}
+
+/**
+ * Get all failure artifacts for a checkpoint
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @returns {Array} Array of failure records
+ */
+export function getFailureArtifacts(feature, checkpointNum) {
+  const dir = failuresDir(feature, checkpointNum);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+
+  return files.map(f => {
+    try {
+      return JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+/**
+ * List all checkpoints for a feature
+ * @param {string} feature - Feature name
+ * @returns {Array} Array of checkpoint info objects
+ */
+export function listCheckpointArtifacts(feature) {
+  const dir = artifactsDir(feature);
+  if (!existsSync(dir)) return [];
+
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && d.name.startsWith('checkpoint-'))
+      .map(d => {
+        const checkpointPath = join(dir, d.name);
+        const manifestPath = join(checkpointPath, 'manifest.json');
+        if (existsSync(manifestPath)) {
+          return JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        return { name: d.name, path: checkpointPath };
+      });
+  } catch {
+    return [];
+  }
+}

package/src/lib/troubleshooting/index.js

@@ -0,0 +1,8 @@
+/**
+ * Troubleshooting Utilities
+ *
+ * Error diagnosis, pattern matching, and automated troubleshooting workflows.
+ */
+
+export * from './troubleshoot-grep.js';
+export * from './troubleshoot-index.js';

package/src/lib/{troubleshoot-grep.js → troubleshooting/troubleshoot-grep.js}

@@ -1,204 +1,204 @@
-/**
- * Troubleshoot Grep Fallback
- * Searches markdown files for matching content when index doesn't find results
- */
-
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join, dirname, basename } from 'path';
-import { fileURLToPath } from 'url';
-import { resolveStandardsDir } from './stack-resolver.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const frameworkRoot = join(__dirname, '..', '..');
-
-// Directories to search (stack standards resolved dynamically)
-const SEARCH_PATHS = [
-  'framework/standards',
-  '.wiki'
-];
-
-function getSearchPaths(basePath) {
-  const paths = [...SEARCH_PATHS];
-  // Insert resolved stack standards path
-  const stackStandards = resolveStandardsDir(basePath || frameworkRoot);
-  const relativePath = stackStandards.replace(basePath || frameworkRoot, '').replace(/^[\\/]/, '');
-  paths.splice(1, 0, relativePath);
-  return paths;
-}
-
-/**
- * Get all markdown files from search paths
- * @param {string} basePath - Base path of the project
- * @returns {string[]} Array of file paths
- */
-function getMarkdownFiles(basePath) {
-  const files = [];
-
-  for (const searchPath of getSearchPaths(basePath)) {
-    const fullPath = join(basePath, searchPath);
-
-    if (!existsSync(fullPath)) {
-      continue;
-    }
-
-    try {
-      const entries = readdirSync(fullPath, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (entry.isFile() && entry.name.endsWith('.md')) {
-          files.push(join(fullPath, entry.name));
-        }
-      }
-    } catch (error) {
-      // Skip directories we can't read
-    }
-  }
-
-  return files;
-}
-
-/**
- * Extract section containing the match
- * @param {string} content - File content
- * @param {number} matchIndex - Index of the match
- * @returns {Object} Section object with title and content
- */
-function extractSection(content, matchIndex) {
-  const lines = content.split('\n');
-  let charCount = 0;
-  let matchLineIndex = 0;
-
-  // Find the line containing the match
-  for (let i = 0; i < lines.length; i++) {
-    charCount += lines[i].length + 1; // +1 for newline
-    if (charCount > matchIndex) {
-      matchLineIndex = i;
-      break;
-    }
-  }
-
-  // Find the section header (## heading) above the match
-  let sectionTitle = 'Unknown Section';
-  let sectionStart = 0;
-
-  for (let i = matchLineIndex; i >= 0; i--) {
-    if (lines[i].startsWith('## ')) {
-      sectionTitle = lines[i].replace('## ', '').trim();
-      sectionStart = i;
-      break;
-    }
-  }
-
-  // Find the end of the section (next ## or end of file)
-  let sectionEnd = lines.length;
-  for (let i = sectionStart + 1; i < lines.length; i++) {
-    if (lines[i].startsWith('## ')) {
-      sectionEnd = i;
-      break;
-    }
-  }
-
-  // Extract section content (limit to ~20 lines around match)
-  const contextStart = Math.max(sectionStart, matchLineIndex - 10);
-  const contextEnd = Math.min(sectionEnd, matchLineIndex + 10);
-  const sectionContent = lines.slice(contextStart, contextEnd).join('\n');
-
-  return {
-    title: sectionTitle,
-    content: sectionContent,
-    lineNumber: matchLineIndex + 1
-  };
-}
-
-/**
- * Search a file for keywords
- * @param {string} filePath - Path to the file
- * @param {string[]} keywords - Keywords to search for
- * @returns {Object[]} Array of matches
- */
-function searchFile(filePath, keywords) {
-  const matches = [];
-
-  try {
-    const content = readFileSync(filePath, 'utf-8');
-    const contentLower = content.toLowerCase();
-
-    for (const keyword of keywords) {
-      const keywordLower = keyword.toLowerCase();
-      let index = contentLower.indexOf(keywordLower);
-
-      while (index !== -1) {
-        const section = extractSection(content, index);
-
-        // Check if we already have a match for this section
-        const existingMatch = matches.find(m => m.section === section.title);
-
-        if (existingMatch) {
-          existingMatch.matchCount++;
-          existingMatch.keywords.add(keyword);
-        } else {
-          matches.push({
-            file: filePath,
-            fileName: basename(filePath),
-            section: section.title,
-            content: section.content,
-            lineNumber: section.lineNumber,
-            matchCount: 1,
-            keywords: new Set([keyword])
-          });
-        }
-
-        index = contentLower.indexOf(keywordLower, index + 1);
-      }
-    }
-  } catch (error) {
-    // Skip files we can't read
-  }
-
-  return matches;
-}
-
-/**
- * Search all markdown files for keywords
- * @param {string[]} keywords - Keywords to search for
- * @param {Object} options - Search options
- * @returns {Object[]} Array of matches sorted by relevance
- */
-export function searchGrep(keywords, options = {}) {
-  // Determine base path
-  const basePath = options.basePath || join(__dirname, '../..');
-
-  const files = getMarkdownFiles(basePath);
-  let allMatches = [];
-
-  for (const file of files) {
-    const matches = searchFile(file, keywords);
-    allMatches = allMatches.concat(matches);
-  }
-
-  // Convert keywords Set to Array and calculate score
-  const results = allMatches.map(match => ({
-    ...match,
-    keywords: Array.from(match.keywords),
-    score: match.matchCount * 5 + match.keywords.size * 3,
-    source: 'grep'
-  }));
-
-  // Sort by score (higher is better) and deduplicate
-  const seen = new Set();
-  const uniqueResults = results
-    .sort((a, b) => b.score - a.score)
-    .filter(r => {
-      const key = `${r.file}:${r.section}`;
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
-    });
-
-  return uniqueResults.slice(0, 10); // Limit to top 10
-}
-
-export default {
-  searchGrep
-};
+/**
+ * Troubleshoot Grep Fallback
+ * Searches markdown files for matching content when index doesn't find results
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { resolveStandardsDir } from '../stacks/stack-resolver.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const frameworkRoot = join(__dirname, '..', '..');
+
+// Directories to search (stack standards resolved dynamically)
+const SEARCH_PATHS = [
+  'framework/standards',
+  '.wiki'
+];
+
+function getSearchPaths(basePath) {
+  const paths = [...SEARCH_PATHS];
+  // Insert resolved stack standards path
+  const stackStandards = resolveStandardsDir(basePath || frameworkRoot);
+  const relativePath = stackStandards.replace(basePath || frameworkRoot, '').replace(/^[\\/]/, '');
+  paths.splice(1, 0, relativePath);
+  return paths;
+}
+
+/**
+ * Get all markdown files from search paths
+ * @param {string} basePath - Base path of the project
+ * @returns {string[]} Array of file paths
+ */
+function getMarkdownFiles(basePath) {
+  const files = [];
+
+  for (const searchPath of getSearchPaths(basePath)) {
+    const fullPath = join(basePath, searchPath);
+
+    if (!existsSync(fullPath)) {
+      continue;
+    }
+
+    try {
+      const entries = readdirSync(fullPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          files.push(join(fullPath, entry.name));
+        }
+      }
+    } catch (error) {
+      // Skip directories we can't read
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract section containing the match
+ * @param {string} content - File content
+ * @param {number} matchIndex - Index of the match
+ * @returns {Object} Section object with title and content
+ */
+function extractSection(content, matchIndex) {
+  const lines = content.split('\n');
+  let charCount = 0;
+  let matchLineIndex = 0;
+
+  // Find the line containing the match
+  for (let i = 0; i < lines.length; i++) {
+    charCount += lines[i].length + 1; // +1 for newline
+    if (charCount > matchIndex) {
+      matchLineIndex = i;
+      break;
+    }
+  }
+
+  // Find the section header (## heading) above the match
+  let sectionTitle = 'Unknown Section';
+  let sectionStart = 0;
+
+  for (let i = matchLineIndex; i >= 0; i--) {
+    if (lines[i].startsWith('## ')) {
+      sectionTitle = lines[i].replace('## ', '').trim();
+      sectionStart = i;
+      break;
+    }
+  }
+
+  // Find the end of the section (next ## or end of file)
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ')) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Extract section content (limit to ~20 lines around match)
+  const contextStart = Math.max(sectionStart, matchLineIndex - 10);
+  const contextEnd = Math.min(sectionEnd, matchLineIndex + 10);
+  const sectionContent = lines.slice(contextStart, contextEnd).join('\n');
+
+  return {
+    title: sectionTitle,
+    content: sectionContent,
+    lineNumber: matchLineIndex + 1
+  };
+}
+
+/**
+ * Search a file for keywords
+ * @param {string} filePath - Path to the file
+ * @param {string[]} keywords - Keywords to search for
+ * @returns {Object[]} Array of matches
+ */
+function searchFile(filePath, keywords) {
+  const matches = [];
+
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const contentLower = content.toLowerCase();
+
+    for (const keyword of keywords) {
+      const keywordLower = keyword.toLowerCase();
+      let index = contentLower.indexOf(keywordLower);
+
+      while (index !== -1) {
+        const section = extractSection(content, index);
+
+        // Check if we already have a match for this section
+        const existingMatch = matches.find(m => m.section === section.title);
+
+        if (existingMatch) {
+          existingMatch.matchCount++;
+          existingMatch.keywords.add(keyword);
+        } else {
+          matches.push({
+            file: filePath,
+            fileName: basename(filePath),
+            section: section.title,
+            content: section.content,
+            lineNumber: section.lineNumber,
+            matchCount: 1,
+            keywords: new Set([keyword])
+          });
+        }
+
+        index = contentLower.indexOf(keywordLower, index + 1);
+      }
+    }
+  } catch (error) {
+    // Skip files we can't read
+  }
+
+  return matches;
+}
+
+/**
+ * Search all markdown files for keywords
+ * @param {string[]} keywords - Keywords to search for
+ * @param {Object} options - Search options
+ * @returns {Object[]} Array of matches sorted by relevance
+ */
+export function searchGrep(keywords, options = {}) {
+  // Determine base path
+  const basePath = options.basePath || join(__dirname, '../..');
+
+  const files = getMarkdownFiles(basePath);
+  let allMatches = [];
+
+  for (const file of files) {
+    const matches = searchFile(file, keywords);
+    allMatches = allMatches.concat(matches);
+  }
+
+  // Convert keywords Set to Array and calculate score
+  const results = allMatches.map(match => ({
+    ...match,
+    keywords: Array.from(match.keywords),
+    score: match.matchCount * 5 + match.keywords.size * 3,
+    source: 'grep'
+  }));
+
+  // Sort by score (higher is better) and deduplicate
+  const seen = new Set();
+  const uniqueResults = results
+    .sort((a, b) => b.score - a.score)
+    .filter(r => {
+      const key = `${r.file}:${r.section}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+  return uniqueResults.slice(0, 10); // Limit to top 10
+}
+
+export default {
+  searchGrep
+};