anvil-dev-framework 0.1.6

package/global/tools/anvil-memory/src/__tests__/test-utils.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared test utilities for Anvil Memory tests
+ *
+ * Provides common helpers for database cleanup, path generation,
+ * and timing measurements used across all test files.
+ */
+
+import { unlinkSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+/**
+ * Base directory for all test databases.
+ * Uses system temp directory to avoid polluting the project.
+ */
+export const TEST_DB_BASE_DIR = join(tmpdir(), 'anvil-memory-tests');
+
+/**
+ * Generates a unique test database path with timestamp and random suffix.
+ * Ensures test isolation by preventing path collisions.
+ *
+ * @param prefix - Optional prefix for the database filename (default: 'test')
+ * @returns Absolute path to a unique test database file
+ */
+export function getTestDbPath(prefix = 'test'): string {
+  return join(
+    TEST_DB_BASE_DIR,
+    `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}.db`
+  );
+}
+
+/**
+ * Ensures the test database directory exists.
+ * Should be called in beforeAll hooks.
+ */
+export function ensureTestDir(): void {
+  if (!existsSync(TEST_DB_BASE_DIR)) {
+    mkdirSync(TEST_DB_BASE_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Cleans up a SQLite database and its associated WAL/SHM files.
+ * Silently ignores errors if files don't exist or can't be deleted.
+ *
+ * @param path - Path to the database file to clean up
+ */
+export function cleanupDb(path: string): void {
+  try {
+    if (existsSync(path)) unlinkSync(path);
+    if (existsSync(`${path}-wal`)) unlinkSync(`${path}-wal`);
+    if (existsSync(`${path}-shm`)) unlinkSync(`${path}-shm`);
+  } catch {
+    // Ignore cleanup errors - files may already be deleted or locked
+  }
+}
+
+/**
+ * Measures the execution time of a synchronous function.
+ *
+ * @param fn - Function to measure
+ * @returns Object containing the function result and execution time in milliseconds
+ */
+export function measureTime<T>(fn: () => T): { result: T; timeMs: number } {
+  const start = performance.now();
+  const result = fn();
+  const timeMs = performance.now() - start;
+  return { result, timeMs };
+}
+
+/**
+ * Valid observation types for test data generation.
+ */
+export const OBSERVATION_TYPES = [
+  'bugfix',
+  'feature',
+  'refactor',
+  'discovery',
+  'decision',
+  'change',
+  'checkpoint',
+  'ralph_iteration',
+  'handoff',
+  'shard',
+  'linear_sync',
+  'session_request',
+] as const;
+
+/**
+ * Returns a random observation type for test data generation.
+ */
+export function randomType(): (typeof OBSERVATION_TYPES)[number] {
+  return OBSERVATION_TYPES[Math.floor(Math.random() * OBSERVATION_TYPES.length)]!;
+}
+
+/**
+ * Generates random words for test content.
+ *
+ * @param count - Number of words to generate
+ * @returns Space-separated string of random words
+ */
+export function randomWords(count: number): string {
+  const words = [
+    'database', 'query', 'index', 'table', 'schema', 'migration',
+    'refactor', 'bugfix', 'feature', 'test', 'performance', 'memory',
+    'cache', 'session', 'observation', 'checkpoint', 'iteration',
+    'component', 'module', 'service', 'handler', 'controller',
+  ];
+  return Array.from(
+    { length: count },
+    () => words[Math.floor(Math.random() * words.length)]
+  ).join(' ');
+}

package/global/tools/anvil-memory/src/commands/checkpoint.ts

@@ -0,0 +1,197 @@
+/**
+ * checkpoint command - Record a CCS checkpoint event
+ *
+ * Usage:
+ *   anvil-memory checkpoint --level <level> --percent <percent> [options]
+ *
+ * Options:
+ *   --level <level>      Checkpoint level (L1, L2, L3) (required)
+ *   --percent <percent>  Context percentage at checkpoint (required)
+ *   --handoff <path>     Path to handoff file
+ *   --session <id>       Session ID
+ *   --task <desc>        Current task description (creates linked observation)
+ *   --progress <desc>    Progress description
+ *   --linear <issue>     Linear issue ID (e.g., ANV-123)
+ *   --path <path>        Custom database path
+ */
+
+import { parseArgs } from 'util';
+import { AnvilMemoryDb, getDefaultDbPath, dbExists } from '../db.ts';
+import type { Checkpoint, CommandResult } from '../types.ts';
+
+// Valid checkpoint levels
+const VALID_LEVELS = ['L1', 'L2', 'L3'] as const;
+type CheckpointLevel = (typeof VALID_LEVELS)[number];
+
+interface CheckpointOptions {
+  level?: string;
+  percent?: string;
+  handoff?: string;
+  session?: string;
+  task?: string;
+  progress?: string;
+  linear?: string;
+  path?: string;
+}
+
+export function parseCheckpointArgs(args: string[]): CheckpointOptions {
+  // Filter out --json which is handled by main
+  const filteredArgs = args.filter((arg) => arg !== '--json');
+
+  const { values } = parseArgs({
+    args: filteredArgs,
+    options: {
+      level: { type: 'string', short: 'l' },
+      percent: { type: 'string', short: 'p' },
+      handoff: { type: 'string', short: 'h' },
+      session: { type: 'string', short: 's' },
+      task: { type: 'string', short: 't' },
+      progress: { type: 'string' },
+      linear: { type: 'string', short: 'i' },
+      path: { type: 'string' },
+    },
+    allowPositionals: false,
+    strict: false,
+  });
+
+  return {
+    level: typeof values.level === 'string' ? values.level : undefined,
+    percent: typeof values.percent === 'string' ? values.percent : undefined,
+    handoff: typeof values.handoff === 'string' ? values.handoff : undefined,
+    session: typeof values.session === 'string' ? values.session : undefined,
+    task: typeof values.task === 'string' ? values.task : undefined,
+    progress: typeof values.progress === 'string' ? values.progress : undefined,
+    linear: typeof values.linear === 'string' ? values.linear : undefined,
+    path: typeof values.path === 'string' ? values.path : undefined,
+  };
+}
+
+export async function handleCheckpoint(args: string[]): Promise<CommandResult> {
+  const options = parseCheckpointArgs(args);
+
+  // Validate required fields
+  if (!options.level) {
+    return {
+      success: false,
+      error: 'Missing required option: --level (L1, L2, or L3)',
+    };
+  }
+
+  if (!options.percent) {
+    return {
+      success: false,
+      error: 'Missing required option: --percent',
+    };
+  }
+
+  // Validate level
+  const level = options.level.toUpperCase();
+  if (!VALID_LEVELS.includes(level as CheckpointLevel)) {
+    return {
+      success: false,
+      error: `Invalid level '${options.level}'. Valid levels: ${VALID_LEVELS.join(', ')}`,
+    };
+  }
+
+  // Validate percent
+  const percent = parseInt(options.percent, 10);
+  if (isNaN(percent) || percent < 0 || percent > 100) {
+    return {
+      success: false,
+      error: `Invalid percent '${options.percent}'. Must be 0-100.`,
+    };
+  }
+
+  // Check database exists
+  const dbPath = options.path ?? getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    return {
+      success: false,
+      error: `Database not found at ${dbPath}. Run 'anvil-memory init' first.`,
+    };
+  }
+
+  try {
+    const db = new AnvilMemoryDb(dbPath);
+
+    // Parse session_id once and validate
+    const parsedSessionId = options.session ? Number.parseInt(options.session, 10) : undefined;
+    const sessionId = parsedSessionId !== undefined && Number.isFinite(parsedSessionId)
+      ? parsedSessionId
+      : undefined;
+
+    // Use single timestamp for consistency
+    const now = new Date().toISOString();
+
+    // Create checkpoint record
+    const checkpoint = db.createCheckpoint({
+      level: level as Checkpoint['level'],
+      context_percent: percent,
+      handoff_file: options.handoff,
+      session_id: sessionId,
+      timestamp: now,
+    });
+
+    // Optionally create linked observation with task context
+    let observation = null;
+    if (options.task) {
+      const content = buildCheckpointContent(level as CheckpointLevel, percent, options);
+      observation = db.createObservation({
+        type: 'checkpoint',
+        title: `${level} Checkpoint at ${percent}%`,
+        content,
+        linear_issue: options.linear,
+        session_id: sessionId,
+        timestamp: now,
+      });
+    }
+
+    db.close();
+
+    return {
+      success: true,
+      message: `Recorded ${level} checkpoint at ${percent}%${observation ? ` with observation #${observation.id}` : ''}`,
+      data: {
+        checkpoint,
+        observation,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Build checkpoint observation content
+ */
+function buildCheckpointContent(
+  level: CheckpointLevel,
+  percent: number,
+  options: CheckpointOptions
+): string {
+  const lines: string[] = [];
+
+  lines.push(`Context checkpoint triggered at ${level} threshold (${percent}%).`);
+  lines.push('');
+
+  if (options.task) {
+    lines.push(`**Current Task**: ${options.task}`);
+  }
+
+  if (options.progress) {
+    lines.push(`**Progress**: ${options.progress}`);
+  }
+
+  if (options.handoff) {
+    lines.push(`**Handoff File**: ${options.handoff}`);
+  }
+
+  if (options.linear) {
+    lines.push(`**Linear Issue**: ${options.linear}`);
+  }
+
+  return lines.join('\n');
+}

package/global/tools/anvil-memory/src/commands/get.ts

@@ -0,0 +1,115 @@
+/**
+ * get command - Fetch observation/session/checkpoint by ID
+ *
+ * Usage:
+ *   anvil-memory get <id> [options]
+ *
+ * Options:
+ *   --type <type>  Record type: observation, session, checkpoint (default: observation)
+ */
+
+import { parseArgs } from 'util';
+import { AnvilMemoryDb, getDefaultDbPath, dbExists } from '../db.ts';
+import type { CommandResult } from '../types.ts';
+
+type RecordType = 'observation' | 'session' | 'checkpoint';
+
+interface GetOptions {
+  id: number;
+  recordType: RecordType;
+  path?: string;
+}
+
+export function parseGetArgs(args: string[]): GetOptions | { error: string } {
+  // Filter out --json which is handled by main
+  const filteredArgs = args.filter((arg) => arg !== '--json');
+
+  const { values, positionals } = parseArgs({
+    args: filteredArgs,
+    options: {
+      type: { type: 'string', short: 't' },
+      path: { type: 'string' },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  // Parse ID from positional
+  if (positionals.length === 0) {
+    return { error: 'Missing ID. Usage: anvil-memory get <id>' };
+  }
+
+  const id = parseInt(positionals[0] ?? '', 10);
+  if (isNaN(id)) {
+    return { error: `Invalid ID: ${positionals[0]}` };
+  }
+
+  // Validate record type
+  const typeVal = typeof values.type === 'string' ? values.type : 'observation';
+  const recordType = typeVal as RecordType;
+  if (!['observation', 'session', 'checkpoint'].includes(recordType)) {
+    return { error: `Invalid type '${recordType}'. Valid types: observation, session, checkpoint` };
+  }
+
+  return {
+    id,
+    recordType,
+    path: typeof values.path === 'string' ? values.path : undefined,
+  };
+}
+
+export async function handleGet(args: string[]): Promise<CommandResult> {
+  const options = parseGetArgs(args);
+
+  if ('error' in options) {
+    return {
+      success: false,
+      error: options.error,
+    };
+  }
+
+  // Check database exists
+  const dbPath = options.path ?? getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    return {
+      success: false,
+      error: `Database not found at ${dbPath}. Run 'anvil-memory init' first.`,
+    };
+  }
+
+  try {
+    const db = new AnvilMemoryDb(dbPath);
+    let result: unknown = null;
+
+    switch (options.recordType) {
+      case 'observation':
+        result = db.getObservation(options.id);
+        break;
+      case 'session':
+        result = db.getSession(options.id);
+        break;
+      case 'checkpoint':
+        result = db.getCheckpoint(options.id);
+        break;
+    }
+
+    db.close();
+
+    if (!result) {
+      return {
+        success: false,
+        error: `${options.recordType} #${options.id} not found`,
+      };
+    }
+
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/global/tools/anvil-memory/src/commands/init.ts

@@ -0,0 +1,94 @@
+/**
+ * init command - Initialize the Anvil Memory database
+ *
+ * Usage:
+ *   anvil-memory init [--path <path>]
+ *
+ * Options:
+ *   --path <path>  Custom database path (default: ~/.anvil/memory.db)
+ *   --force        Reinitialize even if database exists
+ */
+
+import { parseArgs } from 'util';
+import { AnvilMemoryDb, getDefaultDbPath, dbExists } from '../db.ts';
+import type { CommandResult } from '../types.ts';
+
+interface InitOptions {
+  path?: string;
+  force?: boolean;
+}
+
+export function parseInitArgs(args: string[]): InitOptions {
+  // Filter out --json which is handled by main
+  const filteredArgs = args.filter((arg) => arg !== '--json');
+
+  const { values } = parseArgs({
+    args: filteredArgs,
+    options: {
+      path: { type: 'string', short: 'p' },
+      force: { type: 'boolean', short: 'f' },
+    },
+    allowPositionals: true,
+    strict: false, // Allow unknown options
+  });
+
+  return {
+    path: typeof values.path === 'string' ? values.path : undefined,
+    force: values.force === true,
+  };
+}
+
+export async function handleInit(args: string[]): Promise<CommandResult> {
+  const options = parseInitArgs(args);
+  const dbPath = options.path ?? getDefaultDbPath();
+
+  // Check if database already exists
+  if (dbExists(dbPath) && !options.force) {
+    const db = new AnvilMemoryDb(dbPath);
+    const config = db.getConfig();
+    db.close();
+
+    return {
+      success: true,
+      message: `Database already exists at ${dbPath} (version ${config.version})`,
+      data: config,
+    };
+  }
+
+  try {
+    // Initialize database
+    const db = new AnvilMemoryDb(dbPath);
+    const result = db.init();
+
+    // Run integrity check
+    const integrity = db.integrityCheck();
+
+    if (!integrity.ok) {
+      db.close();
+      return {
+        success: false,
+        error: `Database integrity check failed: ${integrity.errors.join(', ')}`,
+      };
+    }
+
+    const config = db.getConfig();
+    db.close();
+
+    return {
+      success: true,
+      message: result.created
+        ? `Created Anvil Memory database at ${dbPath} (version ${config.version})`
+        : `Initialized database at ${dbPath} (version ${config.version})`,
+      data: {
+        ...config,
+        created: result.created,
+        integrityOk: integrity.ok,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/global/tools/anvil-memory/src/commands/observe.ts

@@ -0,0 +1,163 @@
+/**
+ * observe command - Create a new observation
+ *
+ * Usage:
+ *   anvil-memory observe --type <type> --title <title> [options]
+ *
+ * Options:
+ *   --type <type>        Observation type (required)
+ *   --title <title>      Short title (required)
+ *   --content <content>  Full content/description
+ *   --project <project>  Project identifier
+ *   --files <files>      Comma-separated file paths
+ *   --concepts <tags>    Comma-separated concept tags
+ *   --tokens <n>         Work tokens spent
+ *   --session <id>       Session ID
+ *   --issue <id>         Linear issue ID
+ */
+
+import { parseArgs } from 'util';
+import { AnvilMemoryDb, getDefaultDbPath, dbExists } from '../db.ts';
+import type { CommandResult, ObservationType } from '../types.ts';
+
+// Valid observation types
+const VALID_TYPES: ObservationType[] = [
+  'bugfix',
+  'feature',
+  'refactor',
+  'discovery',
+  'decision',
+  'change',
+  'checkpoint',
+  'ralph_iteration',
+  'handoff',
+  'shard',
+  'linear_sync',
+  'session_request',
+];
+
+interface ObserveOptions {
+  type?: string;
+  title?: string;
+  content?: string;
+  project?: string;
+  files?: string;
+  concepts?: string;
+  tokens?: string;
+  session?: string;
+  issue?: string;
+  path?: string;
+}
+
+export function parseObserveArgs(args: string[]): ObserveOptions {
+  // Filter out --json which is handled by main
+  const filteredArgs = args.filter((arg) => arg !== '--json');
+
+  const { values, positionals } = parseArgs({
+    args: filteredArgs,
+    options: {
+      type: { type: 'string', short: 't' },
+      title: { type: 'string' },
+      content: { type: 'string', short: 'c' },
+      project: { type: 'string', short: 'p' },
+      files: { type: 'string', short: 'f' },
+      concepts: { type: 'string' },
+      tokens: { type: 'string' },
+      session: { type: 'string', short: 's' },
+      issue: { type: 'string', short: 'i' },
+      path: { type: 'string' },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  // Allow content as positional argument
+  const contentVal = values.content;
+  const content = typeof contentVal === 'string'
+    ? contentVal
+    : (positionals.join(' ') || undefined);
+
+  return {
+    type: typeof values.type === 'string' ? values.type : undefined,
+    title: typeof values.title === 'string' ? values.title : undefined,
+    content,
+    project: typeof values.project === 'string' ? values.project : undefined,
+    files: typeof values.files === 'string' ? values.files : undefined,
+    concepts: typeof values.concepts === 'string' ? values.concepts : undefined,
+    tokens: typeof values.tokens === 'string' ? values.tokens : undefined,
+    session: typeof values.session === 'string' ? values.session : undefined,
+    issue: typeof values.issue === 'string' ? values.issue : undefined,
+    path: typeof values.path === 'string' ? values.path : undefined,
+  };
+}
+
+export async function handleObserve(args: string[]): Promise<CommandResult> {
+  const options = parseObserveArgs(args);
+
+  // Validate required fields
+  if (!options.type) {
+    return {
+      success: false,
+      error: 'Missing required option: --type',
+    };
+  }
+
+  if (!options.title) {
+    return {
+      success: false,
+      error: 'Missing required option: --title',
+    };
+  }
+
+  // Validate type
+  if (!VALID_TYPES.includes(options.type as ObservationType)) {
+    return {
+      success: false,
+      error: `Invalid type '${options.type}'. Valid types: ${VALID_TYPES.join(', ')}`,
+    };
+  }
+
+  // Check database exists
+  const dbPath = options.path ?? getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    return {
+      success: false,
+      error: `Database not found at ${dbPath}. Run 'anvil-memory init' first.`,
+    };
+  }
+
+  try {
+    const db = new AnvilMemoryDb(dbPath);
+
+    // Parse arrays
+    const files = options.files?.split(',').map((f) => f.trim()).filter(Boolean);
+    const concepts = options.concepts?.split(',').map((c) => c.trim()).filter(Boolean);
+
+    // Create observation
+    const observation = db.createObservation({
+      type: options.type as ObservationType,
+      title: options.title,
+      content: options.content ?? '',
+      project: options.project,
+      files,
+      concepts,
+      work_tokens: options.tokens ? parseInt(options.tokens, 10) : undefined,
+      session_id: options.session ? parseInt(options.session, 10) : undefined,
+      linear_issue: options.issue,
+      timestamp: new Date().toISOString(),
+    });
+
+    db.close();
+
+    return {
+      success: true,
+      message: `Created observation #${observation.id}: ${observation.title}`,
+      data: observation,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}