@ryuu-reinzz/ryuu-cli 0.0.0-stage → 0.4.0

package/src/providers/registry.js

@@ -0,0 +1,104 @@
+import { ProviderError } from '../utils/errors.js';
+
+/**
+ * Multi-provider registry.
+ *
+ * Providers are registered by ID and can be instantiated on demand with a
+ * config object. The registry keeps a cache of created providers so the same
+ * instance is reused across requests within a session.
+ *
+ * Usage:
+ *   const registry = new ProviderRegistry();
+ *   registry.register('tokenharbor', createTokenHarborProvider);
+ *   const provider = await registry.resolve('tokenharbor', config, { logger });
+ *
+ * Provider factories receive (config, deps) and must return an object with at
+ * least `chat(...)`, `ping()`, and a `model` getter (matching the existing
+ * NvidiaProvider interface).
+ */
+export class ProviderRegistry {
+  constructor(factories = {}) {
+    this.factories = new Map();
+    this.providers = new Map();
+    for (const [id, factory] of Object.entries(factories)) {
+      this.factories.set(id, factory);
+    }
+  }
+
+  /** Register a provider factory under an id. Overwrites any existing one. */
+  register(id, factory) {
+    if (!id || typeof id !== 'string') {
+      throw new ProviderError('Provider id must be a non-empty string.', {
+        code: 'INVALID_PROVIDER_ID',
+      });
+    }
+    if (typeof factory !== 'function') {
+      throw new ProviderError(`Provider factory for ${id} must be a function.`, {
+        code: 'INVALID_PROVIDER_FACTORY',
+      });
+    }
+    this.factories.set(id, factory);
+    this.providers.delete(id); // drop any cached instance for the old factory
+  }
+
+  /** Unregister a provider and drop any cached instance. */
+  unregister(id) {
+    this.factories.delete(id);
+    this.providers.delete(id);
+  }
+
+  /** Check whether a provider id is known (registered or already instantiated). */
+  has(id) {
+    return this.factories.has(id) || this.providers.has(id);
+  }
+
+  /** List all known provider ids. */
+  list() {
+    return [...this.factories.keys()];
+  }
+
+  /** Return a cached provider instance, or null when none exists yet. */
+  get(id) {
+    return this.providers.get(id) || null;
+  }
+
+  /** Create (and cache) a provider instance for the given id. */
+  create(id, config, deps = {}) {
+    const factory = this.factories.get(id);
+    if (!factory) {
+      throw new ProviderError(`Unknown provider: ${id}. Registered: ${this.list().join(', ') || '(none)'}`, {
+        code: 'UNKNOWN_PROVIDER',
+      });
+    }
+    const provider = factory(config, deps);
+    this.providers.set(id, provider);
+    return provider;
+  }
+
+  /** Resolve a provider: return the cached instance or create a new one. */
+  resolve(id, config, deps = {}) {
+    if (!this.has(id)) {
+      throw new ProviderError(`Unknown provider: ${id}. Registered: ${this.list().join(', ') || '(none)'}`, {
+        code: 'UNKNOWN_PROVIDER',
+      });
+    }
+    const existing = this.providers.get(id);
+    if (existing) return existing;
+    return this.create(id, config, deps);
+  }
+
+  /** Create providers for every registered id (e.g. for health checks). */
+  async createAll(config, deps = {}) {
+    const instances = new Map();
+    for (const id of this.list()) {
+      try {
+        instances.set(id, this.create(id, config, deps));
+      } catch {
+        // Providers that fail to instantiate are simply skipped.
+      }
+    }
+    return instances;
+  }
+}
+
+export const defaultRegistry = new ProviderRegistry();

package/src/providers/river.js

