@heventure/model-provider-x 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HHWY Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# model-provider-x
+
+`model-provider-x` is a TypeScript CLI/TUI tool for wiring custom model providers into local AI coding tools.
+
+It currently supports:
+
+- OpenCode provider config generation and JSONC merge.
+- Claude Code setup through a local Anthropic Messages-compatible proxy.
+- OpenAI-compatible `/v1/models` discovery.
+- Anthropic Messages API to OpenAI Chat Completions API conversion.
+- Non-streaming and streaming SSE proxy responses.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+Or run the published package directly:
+
+```bash
+npx @heventure/model-provider-x --help
+```
+
+## OpenCode Setup
+
+Run the TUI wizard:
+
+```bash
+node dist/cli/index.js
+```
+
+Or print a config fragment without writing files:
+
+```bash
+node dist/cli/index.js \
+  --name "Unsloth Local" \
+  --id unsloth \
+  --base-url http://localhost:8888/v1 \
+  --models qwen,gemma \
+  --print
+```
+
+## Claude Code Setup
+
+Create or update a provider profile and write Claude Code user settings:
+
+```bash
+node dist/cli/index.js setup --target claude-code \
+  --name "Unsloth Local" \
+  --id unsloth \
+  --base-url http://localhost:8888/v1
+```
+
+Then start the local proxy:
+
+```bash
+node dist/cli/index.js proxy --profile unsloth
+```
+
+The Claude Code setup writes gateway environment values to `~/.claude/settings.json`.
+Upstream provider keys are stored in `~/.config/model-provider-x/config.jsonc`, not in Claude Code settings.
+
+## Commands
+
+```bash
+npx @heventure/model-provider-x --help
+npx @heventure/model-provider-x setup --target claude-code
+npx @heventure/model-provider-x proxy --profile <id>
+npx @heventure/model-provider-x config print --profile <id>
+```
+
+## Development
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+## License
+
+MIT

package/dist/cli/args.js

