@soleri/core 9.5.0 → 9.7.0

package/src/packs/lockfile.ts

@@ -41,15 +41,25 @@ export interface LockEntry {
   soleriRange?: string;
   /** Pack tier: default (ships with engine), community (free), premium (unlocked today) */
   tier?: PackTier;
+  /** Current pack lifecycle state */
+  state?: string;
+  /** Most recent lifecycle transition */
+  lastTransition?: { from: string; to: string; timestamp: string; reason?: string };
+  /** ISO timestamp when the pack was disabled */
+  disabledAt?: string;
+  /** Error details if the pack is in an error state */
+  errorMessage?: string;
 }
 
 export type PackType = 'hooks' | 'skills' | 'knowledge' | 'domain' | 'bundle';
 export type PackSource = 'built-in' | 'local' | 'npm';
 export type PackTier = 'default' | 'community' | 'premium';
 
+export const LOCKFILE_VERSION = 2;
+
 export interface LockfileData {
   /** Lockfile format version */
-  version: 1;
+  version: number;
   /** Map of packId → lock entry */
   packs: Record<string, LockEntry>;
 }
@@ -141,18 +151,73 @@ export class PackLockfile {
     return 'sha256-' + createHash('sha256').update(content).digest('hex');
   }
 
+  /**
+   * Update lifecycle fields for a pack entry and save.
+   */
+  updateLifecycle(
+    packId: string,
+    state: string,
+    transition?: { from: string; to: string; reason?: string },
+  ): void {
+    const entry = this.data.packs[packId];
+    if (!entry) return;
+
+    entry.state = state;
+
+    if (transition) {
+      entry.lastTransition = {
+        from: transition.from,
+        to: transition.to,
+        timestamp: new Date().toISOString(),
+        reason: transition.reason,
+      };
+    }
+
+    if (state === 'disabled') {
+      entry.disabledAt = new Date().toISOString();
+    } else {
+      delete entry.disabledAt;
+    }
+
+    if (state === 'error') {
+      // errorMessage is set externally if needed; keep existing value
+    } else {
+      delete entry.errorMessage;
+    }
+
+    this.dirty = true;
+    this.save();
+  }
+
   private load(): LockfileData {
     if (!existsSync(this.filePath)) {
-      return { version: 1, packs: {} };
+      return { version: LOCKFILE_VERSION, packs: {} };
     }
     try {
       const raw = JSON.parse(readFileSync(this.filePath, 'utf-8'));
-      if (raw.version === 1 && typeof raw.packs === 'object') {
+      if (typeof raw.packs !== 'object') {
+        return { version: LOCKFILE_VERSION, packs: {} };
+      }
+
+      // Migrate v1 → v2: add lifecycle fields
+      if (raw.version === 1) {
+        for (const entry of Object.values(raw.packs) as LockEntry[]) {
+          if (!entry.state) {
+            entry.state = 'ready';
+          }
+        }
+        raw.version = LOCKFILE_VERSION;
+        // Mark dirty so the migrated data gets persisted on next save
+        this.dirty = true;
+      }
+
+      if (raw.version === LOCKFILE_VERSION) {
         return raw as LockfileData;
       }
-      return { version: 1, packs: {} };
+
+      return { version: LOCKFILE_VERSION, packs: {} };
     } catch {
-      return { version: 1, packs: {} };
+      return { version: LOCKFILE_VERSION, packs: {} };
     }
   }
 }

package/src/packs/pack-installer.ts

@@ -22,6 +22,7 @@ import type { Vault } from '../vault/vault.js';
 import type { PluginRegistry } from '../plugins/plugin-registry.js';
 import type { PluginContext } from '../plugins/types.js';
 import type { PackRuntime } from '../domain-packs/pack-runtime.js';
+import { PackLifecycleManager } from './pack-lifecycle.js';
 
 const MANIFEST_FILENAME = 'soleri-pack.json';
 
