@soleri/core 7.0.0 → 8.1.0

package/src/planning/evidence-collector.ts

@@ -0,0 +1,247 @@
+/**
+ * Evidence Collector — cross-references plan tasks against git reality.
+ *
+ * Runs `git diff` to find what actually changed, then matches file changes
+ * against planned tasks to produce an evidence-based drift report.
+ */
+
+import { execFileSync } from 'node:child_process';
+import type { Plan, PlanTask } from './planner.js';
+
+export interface FileChange {
+  path: string;
+  status: 'added' | 'modified' | 'deleted' | 'renamed';
+}
+
+export interface GitTaskEvidence {
+  taskId: string;
+  taskTitle: string;
+  plannedStatus: string;
+  matchedFiles: FileChange[];
+  verdict: 'DONE' | 'PARTIAL' | 'MISSING' | 'SKIPPED';
+}
+
+export interface UnplannedChange {
+  file: FileChange;
+  possibleReason: string;
+}
+
+export interface EvidenceReport {
+  planId: string;
+  planObjective: string;
+  accuracy: number;
+  evidenceSources: string[];
+  taskEvidence: GitTaskEvidence[];
+  unplannedChanges: UnplannedChange[];
+  missingWork: GitTaskEvidence[];
+  summary: string;
+}
+
+/**
+ * Collect git diff evidence for a plan.
+ *
+ * @param plan - The plan to verify
+ * @param projectPath - Project root (must be a git repo)
+ * @param baseBranch - Compare against this branch (default: 'main')
+ */
+export function collectGitEvidence(
+  plan: Plan,
+  projectPath: string,
+  baseBranch: string = 'main',
+): EvidenceReport {
+  const fileChanges = getGitDiff(projectPath, baseBranch);
+  const taskEvidence: GitTaskEvidence[] = [];
+  const matchedFiles = new Set<string>();
+
+  for (const task of plan.tasks) {
+    const matches = findMatchingFiles(task, fileChanges);
+    for (const m of matches) matchedFiles.add(m.path);
+
+    const verdict = determineVerdict(task, matches);
+    taskEvidence.push({
+      taskId: task.id,
+      taskTitle: task.title,
+      plannedStatus: task.status,
+      matchedFiles: matches,
+      verdict,
+    });
+  }
+
+  const unplannedChanges: UnplannedChange[] = fileChanges
+    .filter((f) => !matchedFiles.has(f.path))
+    .map((f) => ({
+      file: f,
+      possibleReason: inferReason(f),
+    }));
+
+  const missingWork = taskEvidence.filter((te) => te.verdict === 'MISSING');
+
+  const totalTasks = taskEvidence.length;
+  const doneTasks = taskEvidence.filter((te) => te.verdict === 'DONE').length;
+  const partialTasks = taskEvidence.filter((te) => te.verdict === 'PARTIAL').length;
+  const skippedTasks = taskEvidence.filter((te) => te.verdict === 'SKIPPED').length;
+  const accuracy =
+    totalTasks > 0
+      ? Math.round(((doneTasks + partialTasks * 0.5 + skippedTasks * 0.25) / totalTasks) * 100)
+      : 100;
+
+  const summary = buildSummary(
+    totalTasks,
+    doneTasks,
+    partialTasks,
+    missingWork.length,
+    unplannedChanges.length,
+  );
+
+  return {
+    planId: plan.id,
+    planObjective: plan.objective,
+    accuracy,
+    evidenceSources: ['git'],
+    taskEvidence,
+    unplannedChanges,
+    missingWork,
+    summary,
+  };
+}
+
+function getGitDiff(projectPath: string, baseBranch: string): FileChange[] {
+  try {
+    const currentBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+
+    const diffTarget = currentBranch === baseBranch ? 'HEAD~10' : baseBranch;
+
+    let output: string;
+    try {
+      output = execFileSync('git', ['diff', '--name-status', `${diffTarget}...HEAD`], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+      });
+    } catch {
+      output = execFileSync('git', ['diff', '--name-status', 'HEAD~5'], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+      });
+    }
+
+    return output
+      .trim()
+      .split('\n')
+      .filter((line) => line.length > 0)
+      .map(parseGitDiffLine)
+      .filter((f): f is FileChange => f !== null);
+  } catch {
+    return [];
+  }
+}
+
+function parseGitDiffLine(line: string): FileChange | null {
+  const match = line.match(/^([AMDRC])\d*\t(.+?)(?:\t(.+))?$/);
+  if (!match) return null;
+
+  const statusChar = match[1];
+  const path = match[3] ?? match[2];
+
+  const statusMap: Record<string, FileChange['status']> = {
+    A: 'added',
+    M: 'modified',
+    D: 'deleted',
+    R: 'renamed',
+    C: 'added',
+  };
+
+  return { path, status: statusMap[statusChar] ?? 'modified' };
+}
+
+function findMatchingFiles(task: PlanTask, files: FileChange[]): FileChange[] {
+  const keywords = extractKeywords(task.title + ' ' + task.description);
+  if (keywords.length === 0) return [];
+
+  return files.filter((f) => {
+    const pathLower = f.path.toLowerCase();
+    return keywords.some((kw) => pathLower.includes(kw));
+  });
+}
+
+function extractKeywords(text: string): string[] {
+  const stopWords = new Set([
+    'the',
+    'and',
+    'for',
+    'with',
+    'that',
+    'this',
+    'from',
+    'into',
+    'add',
+    'create',
+    'implement',
+    'update',
+    'fix',
+    'remove',
+    'delete',
+    'new',
+    'use',
+    'should',
+    'must',
+    'will',
+    'can',
+    'all',
+    'each',
+    'when',
+    'not',
+    'are',
+    'has',
+    'have',
+    'been',
+    'was',
+  ]);
+
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s\-_/.]/g, ' ')
+    .split(/[\s\-_/]+/)
+    .filter((w) => w.length >= 3 && !stopWords.has(w));
+
+  return [...new Set(words)];
+}
+
+function determineVerdict(task: PlanTask, matches: FileChange[]): GitTaskEvidence['verdict'] {
+  if (task.status === 'skipped') return 'SKIPPED';
+  if (matches.length === 0) return 'MISSING';
+  if (task.status === 'completed') return 'DONE';
+  if (matches.length > 0) return 'PARTIAL';
+  return 'MISSING';
+}
+
+function inferReason(file: FileChange): string {
+  const path = file.path.toLowerCase();
+  if (path.includes('index.') || path.includes('barrel')) return 'likely re-export update';
+  if (path.includes('config') || path.includes('.env')) return 'configuration change';
+  if (path.includes('test') || path.includes('spec')) return 'test file';
+  if (path.includes('package.json') || path.includes('lock')) return 'dependency update';
+  if (path.includes('readme') || path.includes('.md')) return 'documentation';
+  if (path.includes('types') || path.includes('.d.ts')) return 'type definition update';
+  return 'unplanned scope';
+}
+
+function buildSummary(
+  total: number,
+  done: number,
+  partial: number,
+  missing: number,
+  unplanned: number,
+): string {
+  const parts: string[] = [];
+  parts.push(`${done}/${total} tasks verified by git evidence`);
+  if (partial > 0) parts.push(`${partial} partially done`);
+  if (missing > 0) parts.push(`${missing} with no file evidence`);
+  if (unplanned > 0) parts.push(`${unplanned} unplanned file changes`);
+  return parts.join(', ');
+}

