@soleri/core 2.9.0 → 2.11.0

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

package/src/packs/resolver.ts

@@ -0,0 +1,237 @@
+/**
+ * Pack Resolver — resolution chain for discovering packs.
+ *
+ * Resolution order:
+ * 1. Local file path (absolute or relative)
+ * 2. Built-in packs (bundled with the agent)
+ * 3. npm registry (@soleri/pack-* or soleri-pack-*)
+ *
+ * Each source implements the PackSource interface.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface ResolvedPack {
+  /** Local directory path to the pack */
+  directory: string;
+  /** Where it was resolved from */
+  source: 'local' | 'built-in' | 'npm';
+  /** npm package name (if resolved from npm) */
+  npmPackage?: string;
+  /** Resolved version (if from npm) */
+  resolvedVersion?: string;
+}
+
+export interface ResolveOptions {
+  /** Built-in pack directories to search */
+  builtinDirs?: string[];
+  /** Whether to try npm resolution. Default: true */
+  npm?: boolean;
+  /** Specific version to install (e.g., "1.2.0") */
+  version?: string;
+  /** npm timeout in ms. Default: 30_000 */
+  npmTimeout?: number;
+}
+
+// ─── Resolver ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a pack identifier to a local directory path.
+ *
+ * @param pack - Local path, built-in name, or npm package name
+ * @param options - Resolution options
+ * @returns Resolved pack directory and source metadata
+ */
+export function resolvePack(pack: string, options: ResolveOptions = {}): ResolvedPack {
+  // 1. Local path — absolute or relative, or existing directory
+  if (pack.startsWith('/') || pack.startsWith('.') || existsSync(pack)) {
+    const dir = resolve(pack);
+    if (!existsSync(dir)) {
+      throw new Error(`Local pack directory not found: ${dir}`);
+    }
+    return { directory: dir, source: 'local' };
+  }
+
+  // 2. Built-in packs — search configured directories
+  if (options.builtinDirs) {
+    for (const builtinDir of options.builtinDirs) {
+      const packDir = join(builtinDir, pack);
+      if (existsSync(packDir) && existsSync(join(packDir, 'soleri-pack.json'))) {
+        return { directory: packDir, source: 'built-in' };
+      }
+    }
+  }
+
+  // 3. npm registry
+  if (options.npm !== false) {
+    return resolveFromNpm(pack, options);
+  }
+
+  throw new Error(
+    `Pack "${pack}" not found. Checked: local path, built-in directories${options.npm !== false ? ', npm registry' : ''}.`,
+  );
+}
+
+/**
+ * Resolve a pack from the npm registry.
+ * Downloads via `npm pack` and extracts to a temp directory.
+ */
+function resolveFromNpm(pack: string, options: ResolveOptions): ResolvedPack {
+  // Normalize npm package name
+  const npmName = pack.startsWith('@')
+    ? pack.replace(/@[^/]*$/, '') // Strip version from scoped: @scope/name@1.0 → @scope/name
+    : pack.includes('/')
+      ? pack
+      : `@soleri/pack-${pack.replace(/@.*$/, '')}`;
+
+  // Extract version
+  const version =
+    options.version ??
+    (pack.includes('@') && !pack.startsWith('@')
+      ? pack.split('@').pop()
+      : pack.startsWith('@') && pack.split('@').length === 3
+        ? pack.split('@').pop()
+        : undefined);
+
+  const spec = version ? `${npmName}@${version}` : npmName;
+  const tmpDir = join(tmpdir(), `soleri-pack-${Date.now()}`);
+  mkdirSync(tmpDir, { recursive: true });
+
+  try {
+    execFileSync('npm', ['pack', spec, '--pack-destination', tmpDir], {
+      stdio: 'pipe',
+      timeout: options.npmTimeout ?? 30_000,
+    });
+
+    // Find the tarball
+    const files = readdirSync(tmpDir).filter((f) => f.endsWith('.tgz'));
+    if (files.length === 0) {
+      throw new Error(`No tarball found after npm pack ${spec}`);
+    }
+
+    const extractDir = join(tmpDir, 'extracted');
+    mkdirSync(extractDir, { recursive: true });
+    execFileSync('tar', ['xzf', join(tmpDir, files[0]), '-C', extractDir], {
+      stdio: 'pipe',
+      timeout: 15_000,
+    });
+
+    // npm pack extracts to a 'package/' subdirectory
+    const packageDir = join(extractDir, 'package');
+    if (!existsSync(packageDir)) {
+      throw new Error(`Extracted package directory not found at ${packageDir}`);
+    }
+
+    // Extract resolved version from package.json if present
+    let resolvedVersion: string | undefined;
+    try {
+      const pkgPath = join(packageDir, 'package.json');
+      if (existsSync(pkgPath)) {
+        const { readFileSync } = require('node:fs');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        resolvedVersion = pkg.version;
+      }
+    } catch {
+      // Version extraction is best-effort
+    }
+
+    return {
+      directory: packageDir,
+      source: 'npm',
+      npmPackage: npmName,
+      resolvedVersion,
+    };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to resolve "${spec}" from npm: ${msg}`, { cause: e });
+  }
+}
+
+/**
+ * Check basic semver compatibility: does `version` satisfy `range`?
+ *
+ * Supports: ">=1.0.0", ">=1.0.0 <2.0.0", "^1.2.3", exact version "1.0.0".
+ * Returns true if range is empty/undefined (no constraint).
+ */
+export function checkVersionCompat(version: string, range?: string): boolean {
+  if (!range) return true;
+  const r = range.trim();
+  if (!r) return true;
+
+  const v = parseVer(version);
+  if (!v) return true; // Can't parse → don't block
+
+  // Handle caret: ^1.2.3 means >=1.2.3 <2.0.0
+  if (r.startsWith('^')) {
+    const base = parseVer(r.slice(1));
+    if (!base) return true;
+    return compareVer(v, base) >= 0 && v[0] === base[0];
+  }
+
+  // Handle tilde: ~1.2.3 means >=1.2.3 <1.3.0
+  if (r.startsWith('~')) {
+    const base = parseVer(r.slice(1));
+    if (!base) return true;
+    return compareVer(v, base) >= 0 && v[0] === base[0] && v[1] === base[1];
+  }
+
+  // Handle compound ranges: ">=1.0.0 <2.0.0"
+  const parts = r.split(/\s+/).filter(Boolean);
+  return parts.every((part) => {
+    if (part.startsWith('>=')) {
+      const base = parseVer(part.slice(2));
+      return base ? compareVer(v, base) >= 0 : true;
+    }
+    if (part.startsWith('>')) {
+      const base = parseVer(part.slice(1));
+      return base ? compareVer(v, base) > 0 : true;
+    }
+    if (part.startsWith('<=')) {
+      const base = parseVer(part.slice(2));
+      return base ? compareVer(v, base) <= 0 : true;
+    }
+    if (part.startsWith('<')) {
+      const base = parseVer(part.slice(1));
+      return base ? compareVer(v, base) < 0 : true;
+    }
+    // Exact match
+    const exact = parseVer(part);
+    return exact ? compareVer(v, exact) === 0 : true;
+  });
+}
+
+type SemVer = [number, number, number];
+
+function parseVer(s: string): SemVer | null {
+  const m = s.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? [+m[1], +m[2], +m[3]] : null;
+}
+
+function compareVer(a: SemVer, b: SemVer): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+/**
+ * Check if a newer version is available on npm.
+ * Returns the latest version string, or null if check fails.
+ */
+export function checkNpmVersion(npmPackage: string, timeout = 10_000): string | null {
+  try {
+    const output = execFileSync('npm', ['view', npmPackage, 'version'], {
+      stdio: 'pipe',
+      timeout,
+    });
+    return output.toString().trim() || null;
+  } catch {
+    return null;
+  }
+}