scalemax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleMax
+
+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,273 @@
+# ScaleMax CLI
+
+Universal installer for configuring AI coding clients to use the ScaleMax OpenAI-compatible API gateway.
+
+ScaleMax CLI is designed to be run from any machine with Node.js installed:
+
+```bash
+npx scalemax
+```
+
+It detects supported AI coding clients, safely backs up existing config files, and writes ScaleMax-compatible configuration using your ScaleMax API key.
+
+## Requirements
+
+- Node.js `18.17` or newer
+- macOS, Linux, or Windows
+- A ScaleMax API key
+- Network access to `https://api.scalemax.pro`
+
+## Installation
+
+### One-time run with npx
+
+```bash
+npx scalemax
+```
+
+### Always use the latest published version
+
+```bash
+npx scalemax@latest
+```
+
+### Global install
+
+```bash
+npm install -g scalemax
+scalemax
+```
+
+## Quick Start
+
+```bash
+npx scalemax
+```
+
+If no ScaleMax configuration exists, the installer prompts:
+
+```text
+Enter your ScaleMax API key:
+```
+
+If configuration already exists, the installer preserves the existing flow:
+
+```text
+✓ Existing ScaleMax configuration detected.
+
+API key:
+••••••••••••••••abcd
+
+1. Keep existing key
+2. Replace with new key
+3. Remove configuration
+4. Exit
+```
+
+After authentication, ScaleMax CLI detects installed clients and lets you configure one client or all detected clients.
+
+## Commands
+
+```bash
+scalemax              Interactive installer
+scalemax login        Store or replace your ScaleMax API key
+scalemax logout       Remove stored ScaleMax API key
+scalemax doctor       Run diagnostics
+scalemax models       List available ScaleMax models
+scalemax update       Reconfigure detected clients with the stored key
+scalemax remove       Remove ScaleMax-generated client configuration
+scalemax --help       Show help
+scalemax --version    Show installed version
+```
+
+## Authentication
+
+ScaleMax CLI stores your API key in a user-level configuration file:
+
+- macOS: `~/Library/Application Support/scalemax/config.json`
+- Linux: `$XDG_CONFIG_HOME/scalemax/config.json` or `~/.config/scalemax/config.json`
+- Windows: `%APPDATA%\scalemax\config.json`
+
+The file is written with private permissions where supported. The API key is never printed; existing keys are displayed only as a masked value such as `••••••••••••••••abcd`.
+
+For CI or non-interactive checks, you may provide the key through the environment:
+
+```bash
+SCALEMAX_API_KEY=sm_live_xxx scalemax models
+```
+
+## Supported clients
+
+- Codex
+- Cursor
+- Claude Code
+- OpenCode
+- OpenClaw
+- Hermes
+- Continue
+- VS Code
+- Windsurf
+
+## Examples
+
+List models:
+
+```bash
+npx scalemax models
+```
+
+Run diagnostics:
+
+```bash
+npx scalemax doctor
+```
+
+Configure all detected clients after login:
+
+```bash
+npx scalemax update
+```
+
+Remove ScaleMax-generated client config and restore backups when available:
+
+```bash
+npx scalemax remove
+```
+
+## Updating
+
+With npx:
+
+```bash
+npx scalemax@latest
+```
+
+With a global install:
+
+```bash
+npm update -g scalemax
+# or
+npm install -g scalemax@latest
+```
+
+## Removing configuration
+
+Remove only the stored ScaleMax API key:
+
+```bash
+scalemax logout
+```
+
+Remove ScaleMax-generated client configuration files and restore backups when possible:
+
+```bash
+scalemax remove
+```
+
+## Troubleshooting
+
+### `No ScaleMax API key found`
+
+Run:
+
+```bash
+scalemax login
+```
+
+### `API check failed: HTTP 401`
+
+Your key is missing, expired, inactive, or mistyped. Run:
+
+```bash
+scalemax login
+```
+
+Then paste a valid ScaleMax API key.
+
+### `npx` runs an old version
+
+Force latest:
+
+```bash
+npx scalemax@latest
+```
+
+Or clear the npm cache:
+
+```bash
+npm cache verify
+```
+
+### Client config looks wrong
+
+Run:
+
+```bash
+scalemax doctor
+```
+
+Then reconfigure:
+
+```bash
+scalemax update
+```
+
+### Remove and start over
+
+```bash
+scalemax remove
+scalemax logout
+npx scalemax@latest
+```
+
+## Release process for maintainers
+
+See `RELEASE.md` in the repository. In short:
+
+```bash
+npm run version:patch   # or version:minor / version:major
+npm run prepublishOnly
+npm publish
+```
+
+Never publish over an existing npm version. Use semantic versioning for every release.
+
+## Safety guarantees
+
+- Existing client configuration files are backed up before writes.
+- Writes are atomic.
+- API keys are masked in terminal output.
+- The published npm package contains only runtime files: `dist/`, `README.md`, `LICENSE`, and `package.json`.
+- Tests, TypeScript source, scripts, local caches, `.env` files, tarballs, and `node_modules` are excluded from the published package.
+
+## FAQ
+
+### Does `npx scalemax` install anything permanently?
+
+`npx` downloads and runs the CLI package. The CLI itself writes ScaleMax configuration only after you choose to configure clients.
+
+### Can I use it without global install?
+
+Yes. Use:
+
+```bash
+npx scalemax@latest
+```
+
+### Can I use a different API key later?
+
+Yes. Run:
+
+```bash
+scalemax login
+```
+
+or rerun the installer and choose `Replace with a new key`.
+
+### Does it support Windows?
+
+Yes. The CLI uses Windows-aware config paths and writes `%APPDATA%\scalemax\config.json` for ScaleMax key storage.
+
+### What endpoint does it configure?
+
+`https://api.scalemax.pro/v1`

