ac-framework 1.6.0 → 1.8.0

package/src/memory/index.js

@@ -0,0 +1,62 @@
+/**
+ * memory/index.js — API pública del sistema de memoria autónoma
+ * 
+ * Sistema de persistencia de conocimiento para agentes AI.
+ * Guarda automáticamente decisiones, patrones, bugfixes y insights.
+ */
+
+// Database
+export { initDatabase, getDatabase, closeDatabase, isDatabaseInitialized } from './database.js';
+
+// Core Engine
+export {
+  saveMemory,
+  searchMemories,
+  getContext,
+  getTimeline,
+  getMemory,
+  updateMemory,
+  deleteMemory,
+  startSession,
+  endSession,
+  getStats,
+  findPatterns,
+  getConnections,
+  anticipateNeeds,
+  exportMemories,
+  importMemories,
+  pruneMemories
+} from './engine.js';
+
+// Utils
+export {
+  redactPrivateContent,
+  extractKeywords,
+  textSimilarity,
+  truncate,
+  isCodeContent,
+  detectLanguage,
+  generateSummary,
+  sanitizeFTSQuery
+} from './utils.js';
+
+// Auto-save system
+export { createAutoSaveHook, AutoSaveManager } from './autosave.js';
+
+// Tipos de memoria válidos para referencia
+export const MEMORY_TYPES = [
+  'architectural_decision',
+  'bugfix_pattern',
+  'api_pattern',
+  'performance_insight',
+  'security_fix',
+  'refactor_technique',
+  'dependency_note',
+  'workaround',
+  'convention',
+  'context_boundary',
+  'general_insight',
+  'session_summary'
+];
+
+export const IMPORTANCE_LEVELS = ['critical', 'high', 'medium', 'low'];

package/src/memory/utils.js

