@artyfacts/claude 1.0.0 → 1.1.0

package/src/executor.ts

@@ -0,0 +1,293 @@
+/**
+ * Claude Code executor for Artyfacts tasks
+ * 
+ * Executes tasks by shelling out to the Claude Code CLI (claude).
+ * This uses the user's existing Claude Code authentication - no separate API key needed.
+ */
+
+import { spawn } from 'child_process';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TaskContext {
+  /** Task ID (section ID) */
+  taskId: string;
+  /** Task heading/title */
+  heading: string;
+  /** Task content/description */
+  content: string;
+  /** Parent artifact ID */
+  artifactId: string;
+  /** Parent artifact title */
+  artifactTitle?: string;
+  /** Task priority (1=high, 2=medium, 3=low) */
+  priority?: number;
+  /** Additional context */
+  context?: Record<string, unknown>;
+}
+
+export interface ExecutionResult {
+  /** Whether execution was successful */
+  success: boolean;
+  /** The generated output */
+  output: string;
+  /** Summary of what was accomplished */
+  summary: string;
+  /** Any error message if failed */
+  error?: string;
+}
+
+export interface ExecutorConfig {
+  /** Path to claude CLI (default: 'claude') */
+  claudePath?: string;
+  /** Timeout in milliseconds (default: 5 minutes) */
+  timeout?: number;
+  /** System prompt prefix */
+  systemPromptPrefix?: string;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+const DEFAULT_SYSTEM_PROMPT = `You are an AI agent working within the Artyfacts task management system.
+
+Your job is to complete tasks assigned to you. For each task:
+1. Understand the requirements from the task heading and content
+2. Complete the task to the best of your ability
+3. Provide a clear, actionable output
+
+Guidelines:
+- Be thorough but concise
+- If the task requires code, provide working code
+- If the task requires analysis, provide structured findings
+- If the task requires a decision, explain your reasoning
+- If you cannot complete the task, explain why
+
+Format your response as follows:
+1. First, provide your main output (the task deliverable)
+2. End with a brief summary line starting with "SUMMARY:"`;
+
+// ============================================================================
+// Executor Class
+// ============================================================================
+
+export class ClaudeExecutor {
+  private config: Required<Pick<ExecutorConfig, 'timeout'>> & ExecutorConfig;
+
+  constructor(config: ExecutorConfig = {}) {
+    this.config = {
+      ...config,
+      timeout: config.timeout || DEFAULT_TIMEOUT,
+      claudePath: config.claudePath || 'claude',
+    };
+  }
+
+  /**
+   * Execute a task using Claude Code CLI
+   */
+  async execute(task: TaskContext): Promise<ExecutionResult> {
+    try {
+      // Build the prompt
+      const prompt = this.buildTaskPrompt(task);
+
+      // Execute via Claude Code CLI
+      const output = await this.runClaude(prompt);
+
+      // Extract summary if present
+      const { content, summary } = this.parseResponse(output, task.heading);
+
+      return {
+        success: true,
+        output: content,
+        summary,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      
+      return {
+        success: false,
+        output: '',
+        summary: `Failed: ${errorMessage}`,
+        error: errorMessage,
+      };
+    }
+  }
+
+  /**
+   * Run Claude Code CLI with the given prompt
+   */
+  private runClaude(prompt: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const claudePath = this.config.claudePath || 'claude';
+      
+      // Use claude CLI with --print flag for non-interactive output
+      // Pass prompt via stdin
+      const proc = spawn(claudePath, ['--print'], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: this.config.timeout,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve(stdout.trim());
+        } else {
+          reject(new Error(stderr || `Claude exited with code ${code}`));
+        }
+      });
+
+      proc.on('error', (err) => {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+          reject(new Error(
+            'Claude Code CLI not found. Please install it:\n' +
+            '  npm install -g @anthropic-ai/claude-code'
+          ));
+        } else {
+          reject(err);
+        }
+      });
+
+      // Send prompt to stdin
+      proc.stdin.write(prompt);
+      proc.stdin.end();
+    });
+  }
+
+  /**
+   * Build the task prompt
+   */
+  private buildTaskPrompt(task: TaskContext): string {
+    const parts: string[] = [];
+
+    // System context
+    const systemPrompt = this.config.systemPromptPrefix 
+      ? `${this.config.systemPromptPrefix}\n\n${DEFAULT_SYSTEM_PROMPT}`
+      : DEFAULT_SYSTEM_PROMPT;
+    
+    parts.push(systemPrompt);
+    parts.push('');
+    parts.push('---');
+    parts.push('');
+
+    // Task header
+    parts.push(`# Task: ${task.heading}`);
+    parts.push('');
+
+    // Artifact context
+    if (task.artifactTitle) {
+      parts.push(`**Artifact:** ${task.artifactTitle}`);
+    }
+    
+    // Priority
+    if (task.priority) {
+      const priorityLabels = ['High', 'Medium', 'Low'];
+      parts.push(`**Priority:** ${priorityLabels[task.priority - 1] || 'Medium'}`);
+    }
+    parts.push('');
+
+    // Task content
+    parts.push('## Description');
+    parts.push(task.content || 'No additional description provided.');
+    parts.push('');
+
+    // Additional context
+    if (task.context && Object.keys(task.context).length > 0) {
+      parts.push('## Additional Context');
+      parts.push('```json');
+      parts.push(JSON.stringify(task.context, null, 2));
+      parts.push('```');
+      parts.push('');
+    }
+
+    // Instructions
+    parts.push('## Instructions');
+    parts.push('Complete this task and provide your output below.');
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Parse the response to extract output and summary
+   */
+  private parseResponse(
+    fullOutput: string,
+    taskHeading: string
+  ): { content: string; summary: string } {
+    // Try to find SUMMARY: line
+    const summaryMatch = fullOutput.match(/SUMMARY:\s*(.+?)(?:\n|$)/i);
+    
+    if (summaryMatch) {
+      const summary = summaryMatch[1].trim();
+      const content = fullOutput.replace(/SUMMARY:\s*.+?(?:\n|$)/i, '').trim();
+      return { content, summary };
+    }
+
+    // No explicit summary, generate one
+    const lines = fullOutput.split('\n').filter((l) => l.trim());
+    const firstLine = lines[0] || '';
+    
+    // Take first 100 chars as summary
+    const summary = firstLine.length > 100
+      ? `${firstLine.substring(0, 97)}...`
+      : firstLine || `Completed: ${taskHeading}`;
+
+    return { content: fullOutput, summary };
+  }
+
+  /**
+   * Test that Claude Code CLI is available and working
+   */
+  async testConnection(): Promise<boolean> {
+    try {
+      const output = await this.runClaude('Say "connected" and nothing else.');
+      return output.toLowerCase().includes('connected');
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if Claude Code CLI is installed
+   */
+  async isInstalled(): Promise<boolean> {
+    return new Promise((resolve) => {
+      const proc = spawn(this.config.claudePath || 'claude', ['--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      proc.on('close', (code) => {
+        resolve(code === 0);
+      });
+
+      proc.on('error', () => {
+        resolve(false);
+      });
+    });
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Claude executor
+ */
+export function createExecutor(config?: ExecutorConfig): ClaudeExecutor {
+  return new ClaudeExecutor(config);
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * @artyfacts/claude - Claude adapter for Artyfacts
+ * 
+ * Execute Artyfacts tasks using Claude Code CLI.
+ * 
+ * @example
+ * ```typescript
+ * import { ClaudeExecutor, ArtyfactsListener, getCredentials } from '@artyfacts/claude';
+ * 
+ * // Get or request credentials
+ * const credentials = await getCredentials();
+ * 
+ * // Create executor (uses Claude Code CLI)
+ * const executor = new ClaudeExecutor();
+ * 
+ * // Create listener
+ * const listener = new ArtyfactsListener({
+ *   apiKey: credentials.apiKey,
+ *   agentId: credentials.agentId,
+ * });
+ * 
+ * // Handle task assignments
+ * listener.on('task_assigned', async (event) => {
+ *   const result = await executor.execute({
+ *     taskId: event.data.taskId,
+ *     heading: event.data.heading,
+ *     content: event.data.content,
+ *     artifactId: event.data.artifactId,
+ *   });
+ *   
+ *   console.log('Task completed:', result.summary);
+ * });
+ * 
+ * // Start listening
+ * listener.connect();
+ * ```
+ * 
+ * @packageDocumentation
+ */
+
+// Authentication - Types
+export type {
+  Credentials,
+  DeviceAuthResponse,
+  TokenResponse,
+} from './auth';
+
+// Authentication - Functions
+export {
+  loadCredentials,
+  saveCredentials,
+  clearCredentials,
+  runDeviceAuth,
+  promptForApiKey,
+  getCredentials,
+} from './auth';
+
+// Claude Executor - Types
+export type {
+  TaskContext,
+  ExecutionResult,
+  ExecutorConfig,
+} from './executor';
+
+// Claude Executor - Classes
+export {
+  ClaudeExecutor,
+  createExecutor,
+} from './executor';
+
+// SSE Listener - Types
+export type {
+  TaskAssignedEvent,
+  HeartbeatEvent,
+  ConnectedEvent,
+  ArtyfactsEvent,
+  EventCallback,
+  ListenerConfig,
+  ConnectionState,
+} from './listener';
+
+// SSE Listener - Classes
+export {
+  ArtyfactsListener,
+  createListener,
+} from './listener';

package/src/listener.ts

@@ -0,0 +1,313 @@
+/**
+ * SSE Event Listener for Artyfacts task assignments
+ * 
+ * Connects to the Artyfacts SSE stream and listens for task_assigned events.
+ * Uses EventSource for automatic reconnection handling.
+ */
+
+import EventSource from 'eventsource';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TaskAssignedEvent {
+  type: 'task_assigned';
+  timestamp: string;
+  data: {
+    taskId: string;
+    sectionId: string;
+    heading: string;
+    content: string;
+    artifactId: string;
+    artifactTitle?: string;
+    priority?: number;
+    assignedTo: string;
+    assignedAt: string;
+  };
+}
+
+export interface HeartbeatEvent {
+  type: 'heartbeat';
+  timestamp: string;
+}
+
+export interface ConnectedEvent {
+  type: 'connected';
+  timestamp: string;
+  data: {
+    agentId: string;
+  };
+}
+
+export type ArtyfactsEvent = TaskAssignedEvent | HeartbeatEvent | ConnectedEvent | {
+  type: string;
+  timestamp: string;
+  data?: Record<string, unknown>;
+};
+
+export type EventCallback<T extends ArtyfactsEvent = ArtyfactsEvent> = (event: T) => void | Promise<void>;
+
+export interface ListenerConfig {
+  /** Artyfacts API key */
+  apiKey: string;
+  /** Agent ID to listen for */
+  agentId: string;
+  /** Base URL for Artyfacts API */
+  baseUrl?: string;
+  /** Callback for state changes */
+  onStateChange?: (state: ConnectionState) => void;
+  /** Callback for errors */
+  onError?: (error: Error) => void;
+}
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_BASE_URL = 'https://artyfacts.dev/api/v1';
+
+// Event types to listen for
+const EVENT_TYPES = [
+  'connected',
+  'heartbeat',
+  'task_assigned',
+  'task_unblocked',
+  'blocker_resolved',
+  'notification',
+] as const;
+
+// ============================================================================
+// EventListener Class
+// ============================================================================
+
+export class ArtyfactsListener {
+  private config: Required<Pick<ListenerConfig, 'apiKey' | 'agentId' | 'baseUrl'>> & ListenerConfig;
+  private eventSource: EventSource | null = null;
+  private callbacks: Map<string, Set<EventCallback>> = new Map();
+  private allCallbacks: Set<EventCallback> = new Set();
+  private state: ConnectionState = 'disconnected';
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 10;
+  private reconnectDelay = 1000;
+
+  constructor(config: ListenerConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    if (!config.agentId) {
+      throw new Error('Agent ID is required');
+    }
+
+    this.config = {
+      ...config,
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+    };
+  }
+
+  /**
+   * Get current connection state
+   */
+  get connectionState(): ConnectionState {
+    return this.state;
+  }
+
+  /**
+   * Check if connected
+   */
+  get isConnected(): boolean {
+    return this.state === 'connected';
+  }
+
+  /**
+   * Subscribe to all events
+   */
+  subscribe(callback: EventCallback): () => void {
+    this.allCallbacks.add(callback);
+    return () => {
+      this.allCallbacks.delete(callback);
+    };
+  }
+
+  /**
+   * Subscribe to a specific event type
+   */
+  on<T extends ArtyfactsEvent>(type: string, callback: EventCallback<T>): () => void {
+    if (!this.callbacks.has(type)) {
+      this.callbacks.set(type, new Set());
+    }
+    this.callbacks.get(type)!.add(callback as EventCallback);
+
+    return () => {
+      const typeCallbacks = this.callbacks.get(type);
+      if (typeCallbacks) {
+        typeCallbacks.delete(callback as EventCallback);
+        if (typeCallbacks.size === 0) {
+          this.callbacks.delete(type);
+        }
+      }
+    };
+  }
+
+  /**
+   * Connect to the SSE stream
+   */
+  connect(): void {
+    if (this.eventSource) {
+      // Already connected or connecting
+      return;
+    }
+
+    this.setState('connecting');
+
+    // Build SSE URL
+    const url = new URL(`${this.config.baseUrl}/events/stream`);
+    url.searchParams.set('apiKey', this.config.apiKey);
+    url.searchParams.set('agentId', this.config.agentId);
+
+    // Create EventSource with headers workaround
+    this.eventSource = new EventSource(url.toString(), {
+      headers: {
+        'Authorization': `Bearer ${this.config.apiKey}`,
+      },
+    } as EventSource.EventSourceInitDict);
+
+    // Handle open
+    this.eventSource.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.reconnectDelay = 1000;
+      this.setState('connected');
+    };
+
+    // Handle generic messages
+    this.eventSource.onmessage = (event: MessageEvent) => {
+      this.handleMessage(event);
+    };
+
+    // Handle errors
+    this.eventSource.onerror = (event: Event) => {
+      this.handleError(event);
+    };
+
+    // Listen for named event types
+    for (const eventType of EVENT_TYPES) {
+      this.eventSource.addEventListener(eventType, (event: MessageEvent) => {
+        this.handleMessage(event, eventType);
+      });
+    }
+  }
+
+  /**
+   * Disconnect from the SSE stream
+   */
+  disconnect(): void {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.setState('disconnected');
+  }
+
+  /**
+   * Reconnect to the SSE stream
+   */
+  reconnect(): void {
+    this.disconnect();
+    this.connect();
+  }
+
+  /**
+   * Handle incoming SSE message
+   */
+  private handleMessage(event: MessageEvent, eventType?: string): void {
+    try {
+      const data = JSON.parse(event.data);
+
+      // Normalize event structure
+      const artyfactsEvent: ArtyfactsEvent = {
+        type: eventType || data.type || 'unknown',
+        timestamp: data.timestamp || new Date().toISOString(),
+        data: data.data || data,
+      };
+
+      // Route to type-specific callbacks
+      const typeCallbacks = this.callbacks.get(artyfactsEvent.type);
+      if (typeCallbacks) {
+        for (const callback of typeCallbacks) {
+          this.safeCallCallback(callback, artyfactsEvent);
+        }
+      }
+
+      // Route to all-events callbacks
+      for (const callback of this.allCallbacks) {
+        this.safeCallCallback(callback, artyfactsEvent);
+      }
+    } catch (err) {
+      console.error('[Listener] Failed to parse SSE message:', event.data, err);
+    }
+  }
+
+  /**
+   * Safely call a callback, handling async and errors
+   */
+  private async safeCallCallback(callback: EventCallback, event: ArtyfactsEvent): Promise<void> {
+    try {
+      await callback(event);
+    } catch (err) {
+      console.error(`[Listener] Error in event callback for '${event.type}':`, err);
+    }
+  }
+
+  /**
+   * Handle SSE error
+   */
+  private handleError(event: Event): void {
+    if (this.eventSource?.readyState === EventSource.CONNECTING) {
+      this.setState('reconnecting');
+    } else if (this.eventSource?.readyState === EventSource.CLOSED) {
+      this.setState('disconnected');
+
+      // Attempt reconnection with exponential backoff
+      if (this.reconnectAttempts < this.maxReconnectAttempts) {
+        this.reconnectAttempts++;
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
+
+        console.log(
+          `[Listener] Connection lost, reconnecting in ${this.reconnectDelay / 1000}s (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`
+        );
+
+        setTimeout(() => {
+          if (this.state === 'disconnected') {
+            this.connect();
+          }
+        }, this.reconnectDelay);
+      } else {
+        const error = new Error('Max reconnection attempts reached');
+        this.config.onError?.(error);
+      }
+    }
+  }
+
+  /**
+   * Update connection state
+   */
+  private setState(state: ConnectionState): void {
+    if (this.state !== state) {
+      this.state = state;
+      this.config.onStateChange?.(state);
+    }
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create an Artyfacts event listener
+ */
+export function createListener(config: ListenerConfig): ArtyfactsListener {
+  return new ArtyfactsListener(config);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/bin/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import('../dist/cli.mjs');