@flowcodex/core 0.3.0

package/src/infrastructure/catalog-parser.ts

@@ -0,0 +1,218 @@
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+export type WireFamily = 'anthropic' | 'openai' | 'openai-compatible' | 'google' | 'unsupported';
+
+export function classifyFamily(npm: string | undefined): WireFamily {
+  if (!npm) return 'unsupported';
+  if (npm === '@anthropic-ai/sdk') return 'anthropic';
+  if (npm === 'openai' || npm === '@openai/api') return 'openai';
+  if (npm === '@google/genai' || npm === '@google/generative-ai') return 'google';
+  if (npm.includes('openai') || npm.includes('compatible')) return 'openai-compatible';
+  return 'unsupported';
+}
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  provider: string;
+  npm?: string | undefined;
+  reasoning: boolean;
+  reasoning_options?: unknown[] | undefined;
+  limit: { context: number; output: number };
+  cost?: {
+    input: number;
+    output: number;
+    cache_read?: number | undefined;
+    cache_write?: number | undefined;
+  } | undefined;
+  tool_call: boolean;
+  modalities: {
+    input: string[];
+    output: string[];
+  };
+}
+
+export interface CatalogEntry {
+  models: ModelInfo[];
+  fetchedAt: number;
+  source: 'snapshot' | 'cache' | 'network';
+}
+
+export interface CatalogParser {
+  load(): Promise<CatalogEntry>;
+  getModels(provider?: string): ModelInfo[];
+  getModel(id: string): ModelInfo | undefined;
+  getCheapestModel(providerId: string, excludeModelId: string): ModelInfo | undefined;
+}
+
+const CACHE_DIR = path.join(os.homedir(), '.flowcodex', 'cache');
+const CACHE_FILE = path.join(CACHE_DIR, 'models-dev.json');
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const MODELS_DEV_URL = 'https://models.dev/api.json';
+
+declare const FLOWCODEX_MODELS_DEV: string | undefined;
+
+function parseRawCatalog(raw: unknown): ModelInfo[] {
+  const data = raw as Record<string, unknown>;
+  if (!data || typeof data !== 'object') return [];
+  const models: ModelInfo[] = [];
+  for (const [providerId, provider] of Object.entries(data)) {
+    if (!provider || typeof provider !== 'object') continue;
+    const p = provider as Record<string, unknown>;
+    const npm = p.npm as string | undefined;
+    const rawModels = p.models as Record<string, unknown> | undefined;
+    if (!rawModels) continue;
+    for (const [modelId, model] of Object.entries(rawModels)) {
+      if (!model || typeof model !== 'object') continue;
+      const m = model as Record<string, unknown>;
+      const limit = m.limit as Record<string, number> | undefined;
+      const cost = m.cost as Record<string, number> | undefined;
+      const modalities = m.modalities as Record<string, string[]> | undefined;
+      models.push({
+        id: modelId,
+        name: (m.name as string) ?? modelId,
+        provider: providerId,
+        npm,
+        reasoning: (m.reasoning as boolean) ?? false,
+        reasoning_options: m.reasoning_options as unknown[] | undefined,
+        limit: {
+          context: limit?.context ?? 200_000,
+          output: limit?.output ?? 8_192,
+        },
+        cost: cost ? {
+          input: cost.input ?? 0,
+          output: cost.output ?? 0,
+          cache_read: cost.cache_read,
+          cache_write: cost.cache_write,
+        } : undefined,
+        tool_call: (m.tool_call as boolean) ?? false,
+        modalities: {
+          input: modalities?.input ?? ['text'],
+          output: modalities?.output ?? ['text'],
+        },
+      });
+    }
+  }
+  return models;
+}
+
+export class DefaultCatalogParser implements CatalogParser {
+  private cached: CatalogEntry | undefined;
+  private disableNetwork: boolean;
+
+  constructor(opts: { disableNetwork?: boolean } = {}) {
+    this.disableNetwork = opts.disableNetwork ?? false;
+  }
+
+  async load(): Promise<CatalogEntry> {
+    if (this.cached) return this.cached;
+
+    const cached = await this.loadFromCache();
+    if (cached) {
+      this.cached = cached;
+      return cached;
+    }
+
+    const snapshot = this.loadFromSnapshot();
+    if (snapshot) {
+      this.cached = snapshot;
+      if (!this.disableNetwork) {
+        void this.refreshInBackground();
+      }
+      return snapshot;
+    }
+
+    if (!this.disableNetwork) {
+      const network = await this.loadFromNetwork();
+      if (network) {
+        this.cached = network;
+        return network;
+      }
+    }
+
+    this.cached = { models: [], fetchedAt: 0, source: 'snapshot' };
+    return this.cached;
+  }
+
+  getModels(provider?: string): ModelInfo[] {
+    if (!this.cached) return [];
+    if (provider) {
+      return this.cached.models.filter((m) => m.provider === provider);
+    }
+    return this.cached.models;
+  }
+
+  getModel(id: string): ModelInfo | undefined {
+    return this.cached?.models.find((m) => m.id === id);
+  }
+
+  getCheapestModel(providerId: string, excludeModelId: string): ModelInfo | undefined {
+    const models = this.getModels(providerId);
+    const candidates = models.filter(
+      (m) =>
+        m.id !== excludeModelId &&
+        m.tool_call === true &&
+        m.cost !== undefined &&
+        m.limit.context >= 16_000,
+    );
+    if (candidates.length === 0) return undefined;
+    candidates.sort((a, b) => a.cost!.output - b.cost!.output);
+    return candidates[0];
+  }
+
+  private async loadFromCache(): Promise<CatalogEntry | undefined> {
+    try {
+      const raw = await fsp.readFile(CACHE_FILE, 'utf-8');
+      const data = JSON.parse(raw);
+      if (Date.now() - data.fetchedAt > CACHE_TTL_MS) return undefined;
+      return {
+        models: parseRawCatalog(data.catalog),
+        fetchedAt: data.fetchedAt,
+        source: 'cache',
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  private loadFromSnapshot(): CatalogEntry | undefined {
+    try {
+      const raw = typeof FLOWCODEX_MODELS_DEV !== 'undefined' ? FLOWCODEX_MODELS_DEV : undefined;
+      if (!raw) return undefined;
+      return {
+        models: parseRawCatalog(JSON.parse(raw)),
+        fetchedAt: 0,
+        source: 'snapshot',
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  private async loadFromNetwork(): Promise<CatalogEntry | undefined> {
+    try {
+      const res = await fetch(MODELS_DEV_URL);
+      if (!res.ok) return undefined;
+      const raw = await res.text();
+      const catalog = JSON.parse(raw);
+      await fsp.mkdir(CACHE_DIR, { recursive: true });
+      await fsp.writeFile(CACHE_FILE, JSON.stringify({ catalog, fetchedAt: Date.now() }), 'utf-8');
+      return {
+        models: parseRawCatalog(catalog),
+        fetchedAt: Date.now(),
+        source: 'network',
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  private async refreshInBackground(): Promise<void> {
+    const fresh = await this.loadFromNetwork();
+    if (fresh) {
+      this.cached = fresh;
+    }
+  }
+}

package/src/infrastructure/index.ts

@@ -0,0 +1,16 @@
+export { DefaultPathResolver } from './path-resolver.js';
+export type { PathResolver } from './path-resolver.js';
+export { safeResolve, safeResolveReal } from './path-resolver.js';
+export { DefaultRetryPolicy } from './retry-policy.js';
+export type { RetryPolicy, ProviderError } from './retry-policy.js';
+export { parseRetryAfter } from './retry-policy.js';
+export { NoopTracer, NoopSpan } from './tracer.js';
+export type { Tracer, Span } from './tracer.js';
+export { DefaultTokenCounter } from './token-counter.js';
+export type { TokenCounter, Usage, ModelPricing } from './token-counter.js';
+export { DefaultSecretScrubber } from './secret-scrubber.js';
+export type { SecretScrubber } from './secret-scrubber.js';
+export { DefaultCatalogParser, classifyFamily } from './catalog-parser.js';
+export type { CatalogParser, CatalogEntry, ModelInfo, WireFamily } from './catalog-parser.js';
+export { createProvider, setProviderConstructors, resolveFamily } from './provider-factory.js';
+export type { ProviderConstructors, ProviderConfigEntry, CreateProviderOptions, FlowCodexLikeConfig } from './provider-factory.js';

package/src/infrastructure/path-resolver.ts

@@ -0,0 +1,123 @@
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import { FsError, ERROR_CODES } from '../types/errors.js';
+
+export interface PathResolver {
+  readonly projectRoot: string;
+  readonly cwd: string;
+  resolve(input: string): string;
+  isInsideRoot(absPath: string): boolean;
+  ensureInsideRoot(absPath: string): string;
+}
+
+const PROJECT_MARKERS = [
+  '.git',
+  'package.json',
+  'pnpm-workspace.yaml',
+  'go.mod',
+  'Cargo.toml',
+  'pyproject.toml',
+] as const;
+
+export class DefaultPathResolver implements PathResolver {
+  readonly projectRoot: string;
+  readonly cwd: string;
+
+  constructor(opts: { projectRoot?: string; cwd?: string } = {}) {
+    this.cwd = opts.cwd ?? process.cwd();
+    this.projectRoot = opts.projectRoot ?? this.detectProjectRoot(this.cwd);
+  }
+
+  detectProjectRoot(start: string): string {
+    const home = require('node:os').homedir();
+    let dir = path.resolve(start);
+    for (;;) {
+      for (const marker of PROJECT_MARKERS) {
+        if (require('node:fs').existsSync(path.join(dir, marker))) {
+          return dir;
+        }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir || dir === home) break;
+      dir = parent;
+    }
+    return path.resolve(start);
+  }
+
+  resolve(input: string): string {
+    const resolved = path.resolve(this.cwd, input);
+    try {
+      return require('node:fs').realpathSync(resolved);
+    } catch {
+      return path.normalize(resolved);
+    }
+  }
+
+  isInsideRoot(absPath: string): boolean {
+    const rel = path.relative(this.projectRoot, absPath);
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+  }
+
+  ensureInsideRoot(absPath: string): string {
+    if (!this.isInsideRoot(absPath)) {
+      throw new FsError({
+        message: `Path "${path.basename(absPath)}" is outside the project root`,
+        code: ERROR_CODES.FS_PATH_ESCAPE,
+        path: absPath,
+        context: { projectRoot: this.projectRoot },
+      });
+    }
+    return absPath;
+  }
+}
+
+export async function safeResolve(
+  input: string,
+  projectRoot: string,
+  cwd: string,
+): Promise<string> {
+  const resolved = path.resolve(cwd, input);
+  const rel = path.relative(projectRoot, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new FsError({
+      message: `Path "${path.basename(resolved)}" is outside the project root`,
+      code: ERROR_CODES.FS_PATH_ESCAPE,
+      path: resolved,
+      context: { projectRoot },
+    });
+  }
+  return resolved;
+}
+
+export async function safeResolveReal(
+  input: string,
+  projectRoot: string,
+  cwd: string,
+): Promise<string> {
+  const resolved = await safeResolve(input, projectRoot, cwd);
+  const realRoot = await fsp.realpath(projectRoot).catch(() => path.resolve(projectRoot));
+
+  let probe = resolved;
+  for (;;) {
+    try {
+      const real = await fsp.realpath(probe);
+      const rel = path.relative(realRoot, real);
+      if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new FsError({
+          message: `Symlink escape detected: "${path.basename(resolved)}" resolves outside the project root`,
+          code: ERROR_CODES.FS_PATH_ESCAPE,
+          path: resolved,
+          context: { realRoot, real },
+        });
+      }
+      break;
+    } catch (err) {
+      if (err instanceof FsError) throw err;
+      const parent = path.dirname(probe);
+      if (parent === probe) break;
+      probe = parent;
+    }
+  }
+
+  return resolved;
+}

package/src/infrastructure/provider-factory.ts

@@ -0,0 +1,116 @@
+import { ERROR_CODES, FlowCodexError } from '../types/errors.js';
+import type { Provider } from '../types/provider.js';
+import { type CatalogParser, classifyFamily, type WireFamily } from './catalog-parser.js';
+
+export interface ProviderConfigEntry {
+  baseUrl?: string | undefined;
+  family?: string | undefined;
+  env?: string | undefined;
+  extraHeaders?: Record<string, string> | undefined;
+  extraBody?: Record<string, unknown> | undefined;
+}
+
+export interface FlowCodexLikeConfig {
+  providers: Record<string, ProviderConfigEntry>;
+}
+
+export interface CreateProviderOptions {
+  providerId: string;
+  apiKey: string;
+  config: FlowCodexLikeConfig;
+  catalog: CatalogParser;
+}
+
+export interface ProviderConstructors {
+  anthropic: new (opts: { apiKey: string; baseUrl?: string }) => Provider;
+  openai: new (opts: {
+    apiKey: string;
+    baseUrl?: string;
+    organization?: string;
+    project?: string;
+  }) => Provider;
+  openaiCompatible: new (opts: {
+    apiKey: string;
+    baseUrl: string;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, unknown>;
+  }) => Provider;
+}
+
+let constructors: ProviderConstructors | undefined;
+
+export function setProviderConstructors(c: ProviderConstructors): void {
+  constructors = c;
+}
+
+export function createProvider(opts: CreateProviderOptions): Provider {
+  const family = resolveFamily(opts.providerId, opts.config, opts.catalog);
+  const entry = opts.config.providers[opts.providerId];
+  const baseUrl = entry?.baseUrl;
+  const cons = constructors;
+  if (!cons) {
+    throw new FlowCodexError({
+      message:
+        'Provider constructors not registered. Call setProviderConstructors() at CLI startup.',
+      code: ERROR_CODES.PROVIDER_UNSUPPORTED,
+      subsystem: 'provider',
+      severity: 'fatal',
+    });
+  }
+  const anthropicOpts: { apiKey: string; baseUrl?: string } = { apiKey: opts.apiKey };
+  if (baseUrl !== undefined) anthropicOpts.baseUrl = baseUrl;
+  const openaiOpts: { apiKey: string; baseUrl?: string; organization?: string; project?: string } =
+    { apiKey: opts.apiKey };
+  if (baseUrl !== undefined) openaiOpts.baseUrl = baseUrl;
+  const compatibleOpts: {
+    apiKey: string;
+    baseUrl: string;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, unknown>;
+  } = {
+    apiKey: opts.apiKey,
+    baseUrl: baseUrl ?? '',
+  };
+  if (entry?.extraHeaders !== undefined) compatibleOpts.extraHeaders = entry.extraHeaders;
+  if (entry?.extraBody !== undefined) compatibleOpts.extraBody = entry.extraBody;
+  switch (family) {
+    case 'anthropic':
+      return new cons.anthropic(anthropicOpts);
+    case 'openai':
+      return new cons.openai(openaiOpts);
+    case 'openai-compatible':
+      return new cons.openaiCompatible(compatibleOpts);
+    case 'google':
+      throw new FlowCodexError({
+        message: `Provider "${opts.providerId}" (google family) is not wired in v0.2.0. Tracked for a v0.2.x patch.`,
+        code: ERROR_CODES.PROVIDER_NOT_WIRED,
+        subsystem: 'provider',
+        severity: 'error',
+      });
+    default:
+      throw new FlowCodexError({
+        message: `Provider "${opts.providerId}" is not supported. Run \`flowcodex auth\` to see wired providers.`,
+        code: ERROR_CODES.PROVIDER_UNSUPPORTED,
+        subsystem: 'provider',
+        severity: 'error',
+      });
+  }
+}
+
+export function resolveFamily(
+  providerId: string,
+  config: FlowCodexLikeConfig,
+  catalog: CatalogParser,
+): WireFamily | 'unsupported' {
+  const explicit = config.providers[providerId]?.family;
+  if (explicit) {
+    return explicit as WireFamily | 'unsupported';
+  }
+  const models = catalog.getModels(providerId);
+  if (models.length > 0) {
+    const npm = models[0]?.npm;
+    const fam = classifyFamily(npm);
+    if (fam !== 'unsupported') return fam;
+  }
+  return 'unsupported';
+}

package/src/infrastructure/provider-presets.ts

@@ -0,0 +1,19 @@
+export interface CompatibilityQuirks {
+  stripCacheControl?: boolean | undefined;
+  systemAsMessage?: boolean | undefined;
+  flattenContentToString?: boolean | undefined;
+  preserveToolCallIds?: boolean | undefined;
+  parallelToolsDisabled?: boolean | undefined;
+  jsonArgumentsBuggy?: boolean | undefined;
+  emptyToolCallContent?: 'null' | 'empty_string' | undefined;
+  reasoningContentEcho?: boolean | undefined;
+}
+
+export const PROVIDER_PRESETS: Record<string, CompatibilityQuirks> = {
+  deepseek: { reasoningContentEcho: true, jsonArgumentsBuggy: true },
+  groq: { jsonArgumentsBuggy: true },
+  openrouter: {},
+  ollama: { emptyToolCallContent: 'null', parallelToolsDisabled: true },
+  vllm: { emptyToolCallContent: 'null', parallelToolsDisabled: true },
+  lmstudio: { emptyToolCallContent: 'null', parallelToolsDisabled: true },
+};

package/src/infrastructure/retry-policy.ts

@@ -0,0 +1,50 @@
+export interface ProviderError {
+  status: number;
+  message: string;
+  retryable: boolean;
+}
+
+export interface RetryPolicy {
+  shouldRetry(err: ProviderError, attempt: number): boolean;
+  maxAttempts(err: ProviderError): number;
+  delayMs(attempt: number, err: ProviderError): number;
+}
+
+const DEFAULTS: Record<number, { max: number; retryable: boolean }> = {
+  429: { max: 5, retryable: true },
+  529: { max: 3, retryable: true },
+  500: { max: 3, retryable: true },
+  502: { max: 3, retryable: true },
+  503: { max: 3, retryable: true },
+  504: { max: 3, retryable: true },
+  599: { max: 2, retryable: true },
+};
+
+const NON_RETRYABLE = new Set([400, 401, 403, 404, 422]);
+
+export class DefaultRetryPolicy implements RetryPolicy {
+  shouldRetry(err: ProviderError, attempt: number): boolean {
+    if (NON_RETRYABLE.has(err.status)) return false;
+    if (err.status >= 500 || err.status === 429 || err.status === 599) {
+      return attempt < this.maxAttempts(err);
+    }
+    return false;
+  }
+
+  maxAttempts(err: ProviderError): number {
+    return DEFAULTS[err.status]?.max ?? 3;
+  }
+
+  delayMs(attempt: number, _err: ProviderError): number {
+    const exp = Math.min(30_000, 1000 * Math.pow(2, attempt));
+    const jitter = Math.floor(Math.random() * 1000);
+    return exp + jitter;
+  }
+}
+
+export function parseRetryAfter(header: string | undefined): number | undefined {
+  if (!header) return undefined;
+  const seconds = parseInt(header, 10);
+  if (!Number.isNaN(seconds)) return Math.min(120_000, Math.max(1_000, seconds * 1000));
+  return undefined;
+}

package/src/infrastructure/secret-scrubber.ts

@@ -0,0 +1,67 @@
+export interface SecretScrubber {
+  scrub(text: string): string;
+  scrubObject<T>(obj: T): T;
+}
+
+interface Pattern {
+  type: string;
+  regex: RegExp;
+  anchors: string[];
+}
+
+const PATTERNS: Pattern[] = [
+  { type: 'anthropic_key', regex: /sk-ant-[A-Za-z0-9_-]{20,}/, anchors: ['sk-ant-'] },
+  { type: 'openai_key', regex: /sk-[A-Za-z0-9]{20,}/, anchors: ['sk-'] },
+  { type: 'github_pat', regex: /ghp_[A-Za-z0-9]{20,}/, anchors: ['ghp_'] },
+  { type: 'github_pat_v2', regex: /github_pat_[A-Za-z0-9_]{20,}/, anchors: ['github_pat_'] },
+  { type: 'aws_access_key', regex: /AKIA[0-9A-Z]{16}/, anchors: ['AKIA'] },
+  { type: 'gcp_key', regex: /AIza[0-9A-Za-z_-]{35}/, anchors: ['AIza'] },
+  { type: 'slack_token', regex: /xox[baprs]-[0-9A-Za-z-]+/, anchors: ['xox'] },
+  { type: 'stripe_key', regex: /sk_live_[0-9A-Za-z]{24,}/, anchors: ['sk_live_'] },
+  { type: 'twilio_sid', regex: /AC[0-9a-f]{32}/, anchors: ['AC'] },
+  { type: 'telegram_bot_token', regex: /\d{6,12}:AAH[0-9A-Za-z_-]{30,}/, anchors: [':AAH', '/bot'] },
+  { type: 'jwt', regex: /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/, anchors: ['eyJ'] },
+  { type: 'private_key', regex: /-----BEGIN[A-Z ]+-----[\s\S]*?-----END[A-Z ]+-----/, anchors: ['-----BEGIN'] },
+  { type: 'mongodb_uri', regex: /mongodb(\+srv)?:\/\/[^\s"'<>]+/, anchors: ['mongodb://', 'mongodb+srv://'] },
+  { type: 'postgres_uri', regex: /postgres(ql)?:\/\/[^\s"'<>]+/, anchors: ['postgres://', 'postgresql://'] },
+  { type: 'mysql_uri', regex: /mysql:\/\/[^\s"'<>]+/, anchors: ['mysql://'] },
+  { type: 'redis_uri', regex: /rediss?:\/\/[^\s"'<>]+/, anchors: ['redis://', 'rediss://'] },
+  { type: 'bearer_token', regex: /Bearer\s+[A-Za-z0-9_.~+/=-]{20,}/, anchors: ['Bearer '] },
+];
+
+const ALL_ANCHORS = PATTERNS.flatMap((p) => p.anchors);
+
+const HIGH_ENTROPY_ENV = /([A-Z_][A-Z0-9_]*)=(["']?)([A-Za-z0-9+/=_-]{20,})\2/g;
+
+export class DefaultSecretScrubber implements SecretScrubber {
+  scrub(text: string): string {
+    if (!this.hasCredentialAnchors(text)) return text;
+    let result = text;
+    for (const p of PATTERNS) {
+      result = result.replace(p.regex, `[REDACTED:${p.type}]`);
+    }
+    result = result.replace(HIGH_ENTROPY_ENV, (_m, name, _q, _val) => `${name}=[REDACTED:high_entropy_env]`);
+    return result;
+  }
+
+  scrubObject<T>(obj: T): T {
+    if (typeof obj === 'string') return this.scrub(obj) as T;
+    if (obj === null || obj === undefined) return obj;
+    if (Array.isArray(obj)) return obj.map((v) => this.scrubObject(v)) as T;
+    if (typeof obj === 'object') {
+      const result: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+        result[k] = this.scrubObject(v);
+      }
+      return result as T;
+    }
+    return obj;
+  }
+
+  hasCredentialAnchors(text: string): boolean {
+    for (const anchor of ALL_ANCHORS) {
+      if (text.includes(anchor)) return true;
+    }
+    return false;
+  }
+}