@@ -0,0 +1,198 @@
+import { MODEL_ID_PATTERN, MAX_MODEL_ID_LENGTH } from './catalog.js';
+import { RIVER_DEFAULT_REASONING_EFFORT, RIVER_PROVIDER_ID, RIVER_REASONING_EFFORTS } from './catalog.js';
+import { registerRequestExtras, passthroughExtras } from './vendor-extras.js';
+
+export {
+  RIVER_BASE_URL,
+  RIVER_DEFAULT_MODEL,
+  RIVER_DEFAULT_REASONING_EFFORT,
+  RIVER_DOCS_URL,
+  RIVER_MODEL_CATALOG,
+  RIVER_PROVIDER_ID,
+  RIVER_REASONING_EFFORTS,
+} from './catalog.js';
+
+/**
+ * River AI provider.
+ *
+ * River speaks the OpenAI Chat Completions protocol, so it reuses the shared
+ * client (`nvidia.js`) and only adds the vendor fields that protocol does not
+ * define. The client asks `vendor-extras.js` for those fields by provider id,
+ * and this module registers the River builder at import time — no subclass, so
+ * one client instance keeps working across `/provider` switches.
+ *
+ * Why this file exists: River keeps thinking *off by default* for its DeepSeek
+ * models, so a plain Chat Completions request never produces `reasoning_content`
+ * and the CLI has nothing to render. River turns thinking on with a top-level
+ * `reasoning_effort` field (see https://docs.river.ai/guides/inference-controls/),
+ * which the shared client never sent. `riverRequestExtras()` adds it.
+ *
+ * The effort is only sent when the model is documented to accept it, and it is
+ * only forced for models whose documented default is *off*; every other River
+ * model already returns `reasoning_content` by itself.
+ */
+
+/**
+ * Per-model reasoning profile, transcribed from
+ * https://docs.river.ai/guides/inference-controls/ (read 2026-10-30).
+ *
+ * `levels` is the model's accepted `reasoning_effort` menu, `onByDefault` tells
+ * whether it already thinks without the field, and `enable` is the level used to
+ * turn thinking on. A model missing from this table is left untouched: an effort
+ * value an endpoint does not know can fail the whole request.
+ */
+export const RIVER_MODEL_REASONING = {
+  'deepseek-ai/DeepSeek-V4.1-Flash-1017': {
+    levels: ['none', 'low', 'high', 'max'],
+    onByDefault: false,
+    enable: 'high',
+  },
+  'deepseek-ai/DeepSeek-V4.1-Flash': {
+    levels: ['none', 'low', 'high', 'max'],
+    onByDefault: false,
+    enable: 'high',
+  },
+  'zai-org/GLM-5.3-Flash': { levels: ['low', 'high', 'max'], onByDefault: true, enable: 'max' },
+  'GLM-5.3': { levels: ['low', 'high', 'max'], onByDefault: true, enable: 'max' },
+  'Qwen/Qwen3.8-27B-FP8': { levels: ['none', 'low', 'medium', 'xhigh'], onByDefault: true, enable: 'xhigh' },
+  'nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-NVFP4': {
+    levels: ['none', 'medium', 'high'],
+    onByDefault: true,
+    enable: 'high',
+  },
+};
+
+/** Environment override for the River reasoning effort. */
+export const RIVER_EFFORT_ENV = 'RYUU_RIVER_REASONING_EFFORT';
+/** Generic environment override, read after the River-specific one. */
+export const REASONING_EFFORT_ENV = 'RYUU_REASONING_EFFORT';
+
+/**
+ * Normalize an effort value.
+ *
+ * Returns one of the documented levels, or null when the value is not a level at
+ * all. "off"/"disabled"/false map to "none" so the same word works in the
+ * environment variable and in config.json.
+ */
+export function normalizeReasoningEffort(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'boolean') return value ? RIVER_DEFAULT_REASONING_EFFORT : 'none';
+  const text = String(value).trim().toLowerCase().replace(/[\s_]+/g, '-');
+  if (!text) return null;
+  if (['off', 'false', 'no', 'disabled', 'disable'].includes(text)) return 'none';
+  if (['on', 'true', 'yes', 'enabled'].includes(text)) return RIVER_DEFAULT_REASONING_EFFORT;
+  return RIVER_REASONING_EFFORTS.includes(text) ? text : null;
+}
+
+/**
+ * The effort the user asked for, or null when they asked for nothing.
+ *
+ * Precedence: `RYUU_RIVER_REASONING_EFFORT`, `reasoningEffort` from config.json,
+ * `RYUU_REASONING_EFFORT`, then `capabilities.reasoningEffort` — so an official
+ * `river` provider and a hand-written provider entry can both set it.
+ */
+export function resolveRequestedEffort(config = {}, env = process.env) {
+  const candidates = [
+    env?.[RIVER_EFFORT_ENV],
+    config?.reasoningEffort,
+    env?.[REASONING_EFFORT_ENV],
+    config?.capabilities?.reasoningEffort,
+  ];
+  for (const candidate of candidates) {
+    const effort = normalizeReasoningEffort(candidate);
+    if (effort) return effort;
+  }
+  return null;
+}
+
+/** The model's documented profile, or null when it is not a known model. */
+export function reasoningProfileFor(model) {
+  return RIVER_MODEL_REASONING[String(model || '')] || null;
+}
+
+/**
+ * Decide which `reasoning_effort` (if any) to send for a model.
+ *
+ * Returns null when the field must be omitted — the user asked for nothing and
+ * the model already reasons by default, or the requested level is not in the
+ * model's documented menu.
+ */
+export function resolveReasoningEffort(config = {}, { env = process.env, model = null, logger = null } = {}) {
+  const target = String(model || config?.model || '');
+  const profile = reasoningProfileFor(target);
+  const requested = resolveRequestedEffort(config, env);
+  let effort = null;
+  if (requested) {
+    effort = requested;
+  } else if (config?.thinking === false) {
+    effort = 'none';
+  } else if (config?.thinking === true) {
+    effort = profile?.enable || RIVER_DEFAULT_REASONING_EFFORT;
+  } else if (profile && !profile.onByDefault) {
+    effort = profile.enable; // DeepSeek: thinking is off unless asked for
+  }
+  if (!effort || effort === 'none') {
+    // "none" only means something to a model that accepts it; elsewhere an
+    // absent field falls back to the same model default.
+    return effort === 'none' && profile?.levels?.includes('none') ? 'none' : null;
+  }
+  if (profile && !profile.levels.includes(effort)) {
+    logger?.warn('reasoning_effort is not supported by this model; using the provider default', {
+      model: target,
+      requested: effort,
+      supported: profile.levels,
+    });
+    return profile.enable && profile.levels.includes(profile.enable) ? profile.enable : null;
+  }
+  return effort;
+}
+
+/**
+ * River's request-body extension for the shared client.
+ *
+ * Opaque pass-through fields first (a hand-written `extraProviders` entry may
+ * carry `extraBody`/`requestParams`), then the `reasoning_effort` that turns
+ * DeepSeek thinking on.
+ */
+export function riverRequestExtras(config = {}, { logger = null, env = process.env } = {}) {
+  const extras = passthroughExtras(config);
+  const effort = resolveReasoningEffort(config, { model: config.model, logger, env });
+  if (effort) extras.reasoning_effort = effort;
+  return extras;
+}
+
+/** True when a requestExtras() payload carries an explicit reasoning effort. */
+export function hasReasoningEffort(extras) {
+  const value = extras?.reasoning_effort;
+  if (value === undefined || value === null) return false;
+  return !(typeof value === 'string' && !value.trim());
+}
+
+/** Human-readable effort for /status. */
+export function describeEffort(effort) {
+  return !effort || effort === 'none' ? 'off (model default)' : effort;
+}
+
+/**
+ * One line describing the reasoning effort that will be sent, or null when the
+ * provider does not use one (so `/status` stays quiet for them).
+ */
+export function describeReasoning(config = {}, { env = process.env, logger = null } = {}) {
+  const extras = riverRequestExtras(config, { env, logger });
+  if (!hasReasoningEffort(extras)) return null;
+  const effort = extras.reasoning_effort;
+  return effort === 'none'
+    ? 'off (reasoning_effort: none)'
+    : `reasoning_effort: ${effort}`;
+}
+
+/** Sanity check used by tests and `/doctor`: the model id must remain valid. */
+export function isValidRiverModel(model) {
+  return typeof model === 'string' && model.length <= MAX_MODEL_ID_LENGTH && MODEL_ID_PATTERN.test(model);
+}
+
+// The shared client consults this table on every request. Registering at import
+// time keeps the wiring in one place: `providers/index.js` only has to import
+// this module, and any provider with the id "river" gets the extension. The host
+// fallback also covers a hand-written `extraProviders` entry for the same API.
+registerRequestExtras(RIVER_PROVIDER_ID, riverRequestExtras, { hosts: ['api.river.ai'] });

