cognitive-core 0.2.4 → 0.3.1

package/src/surfacing/skill-publisher.ts

@@ -1,257 +0,0 @@
-/**
- * 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 } from 'skill-tree';
-import type { Playbook } from '../types/index.js';
-import type { PublishResult, DeprecateResult } from './publisher.js';
-import { getPlaybookSuccessRate } from '../types/playbook.js';
-
-/**
- * Maximum length for the generated `description` field.
- * Claude Code's skill format caps description at 1024 chars, so we truncate
- * to stay safely within that boundary.
- */
-const MAX_DESCRIPTION_LENGTH = 1024;
-
-/**
- * Build the `description` field for a published Skill.
- *
- * The description is what lightweight trigger matchers — notably Claude Code's
- * skill loader — key off to decide whether to load a skill. It needs two things:
- *
- * 1. A short "what it does" lead (pulled from the first situation, or the
- *    strategy if no situation is set).
- * 2. The concrete trigger phrases, surfaced inline so substring/keyword
- *    matchers catch them. These live in `applicability.triggers` on the
- *    playbook but are invisible to downstream consumers unless we lift them.
- *
- * Shape: `<lead>. Use when "<t1>", "<t2>", ..., "<tN>".`
- */
-function buildDescription(playbook: Playbook): string {
-  let lead = playbook.applicability.situations[0]
-    ?? `${playbook.name}: ${playbook.guidance.strategy.slice(0, 100)}`;
-
-  // Ensure a sentence terminator before appending the trigger clause.
-  if (lead.length > 0 && !/[.!?]$/.test(lead)) {
-    lead += '.';
-  }
-
-  const triggers = playbook.applicability.triggers;
-  const triggerClause = triggers.length > 0
-    ? ` Use when ${triggers.map((t) => `"${t}"`).join(', ')}.`
-    : '';
-
-  const full = lead + triggerClause;
-  if (full.length <= MAX_DESCRIPTION_LENGTH) return full;
-  return full.slice(0, MAX_DESCRIPTION_LENGTH - 3) + '...';
-}
-
-/**
- * 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 description for semantic matching and lightweight trigger routing
-  const description = buildDescription(playbook);
-
-  // Build structured instructions body
-  const instructionParts: string[] = [];
-
-  // --- When to use / When not to use (Change A) ---
-  if (playbook.applicability.situations.length > 0) {
-    instructionParts.push(
-      '## When to use\n\n'
-      + playbook.applicability.situations.map((s) => `- ${s}`).join('\n'),
-    );
-  }
-  if (playbook.applicability.antiPatterns.length > 0) {
-    instructionParts.push(
-      '## When not to use\n\n'
-      + playbook.applicability.antiPatterns.map((a) => `- ${a}`).join('\n'),
-    );
-  }
-
-  // --- Solution ---
-  instructionParts.push(`## Solution\n\n${solution}`);
-
-  // --- Verification with bulleted indicators (Change B) ---
-  const verificationParts: string[] = [];
-  if (playbook.verification.successIndicators.length > 0) {
-    verificationParts.push(
-      'Success:\n'
-      + playbook.verification.successIndicators.map((s) => `- ${s}`).join('\n'),
-    );
-  }
-  if (playbook.verification.failureIndicators.length > 0) {
-    verificationParts.push(
-      'Failure:\n'
-      + playbook.verification.failureIndicators.map((f) => `- ${f}`).join('\n'),
-    );
-  }
-  if (playbook.verification.rollbackStrategy) {
-    verificationParts.push(`Rollback: ${playbook.verification.rollbackStrategy}`);
-  }
-  if (verificationParts.length > 0) {
-    instructionParts.push(`## Verification\n\n${verificationParts.join('\n\n')}`);
-  } else {
-    instructionParts.push('## Verification\n\nVerify the approach worked as expected.');
-  }
-
-  // --- Notes (refinements only — anti-patterns now in their own section) ---
-  const notesParts: string[] = [];
-  if (playbook.evolution.refinements.length > 0) {
-    notesParts.push(
-      'Refinements:\n'
-      + playbook.evolution.refinements.map((r) => `- In ${r.context}: ${r.addition}`).join('\n'),
-    );
-  }
-  if (notesParts.length > 0) {
-    instructionParts.push(`## Notes\n\n${notesParts.join('\n\n')}`);
-  }
-
-  // --- Example ---
-  if (playbook.guidance.codeExample) {
-    instructionParts.push(`## Example\n\n\`\`\`\n${playbook.guidance.codeExample}\n\`\`\``);
-  }
-
-  const instructions = instructionParts.join('\n\n');
-
-  // Estimate tokens (rough: 4 chars per token)
-  const tokenEstimate = Math.ceil(instructions.length / 4);
-
-  return {
-    id: playbook.id,
-    name: playbook.name,
-    version: playbook.evolution.version,
-    description,
-    instructions,
-    author: playbook.provenance?.curatedBy ?? '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,
-  };
-}
-
-/**
- * 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.description = (existing.description ? existing.description + ' ' : '') + `[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

@@ -1,285 +0,0 @@
-/**
- * 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;
-  instructions: string;
-  author: string | null;
-  status: string;
-  tags: string;
-  metrics: string;
-  source: string;
-  serving: string;
-  related: 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,
-        instructions TEXT NOT NULL DEFAULT '',
-        author TEXT,
-        status TEXT NOT NULL DEFAULT 'active',
-        tags TEXT NOT NULL DEFAULT '[]',
-        metrics TEXT NOT NULL DEFAULT '{}',
-        source TEXT NOT NULL DEFAULT '{}',
-        serving TEXT NOT NULL DEFAULT '{}',
-        related 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, instructions,
-           author, status, tags, metrics, source,
-           serving, related, created_at, updated_at)
-        VALUES
-          (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `);
-
-      stmt.run(
-        skill.id,
-        skill.name,
-        skill.version,
-        skill.description ?? null,
-        skill.instructions,
-        skill.author ?? null,
-        skill.status,
-        JSON.stringify(skill.tags ?? []),
-        JSON.stringify(skill.metrics ?? {}),
-        JSON.stringify(skill.source ?? {}),
-        JSON.stringify(skill.serving ?? {}),
-        JSON.stringify(skill.related ?? []),
-        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 instructions
-    const rows = this.db.prepare(`
-      SELECT * FROM skills
-      WHERE name LIKE ? OR description LIKE ? OR instructions LIKE ?
-      ORDER BY updated_at DESC
-    `).all(
-      `%${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 ?? '',
-      instructions: row.instructions,
-      author: row.author ?? 'unknown',
-      status: row.status as Skill['status'],
-      tags: JSON.parse(row.tags),
-      related: JSON.parse(row.related),
-      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.instructions}:${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);
-}