wraptc 1.0.2 → 1.0.4

package/src/core/config.ts

@@ -0,0 +1,290 @@
+import { rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { Command } from "commander";
+import type { Config } from "./types";
+import { ConfigSchema } from "./types";
+
+export interface ConfigLoaderOptions {
+  configPath?: string;
+  projectConfigPath?: string;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+export class ConfigLoader {
+  private options: ConfigLoaderOptions;
+
+  constructor(options: ConfigLoaderOptions = {}) {
+    this.options = options;
+  }
+
+  async loadConfig(): Promise<Config> {
+    // Load configs from different sources in order of precedence
+    const configs: Config[] = [];
+
+    // 1. Built-in defaults
+    configs.push(this.getDefaultConfig());
+
+    // 2. System config (optional)
+    const systemConfig = await this.loadSystemConfig();
+    if (systemConfig) {
+      configs.push(systemConfig);
+    }
+
+    // 3. User config
+    const userConfig = await this.loadUserConfig();
+    if (userConfig) {
+      configs.push(userConfig);
+    }
+
+    // 4. Project config
+    const projectConfig = await this.loadProjectConfig();
+    if (projectConfig) {
+      configs.push(projectConfig);
+    }
+
+    // 5. Env variables (WTC_*)
+    const envConfig = this.loadEnvConfig();
+    if (envConfig) {
+      configs.push(envConfig);
+    }
+
+    // Merge all configs
+    const merged = this.mergeConfigs(configs);
+
+    // Validate with Zod
+    const result = ConfigSchema.safeParse(merged);
+    if (!result.success) {
+      throw new Error(`Invalid configuration: ${result.error.message}`);
+    }
+
+    return result.data;
+  }
+
+  private getDefaultConfig(): Config {
+    return {
+      routing: {
+        defaultOrder: ["gemini", "opencode", "qwen-code", "codex"],
+        perModeOverride: {
+          test: ["codex", "gemini"],
+          explain: ["gemini", "qwen-code"],
+        },
+      },
+      providers: {
+        gemini: {
+          binary: "gemini",
+          args: [],
+          jsonMode: "flag",
+          jsonFlag: "--output-format",
+          streamingMode: "jsonl",
+          capabilities: ["generate", "edit", "explain", "test"],
+        },
+        opencode: {
+          binary: "opencode",
+          args: [],
+          jsonMode: "flag",
+          jsonFlag: "-f",
+          streamingMode: "none",
+          capabilities: ["generate", "edit", "explain", "test", "refactor"],
+        },
+        "qwen-code": {
+          binary: "qwen",
+          args: [],
+          jsonMode: "flag",
+          jsonFlag: "--json",
+          streamingMode: "jsonl",
+          capabilities: ["generate", "edit", "explain", "test"],
+        },
+        codex: {
+          binary: "codex",
+          args: [],
+          jsonMode: "none",
+          streamingMode: "line",
+          capabilities: ["generate", "edit", "test"],
+        },
+      },
+      credits: {
+        providers: {
+          gemini: {
+            dailyRequestLimit: 1000,
+            resetHourUtc: 0,
+          },
+          opencode: {
+            dailyRequestLimit: 1000,
+            resetHourUtc: 0,
+          },
+          "qwen-code": {
+            dailyRequestLimit: 2000,
+            resetHourUtc: 0,
+          },
+          codex: {
+            plan: "chatgpt_plus",
+          },
+        },
+      },
+    };
+  }
+
+  private async loadSystemConfig(): Promise<Config | null> {
+    const systemPath = "/etc/wrap-terminalcoder/config.json";
+    return this.loadConfigFile(systemPath);
+  }
+
+  private async loadUserConfig(): Promise<Config | null> {
+    const userPath = join(process.env.HOME || "~", ".config", "wrap-terminalcoder", "config.json");
+    return this.loadConfigFile(userPath);
+  }
+
+  private async loadProjectConfig(): Promise<Config | null> {
+    const projectPath = this.options.projectConfigPath || ".config/wraptc/config.json";
+    return this.loadConfigFile(projectPath);
+  }
+
+  private async loadConfigFile(filePath: string): Promise<Config | null> {
+    // Use Bun.file() for async file existence check and reading
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      return null;
+    }
+
+    // File exists - now errors are meaningful and should be reported
+    try {
+      const content = await file.text();
+      const parsed = JSON.parse(content);
+
+      if (this.options.debug) {
+        console.debug(`[ConfigLoader] Loaded config from ${filePath}`);
+      }
+      return parsed;
+    } catch (error) {
+      // File exists but couldn't be read or parsed - this is a real error
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (errorMessage.includes("JSON")) {
+        throw new Error(`Invalid JSON in config file ${filePath}: ${errorMessage}`);
+      }
+      throw new Error(`Failed to read config file ${filePath}: ${errorMessage}`);
+    }
+  }
+
+  private loadEnvConfig(): Config | null {
+    const envVars = Object.entries(process.env).filter(([key]) => key.startsWith("WTC_"));
+
+    if (envVars.length === 0) {
+      return null;
+    }
+
+    const config: any = {};
+
+    for (const [key, value] of envVars) {
+      // Convert WTC_ROUTING__DEFAULT_ORDER='["qwen-code","gemini"]' to config.routing.defaultOrder
+      const path = key
+        .replace(/^WTC_/, "")
+        .toLowerCase()
+        .split("__")
+        .map((segment) => this.camelCase(segment));
+
+      this.setNestedProperty(config, path, this.parseEnvValue(value));
+    }
+
+    return config;
+  }
+
+  private camelCase(str: string): string {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  }
+
+  private parseEnvValue(value: string | undefined): any {
+    if (!value) return value;
+    // Try to parse as JSON first
+    try {
+      return JSON.parse(value);
+    } catch {
+      // If not JSON, return as string
+      return value;
+    }
+  }
+
+  private setNestedProperty(obj: any, path: string[], value: any): void {
+    if (path.length === 0) {
+      // For empty path, set the value directly on the object
+      obj[""] = value;
+      return;
+    }
+
+    let current = obj;
+
+    for (let i = 0; i < path.length - 1; i++) {
+      const key = path[i];
+      if (!(key in current)) {
+        current[key] = {};
+      }
+      current = current[key];
+    }
+
+    current[path[path.length - 1]] = value;
+  }
+
+  private mergeConfigs(configs: Config[]): Config {
+    // Deep merge all configs, with later configs overriding earlier ones
+    const merged = configs.reduce((acc, config) => {
+      return this.deepMerge(acc, config);
+    }, {} as Config);
+
+    return merged;
+  }
+
+  private deepMerge(target: any, source: any): any {
+    const result = { ...target };
+
+    for (const key in source) {
+      if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+        result[key] = this.deepMerge(result[key] || {}, source[key]);
+      } else {
+        result[key] = source[key];
+      }
+    }
+
+    return result;
+  }
+
+  async saveConfig(config: Config, path?: string): Promise<void> {
+    const configPath = path || this.options.configPath || this.getDefaultUserConfigPath();
+
+    // Ensure directory exists using Bun shell
+    const dir = dirname(configPath);
+    await Bun.$`mkdir -p ${dir}`.quiet();
+
+    // Write atomically: write to temp file, then rename
+    const tempPath = `${configPath}.tmp`;
+
+    // Use Bun.write() for faster file writing
+    await Bun.write(tempPath, JSON.stringify(config, null, 2));
+
+    // Atomic rename
+    await rename(tempPath, configPath);
+  }
+
+  private getDefaultUserConfigPath(): string {
+    return join(process.env.HOME || "~", ".config", "wrap-terminalcoder", "config.json");
+  }
+}
+
+export function addCLIConfigOverrides(command: Command): void {
+  command
+    .option("--provider <provider>", "Override provider")
+    .option("--routing-default-order <order>", "Override routing default order (JSON array)")
+    .option("--config <path>", "Config file path")
+    .hook("preAction", async (thisCommand) => {
+      const opts = thisCommand.opts();
+
+      // Convert CLI options to env variables temporarily
+      if (opts.provider) {
+        process.env.WTC_REQUEST__PROVIDER = opts.provider;
+      }
+      if (opts.routingDefaultOrder) {
+        process.env.WTC_ROUTING__DEFAULT_ORDER = opts.routingDefaultOrder;
+      }
+    });
+}