package/src/providers/tokenharbor.js

@@ -0,0 +1,38 @@
+import { TOKENHARBOR_BASE_URL, TOKENHARBOR_MODEL } from './catalog.js';
+import { registerRequestExtras, passthroughExtras } from './vendor-extras.js';
+
+/**
+ * Token Harbor provider.
+ *
+ * It speaks the OpenAI Chat Completions protocol and already returns
+ * `reasoning_content`, so it needs no vendor request field: the module exists
+ * to own the provider's defaults and to be the place a future Token Harbor-only
+ * field would go.
+ *
+ * A user `extraProviders` entry may still carry `extraBody`/`requestParams`; they
+ * are passed through untouched, which makes an unusual gateway reachable without
+ * a code change.
+ */
+
+export const TOKENHARBOR_DOCS_URL = 'https://tokenharbor.ai/';
+
+/** Request-body extension for Token Harbor: only explicit pass-through fields. */
+export function tokenHarborRequestExtras(config = {}) {
+  return passthroughExtras(config);
+}
+
+/** Declared descriptor, kept next to the client like the other provider modules. */
+export function tokenHarborDescriptor() {
+  return {
+    id: 'tokenharbor',
+    name: 'Token Harbor',
+    apiFormat: 'openai-chat-completions',
+    baseURL: TOKENHARBOR_BASE_URL,
+    defaultModel: TOKENHARBOR_MODEL,
+    models: [{ id: TOKENHARBOR_MODEL, name: 'DeepSeek V4.1 Flash Free', default: true }],
+    capabilities: { streaming: true, tools: true, reasoning: true, multimodal: false },
+    docsUrl: TOKENHARBOR_DOCS_URL,
+  };
+}
+
+registerRequestExtras('tokenharbor', tokenHarborRequestExtras);

