@khanglvm/llm-router 1.0.5

package/src/cli-entry.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { getDefaultConfigPath } from "./node/config-store.js";
+import { runStartCommand } from "./node/start-command.js";
+
+function parseSimpleArgs(argv) {
+  const positional = [];
+  const args = {};
+  let wantsHelp = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === "-h" || token === "--help" || token === "help") {
+      wantsHelp = true;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+      const separator = body.indexOf("=");
+      if (separator >= 0) {
+        args[body.slice(0, separator)] = body.slice(separator + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("-")) {
+          args[body] = next;
+          i += 1;
+        } else {
+          args[body] = true;
+        }
+      }
+      continue;
+    }
+
+    positional.push(token);
+  }
+
+  return { positional, args, wantsHelp };
+}
+
+function parseBoolean(value, fallback = true) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "y"].includes(normalized)) return true;
+  if (["0", "false", "no", "n"].includes(normalized)) return false;
+  return fallback;
+}
+
+function parseNumber(value, fallback = 8787) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+async function runStartFastPath(args) {
+  const result = await runStartCommand({
+    configPath: args.config || args.configPath || getDefaultConfigPath(),
+    host: args.host || "127.0.0.1",
+    port: parseNumber(args.port, 8787),
+    watchConfig: parseBoolean(args["watch-config"] ?? args.watchConfig, true),
+    watchBinary: parseBoolean(args["watch-binary"] ?? args.watchBinary, true),
+    requireAuth: parseBoolean(args["require-auth"] ?? args.requireAuth, false),
+    cliPathForWatch: process.argv[1],
+    onLine: (line) => console.log(line),
+    onError: (line) => console.error(line)
+  });
+
+  if (!result.ok && result.errorMessage) {
+    console.error(result.errorMessage);
+  }
+
+  return result.exitCode ?? (result.ok ? 0 : 1);
+}
+
+async function runSnapCli(argv, isTTY) {
+  const [{ createRegistry, runSingleModuleCli }, { default: routerModule }] = await Promise.all([
+    import("@levu/snap/dist/index.js"),
+    import("./cli/router-module.js")
+  ]);
+
+  const registry = createRegistry([routerModule]);
+  return runSingleModuleCli({
+    registry,
+    argv,
+    moduleId: "router",
+    defaultActionId: "config",
+    helpDefaultTarget: "module",
+    isTTY
+  });
+}
+
+export async function runCli(argv = process.argv.slice(2), isTTY = undefined) {
+  const parsed = parseSimpleArgs(argv);
+  const first = parsed.positional[0];
+  const firstIsStart = first === "start";
+
+  // Bare invocation opens the interactive config manager.
+  if (!first && !parsed.wantsHelp) {
+    return runSnapCli(["config"], isTTY);
+  }
+
+  // Fast-path explicit local start without loading Snap to minimize startup overhead.
+  if (firstIsStart && !parsed.wantsHelp) {
+    const startArgs = argv.slice(1);
+    const parsedStart = parseSimpleArgs(startArgs);
+    return runStartFastPath(parsedStart.args);
+  }
+
+  const normalized = [...argv];
+  if (normalized[0] === "help") normalized[0] = "--help";
+  if (normalized[0] === "setup") normalized[0] = "config";
+  return runSnapCli(normalized, isTTY);
+}
+
+function resolveExecutablePath(filePath) {
+  if (!filePath) return "";
+  try {
+    return realpathSync(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}
+
+const isMain = (() => {
+  const modulePath = resolveExecutablePath(fileURLToPath(import.meta.url));
+  const argvPath = resolveExecutablePath(process.argv[1]);
+  return Boolean(argvPath) && modulePath === argvPath;
+})();
+
+if (isMain) {
+  runCli()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    });
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * Cloudflare Worker entrypoint.
+ * Runtime config is supplied via LLM_ROUTER_CONFIG_JSON (or aliases) env/secret.
+ */
+
+import { createFetchHandler } from "./runtime/handler.js";
+import { runtimeConfigFromEnv } from "./runtime/config.js";
+
+const workerFetch = createFetchHandler({
+  getConfig: async (env) => runtimeConfigFromEnv(env)
+});
+
+export default {
+  async fetch(request, env, ctx) {
+    return workerFetch(request, env, ctx);
+  }
+};
+

package/src/node/config-store.js

@@ -0,0 +1,74 @@
+/**
+ * Local config persistence for ~/.llm-router.json.
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { normalizeRuntimeConfig } from "../runtime/config.js";
+
+export const DEFAULT_CONFIG_FILENAME = ".llm-router.json";
+
+export function getDefaultConfigPath() {
+  return path.join(os.homedir(), DEFAULT_CONFIG_FILENAME);
+}
+
+export async function readConfigFile(filePath = getDefaultConfigPath()) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return normalizeRuntimeConfig(JSON.parse(raw));
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return normalizeRuntimeConfig({});
+    }
+    throw error;
+  }
+}
+
+export async function configFileExists(filePath = getDefaultConfigPath()) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function writeConfigFile(config, filePath = getDefaultConfigPath()) {
+  const normalized = normalizeRuntimeConfig(config);
+  const folder = path.dirname(filePath);
+  await fs.mkdir(folder, { recursive: true });
+  const payload = `${JSON.stringify(normalized, null, 2)}\n`;
+  await fs.writeFile(filePath, payload, { encoding: "utf8", mode: 0o600 });
+  await fs.chmod(filePath, 0o600);
+  return normalized;
+}
+
+export function upsertProvider(config, provider) {
+  const normalized = normalizeRuntimeConfig(config);
+  const idx = normalized.providers.findIndex((item) => item.id === provider.id);
+  if (idx >= 0) {
+    normalized.providers[idx] = {
+      ...normalized.providers[idx],
+      ...provider
+    };
+  } else {
+    normalized.providers.push(provider);
+  }
+  return normalizeRuntimeConfig(normalized);
+}
+
+export function setMasterKey(config, masterKey) {
+  const normalized = normalizeRuntimeConfig(config);
+  normalized.masterKey = masterKey;
+  return normalized;
+}
+
+export function removeProvider(config, providerId) {
+  const normalized = normalizeRuntimeConfig(config);
+  normalized.providers = normalized.providers.filter((provider) => provider.id !== providerId);
+  return normalizeRuntimeConfig(normalized);
+}

package/src/node/config-workflows.js

@@ -0,0 +1,245 @@
+/**
+ * Higher-level config workflows used by CLI actions.
+ */
+
+import { normalizeRuntimeConfig, validateRuntimeConfig } from "../runtime/config.js";
+
+function dedupe(values) {
+  return [...new Set((values || []).filter(Boolean).map((value) => String(value).trim()).filter(Boolean))];
+}
+
+function normalizeBaseUrlByFormatInput(input) {
+  const source = input?.baseUrlByFormat && typeof input.baseUrlByFormat === "object"
+    ? input.baseUrlByFormat
+    : {};
+  const openai = String(
+    source.openai ||
+    input?.openaiBaseUrl ||
+    input?.["openai-base-url"] ||
+    ""
+  ).trim();
+  const claude = String(
+    source.claude ||
+    source.anthropic ||
+    input?.claudeBaseUrl ||
+    input?.anthropicBaseUrl ||
+    input?.["claude-base-url"] ||
+    input?.["anthropic-base-url"] ||
+    ""
+  ).trim();
+
+  const out = {};
+  if (openai) out.openai = openai;
+  if (claude) out.claude = claude;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+export function parseModelListInput(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return dedupe(raw);
+  return dedupe(String(raw).split(/[,\n;\s]+/g));
+}
+
+function normalizeModelArray(models) {
+  const rows = Array.isArray(models) ? models : dedupe(models).map((id) => ({ id }));
+  return rows
+    .map((entry) => {
+      if (typeof entry === "string") return { id: entry };
+      if (!entry || typeof entry !== "object") return null;
+      const id = String(entry.id || entry.name || "").trim();
+      if (!id) return null;
+      const formats = dedupe(entry.formats || entry.format || []).filter((value) => value === "openai" || value === "claude");
+      return {
+        id,
+        ...(formats.length > 0 ? { formats } : {})
+      };
+    })
+    .filter(Boolean);
+}
+
+function buildModelsWithPreferredFormat(modelIds, modelSupport = {}, modelPreferredFormat = {}) {
+  return normalizeModelArray(modelIds.map((id) => {
+    const preferred = modelPreferredFormat[id];
+    if (preferred) {
+      return { id, formats: [preferred] };
+    }
+    return { id, formats: modelSupport[id] || [] };
+  }));
+}
+
+function summarizeEndpointMatrix(endpointMatrix) {
+  if (!Array.isArray(endpointMatrix)) return undefined;
+  return endpointMatrix.map((row) => ({
+    endpoint: row.endpoint,
+    supportedFormats: row.supportedFormats || [],
+    workingFormats: row.workingFormats || [],
+    modelsByFormat: row.modelsByFormat || {},
+    authByFormat: row.authByFormat || {}
+  }));
+}
+
+export function buildProviderFromConfigInput(input) {
+  const providerId = input.providerId || input.id || input.name;
+  const baseUrlByFormat = normalizeBaseUrlByFormatInput(input);
+  const explicitModelIds = parseModelListInput(input.models);
+  const probeModelSupport = input.probe?.modelSupport && typeof input.probe.modelSupport === "object"
+    ? input.probe.modelSupport
+    : {};
+  const probeModelPreferredFormat = input.probe?.modelPreferredFormat && typeof input.probe.modelPreferredFormat === "object"
+    ? input.probe.modelPreferredFormat
+    : {};
+  const explicitModels = explicitModelIds.length > 0
+    ? buildModelsWithPreferredFormat(explicitModelIds, probeModelSupport, probeModelPreferredFormat)
+    : [];
+  const probeModels = input.probe?.models?.length
+    ? buildModelsWithPreferredFormat(input.probe.models, probeModelSupport, probeModelPreferredFormat)
+    : [];
+  const mergedModels = explicitModels.length > 0 ? explicitModels : probeModels;
+  const endpointFormats = baseUrlByFormat ? Object.keys(baseUrlByFormat) : [];
+
+  const preferredFormat = input.probe?.preferredFormat || input.format;
+  const supportedFormats = dedupe([
+    ...(input.probe?.formats || []),
+    ...endpointFormats,
+    ...(input.formats || []),
+    ...(preferredFormat ? [preferredFormat] : [])
+  ]);
+  const baseUrl = String(input.baseUrl || "").trim()
+    || (preferredFormat ? baseUrlByFormat?.[preferredFormat] : "")
+    || baseUrlByFormat?.openai
+    || baseUrlByFormat?.claude
+    || "";
+
+  return normalizeRuntimeConfig({
+    providers: [{
+      id: providerId,
+      name: input.name || providerId,
+      baseUrl,
+      baseUrlByFormat,
+      apiKey: input.apiKey,
+      format: preferredFormat,
+      formats: supportedFormats,
+      auth: input.probe?.auth || input.auth,
+      authByFormat: input.probe?.authByFormat || input.authByFormat,
+      anthropicVersion: input.anthropicVersion,
+      anthropicBeta: input.anthropicBeta,
+      headers: input.headers || {},
+      models: mergedModels,
+      lastProbe: input.probe
+        ? {
+            ok: Boolean(input.probe.ok),
+            at: new Date().toISOString(),
+            formats: input.probe.formats || [],
+            workingFormats: input.probe.workingFormats || [],
+            models: input.probe.models || [],
+            modelSupport: input.probe.modelSupport || undefined,
+            modelPreferredFormat: input.probe.modelPreferredFormat || undefined,
+            endpointMatrix: summarizeEndpointMatrix(input.probe.endpointMatrix),
+            warnings: input.probe.warnings || undefined
+          }
+        : undefined
+    }]
+  }).providers[0];
+}
+
+export function ensureProviderHasModels(provider) {
+  if (Array.isArray(provider.models) && provider.models.length > 0) return provider;
+  return {
+    ...provider,
+    models: []
+  };
+}
+
+function mergeProviderModelsWithExistingFallbacks(existingProvider, incomingProvider) {
+  const existingModelById = new Map((existingProvider?.models || []).map((model) => [model.id, model]));
+  const mergedModels = (incomingProvider?.models || []).map((model) => {
+    const previous = existingModelById.get(model.id);
+    const hasExplicitFallbacks = Object.prototype.hasOwnProperty.call(model, "fallbackModels");
+    if (hasExplicitFallbacks || !previous) return model;
+    if (!Object.prototype.hasOwnProperty.call(previous, "fallbackModels")) return model;
+    return {
+      ...model,
+      fallbackModels: previous.fallbackModels || []
+    };
+  });
+
+  return {
+    ...incomingProvider,
+    models: mergedModels
+  };
+}
+
+export function applyConfigChanges(existingConfig, {
+  provider,
+  masterKey,
+  setDefaultModel = true
+}) {
+  const normalized = normalizeRuntimeConfig(existingConfig);
+  const providers = [...normalized.providers];
+  const existingIndex = providers.findIndex((item) => item.id === provider.id);
+
+  if (existingIndex >= 0) {
+    const mergedProvider = mergeProviderModelsWithExistingFallbacks(
+      providers[existingIndex],
+      ensureProviderHasModels(provider)
+    );
+    providers[existingIndex] = {
+      ...providers[existingIndex],
+      ...mergedProvider
+    };
+  } else {
+    providers.push(ensureProviderHasModels(provider));
+  }
+
+  const nextConfig = normalizeRuntimeConfig({
+    ...normalized,
+    providers,
+    masterKey: masterKey ?? normalized.masterKey,
+    defaultModel: normalized.defaultModel
+  });
+
+  if (setDefaultModel) {
+    const bestDefaultModel =
+      nextConfig.defaultModel ||
+      (provider.models?.[0] ? `${provider.id}/${provider.models[0].id}` : undefined);
+
+    if (bestDefaultModel) {
+      nextConfig.defaultModel = bestDefaultModel;
+    }
+  }
+
+  return nextConfig;
+}
+
+export function buildWorkerConfigPayload(config, { masterKey } = {}) {
+  const normalized = normalizeRuntimeConfig({
+    ...config,
+    masterKey: masterKey ?? config.masterKey
+  });
+
+  const errors = validateRuntimeConfig(normalized, { requireProvider: true, requireMasterKey: true });
+  if (errors.length > 0) {
+    throw new Error(errors.join(" "));
+  }
+
+  const workingProviders = (normalized.providers || []).filter((provider) => {
+    const probe = provider.lastProbe;
+    return !probe || probe.ok !== false;
+  });
+
+  if (workingProviders.length === 0) {
+    throw new Error("At least one working provider is required for worker export.");
+  }
+
+  const payload = {
+    ...normalized,
+    providers: normalized.providers.map((provider) => ({
+      ...provider,
+      // Keep apiKey in payload for all-in-one secret export. Users can later convert to apiKeyEnv if preferred.
+      apiKey: provider.apiKey,
+      lastProbe: provider.lastProbe
+    }))
+  };
+
+  return payload;
+}

package/src/node/instance-state.js

@@ -0,0 +1,206 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+
+const DEFAULT_INSTANCE_STATE_FILENAME = ".llm-router.runtime.json";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  const text = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "y"].includes(text)) return true;
+  if (["0", "false", "no", "n"].includes(text)) return false;
+  return fallback;
+}
+
+function normalizeRuntimeState(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const pid = Number(raw.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+
+  return {
+    pid,
+    host: String(raw.host || "127.0.0.1"),
+    port: Number.isFinite(Number(raw.port)) ? Number(raw.port) : 8787,
+    configPath: String(raw.configPath || ""),
+    watchConfig: normalizeBoolean(raw.watchConfig, true),
+    watchBinary: normalizeBoolean(raw.watchBinary, true),
+    requireAuth: normalizeBoolean(raw.requireAuth, false),
+    managedByStartup: normalizeBoolean(raw.managedByStartup, false),
+    cliPath: String(raw.cliPath || ""),
+    startedAt: String(raw.startedAt || new Date().toISOString()),
+    version: String(raw.version || "")
+  };
+}
+
+export function getRuntimeStatePath() {
+  return path.join(os.homedir(), DEFAULT_INSTANCE_STATE_FILENAME);
+}
+
+export async function readRuntimeState(filePath = getRuntimeStatePath()) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return normalizeRuntimeState(JSON.parse(raw));
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function writeRuntimeState(state, filePath = getRuntimeStatePath()) {
+  const normalized = normalizeRuntimeState(state);
+  if (!normalized) throw new Error("Invalid runtime state.");
+
+  const folder = path.dirname(filePath);
+  await fs.mkdir(folder, { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  await fs.chmod(filePath, 0o600);
+  return normalized;
+}
+
+export async function clearRuntimeState({ pid } = {}, filePath = getRuntimeStatePath()) {
+  if (pid !== undefined && pid !== null) {
+    const current = await readRuntimeState(filePath);
+    if (!current) return false;
+    if (Number(current.pid) !== Number(pid)) return false;
+  }
+
+  try {
+    await fs.rm(filePath, { force: true });
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export function isProcessRunning(pid) {
+  const id = Number(pid);
+  if (!Number.isInteger(id) || id <= 0) return false;
+  try {
+    process.kill(id, 0);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+}
+
+export async function getActiveRuntimeState({ cleanupStale = true } = {}) {
+  const state = await readRuntimeState();
+  if (!state) return null;
+  if (isProcessRunning(state.pid)) return state;
+
+  if (cleanupStale) {
+    await clearRuntimeState({ pid: state.pid });
+  }
+  return null;
+}
+
+export async function stopProcessByPid(pid, { graceMs = 4000 } = {}) {
+  const id = Number(pid);
+  if (!Number.isInteger(id) || id <= 0) {
+    return { ok: false, reason: "Invalid pid." };
+  }
+
+  if (!isProcessRunning(id)) {
+    return { ok: true, alreadyStopped: true };
+  }
+
+  try {
+    process.kill(id, "SIGTERM");
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < graceMs) {
+    if (!isProcessRunning(id)) {
+      return { ok: true, signal: "SIGTERM" };
+    }
+    await sleep(150);
+  }
+
+  if (!isProcessRunning(id)) {
+    return { ok: true, signal: "SIGTERM" };
+  }
+
+  try {
+    process.kill(id, "SIGKILL");
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+
+  await sleep(150);
+  if (isProcessRunning(id)) {
+    return { ok: false, reason: `Process ${id} is still running after SIGKILL.` };
+  }
+  return { ok: true, signal: "SIGKILL" };
+}
+
+export function buildStartArgsFromState(state) {
+  const target = normalizeRuntimeState(state);
+  if (!target) {
+    return {
+      configPath: "",
+      host: "127.0.0.1",
+      port: 8787,
+      watchConfig: true,
+      watchBinary: true,
+      requireAuth: false
+    };
+  }
+  return {
+    configPath: target.configPath,
+    host: target.host,
+    port: target.port,
+    watchConfig: target.watchConfig,
+    watchBinary: target.watchBinary,
+    requireAuth: target.requireAuth
+  };
+}
+
+export function spawnDetachedStart({
+  cliPath,
+  configPath,
+  host = "127.0.0.1",
+  port = 8787,
+  watchConfig = true,
+  watchBinary = true,
+  requireAuth = false
+}) {
+  const finalCliPath = String(cliPath || process.env.LLM_ROUTER_CLI_PATH || process.argv[1] || "").trim();
+  if (!finalCliPath) throw new Error("Cannot spawn llm-router start: CLI path is unknown.");
+
+  const args = [
+    finalCliPath,
+    "start",
+    `--config=${configPath}`,
+    `--host=${host}`,
+    `--port=${port}`,
+    `--watch-config=${watchConfig ? "true" : "false"}`,
+    `--watch-binary=${watchBinary ? "true" : "false"}`,
+    `--require-auth=${requireAuth ? "true" : "false"}`
+  ];
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      LLM_ROUTER_CLI_PATH: finalCliPath
+    }
+  });
+  child.unref();
+  return child.pid;
+}