cognitive-core 0.0.2 → 0.1.2

package/src/surfacing/skill-publisher.ts

@@ -0,0 +1,223 @@
+/**
+ * Skill Publisher
+ *
+ * Converts cognitive-core Playbooks to skill-tree's Skill format and
+ * writes them directly to a StorageAdapter. Handles the Playbook → Skill
+ * conversion at the publish boundary.
+ */
+
+import type { Skill, StorageAdapter, TriggerCondition } from 'skill-tree';
+import type { Playbook } from '../types/index.js';
+import type { PublishResult, DeprecateResult } from './publisher.js';
+import { getPlaybookSuccessRate } from '../types/playbook.js';
+
+/**
+ * Convert a Playbook to a Skill
+ */
+export function convertPlaybookToSkill(playbook: Playbook): Skill {
+  const totalUses = playbook.evolution.successCount + playbook.evolution.failureCount;
+  const successRate = getPlaybookSuccessRate(playbook);
+
+  // Build solution text from guidance
+  let solution = playbook.guidance.strategy;
+  if (playbook.guidance.tactics.length > 0) {
+    solution += '\n\nTactics:\n' + playbook.guidance.tactics.map((t, i) => `${i + 1}. ${t}`).join('\n');
+  }
+  if (playbook.guidance.steps?.length) {
+    solution += '\n\nSteps:\n' + playbook.guidance.steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+  }
+
+  // Build verification text
+  const verification = playbook.verification.successIndicators.length > 0
+    ? playbook.verification.successIndicators.join('. ')
+    : 'Verify the approach worked as expected.';
+
+  // Build notes from anti-patterns and refinements
+  const notesParts: string[] = [];
+  if (playbook.applicability.antiPatterns.length > 0) {
+    notesParts.push('Do NOT use when: ' + playbook.applicability.antiPatterns.join('; '));
+  }
+  if (playbook.verification.failureIndicators.length > 0) {
+    notesParts.push('Watch for: ' + playbook.verification.failureIndicators.join('; '));
+  }
+  if (playbook.evolution.refinements.length > 0) {
+    notesParts.push('Refinements:\n' + playbook.evolution.refinements.map(
+      r => `- In ${r.context}: ${r.addition}`
+    ).join('\n'));
+  }
+  if (playbook.verification.rollbackStrategy) {
+    notesParts.push('Rollback: ' + playbook.verification.rollbackStrategy);
+  }
+
+  // Build trigger conditions
+  const triggerConditions = extractTriggerConditions(playbook);
+
+  // Build description for semantic matching
+  const description = playbook.applicability.situations[0]
+    ?? `${playbook.name}: ${playbook.guidance.strategy.slice(0, 100)}`;
+
+  // Estimate tokens (rough: 4 chars per token)
+  const fullText = [playbook.name, solution, verification, ...notesParts].join(' ');
+  const tokenEstimate = Math.ceil(fullText.length / 4);
+
+  return {
+    id: playbook.id,
+    name: playbook.name,
+    version: playbook.evolution.version,
+    description,
+    problem: playbook.applicability.situations.join('. '),
+    triggerConditions,
+    solution,
+    verification,
+    examples: playbook.guidance.codeExample
+      ? [{ scenario: playbook.applicability.situations[0] ?? playbook.name, before: '', after: playbook.guidance.codeExample }]
+      : [],
+    notes: notesParts.length > 0 ? notesParts.join('\n\n') : undefined,
+    author: 'cognitive-core',
+    tags: playbook.applicability.domains,
+    status: 'active',
+    metrics: {
+      usageCount: totalUses,
+      successRate,
+      lastUsed: playbook.evolution.lastUsed,
+      feedbackScores: [],
+      averageConfidence: playbook.confidence,
+    },
+    source: {
+      type: 'extracted',
+      sessionId: playbook.evolution.createdFrom[0],
+      importedAt: playbook.createdAt,
+    },
+    serving: {
+      summary: description.length > 150 ? description.slice(0, 147) + '...' : description,
+      tokenEstimate,
+    },
+    createdAt: playbook.createdAt,
+    updatedAt: playbook.updatedAt,
+  };
+}
+
+/**
+ * Extract trigger conditions from playbook applicability
+ */
+function extractTriggerConditions(playbook: Playbook): TriggerCondition[] {
+  const triggers: TriggerCondition[] = [];
+
+  // Add situation-based triggers
+  for (const situation of playbook.applicability.situations) {
+    triggers.push({
+      type: 'context',
+      value: situation,
+      description: 'Situation trigger',
+    });
+  }
+
+  // Add explicit triggers with type detection
+  for (const trigger of playbook.applicability.triggers) {
+    let type: TriggerCondition['type'] = 'keyword';
+    if (trigger.toLowerCase().includes('error') || /^[A-Z]{2,}\d+/.test(trigger)) {
+      type = 'error';
+    } else if (trigger.startsWith('/') || trigger.includes('*')) {
+      type = 'pattern';
+    }
+
+    triggers.push({
+      type,
+      value: trigger,
+      description: 'Explicit trigger',
+    });
+  }
+
+  return triggers;
+}
+
+/**
+ * SkillPublisher - Manages publishing graduated playbooks to skill-tree storage
+ */
+export class SkillPublisher {
+  private storage: StorageAdapter;
+  private publishedIds: Set<string> = new Set();
+
+  constructor(storage: StorageAdapter) {
+    this.storage = storage;
+  }
+
+  /**
+   * Publish a playbook as a skill to skill-tree storage
+   */
+  async publishPlaybook(playbook: Playbook): Promise<PublishResult> {
+    const skill = convertPlaybookToSkill(playbook);
+
+    try {
+      const existing = await this.storage.getSkill(skill.id);
+      await this.storage.saveSkill(skill);
+      this.publishedIds.add(skill.id);
+
+      return {
+        published: true,
+        skillId: skill.id,
+        version: skill.version,
+        isUpdate: existing !== null,
+      };
+    } catch (error) {
+      return {
+        published: false,
+        skillId: skill.id,
+        version: skill.version,
+        isUpdate: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Publish multiple playbooks
+   */
+  async publishPlaybooks(playbooks: Playbook[]): Promise<PublishResult[]> {
+    const results: PublishResult[] = [];
+    for (const playbook of playbooks) {
+      results.push(await this.publishPlaybook(playbook));
+    }
+    return results;
+  }
+
+  /**
+   * Deprecate a skill in storage
+   */
+  async deprecateSkill(skillId: string, reason: string): Promise<DeprecateResult> {
+    try {
+      const existing = await this.storage.getSkill(skillId);
+      if (!existing) {
+        return { deprecated: false, skillId, error: 'Skill not found' };
+      }
+
+      existing.status = 'deprecated';
+      existing.notes = (existing.notes ? existing.notes + '\n\n' : '') + `Deprecated: ${reason}`;
+      existing.updatedAt = new Date();
+      await this.storage.saveSkill(existing);
+
+      this.publishedIds.delete(skillId);
+      return { deprecated: true, skillId };
+    } catch (error) {
+      return {
+        deprecated: false,
+        skillId,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Check if a playbook has been published
+   */
+  isPublished(playbookId: string): boolean {
+    return this.publishedIds.has(playbookId);
+  }
+
+  /**
+   * Get count of published skills
+   */
+  getPublishedCount(): number {
+    return this.publishedIds.size;
+  }
+}

package/src/surfacing/sqlite-storage-adapter.ts

@@ -0,0 +1,301 @@
+/**
+ * SQLite Storage Adapter for skill-tree
+ *
+ * Implements skill-tree's StorageAdapter interface using better-sqlite3,
+ * providing persistent skill storage for the learn → graduate → publish loop.
+ *
+ * Follows the same SQLite patterns used by src/embeddings/vector-store.ts:
+ * CREATE IF NOT EXISTS, prepared statements, INSERT OR REPLACE.
+ */
+
+import Database from 'better-sqlite3';
+import type { Skill, StorageAdapter, SkillVersion, SkillLineage } from 'skill-tree';
+
+/**
+ * Raw database row shape for the skills table.
+ */
+interface SkillRow {
+  id: string;
+  name: string;
+  version: string;
+  description: string | null;
+  problem: string | null;
+  solution: string;
+  verification: string | null;
+  notes: string | null;
+  author: string | null;
+  status: string;
+  tags: string;
+  trigger_conditions: string;
+  examples: string;
+  metrics: string;
+  source: string;
+  serving: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface VersionRow {
+  skill_id: string;
+  version: string;
+  skill_snapshot: string;
+  changelog: string;
+  content_hash: string;
+  created_at: string;
+}
+
+/**
+ * SQLite-backed StorageAdapter for skill-tree.
+ *
+ * Stores skills in a `skills` table with JSON columns for nested objects
+ * (tags, metrics, triggerConditions, etc.). Version history is tracked in
+ * a separate `skill_versions` table. Dates are stored as ISO strings.
+ */
+export class SqliteStorageAdapter implements StorageAdapter {
+  private db: Database.Database;
+  private initialized = false;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    // Enable WAL mode for better concurrent read performance
+    this.db.pragma('journal_mode = WAL');
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS skills (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        version TEXT NOT NULL,
+        description TEXT,
+        problem TEXT,
+        solution TEXT NOT NULL,
+        verification TEXT,
+        notes TEXT,
+        author TEXT,
+        status TEXT NOT NULL DEFAULT 'active',
+        tags TEXT NOT NULL DEFAULT '[]',
+        trigger_conditions TEXT NOT NULL DEFAULT '[]',
+        examples TEXT NOT NULL DEFAULT '[]',
+        metrics TEXT NOT NULL DEFAULT '{}',
+        source TEXT NOT NULL DEFAULT '{}',
+        serving TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS skill_versions (
+        skill_id TEXT NOT NULL,
+        version TEXT NOT NULL,
+        skill_snapshot TEXT NOT NULL,
+        changelog TEXT NOT NULL DEFAULT '',
+        content_hash TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (skill_id, version)
+      )
+    `);
+
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_skills_status ON skills(status)
+    `);
+
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_skills_name ON skills(name)
+    `);
+
+    this.initialized = true;
+  }
+
+  async getSkill(id: string): Promise<Skill | null> {
+    const row = this.db.prepare('SELECT * FROM skills WHERE id = ?').get(id) as SkillRow | undefined;
+    return row ? this.rowToSkill(row) : null;
+  }
+
+  async saveSkill(skill: Skill): Promise<void> {
+    const transaction = this.db.transaction(() => {
+      // Upsert the skill
+      const stmt = this.db.prepare(`
+        INSERT OR REPLACE INTO skills
+          (id, name, version, description, problem, solution, verification, notes,
+           author, status, tags, trigger_conditions, examples, metrics, source,
+           serving, created_at, updated_at)
+        VALUES
+          (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+
+      stmt.run(
+        skill.id,
+        skill.name,
+        skill.version,
+        skill.description ?? null,
+        skill.problem ?? null,
+        skill.solution,
+        skill.verification ?? null,
+        skill.notes ?? null,
+        skill.author ?? null,
+        skill.status,
+        JSON.stringify(skill.tags ?? []),
+        JSON.stringify(skill.triggerConditions ?? []),
+        JSON.stringify(skill.examples ?? []),
+        JSON.stringify(skill.metrics ?? {}),
+        JSON.stringify(skill.source ?? {}),
+        JSON.stringify(skill.serving ?? {}),
+        toISOString(skill.createdAt),
+        toISOString(skill.updatedAt),
+      );
+
+      // Record version snapshot
+      const versionStmt = this.db.prepare(`
+        INSERT OR IGNORE INTO skill_versions
+          (skill_id, version, skill_snapshot, changelog, content_hash, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `);
+
+      versionStmt.run(
+        skill.id,
+        skill.version,
+        JSON.stringify(skill),
+        '',
+        hashSkill(skill),
+        toISOString(skill.updatedAt),
+      );
+    });
+
+    transaction();
+  }
+
+  async listSkills(filter?: { tags?: string[]; status?: string[] }): Promise<Skill[]> {
+    let query = 'SELECT * FROM skills WHERE 1=1';
+    const params: unknown[] = [];
+
+    if (filter?.status?.length) {
+      const placeholders = filter.status.map(() => '?').join(',');
+      query += ` AND status IN (${placeholders})`;
+      params.push(...filter.status);
+    }
+
+    query += ' ORDER BY updated_at DESC';
+
+    const rows = this.db.prepare(query).all(...params) as SkillRow[];
+    let skills = rows.map(r => this.rowToSkill(r));
+
+    // Post-filter by tags (JSON array column — filter in JS for simplicity)
+    if (filter?.tags?.length) {
+      skills = skills.filter(s =>
+        filter.tags!.some(tag => s.tags?.includes(tag))
+      );
+    }
+
+    return skills;
+  }
+
+  async deleteSkill(id: string): Promise<boolean> {
+    const result = this.db.prepare('DELETE FROM skills WHERE id = ?').run(id);
+    // Keep version history for lineage tracking
+    return result.changes > 0;
+  }
+
+  async getVersionHistory(skillId: string): Promise<SkillVersion[]> {
+    const rows = this.db.prepare(
+      'SELECT * FROM skill_versions WHERE skill_id = ? ORDER BY created_at ASC'
+    ).all(skillId) as VersionRow[];
+
+    return rows.map(row => ({
+      skillId: row.skill_id,
+      version: row.version,
+      skill: JSON.parse(row.skill_snapshot),
+      changelog: row.changelog,
+      contentHash: row.content_hash,
+      createdAt: new Date(row.created_at),
+    }));
+  }
+
+  async getLineage(skillId: string): Promise<SkillLineage | null> {
+    const versions = await this.getVersionHistory(skillId);
+    if (versions.length === 0) return null;
+
+    return {
+      rootId: skillId,
+      versions,
+      forks: [], // Forks are not tracked in this adapter
+    };
+  }
+
+  async searchSkills(query: string): Promise<Skill[]> {
+    // Simple LIKE-based search across name, description, and solution
+    const rows = this.db.prepare(`
+      SELECT * FROM skills
+      WHERE name LIKE ? OR description LIKE ? OR solution LIKE ? OR problem LIKE ?
+      ORDER BY updated_at DESC
+    `).all(
+      `%${query}%`, `%${query}%`, `%${query}%`, `%${query}%`
+    ) as SkillRow[];
+
+    return rows.map(r => this.rowToSkill(r));
+  }
+
+  /**
+   * Close the database connection. Call when Atlas is shutting down.
+   */
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Convert a database row to a Skill object, parsing JSON columns and dates.
+   */
+  private rowToSkill(row: SkillRow): Skill {
+    const metrics = JSON.parse(row.metrics);
+
+    return {
+      id: row.id,
+      name: row.name,
+      version: row.version,
+      description: row.description ?? '',
+      problem: row.problem ?? '',
+      solution: row.solution,
+      verification: row.verification ?? '',
+      notes: row.notes ?? undefined,
+      author: row.author ?? 'unknown',
+      status: row.status as Skill['status'],
+      tags: JSON.parse(row.tags),
+      triggerConditions: JSON.parse(row.trigger_conditions),
+      examples: JSON.parse(row.examples),
+      metrics: {
+        ...metrics,
+        lastUsed: metrics.lastUsed ? new Date(metrics.lastUsed) : undefined,
+      },
+      source: JSON.parse(row.source),
+      serving: JSON.parse(row.serving),
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at),
+    };
+  }
+}
+
+/**
+ * Safely convert a Date or string to ISO string.
+ */
+function toISOString(value: Date | string | undefined): string {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  return new Date().toISOString();
+}
+
+/**
+ * Simple content hash for version tracking.
+ */
+function hashSkill(skill: Skill): string {
+  const content = `${skill.name}:${skill.solution}:${skill.version}`;
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36);
+}