package/src/core/define-provider.ts

@@ -0,0 +1,212 @@
+/**
+ * defineProvider - Helper for creating CLI provider configurations
+ *
+ * This enables users to add new CLI tools by creating a simple .ts file:
+ *
+ * ```typescript
+ * // ~/.config/wraptc/providers/my-cli.ts
+ * import { defineProvider } from "wrap-terminalcoder";
+ *
+ * export default defineProvider({
+ *   id: "my-cli",
+ *   binary: "my-cli",
+ *   input: { method: "positional" },
+ *   output: { format: "json", textField: "response" },
+ * });
+ * ```
+ */
+
+import { z } from "zod";
+import type { CodingRequest, ProviderErrorContext, ProviderErrorKind, TokenUsage } from "./types";
+
+// Input configuration - how to pass the prompt to the CLI
+export const InputConfigSchema = z
+  .object({
+    // stdin: pipe prompt to stdin
+    // positional: pass prompt as positional argument
+    // flag: pass prompt with a flag (e.g., --prompt "...")
+    method: z.enum(["stdin", "positional", "flag"]).default("stdin"),
+    // Flag name if method is "flag" (e.g., "--prompt")
+    flag: z.string().optional(),
+    // Position if method is "positional" (first or last argument)
+    position: z.enum(["first", "last"]).default("last"),
+  })
+  .default({ method: "stdin" });
+
+// Output configuration - how to parse CLI output
+export const OutputConfigSchema = z
+  .object({
+    // text: raw stdout as response
+    // json: parse JSON, extract textField
+    // jsonl: parse JSON lines
+    format: z.enum(["text", "json", "jsonl"]).default("text"),
+    // Field containing the text response (for json format)
+    textField: z.string().optional(),
+    // Field containing usage info (for json format)
+    usageField: z.string().optional(),
+  })
+  .default({ format: "text" });
+
+// Streaming configuration
+export const StreamingConfigSchema = z
+  .object({
+    // none: no streaming support
+    // line: emit each line as text_delta
+    // jsonl: parse JSON lines and emit as chunks
+    mode: z.enum(["none", "line", "jsonl"]).default("none"),
+  })
+  .default({ mode: "none" });
+
+// Args configuration - how to build command line arguments
+export const ArgsConfigSchema = z
+  .object({
+    // Base arguments always included
+    base: z.array(z.string()).default([]),
+    // Flag to enable JSON output (e.g., "-o json" or "--format json")
+    jsonFlag: z.string().optional(),
+    // Flag to enable streaming
+    streamFlag: z.string().optional(),
+    // Flag for model selection (e.g., "--model")
+    modelFlag: z.string().optional(),
+    // Flag for file context (e.g., "-f" - will be repeated for each file)
+    fileFlag: z.string().optional(),
+    // Flag for max tokens (e.g., "--max-tokens")
+    maxTokensFlag: z.string().optional(),
+    // Flag for temperature (e.g., "--temperature" or "-t")
+    temperatureFlag: z.string().optional(),
+    // Flag for language (e.g., "--language" or "-l")
+    languageFlag: z.string().optional(),
+    // Flag for system prompt (e.g., "--system" or "-S")
+    systemPromptFlag: z.string().optional(),
+    // How to handle system prompt
+    systemPromptMethod: z.enum(["flag", "combined"]).optional(),
+  })
+  .default({ base: [] });
+
+// Error patterns - strings to match in stderr/stdout for error classification
+export const ErrorPatternsSchema = z.record(z.array(z.string())).optional();
+
+// Retry configuration schema
+export const RetryConfigSchema = z
+  .object({
+    // Maximum number of retry attempts (1 = no retries)
+    maxAttempts: z.number().default(1),
+    // Initial delay between retries in milliseconds
+    delayMs: z.number().default(1000),
+    // Multiplier for exponential backoff
+    backoffMultiplier: z.number().default(2),
+    // Error kinds that should trigger a retry
+    retryOn: z.array(z.string()).default(["TRANSIENT"]),
+  })
+  .optional();
+
+// Main provider definition schema
+export const ProviderDefinitionSchema = z.object({
+  // Unique identifier for the provider
+  id: z.string(),
+  // Display name (defaults to id)
+  displayName: z.string().optional(),
+  // Path to the CLI binary
+  binary: z.string(),
+  // Subcommand to invoke (e.g., "exec", "run", "chat")
+  subcommand: z.string().optional(),
+
+  // Environment variables to set for the process
+  env: z.record(z.string()).optional(),
+  // Default working directory for the process
+  defaultCwd: z.string().optional(),
+
+  // Input handling configuration
+  input: InputConfigSchema,
+  // Output parsing configuration
+  output: OutputConfigSchema,
+  // Streaming configuration
+  streaming: StreamingConfigSchema,
+  // Arguments configuration
+  args: ArgsConfigSchema,
+
+  // Error patterns for classification
+  errors: ErrorPatternsSchema,
+  // Exit codes to treat as success (default: [0])
+  allowedExitCodes: z.array(z.number()).default([0]),
+
+  // Timeout in milliseconds (default: 60000 = 1 minute)
+  timeoutMs: z.number().optional(),
+  // Retry configuration for transient errors
+  retry: RetryConfigSchema,
+
+  // Capabilities this provider supports
+  capabilities: z.array(z.string()).default(["generate"]),
+});
+
+// Inferred type from schema
+export type ProviderDefinitionBase = z.infer<typeof ProviderDefinitionSchema>;
+
+// Full provider definition including optional function overrides
+export interface ProviderDefinition extends ProviderDefinitionBase {
+  /**
+   * Custom argument building logic.
+   * Called instead of default arg building when provided.
+   */
+  buildArgs?: (req: CodingRequest) => string[];
+
+  /**
+   * Custom output parsing logic.
+   * Called instead of default parsing when provided.
+   */
+  parseOutput?: (stdout: string) => { text: string; usage?: TokenUsage };
+
+  /**
+   * Custom error classification logic.
+   * Called instead of default pattern matching when provided.
+   */
+  classifyError?: (ctx: ProviderErrorContext) => ProviderErrorKind;
+
+  /**
+   * Custom input handling.
+   * Returns the string to pipe to stdin, or undefined to use args only.
+   */
+  getStdinInput?: (req: CodingRequest) => string | undefined;
+}
+
+// Input type for defineProvider (allows partial nested objects)
+export type ProviderDefinitionInput = Omit<
+  ProviderDefinition,
+  "input" | "output" | "streaming" | "args" | "capabilities"
+> & {
+  input?: Partial<z.infer<typeof InputConfigSchema>>;
+  output?: Partial<z.infer<typeof OutputConfigSchema>>;
+  streaming?: Partial<z.infer<typeof StreamingConfigSchema>>;
+  args?: Partial<z.infer<typeof ArgsConfigSchema>>;
+  capabilities?: string[];
+};
+
+/**
+ * Define a CLI provider with full TypeScript support.
+ *
+ * @example
+ * ```typescript
+ * export default defineProvider({
+ *   id: "my-cli",
+ *   binary: "my-cli",
+ *   input: { method: "positional" },
+ *   output: { format: "json", textField: "response" },
+ * });
+ * ```
+ */
+export function defineProvider(config: ProviderDefinitionInput): ProviderDefinition {
+  // Validate base config with Zod
+  const validated = ProviderDefinitionSchema.parse(config);
+
+  // Merge with function overrides
+  return {
+    ...validated,
+    buildArgs: config.buildArgs,
+    parseOutput: config.parseOutput,
+    classifyError: config.classifyError,
+    getStdinInput: config.getStdinInput,
+  };
+}
+
+// Re-export from centralized error patterns module
+export { DEFAULT_ERROR_PATTERNS, classifyErrorDefault } from "./error-patterns";

