cognitive-core 0.2.4 → 0.3.1

package/src/memory/source-resolver.ts

@@ -1,422 +0,0 @@
-/**
- * Source Resolver — Normalizes playbook sources (local paths, git URLs, shorthands)
- * into local directory paths for the curated loader.
- *
- * Supports:
- * - Local filesystem paths (pass-through)
- * - Git URLs: "git:https://github.com/org/repo" or "git:https://github.com/org/repo#ref"
- * - GitHub shorthand: "github:org/repo" or "github:org/repo#ref"
- *
- * Cloned repos are cached in a configurable directory (default: .atlas/curated-cache/).
- * Cache freshness is controlled by maxAgeMs. Stale caches are refreshed on next resolve.
- */
-
-import { execFile as execFileCb } from 'node:child_process';
-import { existsSync, statSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { mkdir, readFile, readdir } from 'node:fs/promises';
-import { promisify } from 'node:util';
-
-const execFile = promisify(execFileCb);
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Parsed git source components
- */
-export interface ParsedGitSource {
-  url: string;
-  ref?: string;
-  cacheKey: string;
-}
-
-/**
- * Manifest file (cognitive-core.json) at repo root
- */
-export interface PlaybookManifest {
-  /** Relative path to playbook directory within the repo */
-  playbooks: string;
-  /** Optional version label */
-  version?: string;
-  /** Optional display name */
-  name?: string;
-  /** Optional description */
-  description?: string;
-}
-
-/**
- * State persisted per resolved source (stored in system_state)
- */
-export interface SourceState {
-  /** Original config source string */
-  source: string;
-  /** Resolved git URL (empty for local paths) */
-  url: string;
-  /** Requested ref (branch/tag/commit) */
-  ref: string;
-  /** Actual commit SHA loaded */
-  commitSha: string;
-  /** Local cache path */
-  cachePath: string;
-  /** Discovered playbook directory within cache */
-  playbookDir: string;
-  /** ISO timestamp of last successful load */
-  loadedAt: string;
-  /** Number of playbooks loaded from this source */
-  playbookCount: number;
-}
-
-/**
- * Result of resolving a source
- */
-export interface ResolveResult {
-  /** Local directory path containing playbook JSON files */
-  playbookDir: string;
-  /** Whether this is a git source */
-  isGit: boolean;
-  /** Commit SHA (only for git sources) */
-  commitSha?: string;
-  /** Whether the source was freshly cloned/updated */
-  updated: boolean;
-  /** Source identifier for provenance tracking */
-  sourceId: string;
-}
-
-/**
- * Options for source resolution
- */
-export interface ResolveOptions {
-  /** Cache directory (default: .atlas/curated-cache) */
-  cacheDir: string;
-  /** Maximum cache age in milliseconds before refreshing (default: 24h) */
-  maxAgeMs: number;
-  /** Force update regardless of cache age */
-  forceUpdate?: boolean;
-  /** Callback for loading/saving source state */
-  getSourceState?: (source: string) => SourceState | undefined;
-  setSourceState?: (source: string, state: SourceState) => void;
-}
-
-// ============================================================================
-// Public API
-// ============================================================================
-
-/**
- * Check if a source string is a git source (not a local path).
- */
-export function isGitSource(source: string): boolean {
-  return (
-    source.startsWith('git:') ||
-    source.startsWith('github:') ||
-    source.startsWith('git@') ||
-    source.startsWith('git+')
-  );
-}
-
-/**
- * Parse a git source string into URL and optional ref components.
- *
- * Supported formats:
- * - "git:https://github.com/org/repo"
- * - "git:https://github.com/org/repo#v1.0.0"
- * - "github:org/repo"
- * - "github:org/repo#branch"
- */
-export function parseGitSource(source: string): ParsedGitSource {
-  let raw = source;
-
-  // Strip prefix
-  if (raw.startsWith('git:')) {
-    raw = raw.slice(4);
-  } else if (raw.startsWith('git+')) {
-    raw = raw.slice(4);
-  } else if (raw.startsWith('github:')) {
-    const rest = raw.slice(7); // "org/repo" or "org/repo#ref"
-    const [path, ref] = rest.split('#', 2);
-    const url = `https://github.com/${path}.git`;
-    const cacheKey = `github.com/${path}`;
-    return { url, ref, cacheKey };
-  }
-
-  // Parse ref from fragment
-  const hashIdx = raw.indexOf('#');
-  let url: string;
-  let ref: string | undefined;
-
-  if (hashIdx !== -1) {
-    url = raw.slice(0, hashIdx);
-    ref = raw.slice(hashIdx + 1);
-  } else {
-    url = raw;
-  }
-
-  // Ensure .git suffix for HTTPS URLs
-  if (url.startsWith('https://') && !url.endsWith('.git')) {
-    url += '.git';
-  }
-
-  // Build cache key from URL (strip protocol + .git suffix)
-  const cacheKey = url
-    .replace(/^https?:\/\//, '')
-    .replace(/\.git$/, '');
-
-  return { url, ref, cacheKey };
-}
-
-/**
- * Resolve a playbook source to a local directory path.
- *
- * For local paths, returns the path as-is (after verifying it exists).
- * For git sources, clones/updates to a cache directory and discovers
- * the playbook directory within the repo.
- */
-export async function resolvePlaybookSource(
-  source: string,
-  options: ResolveOptions,
-): Promise<ResolveResult | null> {
-  // Local path — pass through
-  if (!isGitSource(source)) {
-    if (!existsSync(source)) {
-      console.warn(`[source-resolver] Local path does not exist: ${source}`);
-      return null;
-    }
-    return {
-      playbookDir: source,
-      isGit: false,
-      updated: false,
-      sourceId: source,
-    };
-  }
-
-  // Git source — parse, clone/update, discover
-  const parsed = parseGitSource(source);
-  const cachePath = join(options.cacheDir, parsed.cacheKey);
-
-  try {
-    // Ensure cache parent dir exists
-    await mkdir(cachePath, { recursive: true });
-
-    const isCloned = existsSync(join(cachePath, '.git'));
-
-    if (!isCloned) {
-      // First-time clone
-      await gitClone(parsed.url, parsed.ref, cachePath);
-    } else if (shouldUpdate(source, options)) {
-      // Update existing cache
-      await gitUpdate(parsed.ref, cachePath);
-    }
-
-    // Get current commit SHA
-    const commitSha = await gitRevParse(cachePath);
-
-    // Check if we already loaded this exact SHA
-    const prevState = options.getSourceState?.(source);
-    if (prevState && prevState.commitSha === commitSha && !options.forceUpdate) {
-      return {
-        playbookDir: prevState.playbookDir,
-        isGit: true,
-        commitSha,
-        updated: false,
-        sourceId: source,
-      };
-    }
-
-    // Discover playbook directory
-    const playbookDir = await discoverPlaybookDir(cachePath);
-    if (!playbookDir) {
-      console.warn(`[source-resolver] No playbook directory found in ${source}`);
-      return null;
-    }
-
-    // Persist source state
-    const state: SourceState = {
-      source,
-      url: parsed.url,
-      ref: parsed.ref ?? '',
-      commitSha,
-      cachePath,
-      playbookDir,
-      loadedAt: new Date().toISOString(),
-      playbookCount: 0, // Updated by caller after loading
-    };
-    options.setSourceState?.(source, state);
-
-    return {
-      playbookDir,
-      isGit: true,
-      commitSha,
-      updated: true,
-      sourceId: source,
-    };
-  } catch (error) {
-    // If we have a cached version, use it despite the error
-    if (existsSync(join(cachePath, '.git'))) {
-      console.warn(
-        `[source-resolver] Failed to update ${source}, using cached version:`,
-        error instanceof Error ? error.message : String(error),
-      );
-      const prevState = options.getSourceState?.(source);
-      if (prevState) {
-        return {
-          playbookDir: prevState.playbookDir,
-          isGit: true,
-          commitSha: prevState.commitSha,
-          updated: false,
-          sourceId: source,
-        };
-      }
-      // Try to discover even without state
-      const playbookDir = await discoverPlaybookDir(cachePath);
-      if (playbookDir) {
-        return {
-          playbookDir,
-          isGit: true,
-          updated: false,
-          sourceId: source,
-        };
-      }
-    }
-
-    console.warn(
-      `[source-resolver] Failed to resolve ${source}, skipping:`,
-      error instanceof Error ? error.message : String(error),
-    );
-    return null;
-  }
-}
-
-// ============================================================================
-// Git operations
-// ============================================================================
-
-async function gitClone(url: string, ref: string | undefined, dest: string): Promise<void> {
-  // Remove the directory first since mkdir already created it
-  rmSync(dest, { recursive: true, force: true });
-
-  const args = ['clone', '--depth', '1', '--single-branch'];
-  if (ref) {
-    args.push('--branch', ref);
-  }
-  args.push(url, dest);
-
-  await execFile('git', args, { timeout: 60_000 });
-}
-
-async function gitUpdate(ref: string | undefined, cachePath: string): Promise<void> {
-  const fetchArgs = ['fetch', 'origin'];
-  if (ref) {
-    fetchArgs.push(ref);
-  }
-  await execFile('git', fetchArgs, { cwd: cachePath, timeout: 30_000 });
-
-  // Always use FETCH_HEAD — works for branches, tags, and commits.
-  // Using origin/${ref} would break for tags (refs/tags/*, not refs/remotes/origin/*).
-  await execFile('git', ['reset', '--hard', 'FETCH_HEAD'], {
-    cwd: cachePath,
-    timeout: 10_000,
-  });
-}
-
-async function gitRevParse(cachePath: string): Promise<string> {
-  const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
-    cwd: cachePath,
-    timeout: 5_000,
-  });
-  return stdout.trim();
-}
-
-// ============================================================================
-// Playbook directory discovery
-// ============================================================================
-
-/**
- * Discover the playbook directory within a cloned repo.
- *
- * Search order:
- * 1. Manifest file (cognitive-core.json) at repo root
- * 2. Convention: playbooks/ directory
- * 3. Convention: curated-playbooks/ directory
- * 4. Root directory if it contains .json files matching schema
- */
-export async function discoverPlaybookDir(repoRoot: string): Promise<string | null> {
-  // 1. Check for manifest
-  const manifestPath = join(repoRoot, 'cognitive-core.json');
-  if (existsSync(manifestPath)) {
-    try {
-      const content = await readFile(manifestPath, 'utf-8');
-      const manifest = JSON.parse(content) as PlaybookManifest;
-      if (manifest.playbooks) {
-        const dir = join(repoRoot, manifest.playbooks);
-        if (existsSync(dir)) {
-          return dir;
-        }
-      }
-    } catch {
-      // Invalid manifest, fall through to convention
-    }
-  }
-
-  // 2. Convention: playbooks/
-  const playbooksDir = join(repoRoot, 'playbooks');
-  if (existsSync(playbooksDir) && statSync(playbooksDir).isDirectory()) {
-    return playbooksDir;
-  }
-
-  // 3. Convention: curated-playbooks/
-  const curatedDir = join(repoRoot, 'curated-playbooks');
-  if (existsSync(curatedDir) && statSync(curatedDir).isDirectory()) {
-    return curatedDir;
-  }
-
-  // 4. Check if root has JSON files that look like playbooks
-  if (await hasPlaybookJsonFiles(repoRoot)) {
-    return repoRoot;
-  }
-
-  return null;
-}
-
-/**
- * Check if a directory contains at least one JSON file that looks like a playbook.
- */
-async function hasPlaybookJsonFiles(dir: string): Promise<boolean> {
-  try {
-    const files = await readdir(dir);
-    const jsonFiles = files.filter(f => f.endsWith('.json'));
-    if (jsonFiles.length === 0) return false;
-
-    // Check first JSON file for required playbook fields
-    const content = await readFile(join(dir, jsonFiles[0]), 'utf-8');
-    const parsed = JSON.parse(content);
-    return !!(parsed.name && parsed.applicability && parsed.guidance);
-  } catch {
-    return false;
-  }
-}
-
-// ============================================================================
-// Cache management
-// ============================================================================
-
-/**
- * Determine whether a cached source should be updated.
- */
-function shouldUpdate(source: string, options: ResolveOptions): boolean {
-  if (options.forceUpdate) return true;
-
-  const state = options.getSourceState?.(source);
-  if (!state) return true; // No previous state, always update
-
-  const loadedAt = new Date(state.loadedAt).getTime();
-  const age = Date.now() - loadedAt;
-  return age > options.maxAgeMs;
-}
-
-/**
- * Generate the system_state key for a source.
- */
-export function sourceStateKey(source: string): string {
-  return `curated-source:${source}`;
-}