@fancyrobot/fred-cli 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fancyrobot/fred-cli",
+  "version": "0.1.0",
+  "description": "Fred AI framework CLI",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "fred": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm"
+  },
+  "dependencies": {
+    "@fancyrobot/fred": "^0.1.0",
+    "@fancyrobot/fred-dev": "^0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.19.0"
+  },
+  "devDependencies": {
+    "effect": "^3.19.15",
+    "@types/bun": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["fred", "cli", "ai", "agents"],
+  "license": "MIT"
+}

package/src/dev.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+
+/**
+ * Dev command handler
+ * Starts the development chat interface with hot reload
+ */
+
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { Fred } from '@fancyrobot/fred';
+import { startDevChat } from '@fancyrobot/fred-dev';
+
+/**
+ * Try to load and call project's setup() function if it exists
+ */
+async function loadProjectSetup(fred: Fred): Promise<void> {
+  // Try to find project's index.ts or src/index.ts
+  const possiblePaths = [
+    resolve(process.cwd(), 'src', 'index.ts'),
+    resolve(process.cwd(), 'index.ts'),
+    resolve(process.cwd(), 'src', 'index.js'),
+    resolve(process.cwd(), 'index.js'),
+  ];
+
+  for (const indexPath of possiblePaths) {
+    if (existsSync(indexPath)) {
+      try {
+        // Dynamically import the project's index file
+        // Bun natively supports TypeScript imports, so we can import .ts files directly
+        const projectModule = await import(pathToFileURL(indexPath).href);
+
+        // Check if setup function is exported
+        if (typeof projectModule.setup === 'function') {
+          // Call the setup function with the Fred instance
+          await projectModule.setup(fred);
+          return;
+        }
+      } catch (error) {
+        // If import fails (e.g., syntax error, missing dependencies), continue to next path
+        // This is expected if the file has errors or doesn't export setup
+        continue;
+      }
+    }
+  }
+
+  // If no setup function found, that's okay - dev-chat will use auto-agent creation
+}
+
+/**
+ * Handle dev command
+ * Uses BunRuntime.runMain internally via startDevChat for proper signal handling.
+ * This function never returns - it runs until interrupted.
+ */
+export function handleDevCommand(): void {
+  const setupHook = async (fred: Fred) => {
+    await loadProjectSetup(fred);
+  };
+
+  // startDevChat uses BunRuntime.runMain internally
+  // It will handle signals and cleanup, and never returns
+  startDevChat(setupHook);
+}