package/src/planning/planner.ts

@@ -385,6 +385,17 @@ export class Planner {
     return [...this.store.plans];
   }
 
+  /**
+   * Permanently remove a plan by ID. Returns true if found and removed.
+   */
+  remove(planId: string): boolean {
+    const idx = this.store.plans.findIndex((p) => p.id === planId);
+    if (idx < 0) return false;
+    this.store.plans.splice(idx, 1);
+    this.save();
+    return true;
+  }
+
   /**
    * Transition a plan to a new status using the typed FSM.
    * Validates that the transition is allowed before applying it.

package/src/plugins/index.ts

@@ -1,5 +1,9 @@
 /**
  * Plugin System — Barrel Exports
+ *
+ * @deprecated Prefer knowledge packs (soleri-pack.json) for new extensions.
+ * The plugin system is maintained for backwards compatibility and is used
+ * internally by the pack installer for facade registration.
  */
 
 export {

package/src/plugins/plugin-registry.ts

@@ -1,6 +1,10 @@
 /**
  * Plugin Registry — tracks loaded plugins and their lifecycle.
  *
+ * @deprecated The plugin system is superseded by knowledge packs (`soleri-pack.json`).
+ * This registry is still used internally by the pack installer to register facades,
+ * but new extensions should use the pack system directly.
+ *
  * Not a singleton — lives on AgentRuntime for testability.
  * Lifecycle: load → register → activate → (deactivate | error)
  */
@@ -161,7 +165,8 @@ export class PluginRegistry {
       throw new Error(`Plugin module "${moduleFile}" must export createFacades(ctx)`);
     } catch (e) {
       throw new Error(
-        `Failed to load plugin module "${moduleFile}": ${e instanceof Error ? e.message : String(e)}`, { cause: e },
+        `Failed to load plugin module "${moduleFile}": ${e instanceof Error ? e.message : String(e)}`,
+        { cause: e },
       );
     }
   }