@@ -31,6 +32,7 @@ const MANIFEST_FILENAME = 'soleri-pack.json';
 
 export class PackInstaller {
   private packs = new Map<string, InstalledPack>();
+  readonly lifecycle = new PackLifecycleManager();
 
   constructor(
     private vault: Vault,
@@ -206,17 +208,21 @@ export class PackInstaller {
       const hooksDir = join(packDir, manifest.hooks?.dir ?? 'hooks');
       const hooks = existsSync(hooksDir) ? listMarkdownFiles(hooksDir) : [];
 
-      // Track installed pack
+      // Track installed pack with lifecycle
+      this.lifecycle.initState(manifest.id, 'installed');
+      this.lifecycle.transition(manifest.id, 'ready', 'Initial install');
+
       const installed: InstalledPack = {
         id: manifest.id,
         manifest,
         directory: packDir,
-        status: 'installed',
+        status: 'ready',
         vaultEntries,
         skills,
         hooks,
         facadesRegistered,
         installedAt: Date.now(),
+        transitions: this.lifecycle.getTransitions(manifest.id),
       };
       this.packs.set(manifest.id, installed);
 
@@ -231,17 +237,23 @@ export class PackInstaller {
     } catch (e) {
       const error = e instanceof Error ? e.message : String(e);
 
+      // Transition to error state
+      this.lifecycle.initState(manifest.id, 'installed');
+      this.lifecycle.transition(manifest.id, 'error', error);
+
       this.packs.set(manifest.id, {
         id: manifest.id,
         manifest,
         directory: packDir,
         status: 'error',
         error,
+        errorMessage: error,
         vaultEntries: 0,
         skills: [],
         hooks: [],
         facadesRegistered: false,
         installedAt: Date.now(),
+        transitions: this.lifecycle.getTransitions(manifest.id),
       });
 
       return {
@@ -269,11 +281,75 @@ export class PackInstaller {
       this.pluginRegistry.deactivate(packId);
     }
 
+    // Transition to uninstalled
+    try {
+      this.lifecycle.transition(packId, 'uninstalled', 'User uninstall');
+    } catch {
+      // May not be tracked in lifecycle — continue anyway
+    }
+    this.lifecycle.remove(packId);
+
     pack.status = 'uninstalled';
     this.packs.delete(packId);
     return true;
   }
 
+  /**
+   * Disable a pack — deactivates capabilities but preserves vault entries.
+   */
+  disable(packId: string): boolean {
+    const pack = this.packs.get(packId);
+    if (!pack) return false;
+
+    this.lifecycle.transition(packId, 'disabled', 'User disabled');
+
+    // Deactivate facades
+    if (pack.facadesRegistered) {
+      this.pluginRegistry.deactivate(packId);
+    }
+
+    pack.status = 'disabled';
+    pack.disabledAt = Date.now();
+    pack.transitions = this.lifecycle.getTransitions(packId);
+    return true;
+  }
+
+  /**
+   * Enable a previously disabled pack — reactivates capabilities.
+   */
+  async enable(packId: string, runtimeCtx?: unknown, packRuntime?: PackRuntime): Promise<boolean> {
+    const pack = this.packs.get(packId);
+    if (!pack) return false;
+
+    this.lifecycle.transition(packId, 'ready', 'User enabled');
+
+    // Reactivate facades
+    if (pack.manifest.facades.length > 0 && this.pluginRegistry.get(packId)) {
+      const ctx: PluginContext = {
+        packRuntime:
+          packRuntime ??
+          ({
+            vault: {},
+            getProject: () => undefined,
+            listProjects: () => [],
+            createCheck: () => '',
+            validateCheck: () => null,
+            validateAndConsume: () => null,
+          } as unknown as PackRuntime),
+        runtime: runtimeCtx ?? {},
+        manifest: this.pluginRegistry.get(packId)!.manifest,
+        directory: pack.directory,
+      };
+      await this.pluginRegistry.activate(packId, ctx);
+      pack.facadesRegistered = true;
+    }
+
+    pack.status = 'ready';
+    pack.disabledAt = undefined;
+    pack.transitions = this.lifecycle.getTransitions(packId);
+    return true;
+  }
+
   /**
    * Get an installed pack by ID.
    */

package/src/packs/pack-lifecycle.ts

@@ -0,0 +1,115 @@
+/**
+ * Pack Lifecycle Manager — Central state machine for pack lifecycle management.
+ *
+ * Manages in-memory pack states, validates transitions against VALID_TRANSITIONS,
+ * records transition history, and notifies listeners on state changes.
+ */
+
+import type { PackState, PackTransition } from './types.js';
+import { VALID_TRANSITIONS } from './types.js';
+
+type TransitionListener = (packId: string, from: PackState, to: PackState, reason?: string) => void;
+
+interface PackEntry {
+  state: PackState;
+  transitions: PackTransition[];
+}
+
+export class PackLifecycleManager {
+  private packs: Map<string, PackEntry> = new Map();
+  private listeners: Array<TransitionListener> = [];
+
+  /**
+   * Transition a pack to a new state. Validates against VALID_TRANSITIONS.
+   * Throws a descriptive error if the transition is not allowed.
+   */
+  transition(packId: string, to: PackState, reason?: string): void {
+    const entry = this.packs.get(packId);
+    if (!entry) {
+      throw new Error(`Pack '${packId}' is not being tracked`);
+    }
+
+    const currentState = entry.state;
+    const validTargets = VALID_TRANSITIONS[currentState];
+
+    if (!validTargets.includes(to)) {
+      throw new Error(
+        `Invalid pack lifecycle transition for '${packId}': '${currentState}' \u2192 '${to}'. Valid targets from '${currentState}': ${validTargets.join(', ')}`,
+      );
+    }
+
+    const transition: PackTransition = {
+      from: currentState,
+      to,
+      timestamp: Date.now(),
+      reason,
+    };
+
+    entry.state = to;
+    entry.transitions.push(transition);
+
+    for (const listener of this.listeners) {
+      listener(packId, currentState, to, reason);
+    }
+  }
+
+  /**
+   * Set initial state without transition validation (for loading from lockfile).
+   */
+  initState(packId: string, state: PackState): void {
+    this.packs.set(packId, { state, transitions: [] });
+  }
+
+  /**
+   * Returns current state of a pack, or undefined if not tracked.
+   */
+  getState(packId: string): PackState | undefined {
+    return this.packs.get(packId)?.state;
+  }
+
+  /**
+   * Returns the full transition history for a pack.
+   */
+  getTransitions(packId: string): PackTransition[] {
+    return this.packs.get(packId)?.transitions ?? [];
+  }
+
+  /**
+   * Register a listener for state transitions. Returns an unsubscribe function.
+   */
+  onTransition(callback: TransitionListener): () => void {
+    this.listeners.push(callback);
+    return () => {
+      const idx = this.listeners.indexOf(callback);
+      if (idx !== -1) {
+        this.listeners.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Remove a pack from tracking entirely.
+   */
+  remove(packId: string): void {
+    this.packs.delete(packId);
+  }
+
+  /**
+   * List all tracked packs with their current state.
+   */
+  listAll(): Array<{ packId: string; state: PackState }> {
+    const result: Array<{ packId: string; state: PackState }> = [];
+    for (const [packId, entry] of this.packs) {
+      result.push({ packId, state: entry.state });
+    }
+    return result;
+  }
+
+  /**
+   * Clear all tracked state and listeners.
+   */
+  reset(): void {
+    this.packs.clear();
+    this.listeners.length = 0;
+  }
+}

package/src/packs/pack-lockfile.test.ts

@@ -81,7 +81,7 @@ describe('PackLockfile', () => {
     expect(existsSync(lockPath)).toBe(true);
 
     const data = JSON.parse(readFileSync(lockPath, 'utf-8'));
-    expect(data.version).toBe(1);
+    expect(data.version).toBe(2);
     expect(data.packs['test-pack'].version).toBe('1.0.0');
   });
 

package/src/packs/pack-system.test.ts

@@ -417,7 +417,7 @@ describe('PackInstaller', () => {
       const pack = installer.get('specific');
       expect(pack).toBeDefined();
       expect(pack?.manifest.version).toBe('3.0.0');
-      expect(pack?.status).toBe('installed');
+      expect(pack?.status).toBe('ready');
     });
   });
 });

package/src/packs/types.ts

@@ -19,6 +19,38 @@
 
 import { z } from 'zod';
 
+// =============================================================================
+// SKILL TRUST & SOURCE TRACKING
+// =============================================================================
+
+/** How much a skill can do — escalates from pure docs to executable code */
+export type TrustLevel = 'markdown_only' | 'assets' | 'scripts';
+
+/** Where a skill came from */
+export type SourceType = 'builtin' | 'pack' | 'local' | 'github' | 'npm';
+
+/** A single file in a skill directory, classified by kind */
+export interface SkillInventoryItem {
+  /** Relative path within the skill directory */
+  path: string;
+  /** What kind of file this is */
+  kind: 'skill' | 'reference' | 'asset' | 'script';
+}
+
+/** Extended metadata for a discovered skill */
+export interface SkillMetadata {
+  /** Computed trust level based on directory contents */
+  trust: TrustLevel;
+  /** Where this skill was sourced from */
+  source: { type: SourceType; uri: string };
+  /** Engine version compatibility check result */
+  compatibility: 'compatible' | 'unknown' | 'invalid';
+  /** Engine version declared by the skill (if any) */
+  engineVersion?: string;
+  /** Classified inventory of all files in the skill directory */
+  inventory: SkillInventoryItem[];
+}
+
 // =============================================================================
 // MANIFEST SCHEMA
 // =============================================================================
@@ -108,13 +140,43 @@ export type PackManifest = z.infer<typeof packManifestSchema>;
 // INSTALL TYPES
 // =============================================================================
 
-export type PackStatus = 'installed' | 'error' | 'uninstalled';
+// ─── Lifecycle States ─────────────────────────────────────────────────
+
+/** Full lifecycle state for a pack */
+export type PackState =
+  | 'installed' // Just installed, not yet activated
+  | 'ready' // Active — capabilities, skills, hooks all live
+  | 'disabled' // Temporarily deactivated — vault entries kept, capabilities off
+  | 'error' // Failed to activate — error message in errorMessage field
+  | 'upgrade_pending' // New version available, old version still active
+  | 'uninstalled'; // Removed — vault entries remain (permanent knowledge)
+
+/** @deprecated Use PackState instead */
+export type PackStatus = PackState;
+
+/** Valid state transitions — key is "from" state, values are allowed "to" states */
+export const VALID_TRANSITIONS: Record<PackState, PackState[]> = {
+  installed: ['ready', 'error', 'uninstalled'],
+  ready: ['ready', 'disabled', 'error', 'upgrade_pending', 'uninstalled'],
+  disabled: ['ready', 'uninstalled'],
+  error: ['ready', 'uninstalled'],
+  upgrade_pending: ['ready', 'error', 'uninstalled'],
+  uninstalled: ['installed'],
+};
+
+/** A recorded state transition */
+export interface PackTransition {
+  from: PackState;
+  to: PackState;
+  timestamp: number;
+  reason?: string;
+}
 
 export interface InstalledPack {
   id: string;
   manifest: PackManifest;
   directory: string;
-  status: PackStatus;
+  status: PackState;
   error?: string;
   /** Number of vault entries seeded */
   vaultEntries: number;
@@ -125,6 +187,14 @@ export interface InstalledPack {
   /** Whether facades were registered via plugin system */
   facadesRegistered: boolean;
   installedAt: number;
+  /** Lifecycle transition history (most recent last) */
+  transitions?: PackTransition[];
+  /** When the pack was disabled (if in disabled state) */
+  disabledAt?: number;
+  /** Error message (if in error state) */
+  errorMessage?: string;
+  /** Version available for upgrade (if in upgrade_pending state) */
+  upgradeVersion?: string;
 }
 
 export interface InstallResult {

package/src/persistence/sqlite-provider.ts

@@ -3,9 +3,14 @@
  *
  * Supports both positional (array) and named (object) parameters.
  * Exposes getDatabase() for backward-compat consumers that need the raw db.
+ *
+ * better-sqlite3 is loaded lazily at construction time (not at module import)
+ * so that code paths that never instantiate a provider don't require the
+ * native module to be installed.
  */
 
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
+import { createRequire } from 'node:module';
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type {
@@ -15,6 +20,24 @@ import type {
   FtsSearchOptions,
 } from './types.js';
 
+type DatabaseConstructor = typeof Database;
+let _DatabaseCtor: DatabaseConstructor | undefined;
+
+function loadDriver(): DatabaseConstructor {
+  if (!_DatabaseCtor) {
+    const req = createRequire(import.meta.url);
+    try {
+      _DatabaseCtor = req('better-sqlite3') as DatabaseConstructor;
+    } catch {
+      throw new Error(
+        'better-sqlite3 is required for persistence but is not installed.\n' +
+          'Run: npm install better-sqlite3',
+      );
+    }
+  }
+  return _DatabaseCtor;
+}
+
 /** Apply performance-tuning PRAGMAs for file-backed SQLite databases. */
 export function applyPerformancePragmas(db: Database.Database): void {
   db.pragma('cache_size = -64000'); // 64MB
@@ -28,8 +51,9 @@ export class SQLitePersistenceProvider implements PersistenceProvider {
   private db: Database.Database;
 
   constructor(path: string = ':memory:') {
+    const Driver = loadDriver();
     if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
-    this.db = new Database(path);
+    this.db = new Driver(path);
     if (path !== ':memory:') applyPerformancePragmas(this.db);
   }
 

package/src/planning/github-projection.ts

@@ -333,6 +333,7 @@ export function formatIssueBody(
   plan: PlanMetadataForIssue,
   taskTitle: string,
   taskDescription: string,
+  options?: { goalContext?: string },
 ): string {
   const lines: string[] = [];
 
@@ -341,6 +342,11 @@ export function formatIssueBody(
   lines.push(`**Objective:** ${plan.objective}`);
   lines.push('');
 
+  if (options?.goalContext) {
+    lines.push(options.goalContext);
+    lines.push('');
+  }
+
   if (plan.decisions.length > 0) {
     lines.push('## Decisions');
     for (const d of plan.decisions) {