@soleri/core 2.12.0 → 8.0.0

package/src/domain-packs/loader.ts

@@ -0,0 +1,124 @@
+/**
+ * Domain Pack loader — resolves, validates, and dependency-sorts domain packs.
+ */
+
+import { validateDomainPack } from './types.js';
+import type { DomainPack, DomainPackManifest, DomainPackRef } from './types.js';
+
+/**
+ * Load a single domain pack from an npm package.
+ *
+ * @param packageName - npm package name (e.g., '@soleri/domain-design')
+ * @returns Validated DomainPackManifest
+ * @throws If package cannot be imported or fails validation
+ */
+export async function loadDomainPack(packageName: string): Promise<DomainPackManifest> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(packageName);
+  } catch (err) {
+    throw new Error(
+      `Failed to import domain pack "${packageName}": ${err instanceof Error ? err.message : String(err)}`, { cause: err },
+    );
+  }
+
+  // Support both default export and named 'pack' export
+  const packCandidate = mod.default ?? mod.pack;
+  if (!packCandidate) {
+    throw new Error(`Domain pack "${packageName}" has no default or named "pack" export.`);
+  }
+
+  const result = validateDomainPack(packCandidate);
+  if (!result.success) {
+    throw new Error(`Domain pack "${packageName}" failed validation: ${result.errors.message}`);
+  }
+
+  return {
+    ...result.data,
+    packageName,
+  };
+}
+
+/**
+ * Load all domain packs from AgentConfig refs.
+ *
+ * @param refs - Array of DomainPackRef from agent config
+ * @returns Validated and dependency-sorted packs
+ */
+export async function loadDomainPacksFromConfig(
+  refs: DomainPackRef[],
+): Promise<DomainPackManifest[]> {
+  const packs = await Promise.all(refs.map((ref) => loadDomainPack(ref.package)));
+  return resolveDependencies(packs);
+}
+
+/**
+ * Topological sort of domain packs by their `requires` field.
+ *
+ * @param packs - Array of domain packs (validated)
+ * @returns Sorted array (dependencies before dependents)
+ * @throws On circular dependencies or missing dependencies
+ */
+export function resolveDependencies<T extends DomainPack>(packs: T[]): T[] {
+  const byName = new Map<string, T>();
+  for (const pack of packs) {
+    byName.set(pack.name, pack);
+  }
+
+  // Check for missing dependencies
+  for (const pack of packs) {
+    if (pack.requires) {
+      for (const dep of pack.requires) {
+        if (!byName.has(dep)) {
+          throw new Error(
+            `Domain pack "${pack.name}" requires "${dep}" but it was not found in the loaded packs.`,
+          );
+        }
+      }
+    }
+  }
+
+  // Kahn's algorithm for topological sort
+  const inDegree = new Map<string, number>();
+  const adjList = new Map<string, string[]>();
+
+  for (const pack of packs) {
+    inDegree.set(pack.name, 0);
+    adjList.set(pack.name, []);
+  }
+
+  for (const pack of packs) {
+    if (pack.requires) {
+      for (const dep of pack.requires) {
+        adjList.get(dep)!.push(pack.name);
+        inDegree.set(pack.name, (inDegree.get(pack.name) ?? 0) + 1);
+      }
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name);
+  }
+
+  const sorted: T[] = [];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    sorted.push(byName.get(current)!);
+
+    for (const dependent of adjList.get(current) ?? []) {
+      const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length !== packs.length) {
+    const remaining = packs
+      .filter((p) => !sorted.some((s) => s.name === p.name))
+      .map((p) => p.name);
+    throw new Error(`Circular dependency detected among domain packs: ${remaining.join(', ')}`);
+  }
+
+  return sorted;
+}

package/src/domain-packs/pack-runtime.ts

@@ -0,0 +1,99 @@
+/**
+ * PackRuntime — the subset of AgentRuntime available to domain packs.
+ *
+ * Domain packs receive this via onActivate(runtime). It exposes only what
+ * packs need: vault search, project registry, and session store.
+ * Packs should NOT depend on the full AgentRuntime interface.
+ */
+
+import type { Vault } from '../vault/vault.js';
+
+/**
+ * Minimal project context for token resolution.
+ * Matches the shape of ProjectRegistry entries.
+ */
+export interface PackProjectContext {
+  id: string;
+  name: string;
+  path: string;
+  colors?: {
+    [scale: string]: {
+      scale: Record<string, string>;
+      base: string;
+    };
+  };
+  semanticTokens?: Record<string, string>;
+}
+
+/**
+ * Session check for tool chaining (contrast → component create).
+ */
+export interface PackCheckContext {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * The runtime interface domain packs receive via onActivate.
+ *
+ * Designed for graceful degradation: packs work without runtime
+ * (simplified mode), but gain full power when connected.
+ */
+export interface PackRuntime {
+  /** Vault for knowledge search and capture */
+  vault: Vault;
+
+  /** Get a registered project by ID (for token resolution) */
+  getProject(projectId: string): PackProjectContext | undefined;
+
+  /** List all registered projects */
+  listProjects(): Array<{ id: string; name: string; path: string }>;
+
+  /** Create a session check (for tool chaining) */
+  createCheck(type: string, data: Record<string, unknown>): string;
+
+  /** Validate a session check */
+  validateCheck(checkId: string, expectedType: string): PackCheckContext | null;
+
+  /** Validate and consume a session check (single-use) */
+  validateAndConsume(checkId: string, expectedType: string): PackCheckContext | null;
+}
+
+/**
+ * Create a PackRuntime from an AgentRuntime.
+ *
+ * This adapter extracts the subset of runtime that packs need,
+ * avoiding tight coupling to the full AgentRuntime interface.
+ */
+export function createPackRuntime(runtime: {
+  vault: Vault;
+  projectRegistry: {
+    getProject(id: string): PackProjectContext | undefined;
+    listProjects(): Array<{ id: string; name: string; path: string }>;
+  };
+  sessionStore?: {
+    createCheck(type: string, data: Record<string, unknown>): string;
+    validateCheck(id: string, type: string): PackCheckContext | null;
+    validateAndConsume(id: string, type: string): PackCheckContext | null;
+  };
+}): PackRuntime {
+  return {
+    vault: runtime.vault,
+    getProject: (id) => runtime.projectRegistry.getProject(id),
+    listProjects: () => runtime.projectRegistry.listProjects(),
+    createCheck: (type, data) => {
+      if (!runtime.sessionStore) throw new Error('Session store not available');
+      return runtime.sessionStore.createCheck(type, data);
+    },
+    validateCheck: (id, type) => {
+      if (!runtime.sessionStore) return null;
+      return runtime.sessionStore.validateCheck(id, type);
+    },
+    validateAndConsume: (id, type) => {
+      if (!runtime.sessionStore) return null;
+      return runtime.sessionStore.validateAndConsume(id, type);
+    },
+  };
+}

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 };
+}