@@ -0,0 +1,128 @@
+/**
+ * utils.js — Utilidades para el sistema de memoria
+ */
+
+/**
+ * Redacta contenido entre etiquetas <private>
+ */
+export function redactPrivateContent(content) {
+  if (!content) return content;
+  
+  const privateRegex = /<private>[\s\S]*?<\/private>/gi;
+  return content.replace(privateRegex, '[REDACTED PRIVATE CONTENT]');
+}
+
+/**
+ * Extrae palabras clave de un texto
+ */
+export function extractKeywords(text, maxKeywords = 5) {
+  if (!text) return [];
+  
+  const stopWords = new Set([
+    'el', 'la', 'los', 'las', 'un', 'una', 'unos', 'unas', 'de', 'del', 'al',
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'en', 'y', 'o', 'pero', 'por', 'para', 'con', 'sin', 'sobre', 'entre',
+    'in', 'and', 'or', 'but', 'for', 'with', 'without', 'on', 'between',
+    'que', 'como', 'cuando', 'donde', 'quien', 'cual', 'esto', 'eso',
+    'that', 'what', 'when', 'where', 'who', 'which', 'this', 'that'
+  ]);
+  
+  const wordCounts = text.toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 3 && !stopWords.has(w))
+    .reduce((acc, word) => {
+      acc[word] = (acc[word] || 0) + 1;
+      return acc;
+    }, {});
+  
+  return Object.entries(wordCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxKeywords)
+    .map(([word]) => word);
+}
+
+/**
+ * Calcula similitud simple entre dos textos (Jaccard)
+ */
+export function textSimilarity(text1, text2) {
+  const set1 = new Set(text1.toLowerCase().split(/\s+/));
+  const set2 = new Set(text2.toLowerCase().split(/\s+/));
+  
+  const intersection = new Set([...set1].filter(x => set2.has(x)));
+  const union = new Set([...set1, ...set2]);
+  
+  return intersection.size / union.size;
+}
+
+/**
+ * Trunca texto con ellipsis
+ */
+export function truncate(text, maxLength = 100) {
+  if (!text || text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Detecta si un contenido parece código
+ */
+export function isCodeContent(text) {
+  const codeIndicators = [
+    /function\s+\w+\s*\(/,
+    /const\s+\w+\s*=/,
+    /let\s+\w+\s*=/,
+    /var\s+\w+\s*=/,
+    /import\s+.*\s+from/,
+    /export\s+(default\s+)?/,
+    /class\s+\w+/,
+    /if\s*\(.*\)\s*\{/,
+    /for\s*\(.*\)\s*\{/,
+    /```[\s\S]*```/
+  ];
+  
+  return codeIndicators.some(pattern => pattern.test(text));
+}
+
+/**
+ * Detecta lenguaje de programación
+ */
+export function detectLanguage(text) {
+  if (/\.tsx?/.test(text) || /interface\s+\w+/.test(text) || /:\s*(string|number|boolean)/.test(text)) {
+    return 'typescript';
+  }
+  if (/\.jsx?/.test(text) || /React\./.test(text) || /useState|useEffect/.test(text)) {
+    return 'javascript';
+  }
+  if (/\.py/.test(text) || /def\s+\w+\s*\(/.test(text) || /import\s+\w+/.test(text)) {
+    return 'python';
+  }
+  if (/\.go/.test(text) || /func\s+\w+\s*\(/.test(text) || /package\s+\w+/.test(text)) {
+    return 'go';
+  }
+  if (/\.rs/.test(text) || /fn\s+\w+\s*\(/.test(text) || /let\s+mut/.test(text)) {
+    return 'rust';
+  }
+  return 'unknown';
+}
+
+/**
+ * Genera un resumen automático
+ */
+export function generateSummary(text, maxSentences = 2) {
+  if (!text) return '';
+  
+  const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 10);
+  return sentences.slice(0, maxSentences).join('. ') + '.';
+}
+
+/**
+ * Sanitiza input para FTS5
+ */
+export function sanitizeFTSQuery(query) {
+  // Escapar caracteres especiales de FTS5
+  return query
+    .replace(/"/g, '""')
+    .replace(/\*/g, '')
+    .replace(/^\^/g, '')
+    .replace(/\$/g, '');
+}

package/src/services/spec-engine.js

@@ -9,10 +9,45 @@ import { readFile, readdir, stat, mkdir, rename, access, writeFile } from 'node:
 import { resolve, join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
+import { initDatabase, getContext, AutoSaveManager } from '../memory/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCHEMAS_DIR = resolve(__dirname, '../schemas');
-const OPENSPEC_DIR = 'openspec';
+
+// Default directory name for AC Framework spec-driven workflows
+const ACFM_DIR = '.acfm';
+// Legacy directory name for backward compatibility
+const LEGACY_DIR = 'openspec';
+
+/**
+ * Determine which spec directory to use for a project.
+ * Priority: .acfm/ > openspec/ (for backward compatibility)
+ * Returns the directory name (not full path)
+ */
+async function getSpecDir(cwd = process.cwd()) {
+  try {
+    // Check if .acfm exists
+    await access(join(cwd, ACFM_DIR));
+    return ACFM_DIR;
+  } catch {
+    try {
+      // Fall back to legacy openspec directory
+      await access(join(cwd, LEGACY_DIR));
+      return LEGACY_DIR;
+    } catch {
+      // Neither exists, default to new .acfm for new projects
+      return ACFM_DIR;
+    }
+  }
+}
+
+/**
+ * Get the effective spec directory name without async
+ * For use when we already know the project is initialized
+ */
+async function getSpecDirSync(cwd = process.cwd()) {
+  return await getSpecDir(cwd);
+}
 
 // ─── Schema Loading ──────────────────────────────────────────────────────────
 
@@ -72,10 +107,12 @@ export async function loadTemplate(schemaName, artifactId) {
 // ─── Project Config ──────────────────────────────────────────────────────────
 
 /**
- * Read the project's openspec/config.yaml
+ * Read the project's spec config.yaml
+ * Supports both .acfm/ (new) and openspec/ (legacy) directories
  */
 export async function readProjectConfig(cwd = process.cwd()) {
-  const configPath = join(cwd, OPENSPEC_DIR, 'config.yaml');
+  const specDir = await getSpecDir(cwd);
+  const configPath = join(cwd, specDir, 'config.yaml');
   try {
     const content = await readFile(configPath, 'utf-8');
     return yaml.load(content) || {};
@@ -86,11 +123,13 @@ export async function readProjectConfig(cwd = process.cwd()) {
 }
 
 /**
- * Check if openspec is initialized in the current project
+ * Check if spec system is initialized in the current project
+ * Supports both .acfm/ (new) and openspec/ (legacy) directories
  */
 export async function isInitialized(cwd = process.cwd()) {
+  const specDir = await getSpecDir(cwd);
   try {
-    await access(join(cwd, OPENSPEC_DIR, 'config.yaml'));
+    await access(join(cwd, specDir, 'config.yaml'));
     return true;
   } catch {
     return false;
@@ -100,13 +139,23 @@ export async function isInitialized(cwd = process.cwd()) {
 // ─── Init ────────────────────────────────────────────────────────────────────
 
 /**
- * Initialize the openspec/ directory structure
+ * Initialize the spec directory structure (.acfm/ by default)
+ * Creates .acfm/ directory with specs/ and changes/ subdirectories
  */
 export async function initProject(cwd = process.cwd(), schemaName = 'spec-driven') {
   // Validate schema exists
   await loadSchema(schemaName);
 
-  const base = join(cwd, OPENSPEC_DIR);
+  // Check for legacy openspec directory - warn if found
+  try {
+    await access(join(cwd, LEGACY_DIR));
+    // Legacy directory exists, but we'll create new .acfm anyway
+    // This allows migration path
+  } catch {
+    // No legacy directory, proceed normally
+  }
+
+  const base = join(cwd, ACFM_DIR);
   await mkdir(join(base, 'specs'), { recursive: true });
   await mkdir(join(base, 'changes'), { recursive: true });
 
@@ -114,11 +163,35 @@ export async function initProject(cwd = process.cwd(), schemaName = 'spec-driven
   try {
     await access(configPath);
     // Already exists, don't overwrite
-    return { created: false, path: base };
+    return { created: false, path: base, dirName: ACFM_DIR };
   } catch {
-    const configContent = `schema: ${schemaName}\n\n# Project context (optional)\n# This is shown to AI when creating artifacts.\n# Add your tech stack, conventions, style guides, domain knowledge, etc.\n# Example:\n#   context: |\n#     Tech stack: TypeScript, React, Node.js\n#     We use conventional commits\n#     Domain: e-commerce platform\n\n# Per-artifact rules (optional)\n# Add custom rules for specific artifacts.\n# Example:\n#   rules:\n#     proposal:\n#       - Keep proposals under 500 words\n#       - Always include a \"Non-goals\" section\n#     tasks:\n#       - Break tasks into chunks of max 2 hours\n`;
+    const configContent = `schema: ${schemaName}
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
+
+# Directory Configuration
+# This project uses: .acfm/
+# Legacy openspec/ directories are supported for backward compatibility.
+`;
     await writeFile(configPath, configContent, 'utf-8');
-    return { created: true, path: base };
+    return { created: true, path: base, dirName: ACFM_DIR };
   }
 }
 
@@ -126,9 +199,11 @@ export async function initProject(cwd = process.cwd(), schemaName = 'spec-driven
 
 /**
  * Get the changes directory path
+ * Supports both .acfm/ (new) and openspec/ (legacy) directories
  */
-function changesDir(cwd) {
-  return join(cwd, OPENSPEC_DIR, 'changes');
+async function changesDir(cwd) {
+  const specDir = await getSpecDir(cwd);
+  return join(cwd, specDir, 'changes');
 }
 
 /**
@@ -137,13 +212,13 @@ function changesDir(cwd) {
 export async function createChange(name, cwd = process.cwd(), schemaOverride = null) {
   const config = await readProjectConfig(cwd);
   if (!config) {
-    throw new Error('OpenSpec not initialized. Run `acfm spec init` first.');
+    throw new Error('Spec system not initialized. Run `acfm spec init` first.');
   }
 
   const schemaName = schemaOverride || config.schema || 'spec-driven';
   const schema = await loadSchema(schemaName);
 
-  const changeDir = join(changesDir(cwd), name);
+  const changeDir = join(await changesDir(cwd), name);
 
   // Check if already exists
   try {
@@ -182,7 +257,7 @@ export async function createChange(name, cwd = process.cwd(), schemaOverride = n
  * List all active (non-archived) changes
  */
 export async function listChanges(cwd = process.cwd()) {
-  const dir = changesDir(cwd);
+  const dir = await changesDir(cwd);
   let entries;
   try {
     entries = await readdir(dir, { withFileTypes: true });
@@ -284,7 +359,7 @@ async function isArtifactDone(changePath, artifact) {
  * Get full status for a change, including per-artifact status
  */
 export async function getChangeStatus(name, cwd = process.cwd()) {
-  const changePath = join(changesDir(cwd), name);
+  const changePath = join(await changesDir(cwd), name);
 
   // Read change metadata
   const metaPath = join(changePath, '.openspec.yaml');
@@ -341,10 +416,10 @@ export async function getChangeStatus(name, cwd = process.cwd()) {
  * Get instructions for creating a specific artifact
  */
 export async function getArtifactInstructions(artifactId, changeName, cwd = process.cwd()) {
-  const changePath = join(changesDir(cwd), changeName);
+  const changePath = join(await changesDir(cwd), changeName);
   const config = await readProjectConfig(cwd);
   if (!config) {
-    throw new Error('OpenSpec not initialized. Run `acfm spec init` first.');
+    throw new Error('Spec system not initialized. Run `acfm spec init` first.');
   }
 
   const metaPath = join(changePath, '.openspec.yaml');
@@ -382,17 +457,18 @@ export async function getArtifactInstructions(artifactId, changeName, cwd = proc
   }
 
   // Build dependencies (paths to completed artifact files the agent should read)
+  const specDir = await getSpecDir(cwd);
   const dependencies = [];
   for (const depId of artifact.dependencies) {
     const depArtifact = schema.artifacts.find(a => a.id === depId);
     if (depArtifact) {
-      const depPath = join(OPENSPEC_DIR, 'changes', changeName, depArtifact.outputPath);
+      const depPath = join(specDir, 'changes', changeName, depArtifact.outputPath);
       dependencies.push(depPath);
     }
   }
 
   // Build output path
-  const outputPath = join(OPENSPEC_DIR, 'changes', changeName, artifact.outputPath);
+  const outputPath = join(specDir, 'changes', changeName, artifact.outputPath);
 
   // Build instruction from schema
   const instruction = artifact.instruction || '';
@@ -400,6 +476,21 @@ export async function getArtifactInstructions(artifactId, changeName, cwd = proc
   // Determine what this artifact unlocks
   const unlocks = artifact.unlocks || [];
 
+  // NUEVO: Recuperar contexto de memoria relevante
+  let relevantMemories = [];
+  try {
+    initDatabase(); // Asegurar DB inicializada
+    relevantMemories = getContext({
+      projectPath: cwd,
+      changeName,
+      limit: 5,
+      lookbackDays: 30
+    });
+  } catch {
+    // Si memory no está inicializado, continuar sin contexto
+    relevantMemories = [];
+  }
+
   return {
     context,
     rules,
@@ -408,6 +499,14 @@ export async function getArtifactInstructions(artifactId, changeName, cwd = proc
     outputPath,
     dependencies,
     unlocks,
+    // NUEVO: Memorias relevantes para el contexto del agente
+    relevantMemories: relevantMemories.map(m => ({
+      id: m.id,
+      type: m.type,
+      content: m.content,
+      importance: m.importance,
+      fromChange: m.changeName
+    }))
   };
 }
 
@@ -415,10 +514,10 @@ export async function getArtifactInstructions(artifactId, changeName, cwd = proc
  * Get instructions for the apply phase (implementing tasks)
  */
 export async function getApplyInstructions(changeName, cwd = process.cwd()) {
-  const changePath = join(changesDir(cwd), changeName);
+  const changePath = join(await changesDir(cwd), changeName);
   const config = await readProjectConfig(cwd);
   if (!config) {
-    throw new Error('OpenSpec not initialized. Run `acfm spec init` first.');
+    throw new Error('Spec system not initialized. Run `acfm spec init` first.');
   }
 
   const metaPath = join(changePath, '.openspec.yaml');
@@ -453,10 +552,11 @@ export async function getApplyInstructions(changeName, cwd = process.cwd()) {
   }
 
   // Build context files — all completed artifacts
+  const specDir = await getSpecDir(cwd);
   const contextFiles = [];
   for (const artifact of schema.artifacts) {
     if (doneMap[artifact.id]) {
-      const artifactPath = join(OPENSPEC_DIR, 'changes', changeName, artifact.outputPath);
+      const artifactPath = join(specDir, 'changes', changeName, artifact.outputPath);
       contextFiles.push(artifactPath);
     }
   }
@@ -507,12 +607,56 @@ export async function getApplyInstructions(changeName, cwd = process.cwd()) {
     instruction = `${remaining} of ${total} tasks remaining. Implement each pending task, following the specs and design. Mark tasks as [x] when complete.`;
   }
 
+  // NUEVO: Recuperar contexto de memoria relevante para implementación
+  let relevantMemories = [];
+  let suggestedPatterns = [];
+  try {
+    initDatabase();
+    
+    // Buscar patrones similares en memorias
+    relevantMemories = getContext({
+      projectPath: cwd,
+      changeName,
+      limit: 5,
+      lookbackDays: 30
+    });
+
+    // Buscar patrones de implementación específicos
+    const pendingTasks = tasks.filter(t => !t.done).map(t => t.task).join(' ');
+    if (pendingTasks) {
+      // Buscar memorias relacionadas con las tareas pendientes
+      const keywords = pendingTasks.toLowerCase().split(/\s+/).filter(w => w.length > 4);
+      if (keywords.length > 0) {
+        const { searchMemories } = await import('../memory/index.js');
+        suggestedPatterns = searchMemories(keywords.slice(0, 5).join(' OR '), {
+          type: 'refactor_technique',
+          limit: 3
+        });
+      }
+    }
+  } catch {
+    // Continuar sin contexto si hay error
+  }
+
   return {
     contextFiles,
     progress: { total, complete, remaining },
     state,
     instruction,
     tasks,
+    // NUEVO: Contexto de memoria para ayudar en implementación
+    relevantMemories: relevantMemories.map(m => ({
+      id: m.id,
+      type: m.type,
+      content: m.content,
+      importance: m.importance,
+      codeSnippet: m.codeSnippet
+    })),
+    suggestedPatterns: suggestedPatterns.map(m => ({
+      id: m.id,
+      content: m.content,
+      type: m.type
+    }))
   };
 }
 
@@ -522,7 +666,7 @@ export async function getApplyInstructions(changeName, cwd = process.cwd()) {
  * Archive a completed change
  */
 export async function archiveChange(name, cwd = process.cwd()) {
-  const changePath = join(changesDir(cwd), name);
+  const changePath = join(await changesDir(cwd), name);
 
   // Verify change exists
   try {
@@ -531,7 +675,7 @@ export async function archiveChange(name, cwd = process.cwd()) {
     throw new Error(`Change "${name}" not found.`);
   }
 
-  const archiveDir = join(changesDir(cwd), 'archive');
+  const archiveDir = join(await changesDir(cwd), 'archive');
   await mkdir(archiveDir, { recursive: true });
 
   const dateStr = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
@@ -571,7 +715,7 @@ export async function getGlobalStatus(cwd = process.cwd()) {
  * Validate a change's artifacts for structural correctness
  */
 export async function validateChange(name, cwd = process.cwd()) {
-  const changePath = join(changesDir(cwd), name);
+  const changePath = join(await changesDir(cwd), name);
   const issues = [];
 
   // Check change exists

package/src/ui/animations.js

@@ -6,6 +6,7 @@ const acGradient = gradient(['#6C5CE7', '#00CEC9', '#0984E3']);
 const successGradient = gradient(['#00CEC9', '#00B894', '#55EFC4']);
 const warmGradient = gradient(['#FDCB6E', '#E17055', '#D63031']);
 const glowGradient = gradient(['#0984E3', '#00CEC9', '#55EFC4', '#00CEC9', '#0984E3']);
+const diamondGradient = gradient(['#6C5CE7', '#A29BFE', '#00CEC9', '#A29BFE', '#6C5CE7']);
 
 // ── Scanning / Loading ───────────────────────────────────────────
 
@@ -240,3 +241,84 @@ export async function stepHeader(stepNum, totalSteps, label) {
   console.log(`  ${stepBadge} ${chalk.hex('#DFE6E9')(label)}`);
   console.log();
 }
+
+// ── Pulse Diamond Intro Animation ─────────────────────────────────
+
+export async function pulseDiamondIntro(durationMs = 1800) {
+  // Simplified but impactful diamond frames
+  const diamondFrames = [
+    // Small
+    ['      ◇      '],
+    // Growing
+    ['     ◇◈◇     '],
+    // Medium
+    ['    ◇◆◈◆◇    '],
+    // Large
+    ['   ◇◆◈◉◈◆◇   ',
+     '    ◇◆◈◆◇    '],
+    // Full with glow
+    ['  ◇◇◆◈◉◈◆◇◇  ',
+     '   ◇◆◈◉◈◆◇   ',
+     '  ◇◇◆◈◉◈◆◇◇  '],
+    // Peak
+    [' ◇◇◆◈◉◈◉◈◆◇◇ ',
+     '◇◇◆◈◉◈◉◈◉◈◆◇◇',
+     ' ◇◇◆◈◉◈◉◈◆◇◇ '],
+    // Hold peak
+    [' ◇◇◆◈◉◈◉◈◆◇◇ ',
+     '◇◇◆◈◉◈◉◈◉◈◆◇◇',
+     ' ◇◇◆◈◉◈◉◈◆◇◇ '],
+    // Back to full
+    ['  ◇◇◆◈◉◈◆◇◇  ',
+     '   ◇◆◈◉◈◆◇   ',
+     '  ◇◇◆◈◉◈◆◇◇  '],
+    // Medium
+    ['   ◇◆◈◉◈◆◇   ',
+     '    ◇◆◈◆◇    '],
+    // Small bright
+    ['     ◆◈◆     '],
+    // Final sparkle
+    ['     ✦◈✦     '],
+  ];
+
+  const frameDelay = Math.floor(durationMs / diamondFrames.length);
+  
+  console.log();
+  console.log();
+  
+  // Animate diamond pulse
+  for (const frame of diamondFrames) {
+    // Clear and redraw
+    if (diamondFrames.indexOf(frame) > 0) {
+      for (let i = 0; i < 5; i++) {
+        process.stdout.write('\x1B[1A\x1B[2K');
+      }
+    }
+    
+    // Top padding
+    console.log();
+    
+    // Diamond lines centered
+    for (const line of frame) {
+      const centered = '  ' + line;
+      console.log(acGradient(centered));
+    }
+    
+    // Bottom padding
+    for (let i = 0; i < 4 - frame.length; i++) {
+      console.log();
+    }
+    
+    await sleep(frameDelay);
+  }
+  
+  // Clear diamond and show final logo
+  for (let i = 0; i < 5; i++) {
+    process.stdout.write('\x1B[1A\x1B[2K');
+  }
+  
+  console.log();
+  console.log(acGradient('  ◢◤◢◤  AC FRAMEWORK  ◥◤◥◤'));
+  console.log(chalk.hex('#636E72')('  ───────────────────────────'));
+  console.log();
+}