@@ -0,0 +1,107 @@
+export function parseCliArgs(argv) {
+    const options = { print: false, yes: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = () => {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error(`${arg} requires a value`);
+            }
+            index += 1;
+            return value;
+        };
+        switch (arg) {
+            case "--api-key":
+                options.apiKey = next();
+                break;
+            case "--base-url":
+                options.baseURL = next();
+                break;
+            case "--config":
+                options.configPath = next();
+                break;
+            case "--id":
+                options.providerId = next();
+                break;
+            case "--models":
+                options.models = next()
+                    .split(",")
+                    .map((model) => model.trim())
+                    .filter(Boolean);
+                break;
+            case "--name":
+                options.providerName = next();
+                break;
+            case "--print":
+                options.print = true;
+                break;
+            case "--yes":
+            case "-y":
+                options.yes = true;
+                break;
+            case "--help":
+            case "-h":
+                throw new HelpRequested();
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return options;
+}
+export function parseModelSelection(selection, models) {
+    const trimmed = selection.trim();
+    if (!trimmed || trimmed.toLowerCase() === "all") {
+        return models;
+    }
+    const selected = new Set();
+    for (const part of trimmed.split(",")) {
+        const token = part.trim();
+        const range = token.match(/^(\d+)-(\d+)$/);
+        if (range) {
+            const start = Number(range[1]);
+            const end = Number(range[2]);
+            for (let index = start; index <= end; index += 1) {
+                addModelByOneBasedIndex(selected, models, index);
+            }
+            continue;
+        }
+        const index = Number(token);
+        if (Number.isInteger(index)) {
+            addModelByOneBasedIndex(selected, models, index);
+            continue;
+        }
+        if (models.includes(token)) {
+            selected.add(token);
+            continue;
+        }
+        throw new Error(`Unknown model selection: ${token}`);
+    }
+    return [...selected];
+}
+export function usage() {
+    return `model-provider-x
+
+Usage:
+  model-provider-x [options]
+
+Options:
+  --base-url <url>     OpenAI-compatible API base URL, for example http://localhost:8888/v1
+  --api-key <key>      Optional API key. Written into config when provided.
+  --name <name>        Provider display name.
+  --id <id>            Provider id used under provider.<id>.
+  --models <list>      Comma-separated model ids. Skips interactive model selection.
+  --config <path>      OpenCode config path to write.
+  --print              Print generated JSON and do not write config.
+  --yes, -y            Accept defaults in non-interactive prompts.
+  --help, -h           Show this help.
+`;
+}
+export class HelpRequested extends Error {
+}
+function addModelByOneBasedIndex(selected, models, index) {
+    const model = models[index - 1];
+    if (!model) {
+        throw new Error(`Model index out of range: ${index}`);
+    }
+    selected.add(model);
+}

package/dist/cli/commands.js

@@ -0,0 +1,139 @@
+import { HelpRequested, parseCliArgs, usage } from "./args.js";
+export function parseCommand(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command.startsWith("--")) {
+        return { command: "opencode", options: parseCliArgs(argv) };
+    }
+    if (command === "setup") {
+        return parseSetupCommand(rest);
+    }
+    if (command === "proxy") {
+        return parseProxyCommand(rest);
+    }
+    if (command === "config") {
+        return parseConfigCommand(rest);
+    }
+    if (command === "--help" || command === "-h") {
+        throw new HelpRequested();
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+export function commandUsage() {
+    return `${usage()}
+Commands:
+  model-provider-x setup --target <opencode|claude-code> [options]
+  model-provider-x proxy --profile <id> [--host 127.0.0.1] [--port 4141]
+  model-provider-x config print --profile <id>
+`;
+}
+function parseSetupCommand(argv) {
+    let target = "opencode";
+    let profileId;
+    let port;
+    let host;
+    let defaultModel;
+    const providerArgs = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = () => {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error(`${arg} requires a value`);
+            }
+            index += 1;
+            return value;
+        };
+        switch (arg) {
+            case "--target":
+                target = parseTarget(next());
+                break;
+            case "--profile":
+                profileId = next();
+                break;
+            case "--port":
+                port = parsePort(next());
+                break;
+            case "--host":
+                host = next();
+                break;
+            case "--default-model":
+                defaultModel = next();
+                break;
+            default:
+                providerArgs.push(arg);
+        }
+    }
+    return { command: "setup", target, profileId, port, host, defaultModel, options: parseCliArgs(providerArgs) };
+}
+function parseProxyCommand(argv) {
+    let profileId;
+    let host;
+    let port;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = () => {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error(`${arg} requires a value`);
+            }
+            index += 1;
+            return value;
+        };
+        switch (arg) {
+            case "--profile":
+                profileId = next();
+                break;
+            case "--host":
+                host = next();
+                break;
+            case "--port":
+                port = parsePort(next());
+                break;
+            case "--help":
+            case "-h":
+                throw new HelpRequested();
+            default:
+                throw new Error(`Unknown proxy argument: ${arg}`);
+        }
+    }
+    if (!profileId) {
+        throw new Error("--profile is required");
+    }
+    return { command: "proxy", profileId, host, port };
+}
+function parseConfigCommand(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "print") {
+        throw new Error(`Unknown config command: ${subcommand ?? ""}`.trim());
+    }
+    let profileId;
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg !== "--profile") {
+            throw new Error(`Unknown config print argument: ${arg}`);
+        }
+        const value = rest[index + 1];
+        if (!value || value.startsWith("--")) {
+            throw new Error("--profile requires a value");
+        }
+        profileId = value;
+        index += 1;
+    }
+    if (!profileId) {
+        throw new Error("--profile is required");
+    }
+    return { command: "config-print", profileId };
+}
+function parseTarget(value) {
+    if (value === "opencode" || value === "claude-code") {
+        return value;
+    }
+    throw new Error(`Unknown setup target: ${value}`);
+}
+function parsePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid port: ${value}`);
+    }
+    return port;
+}

package/dist/cli/index.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { getDefaultToolConfigPath, readToolConfig, upsertProviderProfile } from "../core/tool-config.js";
+import { discoverOpenCodeConfigs, getDefaultConfigPath, writeProviderToConfig } from "../core/config.js";
+import { buildProviderConfig, validateAndFetchModels } from "../core/provider.js";
+import { startProxyServer } from "../proxy/server.js";
+import { getDefaultClaudeSettingsPath, writeClaudeCodeSettings } from "../targets/claude-code.js";
+import { HelpRequested, parseModelSelection } from "./args.js";
+import { commandUsage, parseCommand } from "./commands.js";
+import { canUseTui, multiSelectChoices, renderIntro, selectChoice } from "./tui.js";
+async function main() {
+    try {
+        const command = parseCommand(process.argv.slice(2));
+        await runCommand(command);
+    }
+    catch (error) {
+        if (error instanceof HelpRequested) {
+            console.log(commandUsage());
+            return;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runCommand(command) {
+    if (command.command === "opencode") {
+        await runCli(command.options);
+        return;
+    }
+    if (command.command === "setup") {
+        await runSetup(command);
+        return;
+    }
+    if (command.command === "config-print") {
+        const config = await readToolConfig();
+        const profile = config.profiles[command.profileId];
+        if (!profile) {
+            throw new Error(`Unknown provider profile: ${command.profileId}`);
+        }
+        output.write(`${JSON.stringify(profile, null, 2)}\n`);
+        return;
+    }
+    const config = await readToolConfig();
+    const server = await startProxyServer({
+        profileId: command.profileId,
+        config,
+        host: command.host,
+        port: command.port
+    });
+    output.write(`model-provider-x proxy listening at ${server.baseURL}\n`);
+    await new Promise((resolve) => {
+        const stop = async () => {
+            await server.close();
+            resolve();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+export async function runCli(options) {
+    const rl = createInterface({ input, output });
+    try {
+        output.write(canUseTui() ? renderIntro() : "model-provider-x\n\n");
+        const providerName = await requiredOption(rl, options.providerName, "Provider name");
+        const providerId = await requiredOption(rl, options.providerId ?? slugify(providerName), "Provider id");
+        const baseURL = await requiredOption(rl, options.baseURL, "API base URL");
+        const apiKey = options.apiKey ?? (await rl.question("API key (optional): "));
+        output.write("Fetching models...\n");
+        const fetched = await validateAndFetchModels({ baseURL, apiKey });
+        const selectedModels = options.models ??
+            (canUseTui()
+                ? await multiSelectChoices("Select models", fetched.models.map((model) => ({ label: model, value: model })))
+                : parseModelSelection(await rl.question(formatModelPrompt(fetched.models)), fetched.models));
+        const fragment = buildProviderConfig({
+            providerId,
+            providerName,
+            baseURL: fetched.baseURL,
+            apiKey,
+            models: selectedModels
+        });
+        const provider = fragment.provider[providerId];
+        const json = JSON.stringify(fragment, null, 2);
+        if (options.print) {
+            output.write(`${json}\n`);
+            return;
+        }
+        const targetPath = options.configPath ?? (await chooseConfigPath(rl, providerId, options.yes));
+        if (!targetPath) {
+            output.write(`${json}\n`);
+            return;
+        }
+        if (apiKey.trim()) {
+            output.write("Warning: the API key will be written to the selected OpenCode config.\n");
+        }
+        const result = await writeProviderToConfig({ targetPath, providerId, provider });
+        output.write(`Updated ${result.targetPath}\n`);
+        if (result.backupPath) {
+            output.write(`Backup: ${result.backupPath}\n`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runSetup(command) {
+    if (command.target === "opencode") {
+        await runCli(command.options);
+        return;
+    }
+    await runClaudeCodeSetup(command);
+}
+async function runClaudeCodeSetup(command) {
+    const rl = createInterface({ input, output });
+    try {
+        output.write(canUseTui() ? renderIntro() : "model-provider-x\n\n");
+        const providerName = await requiredOption(rl, command.options.providerName, "Provider name");
+        const providerId = await requiredOption(rl, command.profileId ?? command.options.providerId ?? slugify(providerName), "Provider id");
+        const baseURL = await requiredOption(rl, command.options.baseURL, "API base URL");
+        const apiKey = command.options.apiKey ?? (await rl.question("Upstream API key (optional): "));
+        output.write("Fetching models...\n");
+        const fetched = await validateAndFetchModels({ baseURL, apiKey });
+        const selectedModels = command.options.models ??
+            (canUseTui()
+                ? await multiSelectChoices("Select Claude Code gateway models", fetched.models.map((model) => ({ label: model, value: model })))
+                : parseModelSelection(await rl.question(formatModelPrompt(fetched.models)), fetched.models));
+        const toolConfigPath = getDefaultToolConfigPath();
+        const config = await upsertProviderProfile(toolConfigPath, {
+            id: providerId,
+            name: providerName,
+            baseURL: fetched.baseURL,
+            apiKey: apiKey.trim() || undefined,
+            models: selectedModels
+        }, {
+            host: command.host,
+            port: command.port
+        });
+        const proxyBaseURL = `http://${config.proxy.host}:${config.proxy.port}`;
+        const result = await writeClaudeCodeSettings({
+            targetPath: getDefaultClaudeSettingsPath(),
+            proxy: {
+                baseURL: proxyBaseURL,
+                authToken: config.proxy.authToken,
+                enableModelDiscovery: true,
+                defaultModel: command.defaultModel
+            }
+        });
+        output.write(`Saved profile ${providerId} to ${toolConfigPath}\n`);
+        output.write(`Updated Claude Code settings: ${result.targetPath}\n`);
+        if (result.backupPath) {
+            output.write(`Backup: ${result.backupPath}\n`);
+        }
+        output.write(`Run proxy: model-provider-x proxy --profile ${providerId}\n`);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function requiredOption(rl, value, label) {
+    const answer = value ?? (await rl.question(`${label}: `));
+    if (!answer.trim()) {
+        throw new Error(`${label} is required`);
+    }
+    return answer.trim();
+}
+async function chooseConfigPath(rl, providerId, yes) {
+    const configs = await discoverOpenCodeConfigs({ providerId });
+    if (configs.length === 0) {
+        const defaultPath = getDefaultConfigPath();
+        if (yes) {
+            return defaultPath;
+        }
+        if (canUseTui()) {
+            return selectChoice("No OpenCode config found", [
+                { label: `Create ${defaultPath}`, value: defaultPath },
+                { label: "Print JSON only", value: undefined, hint: "copy it manually" }
+            ]);
+        }
+        const answer = await rl.question(`No OpenCode config found. Create ${defaultPath}? [Y/n/print] `);
+        if (!answer.trim() || answer.trim().toLowerCase() === "y") {
+            return defaultPath;
+        }
+        return undefined;
+    }
+    output.write("OpenCode configs:\n");
+    configs.forEach((config, index) => {
+        output.write(`${index + 1}. ${describeConfig(config)}\n`);
+    });
+    if (yes) {
+        return configs.find((config) => config.writable)?.path;
+    }
+    if (canUseTui()) {
+        return selectChoice("Choose install target", [
+            ...configs.map((config) => ({
+                label: config.label,
+                value: config.path,
+                hint: `${config.path}${config.hasProvider ? " (provider exists)" : ""}`,
+                disabled: !config.writable
+            })),
+            { label: "Print JSON only", value: undefined, hint: "copy it manually" }
+        ]);
+    }
+    const answer = await rl.question("Choose config number, enter a path, or type print: ");
+    if (answer.trim().toLowerCase() === "print") {
+        return undefined;
+    }
+    const index = Number(answer.trim());
+    if (Number.isInteger(index) && configs[index - 1]) {
+        return configs[index - 1].path;
+    }
+    if (answer.trim()) {
+        return answer.trim();
+    }
+    return configs.find((config) => config.writable)?.path;
+}
+function describeConfig(config) {
+    const flags = [config.writable ? "writable" : "read-only", config.hasProvider ? "provider exists" : undefined]
+        .filter(Boolean)
+        .join(", ");
+    return `${config.label} - ${config.path} (${flags})`;
+}
+function formatModelPrompt(models) {
+    const lines = models.map((model, index) => `${index + 1}. ${model}`).join("\n");
+    return `Models:\n${lines}\nSelect models by number, range, name, comma list, or press Enter for all: `;
+}
+function slugify(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+void main();