@soleri/core 2.1.0 → 2.5.0

package/src/project/project-registry.ts

@@ -0,0 +1,370 @@
+/**
+ * Project Registry — SQLite-backed registry for tracking projects,
+ * rules, and cross-project links.
+ *
+ * Uses the Vault's underlying SQLite database via `vault.getDb()`.
+ * Tables are created lazily on first access.
+ */
+
+import type Database from 'better-sqlite3';
+import type { RegisteredProject, ProjectRule, ProjectLink, LinkType } from './types.js';
+
+/** Row shape for the projects table. */
+interface ProjectRow {
+  id: string;
+  path: string;
+  name: string | null;
+  registered_at: number;
+  last_accessed_at: number;
+  metadata: string;
+}
+
+/** Row shape for the project_rules table. */
+interface RuleRow {
+  id: string;
+  project_id: string;
+  category: string;
+  text: string;
+  priority: number;
+  created_at: number;
+}
+
+/** Row shape for the project_links table. */
+interface LinkRow {
+  id: number;
+  source_project_id: string;
+  target_project_id: string;
+  link_type: string;
+  created_at: number;
+}
+
+/**
+ * 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, '');
+}
+
+function rowToProject(row: ProjectRow): RegisteredProject {
+  return {
+    id: row.id,
+    path: row.path,
+    name: row.name ?? undefined,
+    registeredAt: row.registered_at,
+    lastAccessedAt: row.last_accessed_at,
+    metadata: JSON.parse(row.metadata || '{}'),
+  };
+}
+
+function rowToRule(row: RuleRow): ProjectRule {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    category: row.category as ProjectRule['category'],
+    text: row.text,
+    priority: row.priority,
+    createdAt: row.created_at,
+  };
+}
+
+function rowToLink(row: LinkRow): ProjectLink {
+  return {
+    id: row.id,
+    sourceProjectId: row.source_project_id,
+    targetProjectId: row.target_project_id,
+    linkType: row.link_type as LinkType,
+    createdAt: row.created_at,
+  };
+}
+
+export class ProjectRegistry {
+  private db: Database.Database;
+
+  constructor(db: Database.Database) {
+    this.db = db;
+    this.initTables();
+  }
+
+  private initTables(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS registered_projects (
+        id TEXT PRIMARY KEY,
+        path TEXT UNIQUE NOT NULL,
+        name TEXT,
+        registered_at INTEGER NOT NULL,
+        last_accessed_at INTEGER NOT NULL,
+        metadata TEXT DEFAULT '{}'
+      );
+
+      CREATE TABLE IF NOT EXISTS project_rules (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        category TEXT NOT NULL,
+        text TEXT NOT NULL,
+        priority INTEGER DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        FOREIGN KEY (project_id) REFERENCES registered_projects(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS project_links (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_project_id TEXT NOT NULL,
+        target_project_id TEXT NOT NULL,
+        link_type TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(source_project_id, target_project_id, link_type)
+      );
+    `);
+  }
+
+  /**
+   * Register (upsert) a project. Updates lastAccessedAt on re-register.
+   */
+  register(path: string, name?: string, metadata?: Record<string, unknown>): RegisteredProject {
+    const id = pathToId(path);
+    const now = Date.now();
+
+    const existing = this.db.prepare('SELECT * FROM registered_projects WHERE id = ?').get(id) as
+      | ProjectRow
+      | undefined;
+
+    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);
+      return rowToProject({
+        ...existing,
+        last_accessed_at: now,
+        name: newName,
+        metadata: newMetadata,
+      });
+    }
+
+    const row: ProjectRow = {
+      id,
+      path,
+      name: name ?? null,
+      registered_at: now,
+      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);
+
+    return rowToProject(row);
+  }
+
+  /**
+   * 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;
+    return row ? rowToProject(row) : null;
+  }
+
+  /**
+   * 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;
+    return row ? rowToProject(row) : null;
+  }
+
+  /**
+   * List all registered projects.
+   */
+  list(): RegisteredProject[] {
+    const rows = this.db
+      .prepare('SELECT * FROM registered_projects ORDER BY last_accessed_at DESC')
+      .all() as ProjectRow[];
+    return rows.map(rowToProject);
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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);
+  }
+
+  // ─── Rules ──────────────────────────────────────────────────────────
+
+  /**
+   * Add a rule to a project.
+   */
+  addRule(
+    projectId: string,
+    rule: Omit<ProjectRule, 'id' | 'projectId' | 'createdAt'>,
+  ): 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);
+
+    return {
+      id,
+      projectId,
+      category: rule.category,
+      text: rule.text,
+      priority: rule.priority,
+      createdAt: now,
+    };
+  }
+
+  /**
+   * 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[];
+    return rows.map(rowToRule);
+  }
+
+  /**
+   * Remove a rule by ID.
+   */
+  removeRule(ruleId: string): boolean {
+    return this.db.prepare('DELETE FROM project_rules WHERE id = ?').run(ruleId).changes > 0;
+  }
+
+  /**
+   * List all projects with their rules.
+   */
+  listRulesAll(): Array<{ project: RegisteredProject; rules: ProjectRule[] }> {
+    const projects = this.list();
+    return projects.map((project) => ({
+      project,
+      rules: this.getRules(project.id),
+    }));
+  }
+
+  // ─── Links ──────────────────────────────────────────────────────────
+
+  /**
+   * Link two projects.
+   */
+  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);
+
+    // 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);
+    }
+
+    return {
+      id: Number(info.lastInsertRowid),
+      sourceProjectId: sourceId,
+      targetProjectId: targetId,
+      linkType,
+      createdAt: now,
+    };
+  }
+
+  /**
+   * Unlink two projects. If linkType is omitted, removes all links between them.
+   * Returns count of links removed.
+   */
+  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.db
+      .prepare('DELETE FROM project_links WHERE source_project_id = ? AND target_project_id = ?')
+      .run(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[];
+    return rows.map(rowToLink);
+  }
+
+  /**
+   * Get linked projects with details — returns project info, link type, and direction.
+   */
+  getLinkedProjects(
+    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';
+    }> = [];
+
+    for (const link of links) {
+      const isOutgoing = link.sourceProjectId === projectId;
+      const otherProjectId = isOutgoing ? link.targetProjectId : link.sourceProjectId;
+      const project = this.get(otherProjectId);
+      if (project) {
+        results.push({
+          project,
+          linkType: link.linkType,
+          direction: isOutgoing ? 'outgoing' : 'incoming',
+        });
+      }
+    }
+
+    return results;
+  }
+}

package/src/project/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Project registry types — tracks projects, rules, and cross-project links.
+ */
+
+export interface RegisteredProject {
+  id: string;
+  path: string;
+  name?: string;
+  registeredAt: number;
+  lastAccessedAt: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ProjectRule {
+  id: string;
+  projectId: string;
+  category: 'behavior' | 'preference' | 'restriction' | 'convention';
+  text: string;
+  priority: number;
+  createdAt: number;
+}
+
+export type LinkType = 'related' | 'parent' | 'child' | 'fork';
+
+export interface ProjectLink {
+  id: number;
+  sourceProjectId: string;
+  targetProjectId: string;
+  linkType: LinkType;
+  createdAt: number;
+}

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