@soleri/core 2.11.0 → 7.0.0

package/src/domain-packs/skills-installer.ts

@@ -0,0 +1,56 @@
+/**
+ * Skills installer for domain packs.
+ *
+ * Copies skill .md files from the pack to the agent's skills directory.
+ * Does not overwrite existing skills unless force flag is set.
+ */
+
+import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { DomainPack } from './types.js';
+
+export interface SkillsInstallResult {
+  installed: number;
+  skipped: number;
+}
+
+/**
+ * Install skills from a domain pack.
+ *
+ * @param pack - The domain pack with skills
+ * @param targetDir - Agent's skills directory
+ * @param rootDir - Absolute path to the pack's root directory
+ * @param force - Overwrite existing skills if true
+ */
+export function installSkills(
+  pack: DomainPack,
+  targetDir: string,
+  rootDir: string,
+  force = false,
+): SkillsInstallResult {
+  const result: SkillsInstallResult = { installed: 0, skipped: 0 };
+
+  if (!pack.skills || pack.skills.length === 0) return result;
+
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const skill of pack.skills) {
+    const sourcePath = resolve(rootDir, skill.path);
+    const targetPath = join(targetDir, `${skill.name}.md`);
+
+    if (!existsSync(sourcePath)) {
+      result.skipped++;
+      continue;
+    }
+
+    if (existsSync(targetPath) && !force) {
+      result.skipped++;
+      continue;
+    }
+
+    copyFileSync(sourcePath, targetPath);
+    result.installed++;
+  }
+
+  return result;
+}

package/src/domain-packs/token-resolver.ts