package/dist/clients.d.ts

@@ -0,0 +1,2 @@
+import { ClientDefinition } from './types/client.js';
+export declare const clients: ClientDefinition[];

package/dist/clients.js

@@ -0,0 +1,29 @@
+import * as codexDetect from './detect/codex.js';
+import * as codexConfig from './configure/codex.js';
+import * as cursorDetect from './detect/cursor.js';
+import * as cursorConfig from './configure/cursor.js';
+import * as claudeDetect from './detect/claude.js';
+import * as claudeConfig from './configure/claude.js';
+import * as opencodeDetect from './detect/opencode.js';
+import * as opencodeConfig from './configure/opencode.js';
+import * as openclawDetect from './detect/openclaw.js';
+import * as openclawConfig from './configure/openclaw.js';
+import * as hermesDetect from './detect/hermes.js';
+import * as hermesConfig from './configure/hermes.js';
+import * as continueDetect from './detect/continue.js';
+import * as continueConfig from './configure/continue.js';
+import * as vscodeDetect from './detect/vscode.js';
+import * as vscodeConfig from './configure/vscode.js';
+import * as windsurfDetect from './detect/windsurf.js';
+import * as windsurfConfig from './configure/windsurf.js';
+export const clients = [
+    { id: 'codex', name: 'Codex', detect: codexDetect.detect, configure: codexConfig.configure, remove: codexConfig.remove },
+    { id: 'cursor', name: 'Cursor', detect: cursorDetect.detect, configure: cursorConfig.configure, remove: cursorConfig.remove },
+    { id: 'claude', name: 'Claude Code', detect: claudeDetect.detect, configure: claudeConfig.configure, remove: claudeConfig.remove },
+    { id: 'opencode', name: 'OpenCode', detect: opencodeDetect.detect, configure: opencodeConfig.configure, remove: opencodeConfig.remove },
+    { id: 'openclaw', name: 'OpenClaw', detect: openclawDetect.detect, configure: openclawConfig.configure, remove: openclawConfig.remove },
+    { id: 'hermes', name: 'Hermes', detect: hermesDetect.detect, configure: hermesConfig.configure, remove: hermesConfig.remove },
+    { id: 'vscode', name: 'VS Code', detect: vscodeDetect.detect, configure: vscodeConfig.configure, remove: vscodeConfig.remove },
+    { id: 'continue', name: 'Continue', detect: continueDetect.detect, configure: continueConfig.configure, remove: continueConfig.remove },
+    { id: 'windsurf', name: 'Windsurf', detect: windsurfDetect.detect, configure: windsurfConfig.configure, remove: windsurfConfig.remove }
+];

