@soleri/core 2.10.0 → 2.11.0

package/src/claudemd/inject.ts

@@ -0,0 +1,170 @@
+/**
+ * CLAUDE.md injection — marker-based write with diff detection and user-safe zones.
+ *
+ * Improvements over Salvador:
+ * - Diff-before-write: skips I/O if content unchanged
+ * - User-safe zones: `<!-- user:custom -->` blocks inside markers survive regeneration
+ * - Versioned markers: `<!-- agent:mode v1 -->` for future migration
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { OPEN_MARKER, CLOSE_MARKER, USER_ZONE_OPEN, USER_ZONE_CLOSE } from './compose.js';
+import type { InjectionResult, RemovalResult } from './types.js';
+
+/** Legacy marker patterns to detect and migrate */
+const LEGACY_MARKERS = [
+  '<!-- agent:mode -->', // v0 (no version)
+  '<!-- salvador:mode -->', // pre-Soleri
+];
+
+/**
+ * Extract user-safe zone content from an existing agent block.
+ * Returns the content between `<!-- user:custom -->` markers, or null.
+ */
+export function extractUserZone(content: string): string | null {
+  const openIdx = content.indexOf(USER_ZONE_OPEN);
+  const closeIdx = content.indexOf(USER_ZONE_CLOSE);
+  if (openIdx === -1 || closeIdx === -1 || closeIdx <= openIdx) return null;
+  const inner = content.slice(openIdx + USER_ZONE_OPEN.length, closeIdx).trim();
+  return inner || null;
+}
+
+/**
+ * Preserve user-safe zone content when regenerating.
+ * Replaces the empty user zone in `newBlock` with the saved content.
+ */
+function preserveUserZone(newBlock: string, savedZone: string | null): string {
+  if (!savedZone) return newBlock;
+  const emptyZone = `${USER_ZONE_OPEN}\n\n${USER_ZONE_CLOSE}`;
+  const filledZone = `${USER_ZONE_OPEN}\n${savedZone}\n${USER_ZONE_CLOSE}`;
+  return newBlock.replace(emptyZone, filledZone);
+}
+
+/**
+ * Find the agent block boundaries in content.
+ * Handles current and legacy markers.
+ */
+function findBlock(
+  content: string,
+): { openIdx: number; closeIdx: number; closeLen: number } | null {
+  // Current markers
+  const openIdx = content.indexOf(OPEN_MARKER);
+  if (openIdx !== -1) {
+    const closeIdx = content.indexOf(CLOSE_MARKER, openIdx);
+    if (closeIdx > openIdx) {
+      return { openIdx, closeIdx, closeLen: CLOSE_MARKER.length };
+    }
+  }
+
+  // Legacy markers
+  for (const legacy of LEGACY_MARKERS) {
+    const legacyOpen = content.indexOf(legacy);
+    if (legacyOpen === -1) continue;
+    const legacyCloseTag = legacy.replace('<!-- ', '<!-- /');
+    const legacyClose = content.indexOf(legacyCloseTag, legacyOpen);
+    if (legacyClose > legacyOpen) {
+      return { openIdx: legacyOpen, closeIdx: legacyClose, closeLen: legacyCloseTag.length };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Inject an agent block into a CLAUDE.md file.
+ *
+ * - If markers exist: replace (preserving user-safe zones), skip if unchanged
+ * - If legacy markers: migrate
+ * - If no markers: append
+ */
+export function injectCLAUDEmd(filePath: string, block: string): InjectionResult {
+  try {
+    // New file
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, block + '\n', 'utf-8');
+      return { success: true, action: 'injected', message: 'Created file with agent block' };
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const bounds = findBlock(content);
+
+    if (bounds) {
+      // Extract user zone from existing block before replacing
+      const existingBlock = content.slice(bounds.openIdx, bounds.closeIdx + bounds.closeLen);
+      const userZone = extractUserZone(existingBlock);
+      const finalBlock = preserveUserZone(block, userZone);
+
+      // Diff check — skip write if identical
+      if (existingBlock === finalBlock) {
+        return {
+          success: true,
+          action: 'skipped',
+          message: 'Content unchanged — no write needed',
+          diffDetected: false,
+        };
+      }
+
+      const before = content.slice(0, bounds.openIdx);
+      const after = content.slice(bounds.closeIdx + bounds.closeLen);
+      writeFileSync(filePath, before + finalBlock + after, 'utf-8');
+      return {
+        success: true,
+        action: 'replaced',
+        message: 'Replaced agent block (diff detected)',
+        diffDetected: true,
+      };
+    }
+
+    // No markers — append
+    writeFileSync(filePath, content.trimEnd() + '\n\n' + block + '\n', 'utf-8');
+    return { success: true, action: 'injected', message: 'Appended agent block' };
+  } catch (err) {
+    return {
+      success: false,
+      action: 'error',
+      message: `Injection failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * Remove the agent block from a CLAUDE.md file.
+ */
+export function removeCLAUDEmd(filePath: string): RemovalResult {
+  try {
+    if (!existsSync(filePath)) {
+      return { success: true, action: 'not_present', message: 'File does not exist' };
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const bounds = findBlock(content);
+
+    if (!bounds) {
+      return { success: true, action: 'not_present', message: 'No agent block found' };
+    }
+
+    const before = content.slice(0, bounds.openIdx).trimEnd();
+    const after = content.slice(bounds.closeIdx + bounds.closeLen).trimStart();
+    writeFileSync(filePath, after ? before + '\n\n' + after : before + '\n', 'utf-8');
+    return { success: true, action: 'removed', message: 'Removed agent block' };
+  } catch (err) {
+    return {
+      success: false,
+      action: 'error',
+      message: `Removal failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * Check if an agent block is present in a CLAUDE.md file.
+ */
+export function hasCLAUDEmdBlock(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    return findBlock(content) !== null;
+  } catch {
+    return false;
+  }
+}

package/src/claudemd/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Types for CLAUDE.md auto-composition and injection.
+ */
+
+/** Agent metadata for CLAUDE.md generation */
+export interface AgentMeta {
+  id: string;
+  name: string;
+  activationPhrase: string;
+  deactivationPhrase: string;
+  activateCommand: string;
+  deactivateCommand: string;
+  /** Global instruction sections (priority-sorted, lower = higher) */
+  globalInstructions?: GlobalInstruction[];
+}
+
+/** A standalone section in CLAUDE.md not tied to a facade */
+export interface GlobalInstruction {
+  heading: string;
+  content: string;
+  priority?: number;
+}
+
+/** Facade instructions for CLAUDE.md behavioral rules */
+export interface FacadeInstructions {
+  heading: string;
+  rules?: string[];
+  templates?: Record<string, string>;
+  priority?: number;
+  keyOps?: string[];
+}
+
+/** Result of an injection or removal operation */
+export interface InjectionResult {
+  success: boolean;
+  action: 'injected' | 'replaced' | 'skipped' | 'error';
+  message: string;
+  diffDetected?: boolean;
+}
+
+export interface RemovalResult {
+  success: boolean;
+  action: 'removed' | 'not_present' | 'error';
+  message: string;
+}

package/src/context/context-engine.ts

@@ -0,0 +1,302 @@
+/**
+ * Context Engine — entity extraction, knowledge retrieval, and confidence scoring.
+ *
+ * Orchestrates three signals to enrich intent classification:
+ * 1. Entity extraction (regex-based, domain-agnostic)
+ * 2. Knowledge retrieval (vault FTS + Cognee vector + brain recommendations)
+ * 3. Confidence scoring (combines entity + knowledge signals)
+ *
+ * Graceful degradation: if Cognee is unavailable, vault-only.
+ * If vault is empty, keyword confidence from IntentRouter is unchanged.
+ */
+
+import type { Vault } from '../vault/vault.js';
+import type { Brain } from '../brain/brain.js';
+import type { BrainIntelligence } from '../brain/intelligence.js';
+import type { CogneeClient } from '../cognee/client.js';
+import type {
+  EntityType,
+  ExtractedEntity,
+  EntityExtractionResult,
+  KnowledgeItem,
+  KnowledgeRetrievalResult,
+  ContextAnalysis,
+  ConfidenceLevel,
+  ContextEngineConfig,
+} from './types.js';
+
+// ─── Entity Patterns ────────────────────────────────────────────────
+
+const ENTITY_PATTERNS: Array<{ type: EntityType; pattern: RegExp; confidence: number }> = [
+  // File paths: src/foo/bar.ts, ./config.json, foo.tsx
+  { type: 'file', pattern: /(?:\.\/|src\/|packages\/)?[\w\-./]+\.\w{1,6}/g, confidence: 0.8 },
+  // Function/method names: functionName(), ClassName.method()
+  { type: 'function', pattern: /\b[a-z]\w*(?:\.\w+)*\(\)/g, confidence: 0.7 },
+  // Domains: accessibility, performance, security, etc.
+  {
+    type: 'domain',
+    pattern:
+      /\b(?:accessibility|a11y|performance|security|architecture|testing|design|ux|devops|data|analytics|auth|api)\b/gi,
+    confidence: 0.9,
+  },
+  // Actions: create, fix, build, deploy, etc.
+  {
+    type: 'action',
+    pattern:
+      /\b(?:create|build|fix|debug|deploy|test|validate|review|improve|refactor|optimize|migrate|add|remove|update)\b/gi,
+    confidence: 0.8,
+  },
+  // Technologies: React, TypeScript, Node.js, etc.
+  {
+    type: 'technology',
+    pattern:
+      /\b(?:react|vue|svelte|angular|typescript|javascript|node\.?js|python|rust|go|docker|kubernetes|postgres|sqlite|redis|tailwind|css|html|graphql|rest|grpc)\b/gi,
+    confidence: 0.85,
+  },
+  // Patterns: kebab-case compound terms that look like patterns
+  { type: 'pattern', pattern: /\b[a-z]+-[a-z]+(?:-[a-z]+)*\b/g, confidence: 0.5 },
+];
+
+// Words to ignore when extracting patterns
+const STOP_PATTERNS = new Set([
+  'e-mail',
+  'real-time',
+  'built-in',
+  'up-to-date',
+  'well-known',
+  'open-source',
+  'third-party',
+  'cross-platform',
+  'end-to-end',
+  'out-of-the-box',
+]);
+
+// ─── Confidence Thresholds ──────────────────────────────────────────
+
+const HIGH_CONFIDENCE = 0.75;
+const MEDIUM_CONFIDENCE = 0.45;
+
+// ─── Class ──────────────────────────────────────────────────────────
+
+export class ContextEngine {
+  private vault: Vault;
+  private brain: Brain;
+  private brainIntelligence: BrainIntelligence;
+  private cognee: CogneeClient | null;
+  private config: Required<ContextEngineConfig>;
+
+  constructor(
+    vault: Vault,
+    brain: Brain,
+    brainIntelligence: BrainIntelligence,
+    cognee: CogneeClient | null,
+    config?: ContextEngineConfig,
+  ) {
+    this.vault = vault;
+    this.brain = brain;
+    this.brainIntelligence = brainIntelligence;
+    this.cognee = cognee;
+    this.config = {
+      vaultSearchLimit: config?.vaultSearchLimit ?? 10,
+      cogneeSearchLimit: config?.cogneeSearchLimit ?? 10,
+      brainRecommendLimit: config?.brainRecommendLimit ?? 5,
+      minScoreThreshold: config?.minScoreThreshold ?? 0.1,
+    };
+  }
+
+  // ─── Entity Extraction ──────────────────────────────────────────
+
+  extractEntities(prompt: string): EntityExtractionResult {
+    const seen = new Set<string>();
+    const entities: ExtractedEntity[] = [];
+
+    for (const { type, pattern, confidence } of ENTITY_PATTERNS) {
+      // Reset lastIndex for global regex
+      pattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(prompt)) !== null) {
+        const value = match[0].toLowerCase();
+        const key = `${type}:${value}`;
+        if (seen.has(key)) continue;
+        if (type === 'pattern' && STOP_PATTERNS.has(value)) continue;
+        seen.add(key);
+        entities.push({ type, value, confidence });
+      }
+    }
+
+    // Group by type
+    const byType: Partial<Record<EntityType, ExtractedEntity[]>> = {};
+    for (const e of entities) {
+      (byType[e.type] ??= []).push(e);
+    }
+
+    return { entities, byType };
+  }
+
+  // ─── Knowledge Retrieval ────────────────────────────────────────
+
+  async retrieveKnowledge(prompt: string, domain?: string): Promise<KnowledgeRetrievalResult> {
+    const items: KnowledgeItem[] = [];
+    let vaultHits = 0;
+    let cogneeHits = 0;
+    let brainHits = 0;
+
+    // 1. Vault FTS search
+    try {
+      const vaultResults = this.vault.search(prompt, {
+        domain,
+        limit: this.config.vaultSearchLimit,
+      });
+      // Normalize FTS5 -rank scores to 0-1 range
+      const maxScore = vaultResults.length > 0 ? Math.max(...vaultResults.map((r) => r.score)) : 1;
+      for (const r of vaultResults) {
+        items.push({
+          id: r.entry.id,
+          title: r.entry.title,
+          score: maxScore > 0 ? r.score / maxScore : 0.5,
+          source: 'vault',
+          domain: r.entry.domain,
+        });
+        vaultHits++;
+      }
+    } catch {
+      // Vault search failed — continue with other sources
+    }
+
+    // 2. Cognee vector search (async, graceful degradation)
+    if (this.cognee) {
+      try {
+        const cogneeResults = await this.cognee.search(prompt, {
+          limit: this.config.cogneeSearchLimit,
+        });
+        for (const r of cogneeResults) {
+          // Avoid duplicates from vault
+          if (items.some((i) => i.id === r.id)) continue;
+          items.push({
+            id: r.id,
+            title: r.text.slice(0, 100),
+            score: r.score,
+            source: 'cognee',
+          });
+          cogneeHits++;
+        }
+      } catch {
+        // Cognee unavailable — continue without
+      }
+    }
+
+    // 3. Brain recommendations
+    try {
+      const recommendations = this.brainIntelligence.recommend({
+        domain,
+        task: prompt,
+        limit: this.config.brainRecommendLimit,
+      });
+      for (const r of recommendations) {
+        items.push({
+          id: r.pattern,
+          title: r.pattern,
+          score: r.strength / 100,
+          source: 'brain',
+          domain: r.domain,
+        });
+        brainHits++;
+      }
+    } catch {
+      // Brain empty — continue without
+    }
+
+    // Sort by score descending, filter by threshold
+    items.sort((a, b) => b.score - a.score);
+    const filtered = items.filter((i) => i.score >= this.config.minScoreThreshold);
+
+    return { items: filtered, vaultHits, cogneeHits, brainHits };
+  }
+
+  // ─── Context Analysis ───────────────────────────────────────────
+
+  async analyze(prompt: string, domain?: string): Promise<ContextAnalysis> {
+    const start = performance.now();
+
+    // Extract entities
+    const entities = this.extractEntities(prompt);
+
+    // Retrieve knowledge
+    const knowledge = await this.retrieveKnowledge(prompt, domain);
+
+    // Compute confidence from multiple signals
+    const confidence = this.computeConfidence(entities, knowledge);
+    const confidenceLevel = this.toConfidenceLevel(confidence);
+
+    // Detect domains from entities + knowledge
+    const detectedDomains = this.detectDomains(entities, knowledge);
+
+    const processingTimeMs = Math.round(performance.now() - start);
+
+    return {
+      prompt,
+      entities,
+      knowledge,
+      confidence,
+      confidenceLevel,
+      detectedDomains,
+      processingTimeMs,
+    };
+  }
+
+  // ─── Private Helpers ────────────────────────────────────────────
+
+  private computeConfidence(
+    entities: EntityExtractionResult,
+    knowledge: KnowledgeRetrievalResult,
+  ): number {
+    let score = 0;
+
+    // Entity signal (0-0.4): more entities = clearer prompt
+    const entityCount = entities.entities.length;
+    const entitySignal = Math.min(0.4, entityCount * 0.08);
+    score += entitySignal;
+
+    // Action signal (0-0.2): explicit actions boost confidence
+    const actions = entities.byType.action ?? [];
+    if (actions.length > 0) score += 0.2;
+
+    // Knowledge signal (0-0.3): relevant knowledge found
+    if (knowledge.items.length > 0) {
+      const topScore = knowledge.items[0].score;
+      score += topScore * 0.3;
+    }
+
+    // Source diversity bonus (0-0.1): multiple sources = more confident
+    const sources = new Set(knowledge.items.map((i) => i.source));
+    if (sources.size >= 2) score += 0.05;
+    if (sources.size >= 3) score += 0.05;
+
+    return Math.min(1, score);
+  }
+
+  private toConfidenceLevel(confidence: number): ConfidenceLevel {
+    if (confidence >= HIGH_CONFIDENCE) return 'high';
+    if (confidence >= MEDIUM_CONFIDENCE) return 'medium';
+    return 'low';
+  }
+
+  private detectDomains(
+    entities: EntityExtractionResult,
+    knowledge: KnowledgeRetrievalResult,
+  ): string[] {
+    const domains = new Set<string>();
+
+    // From entity extraction
+    for (const e of entities.byType.domain ?? []) {
+      domains.add(e.value);
+    }
+
+    // From knowledge results
+    for (const item of knowledge.items) {
+      if (item.domain) domains.add(item.domain);
+    }
+
+    return [...domains];
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,11 @@
+export { ContextEngine } from './context-engine.js';
+export type {
+  EntityType,
+  ExtractedEntity,
+  EntityExtractionResult,
+  KnowledgeItem,
+  KnowledgeRetrievalResult,
+  ConfidenceLevel,
+  ContextAnalysis,
+  ContextEngineConfig,
+} from './types.js';

package/src/context/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Context Engine types — entity extraction, knowledge retrieval, confidence scoring.
+ */
+
+// ─── Entity Extraction ─────────────────────────────────────────────
+
+export type EntityType = 'file' | 'function' | 'domain' | 'action' | 'pattern' | 'technology';
+
+export interface ExtractedEntity {
+  type: EntityType;
+  value: string;
+  confidence: number;
+}
+
+export interface EntityExtractionResult {
+  entities: ExtractedEntity[];
+  byType: Partial<Record<EntityType, ExtractedEntity[]>>;
+}
+
+// ─── Knowledge Retrieval ────────────────────────────────────────────
+
+export interface KnowledgeItem {
+  id: string;
+  title: string;
+  score: number;
+  source: 'vault' | 'cognee' | 'brain';
+  domain?: string;
+}
+
+export interface KnowledgeRetrievalResult {
+  items: KnowledgeItem[];
+  vaultHits: number;
+  cogneeHits: number;
+  brainHits: number;
+}
+
+// ─── Context Analysis ───────────────────────────────────────────────
+
+export type ConfidenceLevel = 'high' | 'medium' | 'low';
+
+export interface ContextAnalysis {
+  /** Original prompt that was analyzed */
+  prompt: string;
+  /** Extracted entities from the prompt */
+  entities: EntityExtractionResult;
+  /** Retrieved knowledge relevant to the prompt */
+  knowledge: KnowledgeRetrievalResult;
+  /** Enhanced confidence based on entity + knowledge signals */
+  confidence: number;
+  /** Discrete confidence level */
+  confidenceLevel: ConfidenceLevel;
+  /** Domains detected from entities + knowledge */
+  detectedDomains: string[];
+  /** Processing time in milliseconds */
+  processingTimeMs: number;
+}
+
+// ─── Configuration ──────────────────────────────────────────────────
+
+export interface ContextEngineConfig {
+  /** Max vault search results to retrieve. Default: 10. */
+  vaultSearchLimit?: number;
+  /** Max Cognee search results to retrieve. Default: 10. */
+  cogneeSearchLimit?: number;
+  /** Max brain recommendations to include. Default: 5. */
+  brainRecommendLimit?: number;
+  /** Minimum score threshold for knowledge items. Default: 0.1. */
+  minScoreThreshold?: number;
+}