@soleri/core 2.4.0 → 2.6.0

package/src/project/project-registry.ts

@@ -2,11 +2,11 @@
  * Project Registry — SQLite-backed registry for tracking projects,
  * rules, and cross-project links.
  *
- * Uses the Vault's underlying SQLite database via `vault.getDb()`.
+ * Uses the Vault's underlying database via PersistenceProvider.
  * Tables are created lazily on first access.
  */
 
-import type Database from 'better-sqlite3';
+import type { PersistenceProvider } from '../persistence/types.js';
 import type { RegisteredProject, ProjectRule, ProjectLink, LinkType } from './types.js';
 
 /** Row shape for the projects table. */
@@ -42,7 +42,11 @@ interface LinkRow {
  * Generate a deterministic project ID from a filesystem path.
  */
 function pathToId(path: string): string {
-  return path.replace(/[^a-z0-9]/gi, '-').toLowerCase().replace(/-+/g, '-').replace(/^-|-$/g, '');
+  return path
+    .replace(/[^a-z0-9]/gi, '-')
+    .toLowerCase()
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
 }
 
 function rowToProject(row: ProjectRow): RegisteredProject {
@@ -78,15 +82,15 @@ function rowToLink(row: LinkRow): ProjectLink {
 }
 
 export class ProjectRegistry {
-  private db: Database.Database;
+  private provider: PersistenceProvider;
 
-  constructor(db: Database.Database) {
-    this.db = db;
+  constructor(provider: PersistenceProvider) {
+    this.provider = provider;
     this.initTables();
   }
 
   private initTables(): void {
-    this.db.exec(`
+    this.provider.execSql(`
       CREATE TABLE IF NOT EXISTS registered_projects (
         id TEXT PRIMARY KEY,
         path TEXT UNIQUE NOT NULL,
@@ -124,17 +128,19 @@ export class ProjectRegistry {
     const id = pathToId(path);
     const now = Date.now();
 
-    const existing = this.db
-      .prepare('SELECT * FROM registered_projects WHERE id = ?')
-      .get(id) as ProjectRow | undefined;
+    const existing = this.provider.get<ProjectRow>(
+      'SELECT * FROM registered_projects WHERE id = ?',
+      [id],
+    );
 
     if (existing) {
       // Update lastAccessedAt, and optionally name/metadata if provided
       const newName = name ?? existing.name;
       const newMetadata = metadata ? JSON.stringify(metadata) : existing.metadata;
-      this.db
-        .prepare('UPDATE registered_projects SET last_accessed_at = ?, name = ?, metadata = ? WHERE id = ?')
-        .run(now, newName, newMetadata, id);
+      this.provider.run(
+        'UPDATE registered_projects SET last_accessed_at = ?, name = ?, metadata = ? WHERE id = ?',
+        [now, newName, newMetadata, id],
+      );
       return rowToProject({
         ...existing,
         last_accessed_at: now,
@@ -151,11 +157,10 @@ export class ProjectRegistry {
       last_accessed_at: now,
       metadata: JSON.stringify(metadata ?? {}),
     };
-    this.db
-      .prepare(
-        'INSERT INTO registered_projects (id, path, name, registered_at, last_accessed_at, metadata) VALUES (?, ?, ?, ?, ?, ?)',
-      )
-      .run(row.id, row.path, row.name, row.registered_at, row.last_accessed_at, row.metadata);
+    this.provider.run(
+      'INSERT INTO registered_projects (id, path, name, registered_at, last_accessed_at, metadata) VALUES (?, ?, ?, ?, ?, ?)',
+      [row.id, row.path, row.name, row.registered_at, row.last_accessed_at, row.metadata],
+    );
 
     return rowToProject(row);
   }
@@ -164,9 +169,9 @@ export class ProjectRegistry {
    * Get a project by ID.
    */
   get(projectId: string): RegisteredProject | null {
-    const row = this.db
-      .prepare('SELECT * FROM registered_projects WHERE id = ?')
-      .get(projectId) as ProjectRow | undefined;
+    const row = this.provider.get<ProjectRow>('SELECT * FROM registered_projects WHERE id = ?', [
+      projectId,
+    ]);
     return row ? rowToProject(row) : null;
   }
 
@@ -174,9 +179,9 @@ export class ProjectRegistry {
    * Get a project by its filesystem path.
    */
   getByPath(path: string): RegisteredProject | null {
-    const row = this.db
-      .prepare('SELECT * FROM registered_projects WHERE path = ?')
-      .get(path) as ProjectRow | undefined;
+    const row = this.provider.get<ProjectRow>('SELECT * FROM registered_projects WHERE path = ?', [
+      path,
+    ]);
     return row ? rowToProject(row) : null;
   }
 
@@ -184,9 +189,9 @@ export class ProjectRegistry {
    * List all registered projects.
    */
   list(): RegisteredProject[] {
-    const rows = this.db
-      .prepare('SELECT * FROM registered_projects ORDER BY last_accessed_at DESC')
-      .all() as ProjectRow[];
+    const rows = this.provider.all<ProjectRow>(
+      'SELECT * FROM registered_projects ORDER BY last_accessed_at DESC',
+    );
     return rows.map(rowToProject);
   }
 
@@ -194,23 +199,26 @@ export class ProjectRegistry {
    * Unregister a project by ID. Also removes associated rules and links.
    */
   unregister(projectId: string): boolean {
-    const result = this.db.transaction(() => {
-      this.db.prepare('DELETE FROM project_rules WHERE project_id = ?').run(projectId);
-      this.db
-        .prepare('DELETE FROM project_links WHERE source_project_id = ? OR target_project_id = ?')
-        .run(projectId, projectId);
-      return this.db.prepare('DELETE FROM registered_projects WHERE id = ?').run(projectId).changes > 0;
-    })();
-    return result;
+    return this.provider.transaction(() => {
+      this.provider.run('DELETE FROM project_rules WHERE project_id = ?', [projectId]);
+      this.provider.run(
+        'DELETE FROM project_links WHERE source_project_id = ? OR target_project_id = ?',
+        [projectId, projectId],
+      );
+      return (
+        this.provider.run('DELETE FROM registered_projects WHERE id = ?', [projectId]).changes > 0
+      );
+    });
   }
 
   /**
    * Update the lastAccessedAt timestamp for a project.
    */
   touch(projectId: string): void {
-    this.db
-      .prepare('UPDATE registered_projects SET last_accessed_at = ? WHERE id = ?')
-      .run(Date.now(), projectId);
+    this.provider.run('UPDATE registered_projects SET last_accessed_at = ? WHERE id = ?', [
+      Date.now(),
+      projectId,
+    ]);
   }
 
   // ─── Rules ──────────────────────────────────────────────────────────
@@ -224,11 +232,10 @@ export class ProjectRegistry {
   ): ProjectRule {
     const id = `rule-${projectId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const now = Date.now();
-    this.db
-      .prepare(
-        'INSERT INTO project_rules (id, project_id, category, text, priority, created_at) VALUES (?, ?, ?, ?, ?, ?)',
-      )
-      .run(id, projectId, rule.category, rule.text, rule.priority, now);
+    this.provider.run(
+      'INSERT INTO project_rules (id, project_id, category, text, priority, created_at) VALUES (?, ?, ?, ?, ?, ?)',
+      [id, projectId, rule.category, rule.text, rule.priority, now],
+    );
 
     return {
       id,
@@ -244,9 +251,10 @@ export class ProjectRegistry {
    * Get all rules for a project.
    */
   getRules(projectId: string): ProjectRule[] {
-    const rows = this.db
-      .prepare('SELECT * FROM project_rules WHERE project_id = ? ORDER BY priority DESC, created_at ASC')
-      .all(projectId) as RuleRow[];
+    const rows = this.provider.all<RuleRow>(
+      'SELECT * FROM project_rules WHERE project_id = ? ORDER BY priority DESC, created_at ASC',
+      [projectId],
+    );
     return rows.map(rowToRule);
   }
 
@@ -254,7 +262,7 @@ export class ProjectRegistry {
    * Remove a rule by ID.
    */
   removeRule(ruleId: string): boolean {
-    return this.db.prepare('DELETE FROM project_rules WHERE id = ?').run(ruleId).changes > 0;
+    return this.provider.run('DELETE FROM project_rules WHERE id = ?', [ruleId]).changes > 0;
   }
 
   /**
@@ -275,20 +283,18 @@ export class ProjectRegistry {
    */
   link(sourceId: string, targetId: string, linkType: LinkType): ProjectLink {
     const now = Date.now();
-    const info = this.db
-      .prepare(
-        'INSERT OR IGNORE INTO project_links (source_project_id, target_project_id, link_type, created_at) VALUES (?, ?, ?, ?)',
-      )
-      .run(sourceId, targetId, linkType, now);
+    const info = this.provider.run(
+      'INSERT OR IGNORE INTO project_links (source_project_id, target_project_id, link_type, created_at) VALUES (?, ?, ?, ?)',
+      [sourceId, targetId, linkType, now],
+    );
 
     // If insert was ignored (duplicate), fetch existing
     if (info.changes === 0) {
-      const existing = this.db
-        .prepare(
-          'SELECT * FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
-        )
-        .get(sourceId, targetId, linkType) as LinkRow;
-      return rowToLink(existing);
+      const existing = this.provider.get<LinkRow>(
+        'SELECT * FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
+        [sourceId, targetId, linkType],
+      );
+      return rowToLink(existing!);
     }
 
     return {
@@ -306,28 +312,25 @@ export class ProjectRegistry {
    */
   unlink(sourceId: string, targetId: string, linkType?: LinkType): number {
     if (linkType) {
-      return this.db
-        .prepare(
-          'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
-        )
-        .run(sourceId, targetId, linkType).changes;
+      return this.provider.run(
+        'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ? AND link_type = ?',
+        [sourceId, targetId, linkType],
+      ).changes;
     }
-    return this.db
-      .prepare(
-        'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ?',
-      )
-      .run(sourceId, targetId).changes;
+    return this.provider.run(
+      'DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ?',
+      [sourceId, targetId],
+    ).changes;
   }
 
   /**
    * Get all links for a project (both outgoing and incoming).
    */
   getLinks(projectId: string): ProjectLink[] {
-    const rows = this.db
-      .prepare(
-        'SELECT * FROM project_links WHERE source_project_id = ? OR target_project_id = ? ORDER BY created_at DESC',
-      )
-      .all(projectId, projectId) as LinkRow[];
+    const rows = this.provider.all<LinkRow>(
+      'SELECT * FROM project_links WHERE source_project_id = ? OR target_project_id = ? ORDER BY created_at DESC',
+      [projectId, projectId],
+    );
     return rows.map(rowToLink);
   }
 
@@ -338,7 +341,11 @@ export class ProjectRegistry {
     projectId: string,
   ): Array<{ project: RegisteredProject; linkType: LinkType; direction: 'outgoing' | 'incoming' }> {
     const links = this.getLinks(projectId);
-    const results: Array<{ project: RegisteredProject; linkType: LinkType; direction: 'outgoing' | 'incoming' }> = [];
+    const results: Array<{
+      project: RegisteredProject;
+      linkType: LinkType;
+      direction: 'outgoing' | 'incoming';
+    }> = [];
 
     for (const link of links) {
       const isOutgoing = link.sourceProjectId === projectId;

package/src/prompts/index.ts

@@ -0,0 +1,3 @@
+export { TemplateManager } from './template-manager.js';
+export { parseVariables, resolveIncludes } from './parser.js';
+export type { PromptTemplate, TemplateVariable, RenderOptions } from './types.js';

package/src/prompts/parser.ts

@@ -0,0 +1,59 @@
+/**
+ * Template parser — extract variables and resolve includes.
+ */
+
+import type { TemplateVariable } from './types.js';
+
+const VAR_PATTERN = /\{\{(\w+)(?::([^}]*))?\}\}/g;
+const INCLUDE_PATTERN = /@include\(([^)]+)\)/g;
+const MAX_INCLUDE_DEPTH = 10;
+
+/**
+ * Extract unique variables from template content.
+ * Supports {{name}} (required) and {{name:default}} (optional with default).
+ */
+export function parseVariables(content: string): TemplateVariable[] {
+  const seen = new Map<string, TemplateVariable>();
+
+  for (const match of content.matchAll(VAR_PATTERN)) {
+    const name = match[1];
+    const defaultValue = match[2];
+    if (!seen.has(name)) {
+      seen.set(name, {
+        name,
+        required: defaultValue === undefined,
+        defaultValue,
+      });
+    }
+  }
+
+  return Array.from(seen.values());
+}
+
+/**
+ * Resolve @include(partial-name) directives.
+ *
+ * The loader function receives the partial name and returns its content.
+ * Cycle detection prevents infinite recursion.
+ */
+export function resolveIncludes(
+  content: string,
+  loader: (name: string) => string,
+  _stack: Set<string> = new Set(),
+  _depth: number = 0,
+): string {
+  if (_depth > MAX_INCLUDE_DEPTH) {
+    throw new Error(`Include depth exceeded ${MAX_INCLUDE_DEPTH}. Possible circular include.`);
+  }
+
+  return content.replace(INCLUDE_PATTERN, (_match, partialName: string) => {
+    const trimmed = partialName.trim();
+    if (_stack.has(trimmed)) {
+      throw new Error(`Circular include detected: ${trimmed} (stack: ${[..._stack].join(' → ')})`);
+    }
+    const newStack = new Set(_stack);
+    newStack.add(trimmed);
+    const partialContent = loader(trimmed);
+    return resolveIncludes(partialContent, loader, newStack, _depth + 1);
+  });
+}

package/src/prompts/template-manager.ts

@@ -0,0 +1,77 @@
+/**
+ * Template manager — load, render, and list .prompt templates.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import type { PromptTemplate, RenderOptions } from './types.js';
+import { parseVariables, resolveIncludes } from './parser.js';
+
+const VAR_REGEX = /\{\{(\w+)(?::([^}]*))?\}\}/g;
+
+export class TemplateManager {
+  private templates = new Map<string, PromptTemplate>();
+  private templatesDir: string;
+
+  constructor(templatesDir: string) {
+    this.templatesDir = templatesDir;
+  }
+
+  /** Load all .prompt files from templatesDir. */
+  load(): void {
+    if (!existsSync(this.templatesDir)) return;
+
+    const files = readdirSync(this.templatesDir).filter((f) => f.endsWith('.prompt'));
+    for (const file of files) {
+      const fullPath = join(this.templatesDir, file);
+      const content = readFileSync(fullPath, 'utf-8');
+      const name = basename(file, '.prompt');
+      this.templates.set(name, {
+        name,
+        content,
+        variables: parseVariables(content),
+        path: fullPath,
+      });
+    }
+  }
+
+  /**
+   * Render a template by name with variable substitution.
+   *
+   * @param name - Template name (without .prompt extension)
+   * @param vars - Variable values to substitute
+   * @param options - Render options (strict mode)
+   * @throws If template not found, or strict mode and required variable missing
+   */
+  render(name: string, vars: Record<string, string> = {}, options?: RenderOptions): string {
+    const template = this.templates.get(name);
+    if (!template) throw new Error(`Template not found: ${name}`);
+
+    const strict = options?.strict ?? true;
+
+    // Resolve @include() directives
+    const resolved = resolveIncludes(template.content, (partialName) => {
+      const partial = this.templates.get(partialName);
+      if (!partial) throw new Error(`Include not found: ${partialName} (in template: ${name})`);
+      return partial.content;
+    });
+
+    // Replace {{var}} and {{var:default}}
+    return resolved.replace(VAR_REGEX, (_match, varName: string, defaultValue?: string) => {
+      if (vars[varName] !== undefined) return vars[varName];
+      if (defaultValue !== undefined) return defaultValue;
+      if (strict) throw new Error(`Missing required variable: ${varName} (in template: ${name})`);
+      return _match; // Leave placeholder as-is in non-strict mode
+    });
+  }
+
+  /** List all loaded template names. */
+  listTemplates(): string[] {
+    return Array.from(this.templates.keys());
+  }
+
+  /** Get a template by name (raw, unrendered). */
+  getTemplate(name: string): PromptTemplate | null {
+    return this.templates.get(name) ?? null;
+  }
+}

package/src/prompts/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Prompt template types.
+ */
+
+export interface TemplateVariable {
+  /** Variable name, e.g. 'agentName' */
+  name: string;
+  /** Whether the variable must be provided at render time. */
+  required: boolean;
+  /** Default value used when variable is not provided (makes required=false). */
+  defaultValue?: string;
+}
+
+export interface PromptTemplate {
+  /** Template name (filename without .prompt extension). */
+  name: string;
+  /** Raw template content before variable substitution. */
+  content: string;
+  /** Variables extracted from the template. */
+  variables: TemplateVariable[];
+  /** Absolute file path. */
+  path: string;
+}
+
+export interface RenderOptions {
+  /** If true (default), throw on missing required variables. */
+  strict?: boolean;
+}