package/src/providers/vendor-extras.js

@@ -0,0 +1,82 @@
+/**
+ * Provider ids whose request body needs extra fields. Keyed by provider id (and
+ * by API host for a hand-written entry pointing at the same endpoint).
+ *
+ * `passthrough` is the fallback for any provider without a registered builder:
+ * a `extraBody`/`requestParams` object in its config.json entry is copied into
+ * the request verbatim, so an unusual gateway stays reachable without a code
+ * change.
+ */
+
+/** providerId -> { builder, hosts: Set<string> } */
+const builders = new Map();
+
+function hostOf(baseURL) {
+  try {
+    return new URL(String(baseURL || '')).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Register (or replace) the builder for one provider id.
+ *
+ * `hosts` makes the builder apply to any provider whose base URL uses that host,
+ * which keeps a hand-written `extraProviders` entry for the same vendor working.
+ */
+export function registerRequestExtras(providerId, builder, { hosts = [] } = {}) {
+  if (!providerId || typeof builder !== 'function') return;
+  const list = [].concat(hosts).map((host) => String(host || '').toLowerCase()).filter(Boolean);
+  builders.set(String(providerId), { builder, hosts: new Set(list) });
+}
+
+/** Remove a builder. Mostly useful for tests. */
+export function unregisterRequestExtras(providerId) {
+  builders.delete(String(providerId));
+}
+
+/** The registered builder for a provider id, then fall back to its API host. */
+export function requestExtrasFor(providerId, baseURL = '') {
+  const direct = builders.get(String(providerId || ''));
+  if (direct) return direct.builder;
+  const host = hostOf(baseURL);
+  if (!host) return null;
+  for (const entry of builders.values()) {
+    if (entry.hosts.has(host)) return entry.builder;
+  }
+  return null;
+}
+
+/**
+ * Default builder for providers without one: copy the explicit pass-through
+ * objects a config.json entry may carry. Nothing is guessed, so a plain provider
+ * still sends only the standard Chat Completions fields.
+ */
+export function passthroughExtras(config = {}) {
+  const extras = {};
+  for (const field of ['extraBody', 'requestParams']) {
+    const value = config?.[field];
+    if (value && typeof value === 'object' && !Array.isArray(value)) Object.assign(extras, value);
+  }
+  return extras;
+}
+
+/**
+ * Extra top-level request fields for this provider, or null when it has none.
+ * A builder that throws must never break a request: the failure is swallowed
+ * and the request goes out unchanged.
+ */
+export function applyRequestExtras(config, context = {}) {
+  const builder = requestExtrasFor(config?.providerId, config?.baseURL) || passthroughExtras;
+  try {
+    const extras = builder(config, context);
+    return extras && typeof extras === 'object' && Object.keys(extras).length > 0 ? extras : null;
+  } catch (error) {
+    context.logger?.warn('provider request extras failed; sending the request unchanged', {
+      provider: config?.providerId,
+      message: error?.message || String(error),
+    });
+    return null;
+  }
+}

package/src/services/clipboard.js

@@ -0,0 +1,38 @@
+/**
+ * Copying to the terminal clipboard with OSC 52.
+ *
+ * The sequence is written to the tty, so the copy happens in the terminal
+ * emulator (or terminal multiplexer) rather than through an OS command: it works
+ * over SSH, needs no `pbcopy`/`xclip`/`clip.exe`, and touches no other process.
+ * Terminals that ignore OSC 52 simply do nothing, which is why callers report the
+ * result instead of assuming the clipboard changed.
+ */
+
+/** Terminals cap OSC 52 payloads (xterm's default is ~75k of base64). */
+const MAX_CHARS = 100_000;
+
+/** The raw sequence for `text`, or null when there is nothing to copy. */
+export function clipboardPayload(text, { limit = MAX_CHARS } = {}) {
+  const value = String(text ?? '');
+  if (!value.trim()) return null;
+  const kept = value.length > limit ? value.slice(0, limit) : value;
+  return {
+    sequence: `\x1b]52;c;${Buffer.from(kept, 'utf8').toString('base64')}\x1b\\`,
+    chars: [...kept].length,
+    truncated: kept.length < value.length,
+  };
+}
+
+/**
+ * Put `text` on the clipboard. Returns `{ ok, chars, truncated, reason }`; a
+ * failure is reported, never thrown, because a copy must not break a session.
+ */
+export function copyToClipboard(text, { output = process.stdout } = {}) {
+  const payload = clipboardPayload(text);
+  if (!payload) return { ok: false, reason: 'empty', chars: 0 };
+  if (!output || output.isTTY === false || !output.write) {
+    return { ok: false, reason: 'no-tty', chars: 0 };
+  }
+  output.write(payload.sequence);
+  return { ok: true, chars: payload.chars, truncated: payload.truncated };
+}

package/src/services/diff.js

@@ -0,0 +1,153 @@
+/**
+ * Unified diff generation for edit previews and /diff.
+ * Line-based LCS with a bounded matrix; very large files fall back to a
+ * whole-file replacement hunk instead of consuming unbounded memory.
+ */
+
+const MAX_CELLS = 2_000_000;
+
+function splitLines(text) {
+  return String(text ?? '').split('\n');
+}
+
+/** @returns {{type: 'equal'|'del'|'add', line: string}[]} */
+export function diffLines(oldText, newText) {
+  const a = splitLines(oldText);
+  const b = splitLines(newText);
+  const n = a.length;
+  const m = b.length;
+
+  if (n * m > MAX_CELLS) {
+    return [
+      ...a.map((line) => ({ type: 'del', line })),
+      ...b.map((line) => ({ type: 'add', line })),
+    ];
+  }
+
+  const width = m + 1;
+  const dp = new Int32Array((n + 1) * width);
+  for (let i = n - 1; i >= 0; i -= 1) {
+    for (let j = m - 1; j >= 0; j -= 1) {
+      dp[i * width + j] = a[i] === b[j]
+        ? dp[(i + 1) * width + (j + 1)] + 1
+        : Math.max(dp[(i + 1) * width + j], dp[i * width + (j + 1)]);
+    }
+  }
+
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: 'equal', line: a[i] });
+      i += 1;
+      j += 1;
+    } else if (dp[(i + 1) * width + j] >= dp[i * width + (j + 1)]) {
+      ops.push({ type: 'del', line: a[i] });
+      i += 1;
+    } else {
+      ops.push({ type: 'add', line: b[j] });
+      j += 1;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: 'del', line: a[i] });
+    i += 1;
+  }
+  while (j < m) {
+    ops.push({ type: 'add', line: b[j] });
+    j += 1;
+  }
+  return ops;
+}
+
+/**
+ * Produce a standard unified diff. Returns '' when contents are identical.
+ *
+ * @param {string} oldText
+ * @param {string} newText
+ * @param {{oldLabel?: string, newLabel?: string, context?: number, maxLines?: number}} options
+ */
+export function createUnifiedDiff(oldText, newText, {
+  oldLabel = 'a/file',
+  newLabel = 'b/file',
+  context = 3,
+  maxLines = 400,
+} = {}) {
+  if (oldText === newText) return '';
+  const ops = diffLines(oldText, newText);
+
+  // Mark which ops are changes, then group with context.
+  const changed = ops.map((op) => op.type !== 'equal');
+  const hunks = [];
+  let index = 0;
+  while (index < ops.length) {
+    if (!changed[index]) {
+      index += 1;
+      continue;
+    }
+    let start = Math.max(0, index - context);
+    let end = index;
+    // Extend while later changes are within 2*context of the current end.
+    while (end < ops.length) {
+      if (changed[end]) {
+        end += 1;
+        continue;
+      }
+      let nextChange = end;
+      while (nextChange < ops.length && !changed[nextChange]) nextChange += 1;
+      if (nextChange < ops.length && nextChange - end <= context * 2) {
+        end = nextChange;
+        continue;
+      }
+      break;
+    }
+    const hunkEnd = Math.min(ops.length, end + context);
+    hunks.push({ start, end: hunkEnd });
+    index = hunkEnd;
+  }
+
+  const oldLineAt = new Array(ops.length);
+  const newLineAt = new Array(ops.length);
+  let oldNo = 1;
+  let newNo = 1;
+  for (let k = 0; k < ops.length; k += 1) {
+    oldLineAt[k] = oldNo;
+    newLineAt[k] = newNo;
+    if (ops[k].type !== 'add') oldNo += 1;
+    if (ops[k].type !== 'del') newNo += 1;
+  }
+
+  const output = [`--- ${oldLabel}`, `+++ ${newLabel}`];
+  let emitted = 0;
+  for (const hunk of hunks) {
+    if (emitted >= maxLines) {
+      output.push(`@@ diff truncated after ${maxLines} lines @@`);
+      break;
+    }
+    const slice = ops.slice(hunk.start, hunk.end);
+    const oldCount = slice.filter((op) => op.type !== 'add').length;
+    const newCount = slice.filter((op) => op.type !== 'del').length;
+    const oldStart = oldCount === 0 ? oldLineAt[hunk.start] - 1 : oldLineAt[hunk.start];
+    const newStart = newCount === 0 ? newLineAt[hunk.start] - 1 : newLineAt[hunk.start];
+    output.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+    for (const op of slice) {
+      const prefix = op.type === 'equal' ? ' ' : op.type === 'del' ? '-' : '+';
+      output.push(`${prefix}${op.line}`);
+      emitted += 1;
+      if (emitted >= maxLines) break;
+    }
+  }
+  return output.join('\n');
+}
+
+export function diffStats(oldText, newText) {
+  const ops = diffLines(oldText, newText);
+  let added = 0;
+  let removed = 0;
+  for (const op of ops) {
+    if (op.type === 'add') added += 1;
+    else if (op.type === 'del') removed += 1;
+  }
+  return { added, removed, changed: added + removed };
+}