package/src/index.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+
+/**
+ * Fred CLI
+ * Main entry point for CLI commands
+ */
+
+import { handleTestCommand } from './test';
+import { handleDevCommand } from './dev';
+
+/**
+ * Options that require a value
+ */
+const OPTIONS_REQUIRING_VALUE = new Set([
+  'record',
+  'config',
+  'traces-dir',
+  'tracesDir',
+]);
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(args: string[]): { command: string; args: string[]; options: Record<string, any> } {
+  const command = args[0] || 'help';
+  const remainingArgs: string[] = [];
+  const options: Record<string, any> = {};
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.substring(2);
+      const nextArg = args[i + 1];
+      const requiresValue = OPTIONS_REQUIRING_VALUE.has(key);
+
+      // Check if option requires a value
+      if (requiresValue) {
+        // Validate that a value is provided
+        if (nextArg === undefined || nextArg.startsWith('--')) {
+          throw new Error(`Option --${key} requires a value. Example: --${key} <value>`);
+        }
+        options[key] = nextArg;
+        i++; // Skip next arg as it's the value
+      } else {
+        // Handle boolean flags (options that don't require values)
+        if (nextArg === undefined || nextArg.startsWith('--')) {
+          options[key] = true;
+        } else {
+          // If a value is provided for a boolean flag, treat it as the value
+          // (some flags might accept optional values)
+          options[key] = nextArg;
+          i++; // Skip next arg as it's the value
+        }
+      }
+    } else {
+      remainingArgs.push(arg);
+    }
+  }
+
+  return { command, args: remainingArgs, options };
+}
+
+/**
+ * Show help message
+ */
+function showHelp(): void {
+  console.log(`
+Fred CLI
+
+Usage:
+  fred <command> [options]
+
+Commands:
+  dev                     Start development chat interface with hot reload
+                          - If your project exports setup(fred) from src/index.(ts|js) or index.(ts|js), it will be executed before chat starts
+  test                    Run golden trace tests
+  test --record <message>  Record a new golden trace
+  test --update            Update existing golden traces
+  test <pattern>           Run tests matching pattern
+
+Options:
+  --config <file>          Path to Fred config file
+  --traces-dir <dir>       Directory for golden traces (default: tests/golden-traces)
+
+Examples:
+  fred dev
+  fred test
+  fred test --record "Hello, world!"
+  fred test --update
+  fred test --config fred.config.yaml
+  `);
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    showHelp();
+    process.exit(0);
+  }
+
+  const { command, args: commandArgs, options } = parseArgs(args);
+
+  try {
+    let exitCode = 0;
+
+    switch (command) {
+      case 'dev':
+        // handleDevCommand uses BunRuntime.runMain internally and never returns
+        // It handles signals and cleanup, and exits the process
+        handleDevCommand();
+        // This line is never reached
+        return;
+
+      case 'test':
+        exitCode = await handleTestCommand(commandArgs, {
+          pattern: commandArgs[0],
+          update: options.update === true,
+          record: options.record,
+          tracesDir: options['traces-dir'] || options.tracesDir,
+          configFile: options.config,
+        });
+        break;
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        showHelp();
+        exitCode = 1;
+    }
+
+    process.exit(exitCode);
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (import.meta.main) {
+  main();
+}

package/src/test.ts

@@ -0,0 +1,262 @@
+import { readdir, readFile, writeFile, mkdir, unlink } from 'fs/promises';
+import { join, resolve, dirname } from 'path';
+import { existsSync } from 'fs';
+import { Fred } from '@fancyrobot/fred';
+import { NoOpTracer, GoldenTraceRecorder, loadGoldenTrace, runTestCase, formatTestResults, TestCase } from '@fancyrobot/fred';
+import { createHash } from 'crypto';
+
+/**
+ * Test command options
+ */
+export interface TestCommandOptions {
+  pattern?: string;
+  update?: boolean;
+  record?: string;
+  tracesDir?: string;
+  configFile?: string;
+}
+
+/**
+ * Find all golden trace files
+ */
+async function findGoldenTraces(tracesDir: string): Promise<string[]> {
+  if (!existsSync(tracesDir)) {
+    return [];
+  }
+
+  const files = await readdir(tracesDir);
+  return files
+    .filter(file => file.endsWith('.json') && file.startsWith('trace-v'))
+    .map(file => join(tracesDir, file));
+}
+
+/**
+ * Find test case files (JSON files with test definitions)
+ */
+async function findTestCases(tracesDir: string): Promise<TestCase[]> {
+  const testCaseFile = join(tracesDir, 'test-cases.json');
+
+  if (!existsSync(testCaseFile)) {
+    return [];
+  }
+
+  const content = await readFile(testCaseFile, 'utf-8');
+  const testCases = JSON.parse(content);
+
+  if (!Array.isArray(testCases)) {
+    throw new Error('test-cases.json must contain an array of test cases');
+  }
+
+  return testCases;
+}
+
+/**
+ * Record a new golden trace
+ */
+export async function recordTrace(
+  message: string,
+  fred: Fred,
+  tracesDir: string,
+  options?: { conversationId?: string }
+): Promise<string> {
+  // Create recorder with a base tracer
+  const baseTracer = new NoOpTracer();
+  const recorder = new GoldenTraceRecorder(baseTracer);
+
+  // Create tracer with callback to automatically capture spans
+  const tracer = new NoOpTracer((span) => {
+    recorder.addSpan(span);
+  });
+
+  // Enable tracing with the callback-enabled tracer
+  fred.enableTracing(tracer);
+
+  // Record message
+  recorder.recordMessage(message);
+
+  // Process message (spans will be automatically captured via callback)
+  const response = await fred.processMessage(message, {
+    conversationId: options?.conversationId,
+  });
+
+  if (!response) {
+    throw new Error('No response from agent');
+  }
+
+  // Record response
+  recorder.recordResponse(response);
+
+  // Save trace (spans are already captured via callback)
+  const filepath = await recorder.saveToFile(tracesDir);
+  console.log(`Recorded golden trace: ${filepath}`);
+
+  return filepath;
+}
+
+/**
+ * Run golden trace tests
+ */
+export async function runTests(
+  tracesDir: string,
+  pattern?: string
+): Promise<boolean> {
+  // Find test cases
+  const testCases = await findTestCases(tracesDir);
+
+  if (testCases.length === 0) {
+    console.log('No test cases found. Create a test-cases.json file in the traces directory.');
+    return true;
+  }
+
+  // Filter by pattern if provided
+  const filteredCases = pattern
+    ? testCases.filter(tc => tc.name.includes(pattern))
+    : testCases;
+
+  if (filteredCases.length === 0) {
+    console.log(`No test cases match pattern: ${pattern}`);
+    return true;
+  }
+
+  // Run tests
+  const results = [];
+  for (const testCase of filteredCases) {
+    const result = await runTestCase(testCase, tracesDir);
+    results.push(result);
+  }
+
+  // Display results
+  console.log(formatTestResults(results));
+
+  // Return success if all passed
+  return results.every(r => r.passed);
+}
+
+/**
+ * Update golden traces
+ */
+export async function updateTraces(
+  tracesDir: string,
+  fred: Fred,
+  pattern?: string
+): Promise<void> {
+  const traceFiles = await findGoldenTraces(tracesDir);
+
+  if (traceFiles.length === 0) {
+    console.log('No golden traces found to update.');
+    return;
+  }
+
+  // Filter by pattern if provided
+  const filteredFiles = pattern
+    ? traceFiles.filter(file => file.includes(pattern))
+    : traceFiles;
+
+  let successCount = 0;
+  for (const traceFile of filteredFiles) {
+    try {
+      const trace = await loadGoldenTrace(traceFile);
+      const message = trace.trace.message;
+
+      console.log(`Updating trace for: "${message.substring(0, 50)}..."`);
+
+      // Re-record trace
+      await recordTrace(message, fred, tracesDir, {
+        conversationId: trace.metadata.config?.conversationId,
+      });
+
+      // Remove old trace file now that the new one is created
+      await unlink(traceFile);
+      successCount++;
+    } catch (error) {
+      console.error(`Failed to update trace file ${traceFile}:`, error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  console.log(`Updated ${successCount} trace(s)`);
+}
+
+/**
+ * Main test command handler
+ */
+export async function handleTestCommand(
+  args: string[],
+  options: TestCommandOptions
+): Promise<number> {
+  const tracesDir = options.tracesDir || resolve(process.cwd(), 'tests', 'golden-traces');
+
+  // Ensure traces directory exists
+  if (!existsSync(tracesDir)) {
+    await mkdir(tracesDir, { recursive: true });
+  }
+
+  try {
+    // Handle record command
+    if (options.record) {
+      // Load Fred instance
+      let fred!: Fred;
+      if (options.configFile) {
+        fred = new Fred();
+        await fred.initializeFromConfig(options.configFile);
+      } else {
+        // Try to find default config
+        const defaultConfigs = ['fred.config.yaml', 'fred.config.yml', 'fred.config.json'];
+        let configFound = false;
+
+        for (const configFile of defaultConfigs) {
+          if (existsSync(configFile)) {
+            fred = new Fred();
+            await fred.initializeFromConfig(configFile);
+            configFound = true;
+            break;
+          }
+        }
+
+        if (!configFound) {
+          console.error('No config file found. Use --config to specify one.');
+          return 1;
+        }
+      }
+
+      await recordTrace(options.record, fred, tracesDir);
+      return 0;
+    }
+
+    // Handle update command
+    if (options.update) {
+      // Load Fred instance
+      let fred!: Fred;
+      if (options.configFile) {
+        fred = new Fred();
+        await fred.initializeFromConfig(options.configFile);
+      } else {
+        const defaultConfigs = ['fred.config.yaml', 'fred.config.yml', 'fred.config.json'];
+        let configFound = false;
+
+        for (const configFile of defaultConfigs) {
+          if (existsSync(configFile)) {
+            fred = new Fred();
+            await fred.initializeFromConfig(configFile);
+            configFound = true;
+            break;
+          }
+        }
+
+        if (!configFound) {
+          console.error('No config file found. Use --config to specify one.');
+          return 1;
+        }
+      }
+
+      await updateTraces(tracesDir, fred, options.pattern);
+      return 0;
+    }
+
+    // Handle run command (default)
+    const success = await runTests(tracesDir, options.pattern);
+    return success ? 0 : 1;
+  } catch (error) {
+    console.error('Error running tests:', error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}