@sparkleideas/cli 3.1.0-alpha.19 → 3.1.0-alpha.21

package/dist/src/services/headless-worker-executor.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Headless Worker Executor
+ * Enables workers to invoke Claude Code in headless mode with configurable sandbox profiles.
+ *
+ * ADR-020: Headless Worker Integration Architecture
+ * - Integrates with CLAUDE_CODE_HEADLESS and CLAUDE_CODE_SANDBOX_MODE environment variables
+ * - Provides process pool for concurrent execution
+ * - Builds context from file glob patterns
+ * - Supports prompt templates and output parsing
+ * - Implements timeout and graceful error handling
+ *
+ * Key Features:
+ * - Process pool with configurable maxConcurrent
+ * - Context building from file glob patterns with caching
+ * - Prompt template system with context injection
+ * - Output parsing (text, json, markdown)
+ * - Timeout handling with graceful termination
+ * - Execution logging for debugging
+ * - Event emission for monitoring
+ */
+import { EventEmitter } from 'events';
+import type { WorkerType } from './worker-daemon.js';
+/**
+ * Headless worker types - workers that use Claude Code AI
+ */
+export type HeadlessWorkerType = 'audit' | 'optimize' | 'testgaps' | 'document' | 'ultralearn' | 'refactor' | 'deepdive' | 'predict';
+/**
+ * Local worker types - workers that run locally without AI
+ */
+export type LocalWorkerType = 'map' | 'consolidate' | 'benchmark' | 'preload';
+/**
+ * Sandbox mode for headless execution
+ */
+export type SandboxMode = 'strict' | 'permissive' | 'disabled';
+/**
+ * Model types for Claude Code
+ */
+export type ModelType = 'sonnet' | 'opus' | 'haiku';
+/**
+ * Output format for worker results
+ */
+export type OutputFormat = 'text' | 'json' | 'markdown';
+/**
+ * Execution mode for workers
+ */
+export type ExecutionMode = 'local' | 'headless';
+/**
+ * Worker priority levels
+ */
+export type WorkerPriority = 'low' | 'normal' | 'high' | 'critical';
+/**
+ * Base worker configuration (matching worker-daemon.ts)
+ */
+export interface WorkerConfig {
+    type: WorkerType;
+    intervalMs: number;
+    priority: WorkerPriority;
+    description: string;
+    enabled: boolean;
+}
+/**
+ * Headless-specific options
+ */
+export interface HeadlessOptions {
+    /** Prompt template for Claude Code */
+    promptTemplate: string;
+    /** Sandbox profile: strict, permissive, or disabled */
+    sandbox: SandboxMode;
+    /** Model to use: sonnet, opus, or haiku */
+    model?: ModelType;
+    /** Maximum tokens for output */
+    maxOutputTokens?: number;
+    /** Timeout in milliseconds (overrides default) */
+    timeoutMs?: number;
+    /** File glob patterns to include as context */
+    contextPatterns?: string[];
+    /** Output parsing format */
+    outputFormat?: OutputFormat;
+}
+/**
+ * Extended worker configuration with headless options
+ */
+export interface HeadlessWorkerConfig extends WorkerConfig {
+    /** Execution mode: local or headless */
+    mode: ExecutionMode;
+    /** Headless-specific options (required when mode is 'headless') */
+    headless?: HeadlessOptions;
+}
+/**
+ * Executor configuration options
+ */
+export interface HeadlessExecutorConfig {
+    /** Maximum concurrent headless processes */
+    maxConcurrent?: number;
+    /** Default timeout in milliseconds */
+    defaultTimeoutMs?: number;
+    /** Maximum files to include in context */
+    maxContextFiles?: number;
+    /** Maximum characters per file in context */
+    maxCharsPerFile?: number;
+    /** Log directory for execution logs */
+    logDir?: string;
+    /** Whether to cache context between runs */
+    cacheContext?: boolean;
+    /** Context cache TTL in milliseconds */
+    cacheTtlMs?: number;
+}
+/**
+ * Result from headless execution
+ */
+export interface HeadlessExecutionResult {
+    /** Whether execution completed successfully */
+    success: boolean;
+    /** Raw output from Claude Code */
+    output: string;
+    /** Parsed output (if outputFormat is json or markdown) */
+    parsedOutput?: unknown;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Estimated tokens used (if available) */
+    tokensUsed?: number;
+    /** Model used for execution */
+    model: string;
+    /** Sandbox mode used */
+    sandboxMode: SandboxMode;
+    /** Worker type that was executed */
+    workerType: HeadlessWorkerType;
+    /** Timestamp of execution */
+    timestamp: Date;
+    /** Error message if execution failed */
+    error?: string;
+    /** Execution ID for tracking */
+    executionId: string;
+}
+/**
+ * Pool status information
+ */
+export interface PoolStatus {
+    activeCount: number;
+    queueLength: number;
+    maxConcurrent: number;
+    activeWorkers: Array<{
+        executionId: string;
+        workerType: HeadlessWorkerType;
+        startTime: Date;
+        elapsedMs: number;
+    }>;
+    queuedWorkers: Array<{
+        workerType: HeadlessWorkerType;
+        queuedAt: Date;
+        waitingMs: number;
+    }>;
+}
+/**
+ * Array of headless worker types for runtime checking
+ */
+export declare const HEADLESS_WORKER_TYPES: HeadlessWorkerType[];
+/**
+ * Array of local worker types
+ */
+export declare const LOCAL_WORKER_TYPES: LocalWorkerType[];
+/**
+ * Default headless worker configurations based on ADR-020
+ */
+export declare const HEADLESS_WORKER_CONFIGS: Record<HeadlessWorkerType, HeadlessWorkerConfig>;
+/**
+ * Local worker configurations
+ */
+export declare const LOCAL_WORKER_CONFIGS: Record<LocalWorkerType, HeadlessWorkerConfig>;
+/**
+ * Combined worker configurations
+ */
+export declare const ALL_WORKER_CONFIGS: HeadlessWorkerConfig[];
+/**
+ * Check if a worker type is a headless worker
+ */
+export declare function isHeadlessWorker(type: WorkerType): type is HeadlessWorkerType;
+/**
+ * Check if a worker type is a local worker
+ */
+export declare function isLocalWorker(type: WorkerType): type is LocalWorkerType;
+/**
+ * Get model ID from model type
+ */
+export declare function getModelId(model: ModelType): string;
+/**
+ * Get worker configuration by type
+ */
+export declare function getWorkerConfig(type: WorkerType): HeadlessWorkerConfig | undefined;
+/**
+ * HeadlessWorkerExecutor - Executes workers using Claude Code in headless mode
+ *
+ * Features:
+ * - Process pool with configurable concurrency limit
+ * - Pending queue for overflow requests
+ * - Context caching with configurable TTL
+ * - Execution logging for debugging
+ * - Event emission for monitoring
+ * - Graceful termination
+ */
+export declare class HeadlessWorkerExecutor extends EventEmitter {
+    private projectRoot;
+    private config;
+    private processPool;
+    private pendingQueue;
+    private contextCache;
+    private claudeCodeAvailable;
+    private claudeCodeVersion;
+    constructor(projectRoot: string, options?: HeadlessExecutorConfig);
+    /**
+     * Check if Claude Code CLI is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get Claude Code version
+     */
+    getVersion(): Promise<string | null>;
+    /**
+     * Execute a headless worker
+     */
+    execute(workerType: HeadlessWorkerType, configOverrides?: Partial<HeadlessOptions>): Promise<HeadlessExecutionResult>;
+    /**
+     * Get pool status
+     */
+    getPoolStatus(): PoolStatus;
+    /**
+     * Get number of active executions
+     */
+    getActiveCount(): number;
+    /**
+     * Cancel a running execution
+     */
+    cancel(executionId: string): boolean;
+    /**
+     * Cancel all running executions
+     */
+    cancelAll(): number;
+    /**
+     * Clear context cache
+     */
+    clearContextCache(): void;
+    /**
+     * Get worker configuration
+     */
+    getConfig(workerType: HeadlessWorkerType): HeadlessWorkerConfig | undefined;
+    /**
+     * Get all headless worker types
+     */
+    getHeadlessWorkerTypes(): HeadlessWorkerType[];
+    /**
+     * Get all local worker types
+     */
+    getLocalWorkerTypes(): LocalWorkerType[];
+    /**
+     * Ensure log directory exists
+     */
+    private ensureLogDir;
+    /**
+     * Internal execution logic
+     */
+    private executeInternal;
+    /**
+     * Process the pending queue
+     */
+    private processQueue;
+    /**
+     * Build context from file patterns
+     */
+    private buildContext;
+    /**
+     * Simple glob implementation for file matching
+     */
+    private simpleGlob;
+    /**
+     * Match filename against a simple pattern
+     */
+    private matchesPattern;
+    /**
+     * Build full prompt with context
+     */
+    private buildPrompt;
+    /**
+     * Execute Claude Code in headless mode
+     */
+    private executeClaudeCode;
+    /**
+     * Parse JSON output from Claude Code
+     */
+    private parseJsonOutput;
+    /**
+     * Parse markdown output into sections
+     */
+    private parseMarkdownOutput;
+    /**
+     * Create an error result
+     */
+    private createErrorResult;
+    /**
+     * Log execution details for debugging
+     */
+    private logExecution;
+}
+export default HeadlessWorkerExecutor;
+//# sourceMappingURL=headless-worker-executor.d.ts.map

package/dist/src/services/headless-worker-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-worker-executor.d.ts","sourceRoot":"","sources":["../../../src/services/headless-worker-executor.ts"],"names":[],"mappings":"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"}