@soleri/core 9.4.0 → 9.6.0

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

@@ -108,13 +108,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 +155,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,11 +20,30 @@ 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
   db.pragma('temp_store = MEMORY');
   db.pragma('mmap_size = 268435456'); // 256MB
+  db.pragma('synchronous = NORMAL');
 }
 
 export class SQLitePersistenceProvider implements PersistenceProvider {
@@ -27,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

@@ -7,7 +7,10 @@
  * The plan is the source of truth; GitHub issues are the projection.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 // ---------------------------------------------------------------------------
 // Types
@@ -88,15 +91,14 @@ export function parseGitHubRemote(remoteUrl: string): GitHubRepo | null {
  * Detect the GitHub remote from a project directory.
  * Returns null if no GitHub remote found or not a git repo.
  */
-export function detectGitHubRemote(projectPath: string): GitHubRepo | null {
+export async function detectGitHubRemote(projectPath: string): Promise<GitHubRepo | null> {
   try {
-    const output = execFileSync('git', ['remote', 'get-url', 'origin'], {
+    const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], {
       cwd: projectPath,
-      encoding: 'utf-8',
       timeout: 5000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
-    return parseGitHubRemote(output);
+      signal: AbortSignal.timeout(5000),
+    });
+    return parseGitHubRemote(stdout.trim());
   } catch {
     return null;
   }
@@ -105,12 +107,11 @@ export function detectGitHubRemote(projectPath: string): GitHubRepo | null {
 /**
  * Check if the `gh` CLI is authenticated.
  */
-export function isGhAuthenticated(): boolean {
+export async function isGhAuthenticated(): Promise<boolean> {
   try {
-    execFileSync('gh', ['auth', 'status'], {
-      encoding: 'utf-8',
+    await execFileAsync('gh', ['auth', 'status'], {
       timeout: 5000,
-      stdio: ['pipe', 'pipe', 'pipe'],
+      signal: AbortSignal.timeout(5000),
     });
     return true;
   } catch {
@@ -125,9 +126,9 @@ export function isGhAuthenticated(): boolean {
 /**
  * List milestones for a GitHub repo.
  */
-export function listMilestones(repo: GitHubRepo): GitHubMilestone[] {
+export async function listMilestones(repo: GitHubRepo): Promise<GitHubMilestone[]> {
   try {
-    const output = execFileSync(
+    const { stdout } = await execFileAsync(
       'gh',
       [
         'api',
@@ -136,12 +137,12 @@ export function listMilestones(repo: GitHubRepo): GitHubMilestone[] {
         '.[] | {number, title, state}',
       ],
       {
-        encoding: 'utf-8',
         timeout: 10000,
-        stdio: ['pipe', 'pipe', 'pipe'],
+        signal: AbortSignal.timeout(10000),
       },
-    ).trim();
+    );
 
+    const output = stdout.trim();
     if (!output) return [];
 
     // gh --jq outputs one JSON object per line
@@ -157,9 +158,12 @@ export function listMilestones(repo: GitHubRepo): GitHubMilestone[] {
 /**
  * List open issues for a GitHub repo.
  */
-export function listOpenIssues(repo: GitHubRepo, limit: number = 100): GitHubIssue[] {
+export async function listOpenIssues(
+  repo: GitHubRepo,
+  limit: number = 100,
+): Promise<GitHubIssue[]> {
   try {
-    const output = execFileSync(
+    const { stdout } = await execFileAsync(
       'gh',
       [
         'issue',
@@ -174,12 +178,12 @@ export function listOpenIssues(repo: GitHubRepo, limit: number = 100): GitHubIss
         'number,title,state,body',
       ],
       {
-        encoding: 'utf-8',
         timeout: 10000,
-        stdio: ['pipe', 'pipe', 'pipe'],
+        signal: AbortSignal.timeout(10000),
       },
-    ).trim();
+    );
 
+    const output = stdout.trim();
     if (!output) return [];
     return JSON.parse(output) as GitHubIssue[];
   } catch {
@@ -190,18 +194,18 @@ export function listOpenIssues(repo: GitHubRepo, limit: number = 100): GitHubIss
 /**
  * List labels for a GitHub repo.
  */
-export function listLabels(repo: GitHubRepo): GitHubLabel[] {
+export async function listLabels(repo: GitHubRepo): Promise<GitHubLabel[]> {
   try {
-    const output = execFileSync(
+    const { stdout } = await execFileAsync(
       'gh',
       ['label', 'list', '--repo', `${repo.owner}/${repo.repo}`, '--json', 'name,color'],
       {
-        encoding: 'utf-8',
         timeout: 10000,
-        stdio: ['pipe', 'pipe', 'pipe'],
+        signal: AbortSignal.timeout(10000),
       },
-    ).trim();
+    );
 
+    const output = stdout.trim();
     if (!output) return [];
     return JSON.parse(output) as GitHubLabel[];
   } catch {
@@ -217,16 +221,18 @@ export function listLabels(repo: GitHubRepo): GitHubLabel[] {
  * Detect full GitHub context for a project.
  * Returns null if not a GitHub project or gh CLI not available.
  */
-export function detectGitHubContext(projectPath: string): GitHubContext | null {
-  const repo = detectGitHubRemote(projectPath);
+export async function detectGitHubContext(projectPath: string): Promise<GitHubContext | null> {
+  const repo = await detectGitHubRemote(projectPath);
   if (!repo) return null;
 
-  const authenticated = isGhAuthenticated();
+  const authenticated = await isGhAuthenticated();
   if (!authenticated) return null;
 
-  const milestones = listMilestones(repo);
-  const existingIssues = listOpenIssues(repo);
-  const labels = listLabels(repo);
+  const [milestones, existingIssues, labels] = await Promise.all([
+    listMilestones(repo),
+    listOpenIssues(repo),
+    listLabels(repo),
+  ]);
 
   return { repo, authenticated, milestones, existingIssues, labels };
 }
@@ -370,7 +376,7 @@ export function formatIssueBody(
  * Create a GitHub issue using the `gh` CLI.
  * Returns the issue number, or null on failure.
  */
-export function createGitHubIssue(
+export async function createGitHubIssue(
   repo: GitHubRepo,
   title: string,
   body: string,
@@ -378,7 +384,7 @@ export function createGitHubIssue(
     milestone?: number;
     labels?: string[];
   },
-): number | null {
+): Promise<number | null> {
   try {
     const args = [
       'issue',
@@ -399,14 +405,13 @@ export function createGitHubIssue(
       args.push('--label', options.labels.join(','));
     }
 
-    const output = execFileSync('gh', args, {
-      encoding: 'utf-8',
+    const { stdout } = await execFileAsync('gh', args, {
       timeout: 15000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+      signal: AbortSignal.timeout(15000),
+    });
 
     // gh issue create returns the issue URL: https://github.com/owner/repo/issues/123
-    const match = output.match(/\/issues\/(\d+)/);
+    const match = stdout.trim().match(/\/issues\/(\d+)/);
     return match ? parseInt(match[1], 10) : null;
   } catch {
     return null;
@@ -416,13 +421,13 @@ export function createGitHubIssue(
 /**
  * Update an existing GitHub issue body (for linking plans to existing issues).
  */
-export function updateGitHubIssueBody(
+export async function updateGitHubIssueBody(
   repo: GitHubRepo,
   issueNumber: number,
   body: string,
-): boolean {
+): Promise<boolean> {
   try {
-    execFileSync(
+    await execFileAsync(
       'gh',
       [
         'issue',
@@ -434,9 +439,8 @@ export function updateGitHubIssueBody(
         body,
       ],
       {
-        encoding: 'utf-8',
         timeout: 15000,
-        stdio: ['pipe', 'pipe', 'pipe'],
+        signal: AbortSignal.timeout(15000),
       },
     );
     return true;

package/src/planning/plan-lifecycle.ts

@@ -380,7 +380,20 @@ export function createPlanObject(params: {
     scope: params.scope,
     status: params.initialStatus ?? 'draft',
     decisions: params.decisions ?? [],
-    tasks: (params.tasks ?? []).map((t, i) => (Object.assign({id:`task-${i+1}`,title:t.title,description:t.description,status:`pending` as TaskStatus}, t.phase!==undefined&&{phase:t.phase}, t.milestone!==undefined&&{milestone:t.milestone}, t.parentTaskId!==undefined&&{parentTaskId:t.parentTaskId}, {updatedAt:now}))),
+    tasks: (params.tasks ?? []).map((t, i) =>
+      Object.assign(
+        {
+          id: `task-${i + 1}`,
+          title: t.title,
+          description: t.description,
+          status: `pending` as TaskStatus,
+        },
+        t.phase !== undefined && { phase: t.phase },
+        t.milestone !== undefined && { milestone: t.milestone },
+        t.parentTaskId !== undefined && { parentTaskId: t.parentTaskId },
+        { updatedAt: now },
+      ),
+    ),
     ...(params.approach !== undefined && { approach: params.approach }),
     ...(params.context !== undefined && { context: params.context }),
     ...(params.success_criteria !== undefined && { success_criteria: params.success_criteria }),

package/src/queue/pipeline-runner.ts

@@ -58,6 +58,10 @@ export class PipelineRunner {
     if (this.running) return;
     this.running = true;
     this.timer = setInterval(() => this.tick(), this.pollIntervalMs);
+    // Don't prevent process exit for background polling
+    if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+      (this.timer as NodeJS.Timeout).unref();
+    }
   }
 
   /**

package/src/runtime/admin-setup-ops.test.ts

@@ -5,17 +5,21 @@ import type { OpDefinition } from '../facades/types.js';
 
 // ─── Mock Node.js fs/os modules ────────────────────────────────────────
 
+/** Normalize path separators so Windows backslash paths match forward-slash keys */
+const norm = (p: string): string => p.replace(/\\/g, '/');
+
 const mockFs: Record<string, string> = {};
 const mockDirs = new Set<string>();
 
 vi.mock('node:fs', () => ({
-  existsSync: vi.fn((p: string) => p in mockFs || mockDirs.has(p)),
+  existsSync: vi.fn((p: string) => norm(p) in mockFs || mockDirs.has(norm(p))),
   readFileSync: vi.fn((p: string) => {
-    if (p in mockFs) return mockFs[p];
+    const key = norm(p);
+    if (key in mockFs) return mockFs[key];
     throw new Error(`ENOENT: ${p}`);
   }),
   writeFileSync: vi.fn((p: string, content: string) => {
-    mockFs[p] = content;
+    mockFs[norm(p)] = content;
   }),
   mkdirSync: vi.fn((_p: string) => undefined),
   copyFileSync: vi.fn(),
@@ -30,7 +34,8 @@ vi.mock('node:os', () => ({
 
 vi.mock('node:path', async () => {
   const actual = await vi.importActual<typeof import('node:path')>('node:path');
-  return actual;
+  // Always use posix path semantics so mock filesystem keys (forward slashes) work on all platforms
+  return { ...actual.posix, default: actual.posix };
 });
 
 vi.mock('./claude-md-helpers.js', () => ({