@soleri/core 2.12.0 → 7.0.0

package/src/__tests__/playbook.test.ts

@@ -189,7 +189,7 @@ describe('playbook_create op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
+    ops = createSemanticFacades(runtime, 'test').flatMap((f) => f.ops);
   });
 
   afterEach(() => {
@@ -300,7 +300,7 @@ describe('playbook_match op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
+    ops = createSemanticFacades(runtime, 'test').flatMap((f) => f.ops);
   });
 
   afterEach(() => {
@@ -356,7 +356,7 @@ describe('playbook_seed op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
+    ops = createSemanticFacades(runtime, 'test').flatMap((f) => f.ops);
   });
 
   afterEach(() => {
@@ -371,7 +371,7 @@ describe('playbook_seed op', () => {
       errors: number;
     };
 
-    expect(result.seeded).toBe(6);
+    expect(result.seeded).toBe(7);
     expect(result.skipped).toBe(0);
     expect(result.errors).toBe(0);
   });
@@ -384,6 +384,6 @@ describe('playbook_seed op', () => {
     };
 
     expect(result.seeded).toBe(0);
-    expect(result.skipped).toBe(6);
+    expect(result.skipped).toBe(7);
   });
 });

package/src/__tests__/token-resolver.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveToken,
+  listProjectTokens,
+  buildReverseIndex,
+} from '../domain-packs/token-resolver.js';
+import type { PackProjectContext } from '../domain-packs/pack-runtime.js';
+
+const mockProject: PackProjectContext = {
+  id: 'test-project',
+  name: 'Test Project',
+  path: '/test',
+  colors: {
+    primary: {
+      base: '#3B82F6',
+      scale: { '50': '#EFF6FF', '100': '#DBEAFE', '500': '#3B82F6', '900': '#1E3A5F' },
+    },
+    neutral: {
+      base: '#6B7280',
+      scale: { '50': '#F9FAFB', '100': '#F3F4F6', '500': '#6B7280', '900': '#111827' },
+    },
+  },
+  semanticTokens: {
+    'text-inverse': '#FFFFFF',
+    'bg-surface': '#F9FAFB',
+  },
+};
+
+describe('resolveToken', () => {
+  it('should pass through hex values', () => {
+    expect(resolveToken('#FF0000', mockProject)).toBe('#FF0000');
+  });
+
+  it('should resolve named colors', () => {
+    expect(resolveToken('white', mockProject)).toBe('#FFFFFF');
+    expect(resolveToken('black', mockProject)).toBe('#000000');
+  });
+
+  it('should resolve semantic tokens', () => {
+    expect(resolveToken('text-inverse', mockProject)).toBe('#FFFFFF');
+    expect(resolveToken('bg-surface', mockProject)).toBe('#F9FAFB');
+  });
+
+  it('should resolve SCALE[SHADE] format', () => {
+    expect(resolveToken('PRIMARY[500]', mockProject)).toBe('#3B82F6');
+    expect(resolveToken('neutral[900]', mockProject)).toBe('#111827');
+  });
+
+  it('should resolve Tailwind-style tokens', () => {
+    expect(resolveToken('bg-primary-500', mockProject)).toBe('#3B82F6');
+    expect(resolveToken('text-neutral-900', mockProject)).toBe('#111827');
+  });
+
+  it('should throw for unknown tokens', () => {
+    expect(() => resolveToken('unknown-token', mockProject)).toThrow('Cannot resolve');
+  });
+
+  it('should throw for unknown scales', () => {
+    expect(() => resolveToken('ACCENT[500]', mockProject)).toThrow('Unknown color scale');
+  });
+});
+
+describe('listProjectTokens', () => {
+  it('should list all scale and semantic tokens', () => {
+    const tokens = listProjectTokens(mockProject);
+    expect(tokens.length).toBeGreaterThan(0);
+    expect(tokens.some((t) => t.token === 'primary-500')).toBe(true);
+    expect(tokens.some((t) => t.token === 'text-inverse')).toBe(true);
+    expect(tokens.some((t) => t.scale === 'semantic')).toBe(true);
+  });
+});
+
+describe('buildReverseIndex', () => {
+  it('should map hex to token name', () => {
+    const index = buildReverseIndex(mockProject);
+    expect(index.get('#3B82F6')).toBe('primary-500');
+    expect(index.get('#FFFFFF')).toBe('text-inverse');
+  });
+});

package/src/brain/intelligence.ts

