blackriver-gateway 3.8.46

package/bin/cli/commands/setup-open-code.mjs

@@ -0,0 +1,398 @@
+/**
+ * omniroute setup opencode — Wire the bundled @omniroute/opencode-plugin
+ * into a local OpenCode install.
+ *
+ * Closes the gap where `npm install -g omniroute` ships the plugin
+ * inside the omniroute package (`@omniroute/opencode-plugin/dist/`) but
+ * OpenCode discovers plugins via `~/.config/opencode/plugins/` or
+ * via entries in `opencode.json`. Without this command, the user has
+ * to extract the tarball and wire it up by hand (see the plugin README,
+ * "Install" section).
+ *
+ * What it does, in order:
+ *   1. Resolves the bundled plugin path (source + built dist).
+ *   2. Resolves the OpenCode config directory (XDG-aware).
+ *   3. Copies the built plugin into `<opencode>/plugins/omniroute/`.
+ *   4. Creates or updates `opencode.json` with a single `plugin` entry
+ *      pointing at the local copy (so OC ≥1.15 picks it up).
+ *   5. Optionally runs `opencode auth login --provider omniroute`
+ *      so the next `opencode` invocation already has the API key.
+ *
+ * Idempotent: re-running with the same `--provider-id` updates the
+ * entry in place (path + baseURL) without duplicating it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+
+import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";
+import { t } from "../i18n.mjs";
+import { resolveActiveContext } from "../contexts.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// We walk up from this file to find the omniroute package root. The script
+// lives at `<omniroute>/bin/cli/commands/setup-open-code.mjs`, so the
+// package root is three levels up. Using import.meta.url (not process.cwd())
+// means the command works the same way whether you run it from the source
+// repo, a global install, or a symlinked location.
+const PACKAGE_ROOT = resolve(__dirname, "..", "..", "..");
+
+// The bundled plugin ships at PACKAGE_ROOT/@omniroute/opencode-plugin/
+// (see root package.json `files`: ["@omniroute/", ...]). The env override
+// exists so tests can point at a fixture without building the real plugin.
+const BUNDLED_PLUGIN_DIR =
+  process.env.OMNIROUTE_OPENCODE_PLUGIN_DIR || join(PACKAGE_ROOT, "@omniroute", "opencode-plugin");
+
+/**
+ * Resolve the OpenCode config directory. Honours XDG_CONFIG_HOME and the
+ * platform-specific defaults documented at https://opencode.ai/.
+ *
+ * @returns {{ configDir: string, dataDir: string }}
+ */
+function resolveOpenCodeDirs() {
+  const home = os.homedir();
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  const xdgData = process.env.XDG_DATA_HOME;
+  const platform = process.platform;
+
+  let configDir;
+  let dataDir;
+  if (platform === "darwin") {
+    // macOS: ~/Library/Application Support/opencode
+    configDir = join(home, "Library", "Application Support", "opencode");
+    dataDir = configDir; // OC uses the same root for config + data on macOS
+  } else if (platform === "win32") {
+    const appdata = process.env.APPDATA || join(home, "AppData", "Roaming");
+    const localAppdata = process.env.LOCALAPPDATA || join(home, "AppData", "Local");
+    configDir = join(appdata, "opencode");
+    dataDir = join(localAppdata, "opencode");
+  } else {
+    // Linux + everything else: XDG-style
+    configDir = xdgConfig ? join(xdgConfig, "opencode") : join(home, ".config", "opencode");
+    dataDir = xdgData ? join(xdgData, "opencode") : join(home, ".local", "share", "opencode");
+  }
+  return { configDir, dataDir };
+}
+
+/**
+ * Locate the bundled @omniroute/opencode-plugin dist. The plugin may be
+ * present in two states:
+ *
+ *   - Built (`dist/index.cjs` + `dist/index.js` exist) — preferred,
+ *     ships from a published omniroute tarball after Step 8.8 of
+ *     `scripts/build/prepublish.ts` runs.
+ *   - Unbuilt (only `src/index.ts`) — local dev / fresh clone. We surface
+ *     a clear error instead of running tsup here, because the CLI runtime
+ *     may not have tsup available (it's a devDependency).
+ *
+ * @returns {{ distEntry: string, packageDir: string }}
+ */
+function resolveBundledPlugin() {
+  if (!existsSync(BUNDLED_PLUGIN_DIR)) {
+    throw new Error(
+      `Bundled @omniroute/opencode-plugin not found at ${BUNDLED_PLUGIN_DIR}.\n` +
+        `This usually means omniroute was installed from a source tree that does not ` +
+        `include the workspace package. Try reinstalling omniroute (npm install -g omniroute) ` +
+        `or run \`cd @omniroute/opencode-plugin && npm install && npm run build\` from the source repo.`
+    );
+  }
+
+  const esmEntry = join(BUNDLED_PLUGIN_DIR, "dist", "index.js");
+
+  if (!existsSync(esmEntry)) {
+    throw new Error(
+      `@omniroute/opencode-plugin dist/ not built (looked for ${esmEntry}).\n` +
+        `Run \`cd ${BUNDLED_PLUGIN_DIR} && npm install && npm run build\` and re-run this command.`
+    );
+  }
+
+  // ESM-only build (CJS was dropped in tsup config). OpenCode (>=1.15) loads
+  // ESM modules natively.
+  return { distEntry: esmEntry, packageDir: BUNDLED_PLUGIN_DIR };
+}
+
+/**
+ * Copy the plugin package into `<opencodeConfig>/plugins/omniroute/`. We
+ * copy the entire package (dist/ + package.json) so the dist file's
+ * require/import of `zod` and `@opencode-ai/plugin` resolves against the
+ * copy's own node_modules. Without the copy, OpenCode would need to
+ * resolve the peer deps from the omniroute package's tree, which is
+ * unreliable.
+ */
+function installPluginToOpenCode(pluginInfo, opencodeConfigDir) {
+  const targetDir = join(opencodeConfigDir, "plugins", "omniroute");
+  mkdirSync(dirname(targetDir), { recursive: true });
+  mkdirSync(targetDir, { recursive: true });
+
+  // Copy package.json + dist/. We intentionally do NOT recursively copy
+  // node_modules from the source — `peerDependenciesMeta` declares zod +
+  // @opencode-ai/plugin as peers, and the user's OpenCode install already
+  // provides them. Copying our own node_modules would risk duplicate zod
+  // instances (the @opencode-ai/plugin contract uses a singleton).
+  const packageJsonSrc = join(pluginInfo.packageDir, "package.json");
+  const distSrc = join(pluginInfo.packageDir, "dist");
+  cpSync(packageJsonSrc, join(targetDir, "package.json"));
+  cpSync(distSrc, join(targetDir, "dist"), { recursive: true });
+
+  return targetDir;
+}
+
+/**
+ * Update `opencode.json` to register the plugin. Idempotent: if an entry
+ * for the same `providerId` already exists, replace it in place. If the
+ * user has any other plugin entries, preserve them.
+ *
+ * @returns {{ configPath: string, changed: boolean }}
+ */
+function registerPluginInOpenCodeConfig({
+  opencodeConfigDir,
+  pluginTargetDir,
+  providerId,
+  baseURL,
+  displayName,
+}) {
+  const configPath = join(opencodeConfigDir, "opencode.json");
+  let cfg = {};
+  if (existsSync(configPath)) {
+    try {
+      cfg = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch (err) {
+      throw new Error(
+        `Failed to parse existing ${configPath}: ${err.message}\n` +
+          `Fix or remove the file manually, then re-run \`omniroute setup opencode\`.`
+      );
+    }
+  }
+
+  const plugins = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+
+  // Plugin entries can be either a string ("@some/pkg") or a tuple
+  // ("@some/pkg", { options }). The README documents the tuple form, so
+  // we use that. The "module path" is a file:// URL relative to the
+  // opencode config dir — that is what opencode ≥1.15 resolves.
+  const entry = [
+    `./plugins/omniroute/dist/index.js`,
+    {
+      providerId,
+      baseURL,
+      ...(displayName ? { displayName } : {}),
+    },
+  ];
+
+  // Idempotency: drop any prior entry for the same providerId. We also
+  // drop a legacy `opencode-omniroute-auth` entry if present — that
+  // package is the obsolete predecessor of @omniroute/opencode-plugin
+  // and was the root cause of issue #3711.
+  const filtered = plugins.filter((p) => {
+    if (typeof p === "string") {
+      return !p.includes("opencode-omniroute-auth");
+    }
+    if (Array.isArray(p) && p[1] && typeof p[1] === "object") {
+      const pid = p[1].providerId;
+      if (pid === providerId) return false;
+      // Also drop the legacy auth plugin if it's there.
+      if (typeof p[0] === "string" && p[0].includes("opencode-omniroute-auth")) {
+        return false;
+      }
+    }
+    return true;
+  });
+  filtered.push(entry);
+  cfg.plugin = filtered;
+
+  // Make sure the config dir exists, then write the updated config.
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+
+  return { configPath, changed: true };
+}
+
+/**
+ * Optionally invoke `opencode auth login --provider <providerId>`. We
+ * shell out (instead of importing) so this command works even if
+ * OpenCode's CLI surface shifts between minor versions — the user gets
+ * a clear "could not run opencode" message instead of a hard import
+ * failure.
+ */
+function runOpenCodeAuth(providerId) {
+  const isWin = process.platform === "win32";
+  const opencodeBin = isWin ? "opencode.cmd" : "opencode";
+  const res = spawnSync(opencodeBin, ["auth", "login", "--provider", providerId], {
+    stdio: "inherit",
+    shell: false,
+  });
+  if (res.error) {
+    // ENOENT = opencode is not on PATH
+    if (res.error.code === "ENOENT") {
+      printInfo(
+        `opencode CLI not found on PATH. Run \`opencode auth login --provider ${providerId}\` manually after installing OpenCode.`
+      );
+      return 1;
+    }
+    printError(`opencode auth login failed: ${res.error.message}`);
+    return 1;
+  }
+  return typeof res.status === "number" ? res.status : 1;
+}
+
+/**
+ * Top-level action handler. Kept exported so the integration test can
+ * drive it without spawning a subprocess.
+ *
+ * @param {object} opts
+ * @param {string} [opts.providerId="omniroute"]
+ * @param {string} [opts.baseURL="http://localhost:20128"]  (Commander camelCases
+ *   `--base-url` into `baseUrl`, so both spellings are accepted.)
+ * @param {string} [opts.configDir]  Override the OpenCode config dir (tests / non-standard installs).
+ * @param {string} [opts.displayName]
+ * @param {boolean} [opts.auth=false]   Run `opencode auth login` after wiring.
+ * @param {boolean} [opts.nonInteractive=false]   Skip prompts.
+ * @returns {Promise<{ exitCode: number, configPath?: string, pluginTargetDir?: string }>}
+ */
+export async function runSetupOpenCodeCommand(opts = {}) {
+  const providerId = opts.providerId || "omniroute";
+  // Remote-aware: explicit --remote/--base-url → active context → localhost.
+  let baseURL = opts.remote || opts.baseURL || opts.baseUrl;
+  if (!baseURL) {
+    try {
+      const ctx = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
+      baseURL = ctx?.baseUrl;
+    } catch {
+      /* no context */
+    }
+  }
+  if (!baseURL) baseURL = "http://localhost:20128";
+  const displayName = opts.displayName || null;
+  const wantsAuth = Boolean(opts.auth);
+  const nonInteractive = Boolean(opts.nonInteractive);
+
+  printHeading("OmniRoute → OpenCode Plugin Setup");
+
+  const resolvedDirs = resolveOpenCodeDirs();
+  const opencodeConfigDir = opts.configDir || resolvedDirs.configDir;
+  const opencodeDataDir = resolvedDirs.dataDir;
+  printInfo(`OpenCode config dir: ${opencodeConfigDir}`);
+  printInfo(`OpenCode data dir:   ${opencodeDataDir}`);
+
+  // 1. Resolve bundled plugin
+  let pluginInfo;
+  try {
+    pluginInfo = resolveBundledPlugin();
+  } catch (err) {
+    printError(err.message);
+    return { exitCode: 1 };
+  }
+  printInfo(`Bundled plugin:      ${pluginInfo.distEntry}`);
+
+  // 2. Ensure OpenCode config dir exists (opencode will create it on
+  //    first run, but creating it now means we can write opencode.json
+  //    even if OC has never been launched).
+  if (!existsSync(opencodeConfigDir)) {
+    mkdirSync(opencodeConfigDir, { recursive: true });
+    printInfo(`Created OpenCode config dir (didn't exist yet).`);
+  }
+
+  // 3. Copy plugin into OpenCode's plugin dir
+  let pluginTargetDir;
+  try {
+    pluginTargetDir = installPluginToOpenCode(pluginInfo, opencodeConfigDir);
+    printSuccess(`Plugin installed at ${pluginTargetDir}`);
+  } catch (err) {
+    printError(`Failed to install plugin: ${err.message}`);
+    return { exitCode: 1 };
+  }
+
+  // 4. Register in opencode.json
+  let configPath;
+  try {
+    const reg = registerPluginInOpenCodeConfig({
+      opencodeConfigDir,
+      pluginTargetDir,
+      providerId,
+      baseURL,
+      displayName,
+    });
+    configPath = reg.configPath;
+    printSuccess(`opencode.json updated at ${configPath}`);
+  } catch (err) {
+    printError(`Failed to update opencode.json: ${err.message}`);
+    return { exitCode: 1, pluginTargetDir };
+  }
+
+  // 5. Optionally run auth login
+  if (wantsAuth) {
+    if (nonInteractive) {
+      printInfo(`Skipping \`opencode auth login\` (non-interactive mode).`);
+      printInfo(`Run manually: opencode auth login --provider ${providerId}`);
+    } else {
+      printHeading("Authenticating with OpenCode");
+      const authExit = runOpenCodeAuth(providerId);
+      if (authExit !== 0) {
+        return { exitCode: authExit, configPath, pluginTargetDir };
+      }
+    }
+  } else {
+    printInfo(
+      `Next step: opencode auth login --provider ${providerId}   (pass --auth to do this automatically)`
+    );
+  }
+
+  printSuccess("OpenCode plugin setup complete");
+  printInfo(`Restart OpenCode to pick up the new plugin entry.`);
+  return { exitCode: 0, configPath, pluginTargetDir };
+}
+
+/**
+ * Register the `omniroute setup opencode` subcommand on the parent
+ * `setup` command. Commander builds the doc/help from the chain, so
+ * `omniroute setup --help` automatically shows the new subcommand.
+ *
+ * @param {import("commander").Command} setupCommand  the registered `setup` command
+ */
+export function registerSetupOpenCode(setupCommand) {
+  setupCommand
+    .command("opencode")
+    .description(
+      t("setup.opencode") ||
+        "Install and register the bundled @omniroute/opencode-plugin with a local OpenCode install"
+    )
+    .option(
+      "--provider-id <id>",
+      "OpenCode provider id to register (default: omniroute)",
+      "omniroute"
+    )
+    .option(
+      "--base-url <url>",
+      "OmniRoute base URL the plugin should talk to (default: active context or http://localhost:20128)"
+    )
+    .option(
+      "--remote <url>",
+      "Remote OmniRoute URL, e.g. http://192.168.0.15:20128 (overrides --base-url and the context)"
+    )
+    .option("--display-name <name>", "Display name in the OpenCode UI (optional)")
+    .option(
+      "--auth",
+      "Run `opencode auth login --provider <providerId>` after wiring (interactive)",
+      false
+    )
+    .option("--non-interactive", "Do not prompt; skip the auth login step", false)
+    .action(async (opts, cmd) => {
+      // The parent `setup` command uses cmd.optsWithGlobals(); we mirror
+      // that here so global flags (--json, --base-url, --api-key) still
+      // flow through to the runner.
+      const globalOpts = cmd.parent?.parent?.optsWithGlobals?.() ?? {};
+      const merged = {
+        ...opts,
+        output: globalOpts.output,
+        apiKey: opts.apiKey ?? globalOpts.apiKey,
+        baseUrl: opts.baseUrl ?? globalOpts.baseUrl,
+        context: globalOpts.context ?? opts.context,
+      };
+      const { exitCode } = await runSetupOpenCodeCommand(merged);
+      if (exitCode !== 0) process.exit(exitCode);
+    });
+}

package/bin/cli/commands/setup-opencode.mjs

@@ -0,0 +1,129 @@
+/**
+ * omniroute setup-opencode — Remote-aware OpenCode provider generator
+ * (openai-compatible). Distinct from `omniroute setup opencode` (which wires the
+ * @omniroute/opencode-plugin). This writes the `omniroute` provider into
+ * ~/.config/opencode/opencode.json with every catalog model, so you can run
+ * `opencode -m omniroute/<model>`.
+ *
+ * Reuses the proven server-side generator (config-generator/opencode.ts) for the
+ * catalog fetch + merge, then references the API key by env var (never on disk).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";
+import { resolveActiveContext } from "../contexts.mjs";
+
+const ENV_KEY_REF = "{env:OMNIROUTE_API_KEY}";
+
+/** Resolve baseUrl + (literal) apiKey from flags → active context → localhost. */
+export function resolveOpencodeTarget(opts = {}) {
+  let baseUrl;
+  if (opts.remote) {
+    baseUrl = String(opts.remote).replace(/\/+$/, "");
+  } else {
+    try {
+      const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
+      baseUrl = c?.baseUrl;
+    } catch {
+      /* no context */
+    }
+    if (!baseUrl) baseUrl = `http://localhost:${Number(opts.port ?? process.env.PORT ?? 20128) || 20128}`;
+  }
+
+  let apiKey = opts.apiKey ?? opts["api-key"];
+  if (!apiKey) {
+    try {
+      const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
+      apiKey = c?.accessToken || c?.apiKey;
+    } catch {
+      /* no context auth */
+    }
+  }
+  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+/**
+ * Post-process the generator output: reference the API key by env var (keep the
+ * secret off disk) and optionally keep only models whose id matches `only`.
+ * Pure + testable. Returns the final JSON string.
+ *
+ * @param {string} rawJson  output of generateOpencodeConfig
+ * @param {{ only?: string[] }} [opts]
+ * @returns {{ json: string, modelCount: number }}
+ */
+export function postProcessOpencodeConfig(rawJson, opts = {}) {
+  const config = JSON.parse(rawJson);
+  const prov = config.provider?.omniroute;
+  if (prov?.options) prov.options.apiKey = ENV_KEY_REF;
+
+  if (opts.only && opts.only.length && prov?.models) {
+    const kept = {};
+    for (const [id, entry] of Object.entries(prov.models)) {
+      if (opts.only.some((f) => id.includes(f))) kept[id] = entry;
+    }
+    prov.models = kept;
+  }
+  const modelCount = prov?.models ? Object.keys(prov.models).length : 0;
+  return { json: JSON.stringify(config, null, 2) + "\n", modelCount };
+}
+
+export async function runSetupOpencodeCommand(opts = {}) {
+  const { baseUrl, apiKey } = resolveOpencodeTarget(opts);
+  const dryRun = Boolean(opts.dryRun ?? opts["dry-run"]);
+  const only = opts.only ? opts.only.split(",").map((s) => s.trim()).filter(Boolean) : null;
+
+  printHeading("OmniRoute → OpenCode provider (openai-compatible)");
+  printInfo(`Connecting to ${baseUrl} …`);
+
+  // Deferred import: opencode.ts is TypeScript; tsx is registered by
+  // bin/omniroute.mjs before any command runs, so importing here is safe.
+  let raw;
+  try {
+    const { generateOpencodeConfig } = await import(
+      "../../../src/lib/cli-helper/config-generator/opencode.ts"
+    );
+    raw = await generateOpencodeConfig({ baseUrl, apiKey, model: opts.model, providerId: "omniroute" });
+  } catch (err) {
+    printError(`Failed to generate opencode.json: ${err?.message || err}`);
+    printInfo("Make sure OmniRoute is running and --remote/--api-key are correct.");
+    return 1;
+  }
+
+  const { json, modelCount } = postProcessOpencodeConfig(raw, { only });
+  const configDir = join(os.homedir(), ".config", "opencode");
+  const configPath = join(configDir, "opencode.json");
+
+  if (dryRun) {
+    console.log(json.length > 4000 ? json.slice(0, 4000) + "\n… (truncated)" : json);
+    printInfo(`[dry-run] ${modelCount} model(s) under provider 'omniroute' → ${configPath}`);
+    return 0;
+  }
+
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+  writeFileSync(configPath, json, "utf8");
+  printSuccess(`opencode.json updated at ${configPath} (${modelCount} models under 'omniroute')`);
+  printInfo('Use it:  opencode -m omniroute/<model> "..."   (export OMNIROUTE_API_KEY first)');
+  return 0;
+}
+
+export function registerSetupOpencode(program) {
+  program
+    .command("setup-opencode")
+    .description(
+      "Generate the OmniRoute openai-compatible provider in ~/.config/opencode/opencode.json " +
+        "from the live model catalog (local or remote VPS)"
+    )
+    .option("--port <port>", "Local OmniRoute port (ignored when --remote is set)", "20128")
+    .option("--remote <url>", "Remote OmniRoute URL, e.g. http://192.168.0.15:20128")
+    .option("--api-key <key>", "OmniRoute API key (defaults to OMNIROUTE_API_KEY env var)")
+    .option("--model <id>", "Set the default top-level model (omniroute/<id>)")
+    .option("--only <patterns>", "Comma-separated substrings — keep only matching model IDs")
+    .option("--dry-run", "Print what would be written without touching the filesystem")
+    .action(async (opts) => {
+      const code = await runSetupOpencodeCommand(opts);
+      if (code !== 0) process.exit(code);
+    });
+}

package/bin/cli/commands/setup-qwen.mjs

@@ -0,0 +1,156 @@
+/**
+ * omniroute setup-qwen — configure Qwen Code (QwenLM/qwen-code) for OmniRoute.
+ *
+ * Qwen Code is a terminal AI agent with a file-based config at
+ * ~/.qwen/settings.json. For a custom OpenAI-compatible endpoint it uses a
+ * `modelProviders` entry with authType "openai", baseUrl WITH /v1, and an
+ * `envKey` naming the env var holding the key (secret stays in the env, never the
+ * file). Remote-aware; headless test via `qwen -p "..."`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import { printHeading, printInfo, printSuccess, printError, createPrompt } from "../io.mjs";
+import { resolveActiveContext } from "../contexts.mjs";
+
+function ensureV1(url) {
+  const s = String(url || "").replace(/\/+$/, "");
+  return s.endsWith("/v1") ? s : `${s}/v1`;
+}
+
+/** Resolve baseUrl (WITH /v1) + apiKey from flags → active context → localhost. */
+export function resolveQwenTarget(opts = {}) {
+  let root;
+  if (opts.remote) root = String(opts.remote).replace(/\/+$/, "");
+  else {
+    try {
+      root = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT)?.baseUrl;
+    } catch {
+      /* none */
+    }
+    if (!root) root = `http://localhost:${Number(opts.port ?? process.env.PORT ?? 20128) || 20128}`;
+  }
+  let apiKey = opts.apiKey ?? opts["api-key"];
+  if (!apiKey) {
+    try {
+      const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
+      apiKey = c?.accessToken || c?.apiKey;
+    } catch {
+      /* none */
+    }
+  }
+  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
+  return { baseUrl: ensureV1(root), apiKey };
+}
+
+/** Merge the OmniRoute modelProvider into Qwen's settings.json (preserve rest). */
+export function buildQwenSettings(existing, { baseUrl, model }) {
+  const s = existing && typeof existing === "object" ? { ...existing } : {};
+  const providers = Array.isArray(s.modelProviders)
+    ? s.modelProviders.filter((p) => p?.id !== "omniroute")
+    : [];
+  providers.push({
+    id: "omniroute",
+    name: "OmniRoute",
+    authType: "openai",
+    baseUrl,
+    envKey: "OMNIROUTE_API_KEY",
+  });
+  s.modelProviders = providers;
+  if (model) {
+    s.selectedProvider = "omniroute";
+    s.model = model;
+  }
+  return s;
+}
+
+function readJson(path) {
+  try {
+    if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    /* corrupt/missing */
+  }
+  return {};
+}
+
+async function fetchModelIds(baseUrl, apiKey) {
+  try {
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    const res = await fetch(`${baseUrl.replace(/\/v1$/, "")}/v1/models`, {
+      headers,
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) return [];
+    const body = await res.json();
+    const list = Array.isArray(body) ? body : (body.data ?? body.models ?? []);
+    return list.map((m) => (typeof m === "string" ? m : m?.id)).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export async function runSetupQwenCommand(opts = {}) {
+  const { baseUrl, apiKey } = resolveQwenTarget(opts);
+  const dryRun = Boolean(opts.dryRun ?? opts["dry-run"]);
+  const configPath =
+    opts.configPath ?? opts["config-path"] ?? join(os.homedir(), ".qwen", "settings.json");
+
+  printHeading("OmniRoute → Qwen Code (openai-compatible)");
+  printInfo(`baseUrl: ${baseUrl}`);
+
+  let model = opts.model;
+  if (!model) {
+    const ids = await fetchModelIds(baseUrl, apiKey);
+    if (ids.length && !opts.yes) {
+      printInfo(`Examples: ${ids.slice(0, 20).join(", ")}${ids.length > 20 ? " …" : ""}`);
+      const prompt = createPrompt();
+      try {
+        model = await prompt.ask("Model id for Qwen");
+      } finally {
+        prompt.close();
+      }
+    }
+  }
+  if (!model) {
+    printError("A model is required. Pass --model <id>.");
+    return 2;
+  }
+
+  const merged = buildQwenSettings(readJson(configPath), { baseUrl, model });
+  const out = JSON.stringify(merged, null, 2) + "\n";
+
+  if (dryRun) {
+    console.log("\n" + out);
+    printInfo(`[dry-run] → ${configPath}`);
+  } else {
+    mkdirSync(join(configPath, ".."), { recursive: true });
+    writeFileSync(configPath, out, "utf8");
+    printSuccess(`Wrote ${configPath}`);
+  }
+  printInfo(
+    "\nProvide the key (settings reference OMNIROUTE_API_KEY):  export OMNIROUTE_API_KEY=..."
+  );
+  printInfo('Then run:  qwen        (or headless: qwen -p "reply OK")');
+  return 0;
+}
+
+export function registerSetupQwen(program) {
+  program
+    .command("setup-qwen")
+    .description(
+      "Configure Qwen Code for OmniRoute: write ~/.qwen/settings.json (openai modelProvider)"
+    )
+    .option("--port <port>", "Local OmniRoute port (ignored when --remote is set)", "20128")
+    .option("--remote <url>", "Remote OmniRoute URL, e.g. http://192.168.0.15:20128")
+    .option("--api-key <key>", "OmniRoute API key (defaults to OMNIROUTE_API_KEY env var)")
+    .option("--model <id>", "Model id for Qwen (required unless picked interactively)")
+    .option("--config-path <path>", "settings.json path (default: ~/.qwen/settings.json)")
+    .option("--yes", "Non-interactive: do not prompt (requires --model)")
+    .option("--dry-run", "Print what would be written without touching the filesystem")
+    .action(async (opts) => {
+      const code = await runSetupQwenCommand(opts);
+      if (code !== 0) process.exit(code);
+    });
+}