wraptc 1.0.2 → 1.0.4

package/src/core/state.ts

@@ -0,0 +1,258 @@
+import { rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { FullState, ProviderErrorKind, ProviderState } from "./types";
+
+export interface StateManagerOptions {
+  statePath?: string;
+}
+
+export class StateManager {
+  private statePath: string;
+  private state: FullState;
+  private isDirty = false;
+  private saveTimer?: Timer;
+  private initialized = false;
+
+  constructor(options: StateManagerOptions = {}) {
+    this.statePath = options.statePath || this.getDefaultStatePath();
+    this.state = this.createInitialState();
+  }
+
+  private getDefaultStatePath(): string {
+    return join(process.env.HOME || "~", ".config", "wrap-terminalcoder", "state.json");
+  }
+
+  private createInitialState(): FullState {
+    return {
+      version: "1.0.0",
+      providers: {},
+    };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      // Use Bun.file() for faster file reading
+      const file = Bun.file(this.statePath);
+      const exists = await file.exists();
+
+      if (exists) {
+        const data = await file.text();
+        this.state = JSON.parse(data);
+
+        // Reset daily counters if needed
+        await this.resetDailyCountersIfNeeded();
+      }
+    } catch (error) {
+      // If parsing fails or other error, start with initial state
+      console.error("Failed to load state, starting fresh:", error);
+    }
+
+    this.initialized = true;
+  }
+
+  private async resetDailyCountersIfNeeded(): Promise<void> {
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+
+    for (const [_providerId, state] of Object.entries(this.state.providers)) {
+      const lastReset = state.lastReset ? new Date(state.lastReset) : null;
+
+      if (!lastReset || lastReset < today) {
+        state.requestsToday = 0;
+        state.lastReset = now.toISOString();
+        state.outOfCreditsUntil = undefined;
+        // Reset daily tokens saved counter
+        state.tokensSavedToday = 0;
+        this.isDirty = true;
+      }
+    }
+
+    if (this.isDirty) {
+      await this.save();
+    }
+  }
+
+  async getProviderState(providerId: string): Promise<ProviderState> {
+    await this.initialize();
+
+    if (!this.state.providers[providerId]) {
+      this.state.providers[providerId] = {
+        lastUsedAt: undefined,
+        requestsToday: 0,
+        lastReset: undefined,
+        outOfCreditsUntil: undefined,
+        lastErrors: [],
+        consecutiveErrors: 0,
+        tokensSavedToday: 0,
+        totalTokensSaved: 0,
+      };
+      this.isDirty = true;
+    }
+
+    // Ensure new fields exist on existing states (migration)
+    const state = this.state.providers[providerId];
+    if (state.consecutiveErrors === undefined) {
+      state.consecutiveErrors = 0;
+      this.isDirty = true;
+    }
+    if (state.tokensSavedToday === undefined) {
+      state.tokensSavedToday = 0;
+      this.isDirty = true;
+    }
+    if (state.totalTokensSaved === undefined) {
+      state.totalTokensSaved = 0;
+      this.isDirty = true;
+    }
+
+    return state;
+  }
+
+  async recordSuccess(providerId: string, tokensSaved = 0): Promise<void> {
+    const state = await this.getProviderState(providerId);
+    const now = new Date();
+
+    state.lastUsedAt = now.toISOString();
+    state.requestsToday++;
+    state.lastErrors = []; // Clear errors on success
+    state.consecutiveErrors = 0; // Reset error counter on success
+    state.tokensSavedToday += tokensSaved;
+    state.totalTokensSaved += tokensSaved;
+    this.isDirty = true;
+
+    await this.scheduleSave();
+  }
+
+  async recordError(providerId: string, kind: ProviderErrorKind, message: string): Promise<void> {
+    const state = await this.getProviderState(providerId);
+
+    state.lastErrors.push(`[${new Date().toISOString()}] ${kind}: ${message}`);
+    state.consecutiveErrors++;
+
+    // Keep only last 10 errors
+    if (state.lastErrors.length > 10) {
+      state.lastErrors = state.lastErrors.slice(-10);
+    }
+
+    this.isDirty = true;
+
+    await this.scheduleSave();
+  }
+
+  /**
+   * Check if provider should be blacklisted based on error threshold
+   */
+  async shouldBlacklist(providerId: string, errorThreshold: number): Promise<boolean> {
+    const state = await this.getProviderState(providerId);
+    return state.consecutiveErrors >= errorThreshold;
+  }
+
+  /**
+   * Blacklist a provider for a specified duration
+   */
+  async blacklistProvider(providerId: string, durationHours: number): Promise<void> {
+    const until = new Date();
+    until.setHours(until.getHours() + durationHours);
+    await this.markOutOfCredits(providerId, until);
+  }
+
+  /**
+   * Get total tokens saved across all providers
+   */
+  async getTotalTokensSaved(): Promise<number> {
+    await this.initialize();
+    return Object.values(this.state.providers).reduce(
+      (sum, state) => sum + (state.totalTokensSaved || 0),
+      0,
+    );
+  }
+
+  /**
+   * Get tokens saved today across all providers
+   */
+  async getTokensSavedToday(): Promise<number> {
+    await this.initialize();
+    return Object.values(this.state.providers).reduce(
+      (sum, state) => sum + (state.tokensSavedToday || 0),
+      0,
+    );
+  }
+
+  async markOutOfCredits(providerId: string, until: Date): Promise<void> {
+    const state = await this.getProviderState(providerId);
+
+    state.outOfCreditsUntil = until.toISOString();
+    this.isDirty = true;
+
+    await this.scheduleSave();
+  }
+
+  async resetProvider(providerId: string): Promise<void> {
+    const state = await this.getProviderState(providerId);
+
+    state.requestsToday = 0;
+    state.outOfCreditsUntil = undefined;
+    state.lastErrors = [];
+    state.consecutiveErrors = 0;
+    state.tokensSavedToday = 0;
+    // Note: totalTokensSaved is preserved across resets
+    this.isDirty = true;
+
+    await this.scheduleSave();
+  }
+
+  async resetAll(): Promise<void> {
+    this.state = this.createInitialState();
+    this.isDirty = true;
+
+    await this.save();
+  }
+
+  private async scheduleSave(): Promise<void> {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+    }
+
+    // Debounce saves to avoid too many writes
+    this.saveTimer = setTimeout(() => {
+      this.save().catch(console.error);
+    }, 1000);
+  }
+
+  async save(): Promise<void> {
+    if (!this.isDirty) {
+      return;
+    }
+
+    try {
+      // Ensure directory exists using Bun shell
+      const dir = dirname(this.statePath);
+      await Bun.$`mkdir -p ${dir}`.quiet();
+
+      // Write atomically: write to temp file, then rename
+      const tempPath = `${this.statePath}.tmp`;
+
+      // Use Bun.write() for faster file writing
+      await Bun.write(tempPath, JSON.stringify(this.state, null, 2));
+
+      // Atomic rename (still using node:fs rename for reliability)
+      await rename(tempPath, this.statePath);
+    } catch (error) {
+      // Log the error but don't throw to avoid breaking tests
+      console.error("Failed to save state:", error);
+    }
+
+    this.isDirty = false;
+  }
+
+  getState(): FullState {
+    return { ...this.state };
+  }
+
+  getStatePath(): string {
+    return this.statePath;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,206 @@
+// Types for wrap-terminalcoder
+import { z } from "zod";
+
+// Standard coding modes
+export const CodingMode = {
+  GENERATE: "generate",
+  EDIT: "edit",
+  EXPLAIN: "explain",
+  TEST: "test",
+  REVIEW: "review",
+  REFACTOR: "refactor",
+} as const;
+
+export type CodingModeType = (typeof CodingMode)[keyof typeof CodingMode];
+
+// Provider configuration schema
+export const ProviderConfigSchema = z.object({
+  binary: z.string(),
+  args: z.array(z.string()).default([]),
+  jsonMode: z.enum(["none", "flag"]).default("none"),
+  jsonFlag: z.string().optional(),
+  streamingMode: z.enum(["none", "line", "jsonl"]).default("none"),
+  capabilities: z.array(z.string()).default([]),
+  argsTemplate: z.array(z.string()).optional(),
+  // New: default model for this provider
+  defaultModel: z.string().optional(),
+});
+
+// Provider configuration type
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+
+// Provider invoke options
+export interface ProviderInvokeOptions {
+  signal?: AbortSignal;
+  cwd?: string;
+  // Environment variables to pass to the process (merged with provider defaults)
+  env?: Record<string, string>;
+  // Timeout in milliseconds (overrides provider default)
+  timeoutMs?: number;
+}
+
+// Main configuration schema
+export const ConfigSchema = z.object({
+  routing: z.object({
+    defaultOrder: z.array(z.string()),
+    perModeOverride: z.record(z.array(z.string())).optional(),
+  }),
+  providers: z.record(ProviderConfigSchema),
+  credits: z.object({
+    providers: z.record(
+      z.union([
+        z.object({
+          dailyRequestLimit: z.number(),
+          resetHourUtc: z.number(),
+        }),
+        z.object({
+          plan: z.string(),
+        }),
+      ]),
+    ),
+  }),
+});
+
+// Main configuration type
+export type Config = z.infer<typeof ConfigSchema>;
+
+// File context for providing code context
+export const FileContextSchema = z.object({
+  path: z.string(),
+  content: z.string().optional(),
+  language: z.string().optional(),
+});
+
+export type FileContext = z.infer<typeof FileContextSchema>;
+
+// Coding request schema
+export const CodingRequestSchema = z.object({
+  // Required: the main prompt/instruction
+  prompt: z.string(),
+  // Optional: coding mode (generate, edit, explain, test, review, refactor)
+  mode: z.string().optional(),
+  // Optional: specific provider to use (bypasses routing)
+  provider: z.string().optional(),
+  // Optional: specific model to use (provider-specific)
+  model: z.string().optional(),
+  // Optional: enable streaming response
+  stream: z.boolean().optional(),
+  // Optional: file context (renamed from fileContext for consistency)
+  files: z.array(z.union([z.string(), FileContextSchema])).optional(),
+  // Optional: system prompt / instructions
+  systemPrompt: z.string().optional(),
+  // Optional: maximum output tokens
+  maxTokens: z.number().optional(),
+  // Optional: temperature (0-2, default varies by provider)
+  temperature: z.number().min(0).max(2).optional(),
+  // Optional: target language for code generation
+  language: z.string().optional(),
+  // Deprecated: use 'files' instead
+  fileContext: z.array(z.string()).optional(),
+});
+
+// Coding request type
+export interface CodingRequest {
+  prompt: string;
+  mode?: CodingModeType | string;
+  provider?: string;
+  model?: string;
+  stream?: boolean;
+  files?: (string | FileContext)[];
+  systemPrompt?: string;
+  maxTokens?: number;
+  temperature?: number;
+  language?: string;
+  /** @deprecated Use 'files' instead */
+  fileContext?: string[];
+}
+
+// Token usage information
+export interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+
+// Response metadata
+export interface ResponseMeta {
+  elapsedMs?: number;
+  model?: string;
+  finishReason?: "stop" | "length" | "content_filter" | "error";
+}
+
+// Coding response type
+export interface CodingResponse {
+  provider: string;
+  model?: string;
+  text: string;
+  usage?: TokenUsage;
+  meta?: ResponseMeta;
+}
+
+// Streaming event types - unified naming
+export type CodingEvent =
+  // Stream started
+  | { type: "start"; provider: string; model?: string; requestId: string }
+  // Text content delta (incremental text)
+  | { type: "text_delta"; text: string }
+  // Structured chunk (for JSONL mode - parsed JSON object)
+  | { type: "chunk"; data: unknown }
+  // Stream completed successfully
+  | {
+      type: "complete";
+      provider: string;
+      model?: string;
+      text: string;
+      usage?: TokenUsage;
+      finishReason?: "stop" | "length" | "content_filter";
+    }
+  // Error occurred
+  | { type: "error"; provider: string; code: ProviderErrorKind; message: string };
+
+// Error context type
+export interface ProviderErrorContext {
+  stderr?: string;
+  stdout?: string;
+  exitCode?: number | null;
+  httpStatus?: number;
+}
+
+// Error kind enum - expanded
+export type ProviderErrorKind =
+  | "OUT_OF_CREDITS" // Provider credits/quota exhausted
+  | "RATE_LIMIT" // Rate limit hit, retry after cooldown
+  | "BAD_REQUEST" // Invalid request (malformed, missing params)
+  | "UNAUTHORIZED" // Authentication failed (bad API key)
+  | "FORBIDDEN" // Permission denied
+  | "NOT_FOUND" // Resource not found (model, endpoint)
+  | "TIMEOUT" // Request timed out
+  | "CONTEXT_LENGTH" // Input too long for model
+  | "CONTENT_FILTER" // Content blocked by safety filter
+  | "INTERNAL" // Provider internal error
+  | "TRANSIENT" // Temporary error, safe to retry
+  | "UNKNOWN"; // Unknown error type
+
+// Provider info type
+export interface ProviderInfo {
+  id: string;
+  displayName: string;
+  supportsStreaming: boolean;
+  prefersJson: boolean;
+  capabilities?: string[];
+}
+
+// Provider state type
+export interface ProviderState {
+  lastUsedAt?: string;
+  requestsToday: number;
+  lastReset?: string;
+  outOfCreditsUntil?: string;
+  lastErrors: string[];
+}
+
+// Full state type
+export interface FullState {
+  version: string;
+  providers: Record<string, ProviderState>;
+}

package/src/core/unified/capabilities.ts

@@ -0,0 +1,184 @@
+/**
+ * Capability System - Typed capabilities for terminal coders
+ *
+ * Provides a structured way to declare and query provider capabilities.
+ */
+
+/**
+ * Standard capability types
+ */
+export const Capability = {
+  // Coding modes
+  GENERATE: "generate",
+  EDIT: "edit",
+  EXPLAIN: "explain",
+  TEST: "test",
+  REVIEW: "review",
+  REFACTOR: "refactor",
+
+  // Input handling
+  FILE_CONTEXT: "file_context",
+  MULTI_FILE: "multi_file",
+  SYSTEM_PROMPT: "system_prompt",
+
+  // Output features
+  STREAMING: "streaming",
+  JSON_OUTPUT: "json_output",
+  USAGE_TRACKING: "usage_tracking",
+
+  // Advanced features
+  MODEL_SELECTION: "model_selection",
+  TEMPERATURE_CONTROL: "temperature_control",
+  MAX_TOKENS: "max_tokens",
+} as const;
+
+export type CapabilityType = (typeof Capability)[keyof typeof Capability];
+
+/**
+ * Capabilities interface - what a provider can do
+ */
+export interface ICapabilities {
+  /** Supported coding modes */
+  readonly supportedModes: ReadonlySet<string>;
+
+  // Input capabilities
+  readonly supportsFileContext: boolean;
+  readonly supportsMultiFile: boolean;
+  readonly supportsSystemPrompt: boolean;
+
+  // Output capabilities
+  readonly supportsStreaming: boolean;
+  readonly supportsJsonOutput: boolean;
+  readonly supportsUsageTracking: boolean;
+
+  // Request parameter capabilities
+  readonly supportsModelSelection: boolean;
+  readonly supportsTemperature: boolean;
+  readonly supportsMaxTokens: boolean;
+
+  // Feature discovery
+  hasCapability(capability: CapabilityType): boolean;
+  getCapabilities(): CapabilityType[];
+}
+
+/**
+ * Implementation of ICapabilities
+ */
+export class ProviderCapabilities implements ICapabilities {
+  private readonly capabilities: Set<CapabilityType>;
+
+  constructor(capabilityList: CapabilityType[]) {
+    this.capabilities = new Set(capabilityList);
+  }
+
+  get supportedModes(): ReadonlySet<string> {
+    const modes = new Set<string>();
+    const modeCapabilities = [
+      Capability.GENERATE,
+      Capability.EDIT,
+      Capability.EXPLAIN,
+      Capability.TEST,
+      Capability.REVIEW,
+      Capability.REFACTOR,
+    ];
+
+    for (const cap of modeCapabilities) {
+      if (this.capabilities.has(cap)) {
+        modes.add(cap);
+      }
+    }
+
+    return modes;
+  }
+
+  get supportsFileContext(): boolean {
+    return this.capabilities.has(Capability.FILE_CONTEXT);
+  }
+
+  get supportsMultiFile(): boolean {
+    return this.capabilities.has(Capability.MULTI_FILE);
+  }
+
+  get supportsSystemPrompt(): boolean {
+    return this.capabilities.has(Capability.SYSTEM_PROMPT);
+  }
+
+  get supportsStreaming(): boolean {
+    return this.capabilities.has(Capability.STREAMING);
+  }
+
+  get supportsJsonOutput(): boolean {
+    return this.capabilities.has(Capability.JSON_OUTPUT);
+  }
+
+  get supportsUsageTracking(): boolean {
+    return this.capabilities.has(Capability.USAGE_TRACKING);
+  }
+
+  get supportsModelSelection(): boolean {
+    return this.capabilities.has(Capability.MODEL_SELECTION);
+  }
+
+  get supportsTemperature(): boolean {
+    return this.capabilities.has(Capability.TEMPERATURE_CONTROL);
+  }
+
+  get supportsMaxTokens(): boolean {
+    return this.capabilities.has(Capability.MAX_TOKENS);
+  }
+
+  hasCapability(capability: CapabilityType): boolean {
+    return this.capabilities.has(capability);
+  }
+
+  getCapabilities(): CapabilityType[] {
+    return Array.from(this.capabilities);
+  }
+
+  /**
+   * Factory method from string array (for backwards compatibility)
+   */
+  static fromStringArray(strings: string[]): ProviderCapabilities {
+    const capabilities: CapabilityType[] = [];
+
+    for (const str of strings) {
+      // Map legacy string capabilities to typed capabilities
+      const mapping: Record<string, CapabilityType> = {
+        generate: Capability.GENERATE,
+        edit: Capability.EDIT,
+        explain: Capability.EXPLAIN,
+        test: Capability.TEST,
+        review: Capability.REVIEW,
+        refactor: Capability.REFACTOR,
+        streaming: Capability.STREAMING,
+        json_output: Capability.JSON_OUTPUT,
+      };
+
+      const cap = mapping[str.toLowerCase()];
+      if (cap) capabilities.push(cap);
+    }
+
+    return new ProviderCapabilities(capabilities);
+  }
+
+  /**
+   * Create capabilities from provider info
+   */
+  static fromProviderInfo(info: {
+    capabilities?: string[];
+    supportsStreaming?: boolean;
+    prefersJson?: boolean;
+  }): ProviderCapabilities {
+    const caps = ProviderCapabilities.fromStringArray(info.capabilities ?? []);
+    const allCaps = caps.getCapabilities();
+
+    if (info.supportsStreaming) {
+      allCaps.push(Capability.STREAMING);
+    }
+    if (info.prefersJson) {
+      allCaps.push(Capability.JSON_OUTPUT);
+    }
+
+    return new ProviderCapabilities(allCaps);
+  }
+}