@soleri/core 2.10.0 → 2.12.0

package/src/migrations/migration-runner.ts

@@ -0,0 +1,185 @@
+/**
+ * Schema Migration Runner — versioned migration scripts for engine upgrades.
+ *
+ * Migrations run in version order, track state in `_soleri_migrations` table,
+ * and support verify + rollback.
+ */
+
+import type { Database } from 'better-sqlite3';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface Migration {
+  /** Semver version this migration applies to */
+  version: string;
+  /** Human-readable description */
+  description: string;
+  /** Apply the migration */
+  up: (db: Database) => void;
+  /** Verify the migration was applied correctly */
+  verify?: (db: Database) => boolean;
+  /** Rollback (optional) */
+  down?: (db: Database) => void;
+}
+
+export interface MigrationResult {
+  version: string;
+  description: string;
+  status: 'applied' | 'skipped' | 'failed' | 'rolled-back';
+  error?: string;
+  durationMs: number;
+}
+
+export interface MigrationState {
+  version: string;
+  appliedAt: string;
+  description: string;
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────
+
+export class MigrationRunner {
+  constructor(private db: Database) {
+    this.ensureTable();
+  }
+
+  /**
+   * Run all pending migrations in version order.
+   */
+  run(migrations: Migration[]): MigrationResult[] {
+    const applied = this.getApplied();
+    const sorted = [...migrations].sort((a, b) => compareVersions(a.version, b.version));
+    const results: MigrationResult[] = [];
+
+    for (const migration of sorted) {
+      if (applied.has(migration.version)) {
+        results.push({
+          version: migration.version,
+          description: migration.description,
+          status: 'skipped',
+          durationMs: 0,
+        });
+        continue;
+      }
+
+      const start = Date.now();
+      try {
+        migration.up(this.db);
+
+        // Verify if verifier provided
+        if (migration.verify && !migration.verify(this.db)) {
+          // Rollback if possible
+          if (migration.down) {
+            migration.down(this.db);
+            results.push({
+              version: migration.version,
+              description: migration.description,
+              status: 'rolled-back',
+              error: 'Verification failed after apply',
+              durationMs: Date.now() - start,
+            });
+          } else {
+            results.push({
+              version: migration.version,
+              description: migration.description,
+              status: 'failed',
+              error: 'Verification failed, no rollback available',
+              durationMs: Date.now() - start,
+            });
+          }
+          continue;
+        }
+
+        // Record as applied
+        this.recordApplied(migration);
+        results.push({
+          version: migration.version,
+          description: migration.description,
+          status: 'applied',
+          durationMs: Date.now() - start,
+        });
+      } catch (err) {
+        // Attempt rollback
+        if (migration.down) {
+          try {
+            migration.down(this.db);
+          } catch {
+            // Rollback failed — nothing we can do
+          }
+        }
+
+        results.push({
+          version: migration.version,
+          description: migration.description,
+          status: 'failed',
+          error: err instanceof Error ? err.message : String(err),
+          durationMs: Date.now() - start,
+        });
+        // Stop on failure — don't run subsequent migrations
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get list of applied migrations.
+   */
+  listApplied(): MigrationState[] {
+    const stmt = this.db.prepare(
+      'SELECT version, applied_at, description FROM _soleri_migrations ORDER BY version',
+    );
+    const rows = stmt.all() as Array<{ version: string; applied_at: string; description: string }>;
+    return rows.map((row) => ({
+      version: row.version,
+      appliedAt: row.applied_at,
+      description: row.description,
+    }));
+  }
+
+  /**
+   * Get pending migrations (not yet applied).
+   */
+  getPending(migrations: Migration[]): Migration[] {
+    const applied = this.getApplied();
+    return migrations
+      .filter((m) => !applied.has(m.version))
+      .sort((a, b) => compareVersions(a.version, b.version));
+  }
+
+  private getApplied(): Set<string> {
+    const stmt = this.db.prepare('SELECT version FROM _soleri_migrations');
+    const rows = stmt.all() as Array<{ version: string }>;
+    return new Set(rows.map((r) => r.version));
+  }
+
+  private recordApplied(migration: Migration): void {
+    const stmt = this.db.prepare(
+      'INSERT INTO _soleri_migrations (version, applied_at, description) VALUES (?, ?, ?)',
+    );
+    stmt.run(migration.version, new Date().toISOString(), migration.description);
+  }
+
+  private ensureTable(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _soleri_migrations (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL,
+        description TEXT NOT NULL
+      )
+    `);
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}

package/src/packs/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Knowledge Packs — Barrel Exports
+ */
+
+export {
+  packManifestSchema,
+  type PackManifest,
+  type PackStatus,
+  type InstalledPack,
+  type InstallResult,
+  type ValidateResult,
+} from './types.js';
+
+export { PackInstaller } from './pack-installer.js';
+
+export { PackLockfile, inferPackType } from './lockfile.js';
+export type { LockEntry, PackType, PackSource, LockfileData } from './lockfile.js';
+
+export { resolvePack, checkNpmVersion, checkVersionCompat } from './resolver.js';
+export type { ResolvedPack, ResolveOptions } from './resolver.js';

package/src/packs/lockfile.ts

@@ -0,0 +1,180 @@
+/**
+ * Pack Lockfile — persists installed pack metadata to `soleri.lock`.
+ *
+ * Tracks installed pack versions, types, sources, and integrity hashes
+ * for reproducible agent setups. The lockfile enables:
+ * - `soleri pack install --frozen` (CI mode — fail if lockfile is stale)
+ * - `soleri pack outdated` (compare installed vs. latest available)
+ * - Persistence across restarts (unlike the in-memory PackInstaller registry)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface LockEntry {
+  /** Pack ID (from manifest) */
+  id: string;
+  /** Installed version (semver) */
+  version: string;
+  /** Pack type: hooks, skills, knowledge, domain, bundle */
+  type: PackType;
+  /** Where it was installed from */
+  source: PackSource;
+  /** Path to installed pack directory */
+  directory: string;
+  /** SHA-256 of the manifest file at install time */
+  integrity: string;
+  /** ISO timestamp of install */
+  installedAt: string;
+  /** Number of vault entries seeded */
+  vaultEntries: number;
+  /** Skill names discovered */
+  skills: string[];
+  /** Hook names discovered */
+  hooks: string[];
+  /** Whether facades were registered */
+  facadesRegistered: boolean;
+  /** Compatible @soleri/core version range (from manifest "soleri" field) */
+  soleriRange?: string;
+}
+
+export type PackType = 'hooks' | 'skills' | 'knowledge' | 'domain' | 'bundle';
+export type PackSource = 'built-in' | 'local' | 'npm';
+
+export interface LockfileData {
+  /** Lockfile format version */
+  version: 1;
+  /** Map of packId → lock entry */
+  packs: Record<string, LockEntry>;
+}
+
+// ─── Lockfile Manager ─────────────────────────────────────────────────
+
+export class PackLockfile {
+  private data: LockfileData;
+  private dirty = false;
+
+  constructor(private readonly filePath: string) {
+    this.data = this.load();
+  }
+
+  /**
+   * Get a lock entry by pack ID.
+   */
+  get(packId: string): LockEntry | undefined {
+    return this.data.packs[packId];
+  }
+
+  /**
+   * Set (add or update) a lock entry.
+   */
+  set(entry: LockEntry): void {
+    this.data.packs[entry.id] = entry;
+    this.dirty = true;
+  }
+
+  /**
+   * Remove a lock entry.
+   */
+  remove(packId: string): boolean {
+    if (!(packId in this.data.packs)) return false;
+    delete this.data.packs[packId];
+    this.dirty = true;
+    return true;
+  }
+
+  /**
+   * List all lock entries.
+   */
+  list(): LockEntry[] {
+    return Object.values(this.data.packs);
+  }
+
+  /**
+   * Check if a pack is locked.
+   */
+  has(packId: string): boolean {
+    return packId in this.data.packs;
+  }
+
+  /**
+   * Get number of locked packs.
+   */
+  get size(): number {
+    return Object.keys(this.data.packs).length;
+  }
+
+  /**
+   * Save lockfile to disk (only if dirty).
+   */
+  save(): boolean {
+    if (!this.dirty) return false;
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(this.filePath, JSON.stringify(this.data, null, 2) + '\n', 'utf-8');
+    this.dirty = false;
+    return true;
+  }
+
+  /**
+   * Force reload from disk.
+   */
+  reload(): void {
+    this.data = this.load();
+    this.dirty = false;
+  }
+
+  /**
+   * Compute integrity hash for a manifest file.
+   */
+  static computeIntegrity(manifestPath: string): string {
+    if (!existsSync(manifestPath)) return '';
+    const content = readFileSync(manifestPath, 'utf-8');
+    return 'sha256-' + createHash('sha256').update(content).digest('hex');
+  }
+
+  private load(): LockfileData {
+    if (!existsSync(this.filePath)) {
+      return { version: 1, packs: {} };
+    }
+    try {
+      const raw = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+      if (raw.version === 1 && typeof raw.packs === 'object') {
+        return raw as LockfileData;
+      }
+      return { version: 1, packs: {} };
+    } catch {
+      return { version: 1, packs: {} };
+    }
+  }
+}
+
+/**
+ * Infer pack type from manifest content.
+ */
+export function inferPackType(manifest: {
+  vault?: unknown;
+  skills?: unknown;
+  hooks?: unknown;
+  facades?: unknown[];
+  domains?: string[];
+}): PackType {
+  const hasVault = !!manifest.vault;
+  const hasSkills = !!manifest.skills;
+  const hasHooks = !!manifest.hooks;
+  const hasFacades = (manifest.facades?.length ?? 0) > 0;
+
+  // Bundle if multiple content types
+  const types = [hasVault, hasSkills, hasHooks, hasFacades].filter(Boolean).length;
+  if (types > 1) return 'bundle';
+
+  if (hasHooks) return 'hooks';
+  if (hasSkills) return 'skills';
+  if (hasFacades) return 'domain';
+  return 'knowledge';
+}

package/src/packs/pack-installer.ts

@@ -0,0 +1,289 @@
+/**
+ * Pack Installer — validates, loads vault entries, registers facades.
+ *
+ * Install flow:
+ * 1. Read and validate soleri-pack.json manifest
+ * 2. Load vault intelligence bundles from vault/ subdirectory
+ * 3. Register facades via plugin system
+ * 4. Discover skills and hooks
+ * 5. Return install summary
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import {
+  packManifestSchema,
+  type InstalledPack,
+  type InstallResult,
+  type ValidateResult,
+} from './types.js';
+import { loadIntelligenceData } from '../intelligence/loader.js';
+import type { Vault } from '../vault/vault.js';
+import type { PluginRegistry } from '../plugins/plugin-registry.js';
+import type { PluginContext } from '../plugins/types.js';
+
+const MANIFEST_FILENAME = 'soleri-pack.json';
+
+// =============================================================================
+// PACK REGISTRY (in-memory)
+// =============================================================================
+
+export class PackInstaller {
+  private packs = new Map<string, InstalledPack>();
+
+  constructor(
+    private vault: Vault,
+    private pluginRegistry: PluginRegistry,
+  ) {}
+
+  /**
+   * Validate a pack directory without installing.
+   */
+  validate(packDir: string): ValidateResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // 1. Check manifest
+    const manifestPath = join(packDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath)) {
+      return { valid: false, errors: [`No ${MANIFEST_FILENAME} found in ${packDir}`], warnings };
+    }
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    } catch (e) {
+      return {
+        valid: false,
+        errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`],
+        warnings,
+      };
+    }
+
+    const parseResult = packManifestSchema.safeParse(raw);
+    if (!parseResult.success) {
+      const issues = parseResult.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+      return { valid: false, errors: issues, warnings };
+    }
+
+    const manifest = parseResult.data;
+
+    // 2. Count vault entries
+    let vaultEntries = 0;
+    const vaultDir = join(packDir, manifest.vault?.dir ?? 'vault');
+    if (existsSync(vaultDir)) {
+      const entries = loadIntelligenceData(vaultDir);
+      vaultEntries = entries.length;
+    } else if (manifest.vault) {
+      warnings.push(`Vault directory "${manifest.vault.dir}" declared but not found`);
+    }
+
+    // 3. Count skills
+    const skillsDir = join(packDir, manifest.skills?.dir ?? 'skills');
+    const skills = existsSync(skillsDir) ? listMarkdownFiles(skillsDir) : [];
+    if (manifest.skills && skills.length === 0) {
+      warnings.push(`Skills directory "${manifest.skills.dir}" declared but empty or not found`);
+    }
+
+    // 4. Count hooks
+    const hooksDir = join(packDir, manifest.hooks?.dir ?? 'hooks');
+    const hooks = existsSync(hooksDir) ? listMarkdownFiles(hooksDir) : [];
+    if (manifest.hooks && hooks.length === 0) {
+      warnings.push(`Hooks directory "${manifest.hooks.dir}" declared but empty or not found`);
+    }
+
+    // 5. Count facades/ops
+    const facades = manifest.facades.length;
+    const ops = manifest.facades.reduce((sum, f) => sum + f.ops.length, 0);
+
+    return {
+      valid: true,
+      manifest,
+      errors,
+      warnings,
+      counts: { vaultEntries, skills: skills.length, hooks: hooks.length, facades, ops },
+    };
+  }
+
+  /**
+   * Install a knowledge pack from a directory.
+   */
+  async install(packDir: string, runtimeCtx?: unknown): Promise<InstallResult> {
+    // Validate first
+    const validation = this.validate(packDir);
+    if (!validation.valid || !validation.manifest) {
+      return {
+        id: 'unknown',
+        installed: false,
+        vaultEntries: 0,
+        skills: [],
+        hooks: [],
+        facades: 0,
+        error: validation.errors.join('; '),
+      };
+    }
+
+    const manifest = validation.manifest;
+
+    // Check duplicate
+    if (this.packs.has(manifest.id)) {
+      return {
+        id: manifest.id,
+        installed: false,
+        vaultEntries: 0,
+        skills: [],
+        hooks: [],
+        facades: 0,
+        error: `Pack "${manifest.id}" is already installed`,
+      };
+    }
+
+    try {
+      // 1. Seed vault entries
+      let vaultEntries = 0;
+      const vaultDir = join(packDir, manifest.vault?.dir ?? 'vault');
+      if (existsSync(vaultDir)) {
+        const entries = loadIntelligenceData(vaultDir);
+        if (entries.length > 0) {
+          this.vault.seed(entries);
+          vaultEntries = entries.length;
+        }
+      }
+
+      // 2. Register facades via plugin system
+      let facadesRegistered = false;
+      if (manifest.facades.length > 0) {
+        // Convert pack manifest to plugin-compatible format for registry
+        const pluginLoaded = {
+          manifest: {
+            id: manifest.id,
+            name: manifest.name,
+            version: manifest.version,
+            description: manifest.description,
+            domain: manifest.domains[0],
+            dependencies: manifest.dependencies,
+            facades: manifest.facades,
+            intelligence: [],
+          },
+          directory: packDir,
+          provenance: 'custom' as const,
+        };
+
+        if (!this.pluginRegistry.get(manifest.id)) {
+          this.pluginRegistry.register(pluginLoaded);
+        }
+
+        const ctx: PluginContext = {
+          runtime: runtimeCtx ?? {},
+          manifest: pluginLoaded.manifest,
+          directory: packDir,
+        };
+
+        await this.pluginRegistry.activate(manifest.id, ctx);
+        facadesRegistered = true;
+      }
+
+      // 3. Discover skills
+      const skillsDir = join(packDir, manifest.skills?.dir ?? 'skills');
+      const skills = existsSync(skillsDir) ? listMarkdownFiles(skillsDir) : [];
+
+      // 4. Discover hooks
+      const hooksDir = join(packDir, manifest.hooks?.dir ?? 'hooks');
+      const hooks = existsSync(hooksDir) ? listMarkdownFiles(hooksDir) : [];
+
+      // Track installed pack
+      const installed: InstalledPack = {
+        id: manifest.id,
+        manifest,
+        directory: packDir,
+        status: 'installed',
+        vaultEntries,
+        skills,
+        hooks,
+        facadesRegistered,
+        installedAt: Date.now(),
+      };
+      this.packs.set(manifest.id, installed);
+
+      return {
+        id: manifest.id,
+        installed: true,
+        vaultEntries,
+        skills,
+        hooks,
+        facades: manifest.facades.length,
+      };
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+
+      this.packs.set(manifest.id, {
+        id: manifest.id,
+        manifest,
+        directory: packDir,
+        status: 'error',
+        error,
+        vaultEntries: 0,
+        skills: [],
+        hooks: [],
+        facadesRegistered: false,
+        installedAt: Date.now(),
+      });
+
+      return {
+        id: manifest.id,
+        installed: false,
+        vaultEntries: 0,
+        skills: [],
+        hooks: [],
+        facades: 0,
+        error,
+      };
+    }
+  }
+
+  /**
+   * Uninstall a pack — deactivates facades, removes from registry.
+   * Note: vault entries are NOT removed (they become part of knowledge).
+   */
+  uninstall(packId: string): boolean {
+    const pack = this.packs.get(packId);
+    if (!pack) return false;
+
+    // Deactivate facades
+    if (pack.facadesRegistered) {
+      this.pluginRegistry.deactivate(packId);
+    }
+
+    pack.status = 'uninstalled';
+    this.packs.delete(packId);
+    return true;
+  }
+
+  /**
+   * Get an installed pack by ID.
+   */
+  get(packId: string): InstalledPack | undefined {
+    return this.packs.get(packId);
+  }
+
+  /**
+   * List all installed packs.
+   */
+  list(): InstalledPack[] {
+    return Array.from(this.packs.values());
+  }
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function listMarkdownFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => basename(f, '.md'));
+  } catch {
+    return [];
+  }
+}