@@ -0,0 +1,126 @@
+/**
+ * TokenResolver — resolves design token names to hex values.
+ *
+ * Ported from Salvador MCP src/registry/token-resolver.ts.
+ * Supports: #HEX passthrough, SCALE[SHADE] (e.g., PRIMARY[500]),
+ * Tailwind classes (bg-primary-500), semantic tokens (text-inverse),
+ * and named colors (white, black).
+ *
+ * Stateless — create per-invocation with a ProjectContext.
+ */
+
+import type { PackProjectContext } from './pack-runtime.js';
+
+const NAMED_COLORS: Record<string, string> = {
+  white: '#FFFFFF',
+  black: '#000000',
+  transparent: '#00000000',
+};
+
+/**
+ * Resolve a token or color reference to a hex value.
+ *
+ * @param tokenOrHex - Token name, hex value, or color reference
+ * @param project - Project context with color scales and semantic tokens
+ * @returns Uppercase hex string (e.g., "#DC0000")
+ * @throws If the token cannot be resolved
+ */
+export function resolveToken(tokenOrHex: string, project: PackProjectContext): string {
+  // Passthrough hex values
+  if (tokenOrHex.startsWith('#')) {
+    return tokenOrHex.toUpperCase();
+  }
+
+  // Named colors
+  const named = NAMED_COLORS[tokenOrHex.toLowerCase()];
+  if (named) return named;
+
+  // Semantic tokens (e.g., "text-inverse", "bg-surface")
+  if (project.semanticTokens) {
+    const semantic = project.semanticTokens[tokenOrHex];
+    if (semantic) return semantic.toUpperCase();
+  }
+
+  // SCALE[SHADE] format (e.g., "PRIMARY[500]", "neutral[900]")
+  const scaleMatch = tokenOrHex.match(/^(\w+)\[(\d+)\]$/);
+  if (scaleMatch) {
+    const [, scaleName, shade] = scaleMatch;
+    return resolveScale(scaleName.toLowerCase(), shade, project);
+  }
+
+  // Tailwind-style: bg-primary-500, text-neutral-700
+  const tailwindMatch = tokenOrHex.match(/^(?:bg|text|border|ring|fill|stroke)-(\w+)-(\d+)$/);
+  if (tailwindMatch) {
+    const [, scaleName, shade] = tailwindMatch;
+    return resolveScale(scaleName, shade, project);
+  }
+
+  throw new Error(`Cannot resolve token: "${tokenOrHex}"`);
+}
+
+function resolveScale(scaleName: string, shade: string, project: PackProjectContext): string {
+  if (!project.colors) {
+    throw new Error(`Project "${project.name}" has no color scales`);
+  }
+
+  const scale = project.colors[scaleName];
+  if (!scale) {
+    const available = Object.keys(project.colors).join(', ');
+    throw new Error(`Unknown color scale "${scaleName}". Available: ${available}`);
+  }
+
+  const hex = scale.scale[shade];
+  if (!hex) {
+    const available = Object.keys(scale.scale).join(', ');
+    throw new Error(`Unknown shade "${shade}" in scale "${scaleName}". Available: ${available}`);
+  }
+
+  return hex.toUpperCase();
+}
+
+/**
+ * List all tokens available in a project.
+ *
+ * @param project - Project context
+ * @returns Array of { token, hex, scale } for all scale + semantic tokens
+ */
+export function listProjectTokens(
+  project: PackProjectContext,
+): Array<{ token: string; hex: string; scale: string }> {
+  const tokens: Array<{ token: string; hex: string; scale: string }> = [];
+
+  // Scale tokens
+  if (project.colors) {
+    for (const [scaleName, scaleData] of Object.entries(project.colors)) {
+      for (const [shade, hex] of Object.entries(scaleData.scale)) {
+        tokens.push({
+          token: `${scaleName}-${shade}`,
+          hex: hex.toUpperCase(),
+          scale: scaleName,
+        });
+      }
+    }
+  }
+
+  // Semantic tokens
+  if (project.semanticTokens) {
+    for (const [name, hex] of Object.entries(project.semanticTokens)) {
+      tokens.push({ token: name, hex: hex.toUpperCase(), scale: 'semantic' });
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Build a reverse index: hex → token name.
+ * Useful for detecting hardcoded colors.
+ */
+export function buildReverseIndex(project: PackProjectContext): Map<string, string> {
+  const index = new Map<string, string>();
+  const tokens = listProjectTokens(project);
+  for (const t of tokens) {
+    index.set(t.hex.toUpperCase(), t.token);
+  }
+  return index;
+}

package/src/domain-packs/types.ts

@@ -0,0 +1,229 @@
+/**
+ * Domain Pack types — the contract for plug-and-play domain intelligence.
+ *
+ * A DomainPack is an npm package that bundles:
+ * - Custom ops with real algorithmic logic (e.g., WCAG contrast checking)
+ * - Optional standalone facades (one pack can register multiple MCP tools)
+ * - Tiered knowledge (canonical/curated/captured)
+ * - CLAUDE.md behavioral rules
+ * - Skills
+ *
+ * One pack = one npm package, can register multiple facades.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition, FacadeConfig } from '../facades/types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { PackRuntime } from './pack-runtime.js';
+
+// ---------------------------------------------------------------------------
+// Reserved names — packs cannot claim these as facade names
+// ---------------------------------------------------------------------------
+
+export const SEMANTIC_FACADE_NAMES: ReadonlyArray<string> = [
+  'vault',
+  'plan',
+  'brain',
+  'memory',
+  'admin',
+  'curator',
+  'loop',
+  'orchestrate',
+  'control',
+  'cognee',
+  'governance',
+  'context',
+  'agency',
+  'chat',
+  'playbook',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Knowledge Manifest — tiered knowledge with different lifecycle rules
+// ---------------------------------------------------------------------------
+
+/** Three-tier knowledge structure. Each tier has different lifecycle rules. */
+export interface KnowledgeManifest {
+  /** Immutable rules and axioms. Never overwritten by curator. Highest search authority. */
+  canonical?: string;
+  /** Patterns and anti-patterns. Curator can groom, deduplicate, enrich. */
+  curated?: string;
+  /** Seed learnings. Rarely shipped — normally emerges from agent usage. */
+  captured?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Skill Definition (for pack-bundled skills)
+// ---------------------------------------------------------------------------
+
+export interface PackSkillDefinition {
+  /** Skill file name (without .md extension) */
+  name: string;
+  /** Path to the .md skill file relative to the pack */
+  path: string;
+}
+
+// ---------------------------------------------------------------------------
+// DomainPack — the main interface
+// ---------------------------------------------------------------------------
+
+/** The contract every domain pack must implement. */
+export interface DomainPack {
+  /** Unique pack name (e.g., 'design', 'security-intelligence') */
+  name: string;
+  /** Semver version */
+  version: string;
+  /** Domains this pack claims. Ops inject into these domain facades. */
+  domains: string[];
+  /** Custom operations with real logic — injected into claimed domain facades. */
+  ops: OpDefinition[];
+  /** Additional standalone facades (one pack can register multiple MCP tools). */
+  facades?: FacadeConfig[];
+  /** Tiered knowledge to install into the agent's vault. */
+  knowledge?: KnowledgeManifest;
+  /** CLAUDE.md behavioral rules fragment (markdown). */
+  rules?: string;
+  /** Skills to install into the agent's skills directory. */
+  skills?: PackSkillDefinition[];
+  /** Capability handler factory — returns handlers for declared capabilities */
+  capabilities?: (
+    runtime: PackRuntime,
+  ) => Map<string, import('../capabilities/types.js').CapabilityHandler>;
+  /** Other packs this pack depends on (by name). */
+  requires?: string[];
+  /** Called after pack is installed (one-time setup). */
+  onInstall?: (runtime: AgentRuntime) => Promise<void>;
+  /** Called each time the agent starts (runtime initialization). */
+  onActivate?: (runtime: AgentRuntime) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// DomainPackRef — lightweight reference for AgentConfig
+// ---------------------------------------------------------------------------
+
+/** Reference to a domain pack in agent configuration. */
+export interface DomainPackRef {
+  /** Display name */
+  name: string;
+  /** npm package name (e.g., '@soleri/domain-design') */
+  package: string;
+  /** Optional version constraint */
+  version?: string;
+}
+
+// ---------------------------------------------------------------------------
+// DomainPackManifest — validated and resolved pack
+// ---------------------------------------------------------------------------
+
+/** A DomainPack that has been validated and resolved. */
+export interface DomainPackManifest extends DomainPack {
+  /** Resolved from npm package name */
+  packageName: string;
+  /** Absolute path to the pack's root directory */
+  rootDir?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+const knowledgeManifestSchema = z.object({
+  canonical: z.string().optional(),
+  curated: z.string().optional(),
+  captured: z.string().optional(),
+});
+
+const packSkillSchema = z.object({
+  name: z.string(),
+  path: z.string(),
+});
+
+/** Zod schema for validating DomainPack structure (data fields only). */
+const domainPackSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().min(1),
+  domains: z.array(z.string().min(1)).min(1),
+  ops: z.array(
+    z.object({
+      name: z.string().min(1),
+      description: z.string(),
+      auth: z.enum(['read', 'write', 'admin']),
+      handler: z.function(),
+      schema: z.any().optional(),
+      hot: z.boolean().optional(),
+    }),
+  ),
+  facades: z
+    .array(
+      z.object({
+        name: z.string().min(1),
+        description: z.string(),
+        ops: z.array(z.any()),
+      }),
+    )
+    .optional(),
+  knowledge: knowledgeManifestSchema.optional(),
+  rules: z.string().optional(),
+  skills: z.array(packSkillSchema).optional(),
+  requires: z.array(z.string()).optional(),
+  onInstall: z.function().optional(),
+  onActivate: z.function().optional(),
+});
+
+export type ValidateResult =
+  | { success: true; data: DomainPack }
+  | { success: false; errors: z.ZodError };
+
+/**
+ * Validate an unknown value as a DomainPack.
+ *
+ * Beyond Zod shape validation, also checks:
+ * - Op names are unique within the pack
+ * - Facade names don't collide with semantic facades
+ */
+export function validateDomainPack(value: unknown): ValidateResult {
+  const parsed = domainPackSchema.safeParse(value);
+  if (!parsed.success) {
+    return { success: false, errors: parsed.error };
+  }
+
+  const pack = parsed.data as DomainPack;
+
+  // Check for duplicate op names
+  const opNames = new Set<string>();
+  for (const op of pack.ops) {
+    if (opNames.has(op.name)) {
+      return {
+        success: false,
+        errors: new z.ZodError([
+          {
+            code: 'custom',
+            path: ['ops'],
+            message: `Duplicate op name: "${op.name}"`,
+          },
+        ]),
+      };
+    }
+    opNames.add(op.name);
+  }
+
+  // Check facade name collisions with semantic facades
+  if (pack.facades) {
+    for (const facade of pack.facades) {
+      if (SEMANTIC_FACADE_NAMES.includes(facade.name)) {
+        return {
+          success: false,
+          errors: new z.ZodError([
+            {
+              code: 'custom',
+              path: ['facades'],
+              message: `Facade name "${facade.name}" collides with semantic facade. Reserved names: ${SEMANTIC_FACADE_NAMES.join(', ')}`,
+            },
+          ]),
+        };
+      }
+    }
+  }
+
+  return { success: true, data: pack };
+}

package/src/engine/__tests__/register-engine.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for the direct engine registration (replaces facade factory).
+ *
+ * Validates that registerEngine() produces the same tools and behavior
+ * as the old createSemanticFacades() + registerAllFacades() pattern.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createAgentRuntime } from '../../runtime/runtime.js';
+import { captureOps, executeOp } from '../test-helpers.js';
+import { createVaultFacadeOps } from '../../runtime/facades/vault-facade.js';
+import { createBrainFacadeOps } from '../../runtime/facades/brain-facade.js';
+import { createPlanFacadeOps } from '../../runtime/facades/plan-facade.js';
+import { createCuratorFacadeOps } from '../../runtime/facades/curator-facade.js';
+import { createLoopFacadeOps } from '../../runtime/facades/loop-facade.js';
+import type { AgentRuntime } from '../../runtime/types.js';
+
+let runtime: AgentRuntime;
+
+beforeAll(() => {
+  runtime = createAgentRuntime({
+    agentId: 'test-engine',
+    vaultPath: ':memory:',
+  });
+});
+
+afterAll(() => {
+  runtime.close();
+});
+
+describe('Direct op execution (no facade factory)', () => {
+  it('vault ops work without facade dispatch', async () => {
+    const ops = captureOps(createVaultFacadeOps(runtime));
+
+    // Capture a pattern
+    const captureResult = await executeOp(ops, 'capture_enriched', {
+      projectPath: '.',
+      title: 'Test Pattern',
+      description: 'A test pattern for engine registration',
+      type: 'pattern',
+      category: 'testing',
+      severity: 'suggestion',
+      tags: ['test'],
+    });
+    expect(captureResult.success).toBe(true);
+
+    // Search for it
+    const searchResult = await executeOp(ops, 'search', {
+      query: 'test pattern engine',
+    });
+    expect(searchResult.success).toBe(true);
+    expect(searchResult.data).toBeDefined();
+  });
+
+  it('brain ops work without facade dispatch', async () => {
+    const ops = captureOps(createBrainFacadeOps(runtime));
+
+    const statsResult = await executeOp(ops, 'brain_stats', {});
+    expect(statsResult.success).toBe(true);
+    expect(statsResult.data).toBeDefined();
+  });
+
+  it('plan ops work without facade dispatch', async () => {
+    const ops = captureOps(createPlanFacadeOps(runtime));
+
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Test objective',
+      scope: 'Test scope',
+    });
+    expect(createResult.success).toBe(true);
+    expect(createResult.data).toBeDefined();
+  });
+
+  it('curator ops work without facade dispatch', async () => {
+    const ops = captureOps(createCuratorFacadeOps(runtime));
+
+    const statusResult = await executeOp(ops, 'curator_status', {});
+    expect(statusResult.success).toBe(true);
+  });
+
+  it('loop ops work without facade dispatch', async () => {
+    const ops = captureOps(createLoopFacadeOps(runtime));
+
+    const statusResult = await executeOp(ops, 'loop_status', {});
+    expect(statusResult.success).toBe(true);
+  });
+
+  it('returns error for unknown ops', async () => {
+    const ops = captureOps(createVaultFacadeOps(runtime));
+
+    const result = await executeOp(ops, 'nonexistent_op', {});
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Unknown operation');
+  });
+
+  it('response envelope matches old format', async () => {
+    const ops = captureOps(createVaultFacadeOps(runtime));
+
+    const result = await executeOp(ops, 'vault_stats', {}, 'test_vault');
+    expect(result).toHaveProperty('success');
+    expect(result).toHaveProperty('op', 'vault_stats');
+    expect(result).toHaveProperty('facade', 'test_vault');
+  });
+});