@winspan/claude-forge 8.53.2 → 8.54.3

package/src/cli/index.ts

@@ -1,42 +0,0 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import { createRequire } from 'module';
-import { register as registerInit } from './commands/init.js';
-import { register as registerDaemon } from './commands/daemon.js';
-import { register as registerStatus } from './commands/status.js';
-import { register as registerConfig } from './commands/config.js';
-import { register as registerClaudeMd } from './commands/claudemd.js';
-import { register as registerSkills } from './commands/skills.js';
-import { register as registerLogs } from './commands/logs.js';
-import { register as registerMcp } from './commands/mcp.js';
-import { registerMenuCommand } from './commands/menu.js';
-import { createTemplateCommand } from './commands/template.js';
-import { createStatsCommand } from './commands/stats.js';
-import { registerExecutionsCommand } from './commands/executions.js';
-import { register as registerTrace } from './commands/trace.js';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../../package.json') as { version: string };
-
-const program = new Command();
-program
-  .name('claude-forge')
-  .alias('cf')
-  .description('Claude Code governance engine')
-  .version(version);
-
-registerInit(program);
-registerDaemon(program);
-registerStatus(program);
-registerConfig(program);
-registerClaudeMd(program);
-registerSkills(program);
-registerLogs(program);
-registerMcp(program);
-registerMenuCommand(program);
-program.addCommand(createTemplateCommand());
-program.addCommand(createStatsCommand());
-registerExecutionsCommand(program);
-registerTrace(program);
-
-program.parseAsync();

package/src/cli/init/hook-manager.ts