package/src/plugins/types.ts

@@ -1,9 +1,12 @@
 /**
  * Plugin System — Types & Manifest Schema
  *
- * A plugin is a directory containing a `soleri-plugin.json` manifest
- * and optionally additional intelligence data. Plugins register
- * OpDefinition[] (facades) dynamically without re-scaffolding.
+ * @deprecated Prefer knowledge packs (`soleri-pack.json`) over plugins (`soleri-plugin.json`).
+ * Knowledge packs are a superset of plugins — they support facades, vault entries, skills,
+ * hooks, and capability declarations. Plugins only support facades and intelligence entries.
+ *
+ * This module is maintained for backwards compatibility. New extensions should use
+ * the pack system in `../packs/`. See docs/architecture/extension-tiers.md.
  */
 
 import { z } from 'zod';
@@ -101,8 +104,10 @@ export type PluginFacadeBuilder = (ctx: PluginContext) => FacadeConfig[];
  * Context passed to plugin facade builders during activation.
  */
 export interface PluginContext {
-  /** The agent runtime — full access to vault, brain, planner, etc. */
-  runtime: unknown; // AgentRuntime — kept as unknown to avoid circular deps
+  /** Narrowed runtime — vault, projects, session checks. Preferred over full runtime. */
+  packRuntime: import('../domain-packs/pack-runtime.js').PackRuntime;
+  /** @deprecated Full agent runtime. Use packRuntime instead — only vault, projects, and session checks are guaranteed. */
+  runtime: unknown;
   /** The plugin's own manifest */
   manifest: PluginManifest;
   /** The plugin's directory on disk */

package/src/queue/job-queue.ts

@@ -0,0 +1,281 @@
+/**
+ * Job Queue — SQLite-backed FIFO queue with DAG dependencies and retries.
+ *
+ * Generic infrastructure — not curator-specific. Reusable by agency, intake, etc.
+ *
+ * Features:
+ * - Persistent jobs (survive process restarts)
+ * - DAG dependency resolution (job B waits for job A)
+ * - Pipeline grouping (group related jobs under one ID)
+ * - Configurable retries with max limit
+ * - Status tracking: pending → running → completed | failed
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { PersistenceProvider } from '../persistence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
+
+export interface Job {
+  id: string;
+  type: string;
+  status: JobStatus;
+  entryId: string | null;
+  payload: Record<string, unknown>;
+  dependsOn: string[];
+  pipelineId: string | null;
+  retryCount: number;
+  maxRetries: number;
+  result: unknown | null;
+  error: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+
+export interface JobQueueStats {
+  pending: number;
+  running: number;
+  completed: number;
+  failed: number;
+  total: number;
+}
+
+export interface EnqueueOptions {
+  entryId?: string;
+  payload?: Record<string, unknown>;
+  dependsOn?: string[];
+  pipelineId?: string;
+  maxRetries?: number;
+}
+
+// ─── Class ───────────────────────────────────────────────────────────
+
+export class JobQueue {
+  private provider: PersistenceProvider;
+
+  constructor(provider: PersistenceProvider) {
+    this.provider = provider;
+    this.initializeTable();
+  }
+
+  private initializeTable(): void {
+    this.provider.execSql(`
+      CREATE TABLE IF NOT EXISTS job_queue (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        entry_id TEXT,
+        payload TEXT DEFAULT '{}',
+        depends_on TEXT DEFAULT '[]',
+        pipeline_id TEXT,
+        retry_count INTEGER DEFAULT 0,
+        max_retries INTEGER DEFAULT 3,
+        result TEXT,
+        error TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        started_at TEXT,
+        completed_at TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_job_queue_status ON job_queue(status);
+      CREATE INDEX IF NOT EXISTS idx_job_queue_pipeline ON job_queue(pipeline_id);
+    `);
+  }
+
+  /**
+   * Enqueue a new job. Returns the job ID.
+   */
+  enqueue(type: string, options?: EnqueueOptions): string {
+    const id = randomUUID().slice(0, 12);
+    this.provider.run(
+      `INSERT INTO job_queue (id, type, entry_id, payload, depends_on, pipeline_id, max_retries)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        type,
+        options?.entryId ?? null,
+        JSON.stringify(options?.payload ?? {}),
+        JSON.stringify(options?.dependsOn ?? []),
+        options?.pipelineId ?? null,
+        options?.maxRetries ?? 3,
+      ],
+    );
+    return id;
+  }
+
+  /**
+   * Dequeue the oldest pending job with all dependencies completed.
+   * Marks it as running. Returns null if no ready jobs.
+   */
+  dequeue(): Job | null {
+    const ready = this.dequeueReady(1);
+    return ready.length > 0 ? ready[0] : null;
+  }
+
+  /**
+   * Dequeue up to `limit` pending jobs whose dependencies are all completed.
+   */
+  dequeueReady(limit: number = 10): Job[] {
+    const rows = this.provider.all<JobRow>(
+      "SELECT * FROM job_queue WHERE status = 'pending' ORDER BY created_at ASC LIMIT ?",
+      [limit * 3], // Over-fetch to filter by deps
+    );
+
+    const ready: Job[] = [];
+    for (const row of rows) {
+      if (ready.length >= limit) break;
+      const deps = JSON.parse(row.depends_on) as string[];
+      if (deps.length === 0 || this.allDepsCompleted(deps)) {
+        this.provider.run(
+          "UPDATE job_queue SET status = 'running', started_at = datetime('now') WHERE id = ?",
+          [row.id],
+        );
+        const job = rowToJob(row);
+        job.status = 'running';
+        ready.push(job);
+      }
+    }
+    return ready;
+  }
+
+  /**
+   * Mark a job as completed with an optional result.
+   */
+  complete(jobId: string, result?: unknown): void {
+    this.provider.run(
+      "UPDATE job_queue SET status = 'completed', completed_at = datetime('now'), result = ? WHERE id = ?",
+      [result !== undefined ? JSON.stringify(result) : null, jobId],
+    );
+  }
+
+  /**
+   * Mark a job as failed with an error message.
+   */
+  fail(jobId: string, error: string): void {
+    this.provider.run(
+      "UPDATE job_queue SET status = 'failed', completed_at = datetime('now'), error = ? WHERE id = ?",
+      [error, jobId],
+    );
+  }
+
+  /**
+   * Retry a failed job (resets to pending). Returns false if max retries exceeded.
+   */
+  retry(jobId: string): boolean {
+    const row = this.provider.get<JobRow>('SELECT * FROM job_queue WHERE id = ?', [jobId]);
+    if (!row) return false;
+    if (row.retry_count >= row.max_retries) return false;
+
+    this.provider.run(
+      "UPDATE job_queue SET status = 'pending', retry_count = retry_count + 1, error = NULL, started_at = NULL, completed_at = NULL WHERE id = ?",
+      [jobId],
+    );
+    return true;
+  }
+
+  /**
+   * Get queue statistics.
+   */
+  getStats(): JobQueueStats {
+    const rows = this.provider.all<{ status: string; count: number }>(
+      'SELECT status, COUNT(*) as count FROM job_queue GROUP BY status',
+    );
+    const byStatus: Record<string, number> = {};
+    let total = 0;
+    for (const row of rows) {
+      byStatus[row.status] = row.count;
+      total += row.count;
+    }
+    return {
+      pending: byStatus['pending'] ?? 0,
+      running: byStatus['running'] ?? 0,
+      completed: byStatus['completed'] ?? 0,
+      failed: byStatus['failed'] ?? 0,
+      total,
+    };
+  }
+
+  /**
+   * Get all jobs for a pipeline.
+   */
+  getByPipeline(pipelineId: string): Job[] {
+    const rows = this.provider.all<JobRow>(
+      'SELECT * FROM job_queue WHERE pipeline_id = ? ORDER BY created_at ASC',
+      [pipelineId],
+    );
+    return rows.map(rowToJob);
+  }
+
+  /**
+   * Get a single job by ID.
+   */
+  get(jobId: string): Job | null {
+    const row = this.provider.get<JobRow>('SELECT * FROM job_queue WHERE id = ?', [jobId]);
+    return row ? rowToJob(row) : null;
+  }
+
+  /**
+   * Purge completed/failed jobs older than N days.
+   */
+  purge(olderThanDays: number = 30): number {
+    const result = this.provider.run(
+      "DELETE FROM job_queue WHERE status IN ('completed', 'failed') AND completed_at < datetime('now', ?)",
+      [`-${olderThanDays} days`],
+    );
+    return result.changes;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────
+
+  private allDepsCompleted(deps: string[]): boolean {
+    for (const depId of deps) {
+      const row = this.provider.get<{ status: string }>(
+        'SELECT status FROM job_queue WHERE id = ?',
+        [depId],
+      );
+      if (!row || row.status !== 'completed') return false;
+    }
+    return true;
+  }
+}
+
+// ─── Row Types ───────────────────────────────────────────────────────
+
+interface JobRow {
+  id: string;
+  type: string;
+  status: string;
+  entry_id: string | null;
+  payload: string;
+  depends_on: string;
+  pipeline_id: string | null;
+  retry_count: number;
+  max_retries: number;
+  result: string | null;
+  error: string | null;
+  created_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+}
+
+function rowToJob(row: JobRow): Job {
+  return {
+    id: row.id,
+    type: row.type,
+    status: row.status as JobStatus,
+    entryId: row.entry_id,
+    payload: JSON.parse(row.payload) as Record<string, unknown>,
+    dependsOn: JSON.parse(row.depends_on) as string[],
+    pipelineId: row.pipeline_id,
+    retryCount: row.retry_count,
+    maxRetries: row.max_retries,
+    result: row.result ? JSON.parse(row.result) : null,
+    error: row.error,
+    createdAt: row.created_at,
+    startedAt: row.started_at,
+    completedAt: row.completed_at,
+  };
+}