@soleri/core 2.9.0 → 2.11.0

package/src/vault/obsidian-sync.ts

@@ -0,0 +1,346 @@
+/**
+ * Obsidian Bidirectional Sync — export/import vault entries as Obsidian markdown.
+ *
+ * Supports three modes:
+ * - Push (vault → Obsidian)
+ * - Pull (Obsidian → vault)
+ * - Bidirectional (timestamp-based merge with conflict detection)
+ *
+ * Format: YAML frontmatter + body content + wikilinks for related entries.
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
+import { join, extname, relative, dirname } from 'node:path';
+import type { Vault } from './vault.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface ObsidianSyncConfig {
+  vault: Vault;
+}
+
+export interface ExportOptions {
+  types?: string[];
+  domains?: string[];
+  dryRun?: boolean;
+}
+
+export interface ImportOptions {
+  defaultType?: string;
+  defaultDomain?: string;
+  dryRun?: boolean;
+}
+
+export type SyncMode = 'push' | 'pull' | 'bidirectional';
+
+export interface SyncOptions {
+  mode?: SyncMode;
+  dryRun?: boolean;
+}
+
+export interface ExportResult {
+  exported: number;
+  files: string[];
+  skipped: number;
+}
+
+export interface ImportResult {
+  imported: number;
+  updated: number;
+  skipped: number;
+  conflicts: ConflictInfo[];
+}
+
+export interface SyncResult {
+  pushed: number;
+  pulled: number;
+  conflicts: ConflictInfo[];
+  mode: SyncMode;
+}
+
+export interface ConflictInfo {
+  title: string;
+  id: string;
+  vaultUpdated: number;
+  obsidianUpdated: number;
+  vaultSnippet: string;
+  obsidianSnippet: string;
+}
+
+// ─── Format Helpers ──────────────────────────────────────────────────
+
+/**
+ * Convert a vault entry to Obsidian-compatible markdown with YAML frontmatter.
+ */
+export function toObsidianMarkdown(entry: IntelligenceEntry): string {
+  const lines: string[] = ['---'];
+
+  lines.push(`id: "${entry.id}"`);
+  lines.push(`type: "${entry.type}"`);
+  if (entry.domain) lines.push(`domain: "${entry.domain}"`);
+  if (entry.severity) lines.push(`severity: "${entry.severity}"`);
+  if (entry.tags && entry.tags.length > 0) {
+    lines.push(`tags: [${entry.tags.map((t) => `"${t}"`).join(', ')}]`);
+  }
+  lines.push(`updated: ${Date.now()}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# ${entry.title}`);
+  lines.push('');
+  lines.push(entry.description);
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse Obsidian markdown with YAML frontmatter back to vault entry fields.
+ */
+export function fromObsidianMarkdown(content: string): {
+  id?: string;
+  type?: string;
+  domain?: string;
+  severity?: string;
+  tags?: string[];
+  title?: string;
+  description?: string;
+  updated?: number;
+} {
+  const result: Record<string, unknown> = {};
+
+  // Parse YAML frontmatter
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const yaml = fmMatch[1];
+    for (const line of yaml.split('\n')) {
+      const kv = line.match(/^(\w+):\s*(.+)$/);
+      if (!kv) continue;
+      const [, key, value] = kv;
+      if (key === 'tags') {
+        const tagMatch = value.match(/\[([^\]]*)\]/);
+        if (tagMatch) {
+          result.tags = tagMatch[1]
+            .split(',')
+            .map((t) => t.trim().replace(/^"|"$/g, ''))
+            .filter(Boolean);
+        }
+      } else if (key === 'updated') {
+        result.updated = parseInt(value, 10);
+      } else {
+        result[key] = value.replace(/^"|"$/g, '');
+      }
+    }
+  }
+
+  // Parse body
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  const titleMatch = body.match(/^# (.+)$/m);
+  if (titleMatch) {
+    result.title = titleMatch[1];
+  }
+
+  const description = body.replace(/^# .+\n*/, '').trim();
+  if (description) {
+    result.description = description;
+  }
+
+  // Type inference when missing
+  if (!result.type && description) {
+    const lower = description.toLowerCase();
+    if (/\b(don't|avoid|never|anti-pattern)\b/.test(lower)) {
+      result.type = 'anti-pattern';
+    } else if (/\b(always|prefer|use|pattern)\b/.test(lower)) {
+      result.type = 'pattern';
+    } else if (/^rule:/i.test(description)) {
+      result.type = 'rule';
+    } else {
+      result.type = 'concept';
+    }
+  }
+
+  return result as {
+    id?: string;
+    type?: string;
+    domain?: string;
+    severity?: string;
+    tags?: string[];
+    title?: string;
+    description?: string;
+    updated?: number;
+  };
+}
+
+/**
+ * Slugify a title for use as a filename.
+ */
+export function titleToSlug(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 80);
+}
+
+// ─── Sync Engine ─────────────────────────────────────────────────────
+
+export class ObsidianSync {
+  private vault: Vault;
+
+  constructor(config: ObsidianSyncConfig) {
+    this.vault = config.vault;
+  }
+
+  /**
+   * Export vault entries to Obsidian markdown files.
+   */
+  export(obsidianDir: string, opts: ExportOptions = {}): ExportResult {
+    let entries = this.vault.list({});
+
+    // Filter by types and domains (vault.list takes singular, we support arrays)
+    if (opts.types && opts.types.length > 0) {
+      entries = entries.filter((e) => opts.types!.includes(e.type));
+    }
+    if (opts.domains && opts.domains.length > 0) {
+      entries = entries.filter((e) => opts.domains!.includes(e.domain || ''));
+    }
+
+    const files: string[] = [];
+    let skipped = 0;
+
+    for (const entry of entries) {
+      const domain = entry.domain || 'general';
+      const slug = titleToSlug(entry.title);
+      if (!slug) {
+        skipped++;
+        continue;
+      }
+
+      const dir = join(obsidianDir, domain);
+      const filePath = join(dir, `${slug}.md`);
+      const relPath = relative(obsidianDir, filePath);
+
+      if (!opts.dryRun) {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(filePath, toObsidianMarkdown(entry), 'utf-8');
+      }
+
+      files.push(relPath);
+    }
+
+    return { exported: files.length, files, skipped };
+  }
+
+  /**
+   * Import Obsidian markdown files into the vault.
+   */
+  import(obsidianDir: string, opts: ImportOptions = {}): ImportResult {
+    const mdFiles = this.findMarkdownFiles(obsidianDir);
+    let imported = 0;
+    let updated = 0;
+    let skipped = 0;
+    const conflicts: ConflictInfo[] = [];
+
+    for (const file of mdFiles) {
+      const content = readFileSync(file, 'utf-8');
+      const parsed = fromObsidianMarkdown(content);
+
+      if (!parsed.title || !parsed.description) {
+        skipped++;
+        continue;
+      }
+
+      // Use directory name as domain fallback
+      const relDir = dirname(relative(obsidianDir, file));
+      const domain = parsed.domain || (relDir !== '.' ? relDir : opts.defaultDomain || 'general');
+      const type = parsed.type || opts.defaultType || 'concept';
+
+      // Check if exists by ID
+      if (parsed.id) {
+        const existing = this.vault.get(parsed.id);
+        if (existing) {
+          if (!opts.dryRun) {
+            this.vault.update(parsed.id, {
+              title: parsed.title,
+              description: parsed.description,
+              domain,
+              tags: parsed.tags || [],
+            });
+          }
+          updated++;
+          continue;
+        }
+      }
+
+      // New entry
+      if (!opts.dryRun) {
+        this.vault.seed([
+          {
+            id: parsed.id || `obsidian-${titleToSlug(parsed.title)}-${Date.now()}`,
+            type: type as 'pattern' | 'anti-pattern' | 'rule',
+            domain,
+            title: parsed.title,
+            description: parsed.description,
+            severity: (parsed.severity as 'critical' | 'warning' | 'suggestion') || 'suggestion',
+            tags: parsed.tags || [],
+          },
+        ]);
+      }
+      imported++;
+    }
+
+    return { imported, updated, skipped, conflicts };
+  }
+
+  /**
+   * Bidirectional sync between vault and Obsidian directory.
+   */
+  sync(obsidianDir: string, opts: SyncOptions = {}): SyncResult {
+    const mode = opts.mode || 'bidirectional';
+
+    if (mode === 'push') {
+      const result = this.export(obsidianDir, { dryRun: opts.dryRun });
+      return { pushed: result.exported, pulled: 0, conflicts: [], mode };
+    }
+
+    if (mode === 'pull') {
+      const result = this.import(obsidianDir, { dryRun: opts.dryRun });
+      return {
+        pushed: 0,
+        pulled: result.imported + result.updated,
+        conflicts: result.conflicts,
+        mode,
+      };
+    }
+
+    // Bidirectional: export first, then import new entries
+    const exportResult = this.export(obsidianDir, { dryRun: opts.dryRun });
+    const importResult = this.import(obsidianDir, { dryRun: opts.dryRun });
+
+    return {
+      pushed: exportResult.exported,
+      pulled: importResult.imported + importResult.updated,
+      conflicts: importResult.conflicts,
+      mode,
+    };
+  }
+
+  private findMarkdownFiles(dir: string): string[] {
+    const results: string[] = [];
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          results.push(...this.findMarkdownFiles(fullPath));
+        } else if (extname(entry.name) === '.md') {
+          results.push(fullPath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or can't be read
+    }
+    return results;
+  }
+}

package/src/vault/scope-detector.ts

@@ -0,0 +1,219 @@
+/**
+ * Scope detector — classifies knowledge entries into agent/project/team tiers.
+ *
+ * Uses weighted signal heuristics from content, category, tags, and title
+ * to determine where an entry should live:
+ * - agent: personal preferences, local config, workflow habits
+ * - project: repo-specific patterns, architecture decisions, internal APIs
+ * - team: universal patterns, language best practices, design principles
+ */
+
+export type ScopeTier = 'agent' | 'project' | 'team';
+export type ConfidenceLevel = 'HIGH' | 'MEDIUM' | 'LOW';
+
+export interface ScopeSignal {
+  tier: ScopeTier;
+  source: 'content' | 'category' | 'tags' | 'title';
+  indicator: string;
+  weight: number;
+}
+
+export interface ScopeDetectionResult {
+  tier: ScopeTier;
+  confidence: ConfidenceLevel;
+  reason: string;
+  signals: ScopeSignal[];
+}
+
+export interface ScopeInput {
+  title: string;
+  description: string;
+  category?: string;
+  tags?: string[];
+}
+
+// ─── Signal patterns ─────────────────────────────────────────────────
+
+const TEAM_CONTENT_PATTERNS: Array<{ pattern: RegExp; weight: number; desc: string }> = [
+  { pattern: /accessibility|a11y|aria-|screen\s+reader/i, weight: 0.85, desc: 'accessibility' },
+  { pattern: /design\s+system|semantic\s+token/i, weight: 0.8, desc: 'design system' },
+  { pattern: /contrast\s+ratio|wcag/i, weight: 0.85, desc: 'WCAG guidelines' },
+  {
+    pattern: /clean\s+code|solid\s+principle|dry|kiss/i,
+    weight: 0.7,
+    desc: 'clean code principles',
+  },
+  { pattern: /security|xss|csrf|injection|sanitiz/i, weight: 0.75, desc: 'security patterns' },
+  { pattern: /performance|lazy\s+load|memoiz/i, weight: 0.6, desc: 'performance patterns' },
+  { pattern: /type\s+safety|type\s+guard/i, weight: 0.55, desc: 'type safety' },
+  { pattern: /error\s+handling|error\s+boundary/i, weight: 0.6, desc: 'error handling' },
+  { pattern: /touch\s+target|tap\s+target|fitts/i, weight: 0.8, desc: 'UX touch targets' },
+  { pattern: /focus\s+(ring|state|indicator)/i, weight: 0.8, desc: 'focus states' },
+  { pattern: /best\s+practice|anti.?pattern/i, weight: 0.65, desc: 'best practice' },
+];
+
+const PROJECT_CONTENT_PATTERNS: Array<{ pattern: RegExp; weight: number; desc: string }> = [
+  { pattern: /@[\w-]+\/[\w-]+/, weight: 0.9, desc: 'scoped package (@org/pkg)' },
+  { pattern: /packages\/[\w/-]+/, weight: 0.8, desc: 'monorepo path' },
+  { pattern: /src\/[\w/-]+\.(ts|js|tsx|jsx)/, weight: 0.7, desc: 'project file path' },
+  {
+    pattern: /our\s+(project|codebase|team|repo)/i,
+    weight: 0.75,
+    desc: 'project-specific language',
+  },
+  { pattern: /this\s+(project|codebase|repository)/i, weight: 0.8, desc: 'explicit project ref' },
+  { pattern: /internal\s+(api|service)/i, weight: 0.7, desc: 'internal service' },
+  { pattern: /\.config\.(ts|js|mjs)/i, weight: 0.5, desc: 'config file reference' },
+  { pattern: /localhost|127\.0\.0\.1/i, weight: 0.6, desc: 'local dev reference' },
+];
+
+const AGENT_CONTENT_PATTERNS: Array<{ pattern: RegExp; weight: number; desc: string }> = [
+  { pattern: /I\s+prefer|my\s+workflow|my\s+setup/i, weight: 0.8, desc: 'personal preference' },
+  { pattern: /~\/|\/Users\/|\/home\//i, weight: 0.7, desc: 'home directory path' },
+  { pattern: /my\s+(editor|IDE|terminal|shell)/i, weight: 0.75, desc: 'personal tooling' },
+  { pattern: /alias(es)?|shortcut/i, weight: 0.6, desc: 'personal aliases' },
+  { pattern: /habit|routine|always\s+do/i, weight: 0.55, desc: 'personal habit' },
+];
+
+const TEAM_CATEGORIES = new Set([
+  'styling',
+  'accessibility',
+  'performance',
+  'security',
+  'design',
+  'methodology',
+]);
+const PROJECT_CATEGORIES = new Set([
+  'monorepo',
+  'prisma',
+  'infrastructure',
+  'deployment',
+  'config',
+]);
+
+const TEAM_TAGS = new Set([
+  'universal',
+  'best-practice',
+  'a11y',
+  'accessibility',
+  'wcag',
+  'security',
+  'performance',
+  'clean-code',
+  'design-system',
+  'pattern',
+  'principle',
+]);
+const PROJECT_TAGS = new Set([
+  'project-specific',
+  'internal',
+  'monorepo',
+  'infrastructure',
+  'deployment',
+]);
+const AGENT_TAGS = new Set(['personal', 'preference', 'workflow', 'habit', 'local']);
+
+// ─── Analysis functions ──────────────────────────────────────────────
+
+function analyzeContent(text: string): ScopeSignal[] {
+  const signals: ScopeSignal[] = [];
+
+  for (const { pattern, weight, desc } of TEAM_CONTENT_PATTERNS) {
+    if (pattern.test(text)) {
+      signals.push({ tier: 'team', source: 'content', indicator: desc, weight });
+    }
+  }
+  for (const { pattern, weight, desc } of PROJECT_CONTENT_PATTERNS) {
+    if (pattern.test(text)) {
+      signals.push({ tier: 'project', source: 'content', indicator: desc, weight });
+    }
+  }
+  for (const { pattern, weight, desc } of AGENT_CONTENT_PATTERNS) {
+    if (pattern.test(text)) {
+      signals.push({ tier: 'agent', source: 'content', indicator: desc, weight });
+    }
+  }
+
+  return signals;
+}
+
+function analyzeCategory(category: string): ScopeSignal[] {
+  const norm = category.toLowerCase();
+  if (TEAM_CATEGORIES.has(norm)) {
+    return [{ tier: 'team', source: 'category', indicator: `category "${category}"`, weight: 0.7 }];
+  }
+  if (PROJECT_CATEGORIES.has(norm)) {
+    return [
+      { tier: 'project', source: 'category', indicator: `category "${category}"`, weight: 0.6 },
+    ];
+  }
+  return [];
+}
+
+function analyzeTags(tags: string[]): ScopeSignal[] {
+  const signals: ScopeSignal[] = [];
+  for (const tag of tags) {
+    const norm = tag.toLowerCase();
+    if (TEAM_TAGS.has(norm)) {
+      signals.push({ tier: 'team', source: 'tags', indicator: `tag "${tag}"`, weight: 0.8 });
+    } else if (PROJECT_TAGS.has(norm)) {
+      signals.push({ tier: 'project', source: 'tags', indicator: `tag "${tag}"`, weight: 0.8 });
+    } else if (AGENT_TAGS.has(norm)) {
+      signals.push({ tier: 'agent', source: 'tags', indicator: `tag "${tag}"`, weight: 0.8 });
+    }
+  }
+  return signals;
+}
+
+function computeConfidence(scores: Record<ScopeTier, number>, winner: ScopeTier): ConfidenceLevel {
+  const winScore = scores[winner];
+  const others = Object.entries(scores)
+    .filter(([t]) => t !== winner)
+    .map(([, v]) => v);
+  const runnerUp = Math.max(...others, 0);
+
+  if (winScore === 0) return 'LOW';
+  if (runnerUp === 0 && winScore >= 0.5) return 'HIGH';
+  const ratio = winScore / (winScore + runnerUp);
+  if (ratio >= 0.7 && winScore >= 1.0) return 'HIGH';
+  if (ratio >= 0.55) return 'MEDIUM';
+  return 'LOW';
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+export function detectScope(input: ScopeInput): ScopeDetectionResult {
+  const signals: ScopeSignal[] = [];
+  const fullText = `${input.title} ${input.description}`;
+
+  signals.push(...analyzeContent(fullText));
+  if (input.category) signals.push(...analyzeCategory(input.category));
+  if (input.tags?.length) signals.push(...analyzeTags(input.tags));
+
+  const scores: Record<ScopeTier, number> = { agent: 0, project: 0, team: 0 };
+  for (const s of signals) {
+    scores[s.tier] += s.weight;
+  }
+
+  // Default to agent when no signals
+  let winner: ScopeTier = 'agent';
+  let maxScore = 0;
+  for (const [tier, score] of Object.entries(scores) as Array<[ScopeTier, number]>) {
+    if (score > maxScore) {
+      maxScore = score;
+      winner = tier;
+    }
+  }
+
+  const confidence = computeConfidence(scores, winner);
+  const topSignals = signals
+    .filter((s) => s.tier === winner)
+    .sort((a, b) => b.weight - a.weight)
+    .slice(0, 3);
+  const reason =
+    topSignals.length > 0
+      ? topSignals.map((s) => s.indicator).join('; ')
+      : 'No clear signals — defaulting to agent tier';
+
+  return { tier: winner, confidence, reason, signals };
+}