@@ -1,132 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import { FORGE_PATHS } from '../../core/constants.js';
-
-export const CLAUDE_HOME = path.join(os.homedir(), '.claude');
-export const SETTINGS_PATH = path.join(CLAUDE_HOME, 'settings.json');
-export const HOOKS_DIR = FORGE_PATHS.hooks();
-
-export const HOOK_SCRIPT_NAMES = [
-  'pre-tool-use.sh',
-  'post-tool-use.sh',
-  'user-prompt-submit.sh',
-  'notification.sh',
-  'stop.sh',
-] as const;
-
-interface HookCommand {
-  type: string;
-  command: string;
-}
-
-interface HookMatcherBlock {
-  matcher: string;
-  hooks: HookCommand[];
-}
-
-interface ClaudeSettings {
-  hooks?: Record<string, HookMatcherBlock[]>;
-  [key: string]: unknown;
-}
-
-function isForgeCommand(cmd: string): boolean {
-  return cmd.includes('claude-forge') || cmd.includes('.claude-forge');
-}
-
-function entryRefersToForge(entry: HookMatcherBlock): boolean {
-  return entry.hooks.some((h) => isForgeCommand(h.command));
-}
-
-function getForgeHookEntries(): Record<string, HookMatcherBlock> {
-  return {
-    PreToolUse: {
-      matcher: '',
-      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'pre-tool-use.sh')}` }],
-    },
-    PostToolUse: {
-      matcher: '',
-      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'post-tool-use.sh')}` }],
-    },
-    UserPromptSubmit: {
-      matcher: '',
-      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'user-prompt-submit.sh')}` }],
-    },
-    Notification: {
-      matcher: '',
-      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'notification.sh')}` }],
-    },
-    Stop: {
-      matcher: '',
-      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'stop.sh')}` }],
-    },
-  };
-}
-
-/**
- * Copy hook shell scripts from the package to ~/.claude-forge/hooks/
- */
-export function copyHookScripts(): void {
-  if (!fs.existsSync(HOOKS_DIR)) {
-    fs.mkdirSync(HOOKS_DIR, { recursive: true });
-  }
-
-  const srcHooksDir = path.resolve(
-    path.dirname(new URL(import.meta.url).pathname),
-    '../../hooks',
-  );
-
-  for (const file of HOOK_SCRIPT_NAMES) {
-    const src = path.join(srcHooksDir, file);
-    const dest = path.join(HOOKS_DIR, file);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, dest);
-      fs.chmodSync(dest, 0o755);
-    }
-  }
-}
-
-/**
- * Backup Claude Code settings.json before modifying it.
- * Returns the backup path, or null if no settings file exists.
- */
-export function backupSettings(): string | null {
-  if (!fs.existsSync(SETTINGS_PATH)) return null;
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const backupPath = `${SETTINGS_PATH}.backup-${timestamp}`;
-  fs.copyFileSync(SETTINGS_PATH, backupPath);
-  return backupPath;
-}
-
-/**
- * Inject Forge hook entries into Claude Code settings.json.
- * Idempotent: skips hooks that are already present.
- */
-export function injectHooks(): void {
-  let settings: ClaudeSettings = {};
-
-  if (fs.existsSync(SETTINGS_PATH)) {
-    settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8')) as ClaudeSettings;
-  }
-
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-
-  const forgeHooks = getForgeHookEntries();
-
-  for (const [hookType, block] of Object.entries(forgeHooks)) {
-    const existing = (settings.hooks[hookType] ?? []) as HookMatcherBlock[];
-    const alreadyInjected = existing.some((item) => entryRefersToForge(item));
-
-    if (!alreadyInjected) {
-      settings.hooks[hookType] = [...existing, block];
-    }
-  }
-
-  if (!fs.existsSync(CLAUDE_HOME)) {
-    fs.mkdirSync(CLAUDE_HOME, { recursive: true });
-  }
-
-  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf-8');
-}

package/src/core/ai/provider.ts

@@ -1,308 +0,0 @@
-/**
- * Claude AI provider — wrapper around @anthropic-ai/sdk.
- *
- * Adds per-request timeout (AbortController) and bounded retry with exponential
- * backoff for transient failures (AbortError / 429 / 5xx / network errors).
- * SDK's built-in retry is disabled (maxRetries: 0) to avoid double retry layers.
- */
-
-import { promises as fs } from 'node:fs';
-import Anthropic from '@anthropic-ai/sdk';
-import type {
-  AIResponse,
-  CompleteOptions,
-  ImageInput,
-  SupportedImageMediaType,
-} from './types.js';
-
-/**
- * Options for `completeWithImage`. Inherits all transport knobs from
- * `CompleteOptions` and adds the image list.
- */
-export interface CompleteWithImageOptions extends CompleteOptions {
-  /** One or more images to include before the text prompt. */
-  images: ImageInput[];
-}
-import { logger } from '../utils/logger.js';
-import { DEFAULTS } from '../constants.js';
-
-const DEFAULT_MAX_TOKENS = 4096;
-const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_MAX_RETRIES = 2;
-const MAX_BACKOFF_MS = 8_000;
-
-const SUPPORTED_IMAGE_MEDIA_TYPES: ReadonlySet<SupportedImageMediaType> = new Set([
-  'image/png',
-  'image/jpeg',
-  'image/gif',
-  'image/webp',
-]);
-
-/** Sleep helper — exported via object indirection so tests can stub it. */
-export const timing = {
-  delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  },
-};
-
-/** @deprecated Use `timing.delay`; kept for backward compatibility. */
-export function delay(ms: number): Promise<void> {
-  return timing.delay(ms);
-}
-
-/**
- * Determine whether an error from the Anthropic SDK (or network layer) is
- * worth retrying. Covers:
- *   - Abort (our own timeout fires an AbortController)
- *   - 429 rate limit
- *   - 5xx server errors
- *   - Connection / network errors without a status code
- */
-function isRetriable(err: unknown): boolean {
-  if (!err || typeof err !== 'object') return false;
-  const e = err as { name?: string; status?: number; code?: string };
-
-  if (e.name === 'AbortError' || e.name === 'APIUserAbortError') return true;
-  if (typeof e.status === 'number') {
-    if (e.status === 429) return true;
-    if (e.status >= 500 && e.status < 600) return true;
-    return false;
-  }
-  // No HTTP status -> typically a connection error, worth retrying.
-  if (e.name === 'APIConnectionError' || e.name === 'APIConnectionTimeoutError') return true;
-  if (e.code === 'ECONNRESET' || e.code === 'ETIMEDOUT' || e.code === 'ENOTFOUND') return true;
-  return false;
-}
-
-function computeBackoffMs(attempt: number): number {
-  return Math.min(1000 * Math.pow(2, attempt), MAX_BACKOFF_MS);
-}
-
-/** Shape required for `messages.create`'s `messages[].content` parameter. */
-type ClaudeContentBlockParam =
-  | Anthropic.TextBlockParam
-  | Anthropic.ImageBlockParam
-  | Anthropic.ToolUseBlockParam
-  | Anthropic.ToolResultBlockParam;
-
-type ClaudeUserContent = string | ClaudeContentBlockParam[];
-
-export class ClaudeProvider {
-  // Exposed for tests; production code treats it as private.
-  /** @internal */
-  client: Anthropic;
-  private model: string;
-  private callCount = 0;
-  private totalTokens = 0;
-  private totalErrors = 0;
-  private totalLatencyMs = 0;
-
-  constructor(apiKey: string, model?: string, baseUrl?: string) {
-    this.model = model || DEFAULTS.AI_MODEL;
-    this.client = new Anthropic({
-      apiKey,
-      ...(baseUrl ? { baseURL: baseUrl } : {}),
-    });
-  }
-
-  async complete(prompt: string, options?: CompleteOptions): Promise<string> {
-    const response = await this.completeWithUsage(prompt, options);
-    return response.text;
-  }
-
-  async completeWithUsage(prompt: string, options?: CompleteOptions): Promise<AIResponse> {
-    return this.runMessageRequest(prompt, options);
-  }
-
-  /**
-   * Vision-aware completion. Reads each `ImageInput` from disk, base64-encodes
-   * it, and packs the images followed by the text prompt into a single user
-   * message (Claude Vision format).
-   *
-   * Reuses the same retry/timeout pipeline as `completeWithUsage`. Validation
-   * (file existence, media type) runs before the first attempt so bad inputs
-   * fail fast and don't consume retry budget.
-   */
-  async completeWithImage(
-    prompt: string,
-    options: CompleteWithImageOptions,
-  ): Promise<string> {
-    if (!options.images || options.images.length === 0) {
-      throw new Error('completeWithImage: at least one image is required');
-    }
-
-    const imageBlocks = await Promise.all(
-      options.images.map((img) => this.encodeImageBlock(img)),
-    );
-
-    const content: ClaudeContentBlockParam[] = [
-      ...imageBlocks,
-      { type: 'text', text: prompt },
-    ];
-
-    // Strip `images` so the rest of the option bag flows through unchanged.
-    const { images: _images, ...rest } = options;
-    void _images;
-
-    const response = await this.runMessageRequest(content, rest);
-    return response.text;
-  }
-
-  /**
-   * Read an image file and turn it into an Anthropic `ImageBlockParam` with a
-   * base64 source. Validates media type and surfaces a clear error if the file
-   * is missing.
-   */
-  private async encodeImageBlock(img: ImageInput): Promise<Anthropic.ImageBlockParam> {
-    if (!SUPPORTED_IMAGE_MEDIA_TYPES.has(img.mediaType)) {
-      throw new Error(
-        `completeWithImage: unsupported media type "${img.mediaType}". ` +
-          `Supported: ${[...SUPPORTED_IMAGE_MEDIA_TYPES].join(', ')}`,
-      );
-    }
-
-    let buffer: Buffer;
-    try {
-      buffer = await fs.readFile(img.path);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      throw new Error(`completeWithImage: failed to read image at "${img.path}": ${reason}`);
-    }
-
-    return {
-      type: 'image',
-      source: {
-        type: 'base64',
-        media_type: img.mediaType,
-        data: buffer.toString('base64'),
-      },
-    };
-  }
-
-  /**
-   * Core request loop shared by text-only and vision completions. Accepts
-   * already-built user content (string or content blocks) and returns the
-   * unwrapped text plus usage metadata.
-   */
-  private async runMessageRequest(
-    content: ClaudeUserContent,
-    options?: CompleteOptions,
-  ): Promise<AIResponse> {
-    this.callCount++;
-    const modelUsed = options?.model || this.model;
-    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const externalSignal = options?.signal;
-
-    let lastErr: unknown;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      const start = Date.now();
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-      // Forward external aborts into our controller so both sources cancel
-      // the in-flight request.
-      const onExternalAbort = () => controller.abort();
-      if (externalSignal) {
-        if (externalSignal.aborted) controller.abort();
-        else externalSignal.addEventListener('abort', onExternalAbort, { once: true });
-      }
-
-      try {
-        const response = await this.client.messages.create(
-          {
-            model: modelUsed,
-            max_tokens: options?.maxTokens || DEFAULT_MAX_TOKENS,
-            ...(options?.system ? { system: options.system } : {}),
-            messages: [{ role: 'user', content }],
-          },
-          {
-            signal: controller.signal,
-            // Disable SDK-level retry; this method owns retry semantics.
-            maxRetries: 0,
-            timeout: timeoutMs,
-          },
-        );
-
-        const latency = Date.now() - start;
-        this.totalLatencyMs += latency;
-
-        const usage = response.usage;
-        this.totalTokens += (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0);
-
-        logger.debug(
-          `[AI] ${latency}ms | ${usage?.input_tokens ?? 0}+${usage?.output_tokens ?? 0} tokens` +
-            (attempt > 0 ? ` (after ${attempt} retry)` : ''),
-        );
-
-        const textBlock = response.content.find((c) => c.type === 'text');
-        return {
-          text: textBlock?.text ?? '',
-          usage: usage
-            ? {
-                input_tokens: usage.input_tokens,
-                output_tokens: usage.output_tokens,
-              }
-            : undefined,
-          model: modelUsed,
-        };
-      } catch (err) {
-        this.totalLatencyMs += Date.now() - start;
-        lastErr = err;
-
-        // External caller aborted -> never retry, propagate immediately.
-        if (externalSignal?.aborted) {
-          this.totalErrors++;
-          throw err;
-        }
-
-        const canRetry = attempt < maxRetries && isRetriable(err);
-        if (!canRetry) {
-          this.totalErrors++;
-          logger.error(`[AI] Claude API error: ${err instanceof Error ? err.message : String(err)}`);
-          throw err;
-        }
-
-        const backoffMs = computeBackoffMs(attempt);
-        const reason = err instanceof Error ? err.message : String(err);
-        logger.warn(
-          `[ClaudeProvider] retry ${attempt + 1}/${maxRetries} after ${backoffMs}ms (reason: ${reason})`,
-        );
-        await timing.delay(backoffMs);
-      } finally {
-        clearTimeout(timer);
-        if (externalSignal) {
-          externalSignal.removeEventListener('abort', onExternalAbort);
-        }
-      }
-    }
-
-    // Unreachable: loop either returns or throws. Included for type safety.
-    throw lastErr instanceof Error ? lastErr : new Error('ClaudeProvider: exhausted retries');
-  }
-
-  formatStats(): string {
-    if (this.callCount === 0) return 'AI calls: 0';
-    const avgMs = Math.round(this.totalLatencyMs / this.callCount);
-    return `AI calls: ${this.callCount} | errors: ${this.totalErrors} | tokens: ${this.totalTokens} | avg: ${avgMs}ms | model: ${this.model}`;
-  }
-}
-
-/**
- * Create a ClaudeProvider, resolving API key from env if not provided
- */
-export function createProvider(apiKey?: string, model?: string, baseUrl?: string): ClaudeProvider {
-  const key = apiKey
-    || process.env.ANTHROPIC_API_KEY
-    || process.env.ANTHROPIC_AUTH_TOKEN
-    || '';
-
-  if (!key) {
-    throw new Error(
-      'Missing Claude API key. Set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN environment variable.',
-    );
-  }
-
-  return new ClaudeProvider(key, model, baseUrl || process.env.ANTHROPIC_BASE_URL);
-}

package/src/core/ai/types.ts

@@ -1,51 +0,0 @@
-/**
- * AI Provider types — shared type definitions for AI completions
- */
-
-export interface TokenUsage {
-  input_tokens: number;
-  output_tokens: number;
-}
-
-export interface AIResponse {
-  text: string;
-  usage?: TokenUsage;
-  model?: string;
-}
-
-/**
- * Options for AI completion calls.
- *
- * `timeoutMs` (default 30_000) caps each individual request via AbortController.
- * `maxRetries` (default 2) controls retry attempts for AbortError/429/5xx/network errors.
- * `signal` lets callers abort externally (composed with internal timeout signal).
- */
-export interface CompleteOptions {
-  system?: string;
-  maxTokens?: number;
-  model?: string;
-  timeoutMs?: number;
-  maxRetries?: number;
-  signal?: AbortSignal;
-}
-
-/**
- * Supported media types for vision inputs. The whitelist mirrors what the
- * Anthropic API accepts for `Base64ImageSource` (see SDK `Base64ImageSource`).
- */
-export type SupportedImageMediaType =
-  | 'image/png'
-  | 'image/jpeg'
-  | 'image/gif'
-  | 'image/webp';
-
-/**
- * Local image file passed to a vision-capable provider. The provider is
- * responsible for reading and base64-encoding the file.
- */
-export interface ImageInput {
-  /** Absolute or relative path to the image on disk. */
-  path: string;
-  /** Declared media type; must match the file contents. */
-  mediaType: SupportedImageMediaType;
-}

package/src/core/config.ts

@@ -1,124 +0,0 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import yaml from 'js-yaml';
-import type { ForgeConfig } from './types.js';
-import { FORGE_PATHS, DEFAULTS } from './constants.js';
-
-function defaultConfig(): ForgeConfig {
-  return {
-    ai: {
-      api_key: '',
-      model: DEFAULTS.AI_MODEL,
-      provider: DEFAULTS.AI_PROVIDER,
-    },
-    storage: {
-      path: FORGE_PATHS.database(),
-      max_size_mb: DEFAULTS.STORAGE_MAX_SIZE_MB,
-    },
-    web: {
-      enabled: true,
-      port: DEFAULTS.WEB_PORT,
-    },
-    security: {
-      destructiveOps: true,
-      secretsCheck: true,
-      diffSizeCheck: true,
-      diffSizeThreshold: 300,
-    },
-  };
-}
-
-/**
- * Legacy fields kept for one-shot auto-migration. The historical schema used
- * `distill.{api_key,model,base_url,provider}` plus `classifier_model` /
- * `classifier_timeout` for a deprecated classifier feature. We map any of
- * those onto the new `ai.*` block on first load and rewrite the file.
- */
-interface LegacyConfig {
-  distill?: {
-    api_key?: string;
-    model?: string;
-    base_url?: string;
-    provider?: string;
-    classifier_model?: string;
-    classifier_timeout?: number;
-  };
-}
-
-/**
- * Minimal config manager — reads/writes YAML from ~/.claude-forge/config.yaml
- */
-export class ConfigManager {
-  private config: ForgeConfig | null = null;
-  private readonly configPath: string;
-
-  constructor(configPath?: string) {
-    this.configPath = configPath ?? FORGE_PATHS.config();
-  }
-
-  /**
-   * Load config from disk, merging with defaults for missing fields.
-   * Auto-migrates legacy `distill.*` keys into `ai.*` and rewrites the file.
-   */
-  get(): ForgeConfig {
-    if (this.config) return this.config;
-
-    const defaults = defaultConfig();
-
-    if (!existsSync(this.configPath)) {
-      this.config = defaults;
-      return this.config;
-    }
-
-    try {
-      const raw = readFileSync(this.configPath, 'utf-8');
-      const parsed = yaml.load(raw) as (Partial<ForgeConfig> & LegacyConfig) | null;
-
-      if (!parsed || typeof parsed !== 'object') {
-        this.config = defaults;
-        return this.config;
-      }
-
-      const legacy = parsed.distill;
-      const aiInput = parsed.ai ?? (legacy ? {
-        api_key: legacy.api_key ?? '',
-        model: legacy.model ?? defaults.ai.model,
-        base_url: legacy.base_url,
-        provider: legacy.provider ?? defaults.ai.provider,
-      } : undefined);
-
-      this.config = {
-        ai: { ...defaults.ai, ...aiInput },
-        storage: { ...defaults.storage, ...parsed.storage },
-        web: { ...defaults.web, ...parsed.web },
-        security: { ...defaults.security!, ...parsed.security },
-      } as ForgeConfig;
-
-      // One-shot rewrite if we just upgraded a legacy file.
-      if (legacy && !parsed.ai) {
-        try {
-          this.save();
-        } catch {
-          // Non-fatal: config still works in-memory; user may not have write perms.
-        }
-      }
-
-      return this.config;
-    } catch {
-      this.config = defaults;
-      return this.config;
-    }
-  }
-
-  /**
-   * Write current config to disk
-   */
-  save(): void {
-    const dir = FORGE_PATHS.home();
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-    }
-
-    const content = yaml.dump(this.get(), { lineWidth: 120, noRefs: true });
-    writeFileSync(this.configPath, content, 'utf-8');
-  }
-}