package/src/core/error-patterns.ts

@@ -0,0 +1,147 @@
+/**
+ * Centralized Error Pattern Registry
+ *
+ * This module provides a unified set of error patterns for classifying
+ * errors across all providers. Providers can extend these patterns
+ * with provider-specific patterns.
+ */
+
+import type { ProviderErrorKind } from "./types";
+
+/**
+ * Default error patterns used by all providers
+ * Patterns are matched case-insensitively against stderr + stdout
+ */
+export const DEFAULT_ERROR_PATTERNS: Record<ProviderErrorKind, string[]> = {
+  OUT_OF_CREDITS: [
+    "quota exceeded",
+    "out of quota",
+    "out of credits",
+    "credits exhausted",
+    "insufficient quota",
+    "no credits remaining",
+    "credit limit",
+    "you've exceeded your quota",
+  ],
+  RATE_LIMIT: ["rate limit", "rate_limit", "too many requests", "429", "throttle", "slow down"],
+  BAD_REQUEST: [
+    "bad request",
+    "invalid request",
+    "malformed",
+    "400",
+    "validation error",
+    "invalid parameter",
+  ],
+  UNAUTHORIZED: [
+    "unauthorized",
+    "authentication failed",
+    "invalid api key",
+    "api key invalid",
+    "api key missing",
+    "401",
+  ],
+  FORBIDDEN: ["forbidden", "permission denied", "access denied", "403"],
+  NOT_FOUND: ["not found", "404", "no such file", "command not found", "model not found"],
+  TIMEOUT: ["timeout", "timed out", "deadline exceeded", "request timeout"],
+  CONTEXT_LENGTH: [
+    "context length",
+    "too long",
+    "max tokens",
+    "token limit",
+    "context too large",
+    "input too long",
+  ],
+  CONTENT_FILTER: ["content filter", "blocked", "safety", "moderation", "policy violation"],
+  INTERNAL: ["internal error", "internal server error", "server error", "500", "502", "503"],
+  TRANSIENT: [
+    "temporarily unavailable",
+    "service unavailable",
+    "connection refused",
+    "econnrefused",
+    "econnreset",
+    "network error",
+    "connection reset",
+    "socket hang up",
+  ],
+  UNKNOWN: [],
+};
+
+/**
+ * Classify an error based on the combined output using default patterns
+ */
+export function classifyErrorDefault(
+  stderr = "",
+  stdout = "",
+  exitCode?: number | null,
+  httpStatus?: number,
+): ProviderErrorKind {
+  // HTTP status code based classification takes priority
+  if (httpStatus) {
+    if (httpStatus === 401) return "UNAUTHORIZED";
+    if (httpStatus === 403) return "FORBIDDEN";
+    if (httpStatus === 404) return "NOT_FOUND";
+    if (httpStatus === 429) return "RATE_LIMIT";
+    if (httpStatus >= 500) return "INTERNAL";
+  }
+
+  const combined = (stderr + stdout).toLowerCase();
+
+  for (const [kind, patterns] of Object.entries(DEFAULT_ERROR_PATTERNS)) {
+    if (patterns.some((p) => combined.includes(p.toLowerCase()))) {
+      return kind as ProviderErrorKind;
+    }
+  }
+
+  // Check exit codes for common error types
+  if (exitCode === 127) {
+    return "NOT_FOUND"; // Command not found
+  }
+
+  return "TRANSIENT";
+}
+
+/**
+ * Merge provider-specific patterns with default patterns
+ */
+export function mergeErrorPatterns(
+  providerPatterns: Partial<Record<ProviderErrorKind, string[]>>,
+): Record<ProviderErrorKind, string[]> {
+  const merged = { ...DEFAULT_ERROR_PATTERNS };
+
+  for (const [kind, patterns] of Object.entries(providerPatterns)) {
+    if (patterns) {
+      merged[kind as ProviderErrorKind] = [
+        ...patterns,
+        ...DEFAULT_ERROR_PATTERNS[kind as ProviderErrorKind],
+      ];
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Create a classifier function with merged patterns
+ */
+export function createErrorClassifier(
+  providerPatterns: Partial<Record<ProviderErrorKind, string[]>> = {},
+): (stderr?: string, stdout?: string, exitCode?: number | null) => ProviderErrorKind {
+  const patterns = mergeErrorPatterns(providerPatterns);
+
+  return (stderr = "", stdout = "", exitCode?: number | null): ProviderErrorKind => {
+    const combined = (stderr + stdout).toLowerCase();
+
+    for (const [kind, kindPatterns] of Object.entries(patterns)) {
+      if (kindPatterns.some((p) => combined.includes(p.toLowerCase()))) {
+        return kind as ProviderErrorKind;
+      }
+    }
+
+    // Check exit codes for common error types
+    if (exitCode === 127) {
+      return "NOT_FOUND";
+    }
+
+    return "TRANSIENT";
+  };
+}