@@ -497,12 +497,31 @@ export class BrainIntelligence {
     limit?: number;
   }): PatternStrength[] {
     const limit = context.limit ?? 5;
-    const strengths = this.getStrengths({
+
+    // Try domain-filtered first, fall back to all domains if too few results
+    let strengths = this.getStrengths({
       domain: context.domain,
-      minStrength: 30,
+      minStrength: 20, // lowered from 30 — small corpus needs lower threshold
       limit: limit * 3,
     });
 
+    // If domain-filtered returns too few, try without domain filter
+    // This handles cases where domain was stored as 'unknown' due to
+    // vault.get() returning null during computeStrengths
+    if (strengths.length < limit && context.domain) {
+      const allStrengths = this.getStrengths({
+        minStrength: 20,
+        limit: limit * 5,
+      });
+      // Include domain-matching AND entries where domain lookup failed
+      const additional = allStrengths.filter(
+        (s) =>
+          !strengths.some((existing) => existing.pattern === s.pattern) &&
+          (s.domain === context.domain || s.domain === 'unknown'),
+      );
+      strengths = [...strengths, ...additional];
+    }
+
     // If task context provided, boost patterns with matching terms
     if (context.task) {
       const taskTerms = new Set(context.task.toLowerCase().split(/\W+/).filter(Boolean));

package/src/capabilities/chain-mapping.ts

@@ -0,0 +1,93 @@
+/**
+ * Chain-to-capability mapping — v1 to v2 bridge.
+ *
+ * Maps Soleri's existing 26 v1 chain names (from data/flows/*.flow.yaml)
+ * to capability IDs in domain.action format.
+ *
+ * Used during migration: flows with chains: [] are auto-translated to
+ * capability references. Remove this file when all flows use needs: []
+ * exclusively.
+ *
+ * @see docs/architecture/capability-packs.md — "Chain-to-capability mapping"
+ */
+
+/**
+ * Exhaustive map of every chain name used across Soleri's 8 flow YAML files.
+ *
+ * Sources:
+ *   build.flow.yaml    — vault-search, memory-search, component-search,
+ *                         recommend-design-system, architecture-search,
+ *                         brain-recommend, component-workflow,
+ *                         validate-component, validate-tokens
+ *   deliver.flow.yaml  — validate-component, validate-tokens,
+ *                         design-rules-check, test-coverage-check,
+ *                         performance-audit, delivery-checklist
+ *   design.flow.yaml   — vault-search, memory-search, cognee-design-search,
+ *                         recommend-design-system, recommend-style,
+ *                         recommend-palette, recommend-typography,
+ *                         get-stack-guidelines, brain-recommend
+ *   enhance.flow.yaml  — vault-search, memory-search, architecture-search,
+ *                         brain-recommend, validate-component, validate-tokens
+ *   explore.flow.yaml  — vault-search, memory-search, brain-strengths,
+ *                         brain-recommend, playbook-search
+ *   fix.flow.yaml      — vault-search-antipatterns, memory-search,
+ *                         error-pattern-search, brain-recommend,
+ *                         validate-component, validate-tokens
+ *   plan.flow.yaml     — vault-search, memory-search, brain-recommend,
+ *                         architecture-search, plan-create
+ *   review.flow.yaml   — validate-component, validate-tokens,
+ *                         design-rules-check, vault-search, contrast-check,
+ *                         accessibility-audit, review-report
+ */
+const CHAIN_TO_CAPABILITY: Record<string, string> = {
+  // Vault & Knowledge
+  'vault-search': 'vault.search',
+  'vault-search-antipatterns': 'vault.search',
+  'memory-search': 'memory.search',
+  'playbook-search': 'vault.playbook',
+
+  // Brain
+  'brain-recommend': 'brain.recommend',
+  'brain-strengths': 'brain.strengths',
+
+  // Components
+  'component-search': 'component.search',
+  'component-workflow': 'component.workflow',
+  'validate-component': 'component.validate',
+
+  // Design
+  'contrast-check': 'color.validate',
+  'validate-tokens': 'token.check',
+  'design-rules-check': 'design.rules',
+  'recommend-design-system': 'design.recommend',
+  'recommend-palette': 'design.palette',
+  'recommend-style': 'design.style',
+  'recommend-typography': 'design.typography',
+  'get-stack-guidelines': 'stack.guidelines',
+
+  // Architecture
+  'architecture-search': 'architecture.search',
+  'cognee-design-search': 'cognee.search',
+
+  // Planning
+  'plan-create': 'plan.create',
+
+  // Review & Quality
+  'review-report': 'review.report',
+  'accessibility-audit': 'a11y.audit',
+  'performance-audit': 'perf.audit',
+  'test-coverage-check': 'test.coverage',
+  'error-pattern-search': 'debug.patterns',
+  'delivery-checklist': 'deliver.checklist',
+};
+
+/**
+ * Translate a v1 chain name to a v2 capability ID.
+ *
+ * @param chain - The chain name from a flow YAML `chains:` field
+ * @returns The corresponding capability ID in domain.action format, or
+ *          undefined if no mapping exists
+ */
+export function chainToCapability(chain: string): string | undefined {
+  return CHAIN_TO_CAPABILITY[chain];
+}

package/src/capabilities/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Capability system — barrel export.
+ *
+ * @see docs/architecture/capability-packs.md
+ */
+
+export { CapabilityRegistry } from './registry.js';
+export type { FlowForValidation } from './registry.js';
+export { chainToCapability } from './chain-mapping.js';
+export type {
+  CapabilityDefinition,
+  CapabilityHandler,
+  CapabilityContext,
+  CapabilityResult,
+  KnowledgeContext,
+  BrainRecommendation,
+  RegisteredCapability,
+  ResolvedCapability,
+  PackSuggestion,
+  FlowValidation,
+} from './types.js';

package/src/capabilities/registry.ts

@@ -0,0 +1,290 @@
+/**
+ * Capability Registry — runtime resolution engine for the three-layer architecture.
+ *
+ * Maps capability IDs (domain.action) to pack handlers. Resolves dependencies,
+ * checks availability, and supports graceful degradation when capabilities are
+ * missing.
+ *
+ * Registration flow:
+ * 1. Pack manifest declares capabilities (static, serializable)
+ * 2. Pack's onActivate() provides handlers (runtime, async)
+ * 3. registerPack() reconciles declarations with handlers
+ *
+ * @see docs/architecture/capability-packs.md
+ */
+
+import type {
+  CapabilityDefinition,
+  CapabilityHandler,
+  RegisteredCapability,
+  ResolvedCapability,
+  PackSuggestion,
+  FlowValidation,
+} from './types.js';
+import { chainToCapability } from './chain-mapping.js';
+
+// ---------------------------------------------------------------------------
+// Flow shape accepted by validateFlow — intentionally minimal so callers
+// don't need to import the full Flow type from ../flows/types.js.
+// ---------------------------------------------------------------------------
+
+export interface FlowForValidation {
+  steps: Array<{
+    needs?: string[];
+    chains?: string[];
+  }>;
+  onMissingCapability?: {
+    default?: string;
+    blocking?: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class CapabilityRegistry {
+  private capabilities = new Map<string, RegisteredCapability>();
+  private packs = new Map<string, { id: string; capabilities: CapabilityDefinition[] }>();
+
+  // -----------------------------------------------------------------------
+  // Registration
+  // -----------------------------------------------------------------------
+
+  /**
+   * Register all capabilities from an installed pack.
+   *
+   * For each definition in `definitions`, the corresponding handler is looked
+   * up in `handlers`. If no handler is found the capability is skipped with a
+   * warning. When multiple packs provide the same capability, providers are
+   * sorted by priority (descending) — highest priority wins on resolve().
+   *
+   * @param packId      - Unique identifier for the pack
+   * @param definitions - Capability definitions from the pack manifest
+   * @param handlers    - Map of capabilityId → handler from onActivate()
+   * @param priority    - Higher = preferred (core=100, user=75, domain=50, fallback=0)
+   */
+  registerPack(
+    packId: string,
+    definitions: CapabilityDefinition[],
+    handlers: Map<string, CapabilityHandler>,
+    priority: number = 0,
+  ): void {
+    for (const definition of definitions) {
+      const handler = handlers.get(definition.id);
+      if (!handler) {
+        console.warn(
+          `Pack "${packId}" declares capability "${definition.id}" but no handler provided — skipping`,
+        );
+        continue;
+      }
+
+      const existing = this.capabilities.get(definition.id);
+      if (existing) {
+        // Add as additional provider, keep sorted by priority descending
+        existing.providers.push({ packId, handler, priority });
+        existing.providers.sort((a, b) => b.priority - a.priority);
+      } else {
+        this.capabilities.set(definition.id, {
+          definition,
+          providers: [{ packId, handler, priority }],
+        });
+      }
+    }
+
+    // Store pack metadata for suggestPacksFor() lookups
+    this.packs.set(packId, { id: packId, capabilities: definitions });
+  }
+
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+
+  /**
+   * Check if a capability is registered (has at least one provider).
+   */
+  has(capabilityId: string): boolean {
+    return this.capabilities.has(capabilityId);
+  }
+
+  /**
+   * Resolve a capability — returns the highest-priority handler, knowledge
+   * refs, and provider list. If the capability is missing or has unsatisfied
+   * dependencies, returns `available: false` with suggestions.
+   */
+  resolve(capabilityId: string): ResolvedCapability {
+    const registered = this.capabilities.get(capabilityId);
+
+    if (!registered) {
+      return {
+        available: false,
+        capabilityId,
+        suggestion: this.suggestPacksFor([capabilityId]),
+      };
+    }
+
+    // Check dependency satisfaction
+    const depends = registered.definition.depends ?? [];
+    const missingDeps = depends.filter((dep) => !this.capabilities.has(dep));
+
+    if (missingDeps.length > 0) {
+      return {
+        available: false,
+        capabilityId,
+        missingDependencies: missingDeps,
+        suggestion: this.suggestPacksFor(missingDeps),
+      };
+    }
+
+    // Resolved — return the highest-priority provider (index 0 after sort)
+    const primary = registered.providers[0];
+    return {
+      available: true,
+      capabilityId,
+      handler: primary.handler,
+      providers: registered.providers.map((p) => p.packId),
+      knowledge: registered.definition.knowledge ?? [],
+    };
+  }
+
+  /**
+   * List all registered capabilities grouped by domain.
+   *
+   * Domain is derived from the first segment of the capability ID
+   * (e.g., "color" from "color.validate").
+   */
+  list(): Map<string, CapabilityDefinition[]> {
+    const grouped = new Map<string, CapabilityDefinition[]>();
+
+    for (const [id, registered] of this.capabilities) {
+      const domain = id.split('.')[0];
+      const group = grouped.get(domain) ?? [];
+      group.push(registered.definition);
+      grouped.set(domain, group);
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Search registered packs for capabilities matching the requested IDs.
+   *
+   * This searches ALL packs (not just capabilities currently registered with
+   * handlers) — useful for suggesting which packs to install when a capability
+   * is missing.
+   */
+  suggestPacksFor(capabilityIds: string[]): PackSuggestion[] {
+    if (capabilityIds.length === 0) return [];
+
+    const idSet = new Set(capabilityIds);
+    const suggestions: PackSuggestion[] = [];
+
+    for (const [, pack] of this.packs) {
+      const provides = pack.capabilities.filter((cap) => idSet.has(cap.id)).map((cap) => cap.id);
+
+      if (provides.length > 0) {
+        suggestions.push({ packId: pack.id, provides });
+      }
+    }
+
+    return suggestions;
+  }
+
+  // -----------------------------------------------------------------------
+  // Validation
+  // -----------------------------------------------------------------------
+
+  /**
+   * Validate a flow's capability requirements against installed packs.
+   *
+   * Reads both `needs` (v2 preferred) and `chains` (v1 deprecated) fields.
+   * For v1 chains, attempts best-effort mapping via chainToCapability().
+   *
+   * Missing capabilities are classified as either "blocking" or "degraded"
+   * based on the flow's onMissingCapability config.
+   */
+  validateFlow(flow: FlowForValidation): FlowValidation {
+    // Collect all capability IDs needed across all steps
+    const needed = new Set<string>();
+
+    for (const step of flow.steps) {
+      // v2: needs field (preferred)
+      if (step.needs) {
+        for (const cap of step.needs) {
+          needed.add(cap);
+        }
+      }
+
+      // v1: chains field (deprecated, best-effort mapping)
+      if (step.chains) {
+        for (const chain of step.chains) {
+          const capId = chainToCapability(chain);
+          if (capId) needed.add(capId);
+        }
+      }
+    }
+
+    // Partition into available vs missing
+    const available: string[] = [];
+    const missing: string[] = [];
+
+    for (const capId of needed) {
+      if (this.has(capId)) {
+        available.push(capId);
+      } else {
+        missing.push(capId);
+      }
+    }
+
+    // Classify missing capabilities by impact
+    const blockingSet = new Set(flow.onMissingCapability?.blocking ?? []);
+
+    const degraded = missing.map((capability) => ({
+      capability,
+      impact: blockingSet.has(capability) ? ('blocking' as const) : ('degraded' as const),
+      suggestion: this.suggestPacksFor([capability]),
+    }));
+
+    const hasBlocker = degraded.some((d) => d.impact === 'blocking');
+
+    return {
+      valid: missing.length === 0,
+      available,
+      missing,
+      degraded,
+      canRunPartially: !hasBlocker,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // Inspection (useful for debugging / CLI commands)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Total number of registered capabilities.
+   */
+  get size(): number {
+    return this.capabilities.size;
+  }
+
+  /**
+   * Total number of registered packs.
+   */
+  get packCount(): number {
+    return this.packs.size;
+  }
+
+  /**
+   * Get all registered capability IDs.
+   */
+  ids(): string[] {
+    return [...this.capabilities.keys()];
+  }
+
+  /**
+   * Get the RegisteredCapability for a given ID, or undefined.
+   */
+  get(capabilityId: string): RegisteredCapability | undefined {
+    return this.capabilities.get(capabilityId);
+  }
+}