anvil-dev-framework 0.1.6

package/global/tools/anvil-memory/src/index.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env bun
+/**
+ * Anvil Memory CLI
+ *
+ * Persistent memory system for the Anvil framework.
+ *
+ * Commands:
+ *   init      Initialize the memory database
+ *   observe   Create a new observation
+ *   search    Search observations with FTS5
+ *   get       Fetch observation by ID
+ *   context   Generate session context
+ *   timeline  Query events around an anchor
+ *   checkpoint Record a CCS checkpoint
+ *   ralph-iteration Record a Ralph iteration
+ *
+ * Usage:
+ *   anvil-memory init [--path <path>]
+ *   anvil-memory observe --type <type> --title <title> [--content <content>]
+ *   anvil-memory search <query> [--limit <n>] [--type <type>]
+ *   anvil-memory get <id>
+ *   anvil-memory context [--limit <n>] [--format <format>]
+ */
+
+import { parseArgs } from 'util';
+import type { CommandResult } from './types.ts';
+import { handleInit } from './commands/init.ts';
+import { handleObserve } from './commands/observe.ts';
+import { handleSearch } from './commands/search.ts';
+import { handleGet } from './commands/get.ts';
+import { handleCheckpoint } from './commands/checkpoint.ts';
+
+const VERSION = '0.1.0';
+
+// Available commands
+const COMMANDS = [
+  'init',
+  'observe',
+  'search',
+  'get',
+  'context',
+  'timeline',
+  'checkpoint',
+  'ralph-iteration',
+  'help',
+  'version',
+] as const;
+
+type Command = (typeof COMMANDS)[number];
+
+function printHelp(): void {
+  console.log(`
+anvil-memory v${VERSION}
+Persistent memory system for the Anvil framework.
+
+USAGE:
+  anvil-memory <command> [options]
+
+COMMANDS:
+  init                  Initialize the memory database
+  observe               Create a new observation
+  search <query>        Search observations with full-text search
+  get <id>              Fetch observation by ID
+  context               Generate session context
+  timeline              Query events around an anchor
+  checkpoint            Record a CCS checkpoint
+  ralph-iteration       Record a Ralph iteration
+  help                  Show this help message
+  version               Show version
+
+OPTIONS:
+  --help, -h            Show help for a command
+  --json                Output in JSON format
+  --path <path>         Database path (default: ~/.anvil/memory.db)
+
+EXAMPLES:
+  anvil-memory init
+  anvil-memory observe --type feature --title "Added auth" --content "Details..."
+  anvil-memory search "authentication" --limit 10
+  anvil-memory get 42
+  anvil-memory context --limit 20 --format inject
+
+For more information, see: docs/guides/anvil-memory.md
+`);
+}
+
+function printVersion(): void {
+  console.log(`anvil-memory v${VERSION}`);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // Handle no arguments
+  if (args.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const command = args[0] as Command;
+
+  // Handle help and version
+  if (command === 'help' || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === 'version' || args.includes('--version') || args.includes('-v')) {
+    printVersion();
+    process.exit(0);
+  }
+
+  // Validate command
+  if (!COMMANDS.includes(command as Command)) {
+    console.error(`Error: Unknown command '${command}'`);
+    console.error(`Run 'anvil-memory help' for available commands.`);
+    process.exit(1);
+  }
+
+  // Route to command handler
+  let result: CommandResult;
+
+  try {
+    switch (command) {
+      case 'init':
+        result = await handleInit(args.slice(1));
+        break;
+      case 'observe':
+        result = await handleObserve(args.slice(1));
+        break;
+      case 'search':
+        result = await handleSearch(args.slice(1));
+        break;
+      case 'get':
+        result = await handleGet(args.slice(1));
+        break;
+      case 'context':
+        result = await handleContext(args.slice(1));
+        break;
+      case 'timeline':
+        result = await handleTimeline(args.slice(1));
+        break;
+      case 'checkpoint':
+        result = await handleCheckpoint(args.slice(1));
+        break;
+      case 'ralph-iteration':
+        result = await handleRalphIteration(args.slice(1));
+        break;
+      default:
+        result = { success: false, error: `Command '${command}' not implemented` };
+    }
+  } catch (error) {
+    result = {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  // Output result
+  const useJson = args.includes('--json');
+
+  if (useJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!result.success) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  } else if (result.message) {
+    console.log(result.message);
+  } else if (result.data) {
+    console.log(JSON.stringify(result.data, null, 2));
+  }
+}
+
+// Command handlers - stubs for later phases
+async function handleContext(_args: string[]): Promise<CommandResult> {
+  // TODO: Implement in Phase 4.1 (ANV-188)
+  return {
+    success: false,
+    error: 'context command not yet implemented (Phase 4.1)',
+  };
+}
+
+async function handleTimeline(_args: string[]): Promise<CommandResult> {
+  // TODO: Implement in Phase 4.2 (ANV-189)
+  return {
+    success: false,
+    error: 'timeline command not yet implemented (Phase 4.2)',
+  };
+}
+
+// handleCheckpoint is now imported from ./commands/checkpoint.ts (ANV-202)
+
+async function handleRalphIteration(_args: string[]): Promise<CommandResult> {
+  // TODO: Implement in Phase 4.3 (ANV-190)
+  return {
+    success: false,
+    error: 'ralph-iteration command not yet implemented (Phase 4.3)',
+  };
+}
+
+// Run main
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/global/tools/anvil-memory/src/types.ts

@@ -0,0 +1,122 @@
+/**
+ * Anvil Memory Type Definitions
+ *
+ * Core types for the persistent memory system.
+ */
+
+// Observation types matching spec
+export type ObservationType =
+  | 'bugfix'
+  | 'feature'
+  | 'refactor'
+  | 'discovery'
+  | 'decision'
+  | 'change'
+  | 'checkpoint'
+  | 'ralph_iteration'
+  | 'handoff'
+  | 'shard'
+  | 'linear_sync'
+  | 'session_request';
+
+// Core observation record
+export interface Observation {
+  id: number;
+  timestamp: string;           // ISO 8601
+  type: ObservationType;
+  title: string;
+  content: string;
+  project?: string;            // Project identifier
+  files?: string[];            // Associated file paths
+  concepts?: string[];         // Semantic tags
+  work_tokens?: number;        // Tokens spent on this work
+  session_id?: number;         // FK to sessions
+  linear_issue?: string;       // Linear issue ID (e.g., "ANV-180")
+}
+
+// Session record (conversation boundary)
+export interface Session {
+  id: number;
+  started_at: string;          // ISO 8601
+  ended_at?: string;           // ISO 8601
+  project: string;
+  branch?: string;
+  git_hash?: string;
+  context_peak_percent?: number;
+  summary?: string;
+}
+
+// Checkpoint record (CCS events)
+export interface Checkpoint {
+  id: number;
+  timestamp: string;           // ISO 8601
+  level: 'L1' | 'L2' | 'L3';
+  context_percent: number;
+  handoff_file?: string;
+  session_id?: number;
+  resumed?: boolean;
+  resume_session_id?: number;
+}
+
+// Ralph iteration record
+export interface RalphIteration {
+  id: number;
+  session_id: string;          // Ralph session ID
+  iteration: number;
+  started_at: string;          // ISO 8601
+  ended_at?: string;
+  status: 'running' | 'completed' | 'failed' | 'checkpointed';
+  items_completed?: number;
+  items_total?: number;
+  checkpoint_id?: number;
+}
+
+// User prompt record
+export interface Prompt {
+  id: number;
+  timestamp: string;           // ISO 8601
+  content: string;
+  project?: string;
+  session_id?: number;
+}
+
+// Search result with highlighting
+export interface SearchResult<T> {
+  item: T;
+  snippet?: string;            // Highlighted match
+  score?: number;              // Relevance score
+}
+
+// Context generation options
+export interface ContextOptions {
+  limit?: number;              // Max observations
+  types?: ObservationType[];   // Filter by type
+  project?: string;            // Filter by project
+  since?: string;              // ISO 8601 timestamp
+  concepts?: string[];         // Filter by concepts
+  format?: 'inject' | 'markdown' | 'json';
+}
+
+// Timeline query options
+export interface TimelineOptions {
+  anchor: number;              // Observation ID as center
+  depthBefore?: number;        // Events before anchor
+  depthAfter?: number;         // Events after anchor
+  types?: string[];            // Filter record types
+  project?: string;
+}
+
+// CLI command result
+export interface CommandResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  message?: string;
+}
+
+// Database configuration
+export interface DbConfig {
+  path: string;                // Path to SQLite database
+  migrated: boolean;           // Whether migrations have run
+  version: number;             // Schema version
+}

package/global/tools/anvil-memory/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}