package/dist/commands/configure.d.ts

@@ -0,0 +1,7 @@
+export declare function detectAll(home?: string): Promise<import("../types/client.js").DetectionResult[]>;
+export declare function printDetected(home?: string): Promise<import("../types/client.js").DetectionResult[]>;
+export declare function configureCommand(opts?: {
+    all?: boolean;
+    home?: string;
+    promptLaunch?: boolean;
+}): Promise<void>;

package/dist/commands/configure.js

@@ -0,0 +1,78 @@
+import { select, isCancel, cancel, confirm } from '@clack/prompts';
+import chalk from 'chalk';
+import ora from 'ora';
+import { clients } from '../clients.js';
+import { SCALEMAX_BASE_URL } from '../constants.js';
+import { loadApiKey } from '../utils/keyStore.js';
+import { homeDir } from '../utils/paths.js';
+import { launchCodex } from '../configure/codex.js';
+export async function detectAll(home = homeDir()) {
+    const ctx = { home, platform: process.platform, env: process.env };
+    return Promise.all(clients.map(c => c.detect(ctx)));
+}
+export async function printDetected(home = homeDir()) {
+    const detections = await detectAll(home);
+    console.log(chalk.bold('\nDetected Clients\n'));
+    for (const d of detections)
+        console.log(`${d.installed ? chalk.green('✓') : chalk.dim('✗')} ${d.name}`);
+    console.log('');
+    return detections;
+}
+async function maybeLaunchCodex(chosen, successful) {
+    if (!chosen.includes('codex') || !successful.has('codex'))
+        return;
+    console.log(chalk.green('\nConfiguration completed.\n'));
+    const answer = await confirm({ message: 'Would you like to launch Codex now?', initialValue: true });
+    if (isCancel(answer) || answer === false)
+        return;
+    console.log('\nLaunching Codex...\n');
+    const result = await launchCodex();
+    if (result.ok)
+        console.log(chalk.green(`✓ ${result.message}`));
+    else {
+        console.log(chalk.red(`✗ ${result.message}`));
+        if (result.output)
+            console.log(result.output);
+    }
+    console.log('\nIf Codex asks for authentication,\nit should already be configured to use ScaleMax.\n\nIf you still see the official login screen,\nthe configuration is incomplete or Codex rejected the generated auth/config files.\n');
+}
+export async function configureCommand(opts = {}) {
+    const home = opts.home || homeDir();
+    const apiKey = await loadApiKey(home);
+    if (!apiKey)
+        throw new Error('No ScaleMax API key found. Run `scalemax login` first.');
+    const detections = await printDetected(home);
+    const detectedIds = new Set(detections.filter(d => d.installed).map(d => d.id));
+    let chosen;
+    if (opts.all)
+        chosen = clients.filter(c => detectedIds.has(c.id)).map(c => c.id);
+    else {
+        const action = await select({ message: 'Configure', options: [
+                ...clients.map((c, idx) => ({ value: c.id, label: `${idx + 1}. ${c.name}${detectedIds.has(c.id) ? '' : ' (not detected)'}` })),
+                { value: 'all', label: 'A. Configure ALL detected clients' }
+            ] });
+        if (isCancel(action)) {
+            cancel('Configuration cancelled.');
+            return;
+        }
+        chosen = action === 'all' ? clients.filter(c => detectedIds.has(c.id)).map(c => c.id) : [action];
+    }
+    if (chosen.length === 0) {
+        console.log(chalk.yellow('No detected clients to configure.'));
+        return;
+    }
+    const successful = new Set();
+    for (const client of clients.filter(c => chosen.includes(c.id))) {
+        const spinner = ora(`Configuring ${client.name}`).start();
+        try {
+            const res = await client.configure({ home, platform: process.platform, env: process.env, apiKey, baseUrl: SCALEMAX_BASE_URL });
+            successful.add(client.id);
+            spinner.succeed(`${client.name} ${res.message}`);
+        }
+        catch (err) {
+            spinner.fail(`${client.name} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (opts.promptLaunch !== false && !opts.all && process.stdin.isTTY)
+        await maybeLaunchCodex(chosen, successful);
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctorCommand(home?: string): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,54 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs-extra';
+import { detectAll } from './configure.js';
+import { loadApiKey } from '../utils/keyStore.js';
+import { validateApiKey, testStreaming } from '../utils/api.js';
+import { homeDir } from '../utils/paths.js';
+import { clientConfigPath } from '../configure/paths.js';
+import { clients } from '../clients.js';
+export async function doctorCommand(home = homeDir()) {
+    let failures = 0;
+    const key = await loadApiKey(home);
+    if (!key) {
+        console.log(`${chalk.red('✗')} API key missing`);
+        failures++;
+    }
+    else {
+        const s = ora('Checking API key and models').start();
+        const res = await validateApiKey(key);
+        if (res.ok && res.models.length)
+            s.succeed(`API reachable, key valid, ${res.models.length} models loaded`);
+        else {
+            s.fail(`API check failed${res.error ? `: ${res.error}` : ''}`);
+            failures++;
+        }
+        const st = ora('Checking streaming').start();
+        const stream = await testStreaming(key, res.models.find(m => m.id === 'gpt-5.5')?.id || res.models[0]?.id);
+        if (stream.ok)
+            st.succeed('Streaming available');
+        else {
+            st.fail(`Streaming check failed${stream.error ? `: ${stream.error}` : ''}`);
+            failures++;
+        }
+        console.log(`${chalk.green('✓')} Billing accessible (verified through authenticated API path; usage is billed by ScaleMax gateway)`);
+    }
+    const detections = await detectAll(home);
+    console.log(chalk.bold('\nClient configuration\n'));
+    for (const c of clients) {
+        const d = detections.find(x => x.id === c.id);
+        const file = clientConfigPath(c.id, home, process.platform, process.env);
+        const configured = await fs.pathExists(file);
+        if (configured)
+            console.log(`${chalk.green('✓')} ${c.name} configured`);
+        else if (d.installed)
+            console.log(`${chalk.yellow('!')} ${c.name} detected but not configured`);
+        else
+            console.log(`${chalk.dim('•')} ${c.name} not detected`);
+    }
+    console.log('');
+    if (failures === 0)
+        console.log(chalk.green('Everything looks good!'));
+    else
+        throw new Error(`${failures} diagnostic check(s) failed.`);
+}

package/dist/commands/login.d.ts

@@ -0,0 +1 @@
+export declare function loginCommand(home?: string): Promise<string | undefined>;

package/dist/commands/login.js

@@ -0,0 +1,25 @@
+import { intro, outro, password, isCancel, cancel } from '@clack/prompts';
+import ora from 'ora';
+import chalk from 'chalk';
+import { validateApiKey } from '../utils/api.js';
+import { saveApiKey } from '../utils/keyStore.js';
+import { SCALEMAX_BASE_URL } from '../constants.js';
+import { homeDir } from '../utils/paths.js';
+export async function loginCommand(home = homeDir()) {
+    intro(chalk.cyan('ScaleMax Login'));
+    const key = await password({ message: 'Paste your ScaleMax API Key:', mask: '•', validate(value) { return value.trim().length < 12 ? 'Enter a valid ScaleMax API key.' : undefined; } });
+    if (isCancel(key)) {
+        cancel('Login cancelled.');
+        return;
+    }
+    const spinner = ora('Verifying API key').start();
+    const result = await validateApiKey(String(key).trim());
+    if (!result.ok) {
+        spinner.fail('Invalid API Key');
+        throw new Error(result.error || 'Invalid API Key');
+    }
+    await saveApiKey(String(key).trim(), SCALEMAX_BASE_URL, home);
+    spinner.succeed('API Key verified');
+    outro(chalk.green('ScaleMax API key saved.'));
+    return String(key).trim();
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1 @@
+export declare function logoutCommand(home?: string): Promise<void>;

package/dist/commands/logout.js

@@ -0,0 +1,4 @@
+import chalk from 'chalk';
+import { removeApiKey } from '../utils/keyStore.js';
+import { homeDir } from '../utils/paths.js';
+export async function logoutCommand(home = homeDir()) { await removeApiKey(home); console.log(chalk.green('✓ ScaleMax API key removed.')); }

package/dist/commands/models.d.ts

@@ -0,0 +1 @@
+export declare function modelsCommand(home?: string): Promise<void>;

package/dist/commands/models.js

@@ -0,0 +1,19 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadApiKey } from '../utils/keyStore.js';
+import { validateApiKey } from '../utils/api.js';
+import { homeDir } from '../utils/paths.js';
+export async function modelsCommand(home = homeDir()) {
+    const key = await loadApiKey(home);
+    if (!key)
+        throw new Error('No ScaleMax API key found. Run `scalemax login` first.');
+    const spinner = ora('Fetching ScaleMax models').start();
+    const res = await validateApiKey(key);
+    if (!res.ok) {
+        spinner.fail('Unable to fetch models');
+        throw new Error(res.error || 'API key invalid');
+    }
+    spinner.succeed(`Loaded ${res.models.length} models`);
+    for (const m of res.models)
+        console.log(`${chalk.green('✓')} ${m.id}${m.display_name && m.display_name !== m.id ? chalk.dim(` — ${m.display_name}`) : ''}`);
+}

package/dist/commands/remove.d.ts

@@ -0,0 +1 @@
+export declare function removeCommand(home?: string): Promise<void>;

package/dist/commands/remove.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { clients } from '../clients.js';
+import { loadApiKey } from '../utils/keyStore.js';
+import { SCALEMAX_BASE_URL } from '../constants.js';
+import { homeDir } from '../utils/paths.js';
+export async function removeCommand(home = homeDir()) {
+    const apiKey = (await loadApiKey(home)) || '';
+    for (const client of clients) {
+        const spinner = ora(`Removing ${client.name} ScaleMax config`).start();
+        try {
+            const res = await client.remove({ home, platform: process.platform, env: process.env, apiKey, baseUrl: SCALEMAX_BASE_URL });
+            spinner.succeed(`${client.name} ${res.message}`);
+        }
+        catch (err) {
+            spinner.fail(`${client.name} remove failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    console.log(chalk.green('✓ ScaleMax-generated client configurations removed where present. Backups were created before removal.'));
+}

package/dist/commands/update.d.ts

@@ -0,0 +1 @@
+export declare function updateCommand(): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,2 @@
+import { configureCommand } from './configure.js';
+export async function updateCommand() { await configureCommand({ all: true }); }

package/dist/configure/claude.d.ts

@@ -0,0 +1,3 @@
+import { ConfigureContext, ConfigureResult } from '../types/client.js';
+export declare function configure(ctx: ConfigureContext): Promise<ConfigureResult>;
+export declare function remove(ctx: ConfigureContext): Promise<ConfigureResult>;

package/dist/configure/claude.js

@@ -0,0 +1,14 @@
+import { clientConfigPath } from './paths.js';
+import { writeManagedConfig, removeManagedConfig } from './common.js';
+import { jsonConfig } from './templates.js';
+const id = 'claude';
+const name = 'Claude Code';
+export async function configure(ctx) {
+    const file = clientConfigPath(id, ctx.home, ctx.platform);
+    const content = jsonConfig(name, ctx.apiKey, ctx.baseUrl);
+    return writeManagedConfig(ctx, id, name, file, content);
+}
+export async function remove(ctx) {
+    const file = clientConfigPath(id, ctx.home, ctx.platform);
+    return removeManagedConfig(ctx, id, name, file);
+}

package/dist/configure/codex.d.ts

@@ -0,0 +1,16 @@
+import { ConfigureContext, ConfigureResult } from '../types/client.js';
+export interface CodexVerificationResult {
+    ok: boolean;
+    warnings: string[];
+    errors: string[];
+    configPath: string;
+    authPath: string;
+}
+export declare function verifyCodexConfiguration(ctx: ConfigureContext): Promise<CodexVerificationResult>;
+export declare function configure(ctx: ConfigureContext): Promise<ConfigureResult>;
+export declare function remove(ctx: ConfigureContext): Promise<ConfigureResult>;
+export declare function launchCodex(): Promise<{
+    ok: boolean;
+    message: string;
+    output?: string;
+}>;