@cleocode/core 2.0.0

package/src/admin/sync.ts

@@ -0,0 +1,164 @@
+/**
+ * Admin Sync Operations
+ *
+ * Core functions for sync state management used by dispatch layer.
+ *
+ * @task T5326
+ * @epic T5323
+ */
+
+import { rm, rmdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readJson } from '../store/json.js';
+import { getCleoDir } from '../paths.js';
+
+/** Sync session state stored in .cleo/sync/todowrite-session.json. */
+interface SyncSessionState {
+  session_id: string;
+  injected_at: string;
+  injectedPhase?: string;
+  injected_tasks: string[];
+  task_metadata?: Record<string, { phase?: string }>;
+}
+
+/** Result for sync status operation. */
+export interface SyncStatusResult {
+  active: boolean;
+  sessionId?: string;
+  injectedAt?: string;
+  injectedPhase?: string;
+  taskCount?: number;
+  taskIds?: string[];
+  phases?: Array<{ phase: string; count: number }>;
+  stateFile: string;
+}
+
+/** Result for sync clear operation. */
+export interface SyncClearResult {
+  cleared?: { stateFile: string };
+  dryRun?: boolean;
+  wouldDelete?: { stateFile: string; syncDirectory: string };
+  noChange?: boolean;
+}
+
+/**
+ * Get current sync status.
+ * @task T5326
+ */
+export async function getSyncStatus(projectRoot: string): Promise<{
+  success: boolean;
+  data?: SyncStatusResult;
+  error?: { code: string; message: string };
+}> {
+  try {
+    const cleoDir = getCleoDir(projectRoot);
+    const stateFile = join(cleoDir, 'sync', 'todowrite-session.json');
+    const sessionState = await readJson<SyncSessionState>(stateFile);
+
+    if (!sessionState) {
+      return {
+        success: true,
+        data: {
+          active: false,
+          stateFile,
+        },
+      };
+    }
+
+    // Build phase distribution from metadata
+    let phases: Array<{ phase: string; count: number }> | undefined;
+    if (sessionState.task_metadata) {
+      const phaseMap = new Map<string, number>();
+      for (const meta of Object.values(sessionState.task_metadata)) {
+        const phase = meta.phase ?? 'unknown';
+        phaseMap.set(phase, (phaseMap.get(phase) ?? 0) + 1);
+      }
+      phases = [...phaseMap.entries()].map(([phase, count]) => ({ phase, count }));
+    }
+
+    return {
+      success: true,
+      data: {
+        active: true,
+        sessionId: sessionState.session_id,
+        injectedAt: sessionState.injected_at,
+        injectedPhase: sessionState.injectedPhase ?? 'none',
+        taskCount: sessionState.injected_tasks.length,
+        taskIds: sessionState.injected_tasks,
+        phases,
+        stateFile,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      error: { code: 'E_SYNC_STATUS_FAILED', message },
+    };
+  }
+}
+
+/**
+ * Clear sync state.
+ * @task T5326
+ */
+export async function clearSyncState(
+  projectRoot: string,
+  dryRun?: boolean,
+): Promise<{
+  success: boolean;
+  data?: SyncClearResult;
+  error?: { code: string; message: string };
+}> {
+  try {
+    const cleoDir = getCleoDir(projectRoot);
+    const syncDir = join(cleoDir, 'sync');
+    const stateFile = join(syncDir, 'todowrite-session.json');
+
+    let exists = false;
+    try {
+      await stat(stateFile);
+      exists = true;
+    } catch {
+      // File doesn't exist
+    }
+
+    if (!exists) {
+      return {
+        success: true,
+        data: { noChange: true },
+      };
+    }
+
+    if (dryRun) {
+      return {
+        success: true,
+        data: {
+          dryRun: true,
+          wouldDelete: { stateFile, syncDirectory: syncDir },
+        },
+      };
+    }
+
+    await rm(stateFile, { force: true });
+    // Clean up empty sync directory
+    try {
+      await rmdir(syncDir);
+    } catch {
+      // not empty or doesn't exist
+    }
+
+    return {
+      success: true,
+      data: {
+        cleared: { stateFile },
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      error: { code: 'E_SYNC_CLEAR_FAILED', message },
+    };
+  }
+}

package/src/adrs/find.ts

@@ -0,0 +1,157 @@
+/**
+ * ADR Cognitive Search (T4942)
+ *
+ * In-memory fuzzy search across ADR title, summary, keywords, and topics.
+ * Chosen over SQLite FTS5 because the ADR set is small (<50) and in-memory
+ * search avoids the complexity of FTS5 virtual table DDL and drizzle integration.
+ *
+ * Scoring (higher = better match):
+ *   40 — keyword tag exact match
+ *   30 — topics tag exact match
+ *   20 — title contains query term
+ *   10 — summary contains query term
+ *    5 — id contains query term
+ *
+ * @task T4942
+ * @see ADR-017 §5.4 for cognitive search spec
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseAdrFile } from './parse.js';
+import type { AdrFindResult } from './types.js';
+
+/** Normalise a string for comparison: lowercase, strip punctuation */
+function normalise(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Split a comma-separated tag string into normalised tokens */
+function parseTags(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((t) => normalise(t))
+    .filter(Boolean);
+}
+
+/** Return true if any query term is found in the target string */
+function containsAny(target: string, terms: string[]): boolean {
+  const t = normalise(target);
+  return terms.some((term) => t.includes(term));
+}
+
+/** Return matched query terms found in the target */
+function matchedTerms(target: string, terms: string[]): string[] {
+  const t = normalise(target);
+  return terms.filter((term) => t.includes(term));
+}
+
+export async function findAdrs(
+  projectRoot: string,
+  query: string,
+  opts?: { topics?: string; keywords?: string; status?: string },
+): Promise<AdrFindResult> {
+  const adrsDir = join(projectRoot, '.cleo', 'adrs');
+
+  if (!existsSync(adrsDir)) {
+    return { adrs: [], query, total: 0 };
+  }
+
+  const files = readdirSync(adrsDir)
+    .filter((f) => f.endsWith('.md') && f.startsWith('ADR-'))
+    .sort();
+
+  const queryTerms = normalise(query)
+    .split(' ')
+    .filter((t) => t.length > 1);
+  const filterTopics = opts?.topics ? parseTags(opts.topics) : null;
+  const filterKeywords = opts?.keywords ? parseTags(opts.keywords) : null;
+
+  const results: AdrFindResult['adrs'] = [];
+
+  for (const file of files) {
+    const record = parseAdrFile(join(adrsDir, file), projectRoot);
+    const fm = record.frontmatter;
+
+    // Status filter
+    if (opts?.status && fm.Status !== opts.status) continue;
+
+    // Topics filter (hard filter — must match all specified topics)
+    if (filterTopics && filterTopics.length > 0) {
+      const adrTopics = parseTags(fm.Topics);
+      if (!filterTopics.every((t) => adrTopics.includes(t))) continue;
+    }
+
+    // Keywords filter (hard filter — must match all specified keywords)
+    if (filterKeywords && filterKeywords.length > 0) {
+      const adrKeywords = parseTags(fm.Keywords);
+      if (!filterKeywords.every((k) => adrKeywords.includes(k))) continue;
+    }
+
+    // Scoring
+    let score = 0;
+    const matchedFields: string[] = [];
+
+    if (queryTerms.length > 0) {
+      // Keywords exact match (highest signal)
+      const adrKeywords = parseTags(fm.Keywords);
+      const kwMatches = queryTerms.filter((term) => adrKeywords.some((kw) => kw.includes(term)));
+      if (kwMatches.length > 0) {
+        score += 40 * kwMatches.length;
+        matchedFields.push('keywords');
+      }
+
+      // Topics match
+      const adrTopics = parseTags(fm.Topics);
+      const topicMatches = queryTerms.filter((term) => adrTopics.some((tp) => tp.includes(term)));
+      if (topicMatches.length > 0) {
+        score += 30 * topicMatches.length;
+        matchedFields.push('topics');
+      }
+
+      // Title contains
+      if (containsAny(record.title, queryTerms)) {
+        score += 20 * matchedTerms(record.title, queryTerms).length;
+        matchedFields.push('title');
+      }
+
+      // Summary contains
+      if (fm.Summary && containsAny(fm.Summary, queryTerms)) {
+        score += 10 * matchedTerms(fm.Summary, queryTerms).length;
+        matchedFields.push('summary');
+      }
+
+      // ID contains (e.g. "ADR-017")
+      if (containsAny(record.id, queryTerms)) {
+        score += 5;
+        matchedFields.push('id');
+      }
+
+      // Skip if no match and a query was provided
+      if (score === 0) continue;
+    }
+
+    results.push({
+      id: record.id,
+      title: record.title,
+      status: fm.Status,
+      date: fm.Date,
+      filePath: record.file,
+      summary: fm.Summary,
+      keywords: fm.Keywords,
+      topics: fm.Topics,
+      score,
+      matchedFields: [...new Set(matchedFields)],
+    });
+  }
+
+  // Sort by score descending, then by ADR ID ascending for ties
+  results.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+
+  return { adrs: results, query, total: results.length };
+}

package/src/adrs/index.ts

@@ -0,0 +1,24 @@
+/**
+ * ADR Core Module (ADR-017)
+ *
+ * Barrel export for ADR operations.
+ *
+ * @task T4792
+ */
+
+export { findAdrs } from './find.js';
+export type { PipelineAdrLinkResult } from './link-pipeline.js';
+export { linkPipelineAdr } from './link-pipeline.js';
+export { listAdrs } from './list.js';
+export { extractAdrId, extractTitle, parseAdrFile, parseFrontmatter } from './parse.js';
+export { showAdr } from './show.js';
+export { syncAdrsToDb } from './sync.js';
+export type {
+  AdrFindResult,
+  AdrFrontmatter,
+  AdrListResult,
+  AdrRecord,
+  AdrSyncResult,
+} from './types.js';
+export type { AdrValidationError, AdrValidationResult } from './validate.js';
+export { validateAllAdrs } from './validate.js';

package/src/adrs/link-pipeline.ts

@@ -0,0 +1,181 @@
+/**
+ * RCASD Pipeline ADR Auto-linking (T4942, T4947)
+ *
+ * When an architecture_decision stage completes for a pipeline task, this
+ * module automatically:
+ *   1. Finds ADRs in .cleo/adrs/ that reference the task in Related Tasks
+ *   2. Upserts those ADRs into architecture_decisions DB
+ *   3. Creates adr_task_links with link_type='implements'
+ *   4. Links related ADRs via adr_relations if cross-references exist
+ *
+ * Called from lifecycle/pipeline.ts when advancing FROM architecture_decision.
+ *
+ * @task T4947
+ * @see ADR-017 §5.3 for adr_task_links and adr_relations schemas
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { adrRelations, adrTaskLinks, architectureDecisions } from '../store/tasks-schema.js';
+import { parseAdrFile } from './parse.js';
+
+export interface PipelineAdrLinkResult {
+  linked: Array<{ adrId: string; taskId: string }>;
+  synced: number;
+  skipped: number;
+  errors: Array<{ file: string; error: string }>;
+}
+
+/**
+ * Parse comma-separated task IDs from a Related Tasks value
+ */
+function parseTaskIds(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((t) => t.trim())
+    .filter((t) => /^T\d{1,5}$/.test(t));
+}
+
+/**
+ * Scan .cleo/adrs/ for ADRs that reference the given taskId in Related Tasks.
+ * Returns file paths of matching ADRs.
+ */
+function findAdrsForTask(adrsDir: string, taskId: string): string[] {
+  if (!existsSync(adrsDir)) return [];
+
+  return readdirSync(adrsDir)
+    .filter((f) => f.endsWith('.md') && /^ADR-\d+/.test(f))
+    .filter((file) => {
+      try {
+        const content = readFileSync(join(adrsDir, file), 'utf-8');
+        // Quick check before parsing — look for task ID in Related Tasks line
+        const relatedTasksMatch = content.match(/^\*\*Related Tasks\*\*:\s*(.+)$/m);
+        if (!relatedTasksMatch) return false;
+        const taskIds = parseTaskIds(relatedTasksMatch[1]);
+        return taskIds.includes(taskId);
+      } catch {
+        return false;
+      }
+    })
+    .map((f) => join(adrsDir, f));
+}
+
+/**
+ * Link ADRs to a pipeline task when the architecture_decision stage completes.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param taskId      - Task ID that owns the pipeline (e.g., 'T4942')
+ */
+export async function linkPipelineAdr(
+  projectRoot: string,
+  taskId: string,
+): Promise<PipelineAdrLinkResult> {
+  const result: PipelineAdrLinkResult = {
+    linked: [],
+    synced: 0,
+    skipped: 0,
+    errors: [],
+  };
+
+  const adrsDir = join(projectRoot, '.cleo', 'adrs');
+  const matchingFiles = findAdrsForTask(adrsDir, taskId);
+
+  if (matchingFiles.length === 0) {
+    return result;
+  }
+
+  const { getDb } = await import('../store/sqlite.js');
+  const { and, eq } = await import('drizzle-orm');
+  const db = await getDb(projectRoot);
+  const now = new Date().toISOString();
+
+  for (const filePath of matchingFiles) {
+    const filename = filePath.split('/').pop()!;
+    try {
+      const record = parseAdrFile(filePath, projectRoot);
+      const fm = record.frontmatter;
+      const content = readFileSync(filePath, 'utf-8');
+      const relativePath = `.cleo/adrs/${filename}`;
+
+      // Upsert ADR row
+      const existing = await db
+        .select({ id: architectureDecisions.id })
+        .from(architectureDecisions)
+        .where(eq(architectureDecisions.id, record.id))
+        .all();
+
+      const rowBase = {
+        id: record.id,
+        title: record.title,
+        status: (fm.Status ?? 'proposed') as 'proposed' | 'accepted' | 'superseded' | 'deprecated',
+        content,
+        filePath: relativePath,
+        date: fm.Date ?? '',
+        acceptedAt: fm.Accepted ?? null,
+        gate: (fm.Gate ?? null) as 'HITL' | 'automated' | null,
+        gateStatus: (fm['Gate Status'] ?? null) as 'pending' | 'passed' | 'waived' | null,
+        amendsId: null as string | null,
+        supersedesId: null as string | null,
+        supersededById: null as string | null,
+        summary: fm.Summary ?? null,
+        keywords: fm.Keywords ?? null,
+        topics: fm.Topics ?? null,
+        updatedAt: now,
+      };
+
+      if (existing.length > 0) {
+        await db
+          .update(architectureDecisions)
+          .set(rowBase)
+          .where(eq(architectureDecisions.id, record.id));
+      } else {
+        await db.insert(architectureDecisions).values({ ...rowBase, createdAt: now });
+      }
+      result.synced++;
+
+      // Create implements link (upsert: delete existing, insert new)
+      // First remove any existing link between this ADR and task
+      await db
+        .delete(adrTaskLinks)
+        .where(and(eq(adrTaskLinks.adrId, record.id), eq(adrTaskLinks.taskId, taskId)));
+
+      await db.insert(adrTaskLinks).values({ adrId: record.id, taskId, linkType: 'implements' });
+
+      result.linked.push({ adrId: record.id, taskId });
+
+      // Cross-reference: if ADR references other ADRs via Related ADRs, create adr_relations
+      if (fm['Related ADRs']) {
+        const relatedIds = fm['Related ADRs']
+          .split(',')
+          .map((r) => r.trim())
+          .filter((r) => /^ADR-\d+$/.test(r));
+
+        for (const toId of relatedIds) {
+          try {
+            // Only create relation if target ADR exists in DB
+            const targetExists = await db
+              .select({ id: architectureDecisions.id })
+              .from(architectureDecisions)
+              .where(eq(architectureDecisions.id, toId))
+              .all();
+
+            if (targetExists.length > 0) {
+              await db
+                .insert(adrRelations)
+                .values({ fromAdrId: record.id, toAdrId: toId, relationType: 'related' })
+                .onConflictDoNothing();
+            }
+          } catch {
+            // Ignore relation errors — non-fatal
+          }
+        }
+      }
+    } catch (err) {
+      result.errors.push({ file: filename, error: String(err) });
+      result.skipped++;
+    }
+  }
+
+  return result;
+}

package/src/adrs/list.ts

@@ -0,0 +1,51 @@
+/**
+ * ADR List Operation (ADR-017)
+ *
+ * Lists ADR records from .cleo/adrs/ with optional filtering.
+ *
+ * @task T4792
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { paginate } from '../pagination.js';
+import { parseAdrFile } from './parse.js';
+import type { AdrListResult } from './types.js';
+
+/** List ADRs from .cleo/adrs/ directory with optional status filter */
+export async function listAdrs(
+  projectRoot: string,
+  opts?: { status?: string; since?: string; limit?: number; offset?: number },
+): Promise<AdrListResult> {
+  const adrsDir = join(projectRoot, '.cleo', 'adrs');
+
+  if (!existsSync(adrsDir)) {
+    return { adrs: [], total: 0, filtered: 0 };
+  }
+
+  const files = readdirSync(adrsDir)
+    .filter((f) => f.endsWith('.md') && f.startsWith('ADR-'))
+    .sort();
+
+  const records = files.map((f) => parseAdrFile(join(adrsDir, f), projectRoot));
+
+  const total = records.length;
+  const filtered = records.filter((r) => {
+    if (opts?.status && r.frontmatter.Status !== opts.status) return false;
+    if (opts?.since && r.frontmatter.Date < opts.since) return false;
+    return true;
+  });
+  const page = paginate(filtered, opts?.limit, opts?.offset);
+
+  return {
+    adrs: page.items.map((r) => ({
+      id: r.id,
+      title: r.title,
+      status: r.frontmatter.Status,
+      date: r.frontmatter.Date,
+      filePath: r.file,
+    })),
+    total,
+    filtered: filtered.length,
+  };
+}

package/src/adrs/parse.ts

@@ -0,0 +1,58 @@
+/**
+ * ADR Frontmatter Parser (ADR-017)
+ *
+ * Parses bold-key frontmatter from ADR markdown files.
+ * Pattern: **Key**: value
+ *
+ * @task T4792
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AdrFrontmatter, AdrRecord } from './types.js';
+
+/** Extract ADR ID from filename (e.g., 'ADR-007-domain-consolidation.md' -> 'ADR-007') */
+export function extractAdrId(filename: string): string {
+  const match = filename.match(/^(ADR-\d+)/);
+  return match ? match[1]! : filename.replace('.md', '');
+}
+
+/** Parse bold-key frontmatter pattern: **Key**: value */
+export function parseFrontmatter(content: string): AdrFrontmatter {
+  const entries: Array<[string, string]> = [];
+  const lines = content.split('\n');
+
+  // Parse lines until first --- separator (skip H1 title)
+  for (const line of lines) {
+    if (line.trim() === '---') break;
+    const match = line.match(/^\*\*([^*]+)\*\*:\s*(.+)$/);
+    if (match) {
+      entries.push([match[1]!.trim(), match[2]!.trim()]);
+    }
+  }
+
+  // The parsed key-value pairs are structurally an AdrFrontmatter at runtime.
+  // Use Partial first (overlap) then assert the full type.
+  const partial: Partial<AdrFrontmatter> = Object.fromEntries(entries);
+  return partial as AdrFrontmatter;
+}
+
+/** Extract H1 title from markdown */
+export function extractTitle(content: string): string {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1]!.trim() : 'Untitled';
+}
+
+/** Parse a single ADR markdown file into an AdrRecord */
+export function parseAdrFile(filePath: string, projectRoot: string): AdrRecord {
+  const absolutePath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+  const content = readFileSync(absolutePath, 'utf-8');
+  const filename = filePath.split('/').pop()!;
+
+  return {
+    id: extractAdrId(filename),
+    file: filePath,
+    title: extractTitle(content),
+    frontmatter: parseFrontmatter(content),
+  };
+}

package/src/adrs/show.ts

@@ -0,0 +1,25 @@
+/**
+ * ADR Show Operation (ADR-017)
+ *
+ * Retrieves a single ADR record by ID.
+ *
+ * @task T4792
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseAdrFile } from './parse.js';
+import type { AdrRecord } from './types.js';
+
+/** Retrieve a single ADR by ID (e.g., 'ADR-007') */
+export async function showAdr(projectRoot: string, adrId: string): Promise<AdrRecord | null> {
+  const adrsDir = join(projectRoot, '.cleo', 'adrs');
+
+  if (!existsSync(adrsDir)) return null;
+
+  const files = readdirSync(adrsDir).filter((f) => f.startsWith(adrId) && f.endsWith('.md'));
+  if (files.length === 0) return null;
+
+  const filePath = join(adrsDir, files[0]!);
+  return parseAdrFile(filePath, projectRoot);
+}