scalemax 0.1.11 → 0.1.13

package/README.md

@@ -12,7 +12,7 @@ It detects supported AI coding clients, safely backs up existing config files, a
 
 ## Requirements
 
-- Node.js `18.17` or newer
+- Node.js `18.19` or newer
 - macOS, Linux, or Windows
 - A ScaleMax API key
 - Network access to `https://api.scalemax.pro`
@@ -112,6 +112,10 @@ SCALEMAX_API_KEY=sm_live_xxx scalemax models
 
 For clients without a stable official config file, the installer writes a ScaleMax setup guide under `~/.scalemax/` instead of modifying private app storage.
 
+### Claude Code
+
+ScaleMax configures Claude Code with the Anthropic-compatible origin `https://api.scalemax.pro`, preserves unrelated settings and environment variables, and selects a live `claude-*` model from the authenticated model catalog (preferring `claude-opus-4-8`). It verifies `/v1/messages` after setup and rolls back managed changes if verification fails. Claude Code picker aliases such as `claude-opus-4-8[1m]` are normalized by the ScaleMax gateway.
+
 ### Cursor BYOK routing on macOS
 
 Cursor can send named models through its own plan-gated router unless its local BYOK runtime is active. When you select Cursor, `npx scalemax`:

package/dist/clients.js

@@ -20,7 +20,7 @@ export const clients = [
     { id: 'codex', name: 'Codex', detect: codexDetect.detect, install: codexConfig.install, configure: codexConfig.configure, verify: codexConfig.verify, launch: codexConfig.launch, remove: codexConfig.remove },
     { id: 'cursor', name: 'Cursor', detect: cursorDetect.detect, configure: cursorConfig.configure, verify: cursorConfig.verify, remove: cursorConfig.remove },
     { id: 'trae-solo', name: 'TRAE SOLO', detect: traeSoloDetect.detect, configure: traeSoloConfig.configure, remove: traeSoloConfig.remove },
-    { id: 'claude', name: 'Claude Code', detect: claudeDetect.detect, configure: claudeConfig.configure, remove: claudeConfig.remove },
+    { id: 'claude', name: 'Claude Code', detect: claudeDetect.detect, configure: claudeConfig.configure, verify: claudeConfig.verify, 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 },

package/dist/commands/configure.js

@@ -85,6 +85,7 @@ export async function configureCommand(opts = {}) {
         return;
     }
     const successful = new Set();
+    const failures = [];
     for (const client of availableClients.filter(c => chosen.includes(c.id))) {
         let allowAppModification = false;
         if (client.id === 'cursor') {
@@ -111,7 +112,9 @@ export async function configureCommand(opts = {}) {
                 spinner.succeed(`${client.name} ${res.message}`);
             }
             catch (err) {
-                spinner.fail(`${client.name} install failed: ${err instanceof Error ? err.message : String(err)}`);
+                const message = err instanceof Error ? err.message : String(err);
+                spinner.fail(`${client.name} install failed: ${message}`);
+                failures.push(`${client.name}: ${message}`);
                 continue;
             }
         }
@@ -122,15 +125,31 @@ export async function configureCommand(opts = {}) {
             spinner.succeed(`${client.name} ${res.message}`);
             if (client.verify) {
                 const verify = ora(`Verifying ${client.name}`).start();
-                const v = await client.verify(ctx);
-                verify.succeed(`${client.name} ${v.message}`);
+                try {
+                    const v = await client.verify(ctx);
+                    verify.succeed(`${client.name} ${v.message}`);
+                }
+                catch (error) {
+                    verify.fail(`${client.name} verification failed`);
+                    try {
+                        await client.remove(ctx);
+                    }
+                    catch (rollback) {
+                        throw new Error(`${error instanceof Error ? error.message : String(error)}; rollback also failed: ${rollback instanceof Error ? rollback.message : String(rollback)}`);
+                    }
+                    throw error;
+                }
             }
             successful.add(client.id);
         }
         catch (err) {
-            spinner.fail(`${client.name} failed: ${err instanceof Error ? err.message : String(err)}`);
+            const message = err instanceof Error ? err.message : String(err);
+            spinner.fail(`${client.name} failed: ${message}`);
+            failures.push(`${client.name}: ${message}`);
         }
     }
     if (opts.promptLaunch !== false && !opts.all && process.stdin.isTTY)
         await maybeLaunchCodex(chosen, successful);
+    if (failures.length)
+        throw new Error(`${failures.length} client configuration(s) failed:\n${failures.map(f => `- ${f}`).join('\n')}`);
 }

package/dist/commands/doctor.js

@@ -1,15 +1,15 @@
 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';
+import { SCALEMAX_BASE_URL } from '../constants.js';
 export async function doctorCommand(home = homeDir()) {
     let failures = 0;
     const key = await loadApiKey(home);
+    let models = [];
     if (!key) {
         console.log(`${chalk.red('✗')} API key missing`);
         failures++;
@@ -17,34 +17,48 @@ export async function doctorCommand(home = homeDir()) {
     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++;
+        models = res.models;
+        if (res.ok && models.length) {
+            s.succeed(`API reachable, key valid, ${models.length} models loaded`);
+            console.log(`${chalk.green('✓')} Usage and key metadata accessible through the authenticated API`);
+            const st = ora('Checking streaming (small billable request)').start();
+            const stream = await testStreaming(key, models.find(m => m.id === 'fable-5')?.id || models[0]?.id);
+            if (stream.ok)
+                st.succeed('Streaming available');
+            else {
+                st.fail(`Streaming check failed${stream.error ? `: ${stream.error}` : ''}`);
+                failures++;
+            }
         }
-        const st = ora('Checking streaming').start();
-        const stream = await testStreaming(key, res.models.find(m => m.id === 'fable-5')?.id || res.models[0]?.id);
-        if (stream.ok)
-            st.succeed('Streaming available');
         else {
-            st.fail(`Streaming check failed${stream.error ? `: ${stream.error}` : ''}`);
+            s.fail(`API check failed${res.error ? `: ${res.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`);
+    for (const client of clients) {
+        const d = detections.find(x => x.id === client.id);
+        if (!d.installed) {
+            console.log(`${chalk.dim('•')} ${client.name} not detected`);
+            continue;
+        }
+        if (!d.configured) {
+            console.log(`${chalk.yellow('!')} ${client.name} detected but not configured`);
+            continue;
+        }
+        if (client.verify && key && models.length) {
+            try {
+                const v = await client.verify({ home, platform: process.platform, env: process.env, apiKey: key, baseUrl: SCALEMAX_BASE_URL, models });
+                console.log(`${chalk.green('✓')} ${client.name} ${v.message}`);
+            }
+            catch (error) {
+                console.log(`${chalk.red('✗')} ${client.name} verification failed: ${error instanceof Error ? error.message : String(error)}`);
+                failures++;
+            }
+        }
         else
-            console.log(`${chalk.dim('•')} ${c.name} not detected`);
+            console.log(`${chalk.green('✓')} ${client.name} configured (${d.reason || 'detector confirmed'})`);
     }
     console.log('');
     if (failures === 0)

package/dist/commands/remove.js

@@ -6,6 +6,7 @@ import { SCALEMAX_BASE_URL } from '../constants.js';
 import { homeDir } from '../utils/paths.js';
 export async function removeCommand(home = homeDir()) {
     const apiKey = (await loadApiKey(home)) || '';
+    const failures = [];
     for (const client of clients) {
         const spinner = ora(`Removing ${client.name} ScaleMax config`).start();
         try {
@@ -13,8 +14,12 @@ export async function removeCommand(home = homeDir()) {
             spinner.succeed(`${client.name} ${res.message}`);
         }
         catch (err) {
-            spinner.fail(`${client.name} remove failed: ${err instanceof Error ? err.message : String(err)}`);
+            const message = err instanceof Error ? err.message : String(err);
+            spinner.fail(`${client.name} remove failed: ${message}`);
+            failures.push(`${client.name}: ${message}`);
         }
     }
-    console.log(chalk.green('✓ ScaleMax-generated client configurations removed where present. Backups were created before removal.'));
+    if (failures.length)
+        throw new Error(`${failures.length} client removal(s) failed:\n${failures.map(f => `- ${f}`).join('\n')}`);
+    console.log(chalk.green('✓ ScaleMax-managed client configurations removed or restored; unmanaged files were left unchanged.'));
 }

package/dist/configure/api-code.js

@@ -5,7 +5,7 @@ const id = 'api-code';
 const name = 'API Code';
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    const content = jsonConfig(name, ctx.apiKey, ctx.baseUrl, { "environment": { "SCALEMAX_API_KEY": "your ScaleMax API key", "SCALEMAX_BASE_URL": "https://api.scalemax.pro/v1" }, "node": "import OpenAI from 'openai';\nconst client = new OpenAI({ apiKey: process.env.SCALEMAX_API_KEY, baseURL: 'https://api.scalemax.pro/v1' });", "python": "from openai import OpenAI\nclient = OpenAI(api_key='...', base_url='https://api.scalemax.pro/v1')" });
+    const content = jsonConfig(name, '$SCALEMAX_API_KEY', ctx.baseUrl, { "environment": { "SCALEMAX_API_KEY": "your ScaleMax API key", "SCALEMAX_BASE_URL": "https://api.scalemax.pro/v1" }, "node": "import OpenAI from 'openai';\nconst client = new OpenAI({ apiKey: process.env.SCALEMAX_API_KEY, baseURL: 'https://api.scalemax.pro/v1' });", "python": "from openai import OpenAI\nclient = OpenAI(api_key='...', base_url='https://api.scalemax.pro/v1')" });
     const result = await writeManagedConfig(ctx, id, name, file, content);
     return { ...result, message: 'API code examples written' };
 }

package/dist/configure/cherry-studio.js

@@ -5,7 +5,7 @@ const id = 'cherry-studio';
 const name = 'Cherry Studio';
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    const content = jsonConfig(name, ctx.apiKey, ctx.baseUrl, { "officialSetup": ["Settings > Model Service / Model Providers", "Provider type: OpenAI or OpenAI Compatible", "API host/base URL: https://api.scalemax.pro/v1", "Add ScaleMax model IDs or fetch from /v1/models"], "recommendedModel": "fable-5" });
+    const content = jsonConfig(name, '$SCALEMAX_API_KEY', ctx.baseUrl, { "officialSetup": ["Settings > Model Service / Model Providers", "Provider type: OpenAI or OpenAI Compatible", "API host/base URL: https://api.scalemax.pro/v1", "Add ScaleMax model IDs or fetch from /v1/models"], "recommendedModel": "fable-5" });
     const result = await writeManagedConfig(ctx, id, name, file, content);
     return { ...result, message: 'setup guide written; enter these values in Cherry Studio model provider settings' };
 }

package/dist/configure/claude.d.ts

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

package/dist/configure/claude.js

@@ -1,24 +1,36 @@
 import { clientConfigPath } from './paths.js';
-import { writeManagedConfig, removeManagedConfig } from './common.js';
-const id = 'claude';
-const name = 'Claude Code';
+import { writeMergedJsonConfig, removeManagedConfig } from './common.js';
+import { GENERATED_HEADER } from '../constants.js';
+import fs from 'fs-extra';
+const id = 'claude', name = 'Claude Code';
+function claudeModel(ctx) { const ids = (ctx.models || []).map(m => m.id).filter(x => x.startsWith('claude-')); for (const preferred of ['claude-opus-4-8', 'claude-sonnet-5', 'claude-opus-4-7', 'claude-opus-4-6', 'claude-haiku-4-5-20251001'])
+    if (ids.includes(preferred))
+        return preferred; if (ids.length)
+    return ids[0]; throw new Error('No Claude models are available for this API key; Claude Code was not changed.'); }
+function anthropicOrigin(baseUrl) { const url = new URL(baseUrl); url.pathname = url.pathname.replace(/\/v1\/?$/, '').replace(/\/$/, ''); url.search = ''; url.hash = ''; return url.toString().replace(/\/$/, ''); }
 export async function configure(ctx) {
-    const file = clientConfigPath(id, ctx.home, ctx.platform);
-    const content = JSON.stringify({
-        env: {
-            ANTHROPIC_AUTH_TOKEN: ctx.apiKey,
-            ANTHROPIC_BASE_URL: ctx.baseUrl,
-            ANTHROPIC_MODEL: 'fable-5'
-        },
-        scalemax: {
-            managedBy: 'ScaleMax CLI',
-            note: 'Claude Code uses Anthropic Messages, not OpenAI Chat Completions. This file stores ScaleMax values, but Claude Code requires a ScaleMax Anthropic-compatible endpoint before it can work reliably.'
-        }
-    }, null, 2) + '\n';
-    const result = await writeManagedConfig(ctx, id, name, file, content);
-    return { ...result, message: 'settings written; Claude Code requires Anthropic-compatible ScaleMax endpoint' };
+    const file = clientConfigPath(id, ctx.home, ctx.platform), model = claudeModel(ctx);
+    const result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
+        const env = existing.env && typeof existing.env === 'object' && !Array.isArray(existing.env) ? existing.env : {};
+        return JSON.stringify({ ...existing, env: { ...env, ANTHROPIC_AUTH_TOKEN: ctx.apiKey, ANTHROPIC_BASE_URL: anthropicOrigin(ctx.baseUrl), ANTHROPIC_MODEL: model }, 'scalemax.managedBy': GENERATED_HEADER, scalemax: { managedBy: 'ScaleMax CLI', anthropicModel: model } }, null, 2) + '\n';
+    });
+    return { ...result, message: `configured Anthropic-compatible routing with ${model}` };
 }
-export async function remove(ctx) {
-    const file = clientConfigPath(id, ctx.home, ctx.platform);
-    return removeManagedConfig(ctx, id, name, file);
+export async function verify(ctx) {
+    const file = clientConfigPath(id, ctx.home, ctx.platform), settings = await fs.readJson(file);
+    const env = settings?.env || {}, model = String(env.ANTHROPIC_MODEL || '');
+    if (!model.startsWith('claude-') || env.ANTHROPIC_BASE_URL !== anthropicOrigin(ctx.baseUrl) || env.ANTHROPIC_AUTH_TOKEN !== ctx.apiKey)
+        throw new Error('Claude Code settings do not match the authenticated ScaleMax configuration.');
+    const response = await fetch(`${anthropicOrigin(ctx.baseUrl)}/v1/messages`, { method: 'POST', headers: { Authorization: `Bearer ${ctx.apiKey}`, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' }, body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: 'user', content: 'Reply OK' }] }), signal: AbortSignal.timeout(15000) });
+    if (!response.ok) {
+        let message = `HTTP ${response.status}`;
+        try {
+            const body = await response.json();
+            message = body?.error?.message || message;
+        }
+        catch { }
+        throw new Error(`Claude Messages verification failed: ${message}`);
+    }
+    return { id, name, changed: false, path: file, message: `verified Anthropic Messages with ${model}` };
 }
+export async function remove(ctx) { return removeManagedConfig(ctx, id, name, clientConfigPath(id, ctx.home, ctx.platform)); }

package/dist/configure/codex.d.ts

@@ -6,7 +6,7 @@ export interface CodexVerificationResult {
     configPath: string;
     authPath: string;
 }
-export declare function mergeCodexConfig(existing: string, baseUrl: string): string;
+export declare function mergeCodexConfig(existing: string, baseUrl: string, model?: string): string;
 export declare function verifyCodexConfiguration(ctx: ConfigureContext): Promise<CodexVerificationResult>;
 export declare function install(ctx: InstallContext): Promise<ConfigureResult>;
 export declare function verify(ctx: ConfigureContext): Promise<ConfigureResult>;

package/dist/configure/codex.js

@@ -8,12 +8,19 @@ import { commandExists } from '../utils/exec.js';
 const id = 'codex';
 const name = 'Codex';
 const provider = 'scalemax';
-const model = 'gpt-5.5';
+const fallbackModel = 'gpt-5.5';
 const reasoningEffort = 'medium';
-function scalemaxCodexBlock(baseUrl) {
-    return `# ${GENERATED_HEADER}\nmodel = "${model}"\nmodel_provider = "${provider}"\nmodel_reasoning_effort = "${reasoningEffort}"\n# Recommended ScaleMax Codex models: gpt-5.5, gpt-5.6-terra, gpt-5.6-sol, gpt-5.6-luna, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, fable-5, fable-5-ultra.\n# Provider-internal gpt-5.3-codex-spark is routed behind the public gpt-5.3-codex Codex slug.\n\n[model_providers.${provider}]\nname = "ScaleMax"\nbase_url = "${baseUrl}"\nwire_api = "responses"\nrequires_openai_auth = true\n`;
+function selectedModel(ctx) {
+    const ids = new Set((ctx.models || []).map(m => m.id));
+    for (const candidate of ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5', 'gpt-5.4', 'gpt-5.3-codex'])
+        if (ids.has(candidate))
+            return candidate;
+    return ctx.models?.[0]?.id || fallbackModel;
+}
+function scalemaxCodexBlock(baseUrl, model = fallbackModel) {
+    return `# ${GENERATED_HEADER}\nmodel = "${model}"\nmodel_provider = "${provider}"\nmodel_reasoning_effort = "${reasoningEffort}"\n# ScaleMax models are loaded from the authenticated live model catalog.\n\n[model_providers.${provider}]\nname = "ScaleMax"\nbase_url = "${baseUrl}"\nwire_api = "responses"\nrequires_openai_auth = true\n`;
 }
-export function mergeCodexConfig(existing, baseUrl) {
+export function mergeCodexConfig(existing, baseUrl, model = fallbackModel) {
     const preserved = [];
     let section = '';
     let skipScaleMaxProvider = false;
@@ -28,17 +35,17 @@ export function mergeCodexConfig(existing, baseUrl) {
         }
         if (skipScaleMaxProvider)
             continue;
-        if (!section && /^(model|model_provider|model_reasoning_effort|disable_response_storage)\s*=/.test(line))
+        if (!section && /^(model|model_provider|model_reasoning_effort)\s*=/.test(line))
             continue;
         if (line === `# ${GENERATED_HEADER}`)
             continue;
         preserved.push(raw);
     }
     const tail = preserved.join('\n').trim();
-    return `${scalemaxCodexBlock(baseUrl)}${tail ? `\n${tail}\n` : ''}`;
+    return `${scalemaxCodexBlock(baseUrl, model)}${tail ? `\n${tail}\n` : ''}`;
 }
-function codexAuth(apiKey) {
-    return JSON.stringify({ auth_mode: 'apikey', OPENAI_API_KEY: apiKey }, null, 2) + '\n';
+function codexAuth(apiKey, existing = {}) {
+    return JSON.stringify({ ...existing, auth_mode: 'apikey', OPENAI_API_KEY: apiKey }, null, 2) + '\n';
 }
 function legacyCodexConfigPath(home) {
     return path.join(home, '.codex', 'config.json');
@@ -81,6 +88,19 @@ async function latestRestorableBackup(file, home) {
     return undefined;
 }
 async function restoreOrRemove(file, home) {
+    if (!(await fs.pathExists(file)))
+        return 'no ScaleMax configuration found';
+    const current = await fs.readFile(file, 'utf8').catch(() => '');
+    let managed = current.includes(GENERATED_HEADER);
+    if (!managed && file.endsWith('auth.json')) {
+        try {
+            const parsed = JSON.parse(current);
+            managed = parsed?.auth_mode === 'apikey' && typeof parsed?.OPENAI_API_KEY === 'string' && /^sm_(live|dev|trial)_/.test(parsed.OPENAI_API_KEY);
+        }
+        catch { }
+    }
+    if (!managed)
+        return 'left unmanaged configuration unchanged';
     const restore = await latestRestorableBackup(file, home);
     if (restore) {
         await fs.ensureDir(path.dirname(file));
@@ -88,17 +108,15 @@ async function restoreOrRemove(file, home) {
         await fs.chmod(file, 0o600).catch(() => undefined);
         return `restored backup ${restore}`;
     }
-    if (await fs.pathExists(file)) {
-        await fs.remove(file);
-        return 'removed ScaleMax configuration';
-    }
-    return 'no ScaleMax configuration found';
+    await fs.remove(file);
+    return 'removed ScaleMax configuration';
 }
 export async function verifyCodexConfiguration(ctx) {
     const configPath = codexConfigPath(ctx.home);
     const authPath = codexAuthPath(ctx.home);
     const errors = [];
     const warnings = [];
+    const model = selectedModel(ctx);
     if (!(await fs.pathExists(configPath)))
         errors.push(`${configPath} does not exist`);
     if (!(await fs.pathExists(authPath)))
@@ -177,7 +195,8 @@ export async function verifyCodexConfiguration(ctx) {
         const res = await fetch(`${ctx.baseUrl}/responses`, {
             method: 'POST',
             headers: { Authorization: `Bearer ${ctx.apiKey}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify({ model, input: 'Say OK', stream: false })
+            body: JSON.stringify({ model, input: 'Say OK', stream: false }),
+            signal: AbortSignal.timeout(15000)
         });
         if (res.status === 404)
             warnings.push('ScaleMax /v1/responses is not available yet. Current Codex requires the Responses API, so it may launch but cannot complete requests until the gateway supports /v1/responses.');
@@ -210,20 +229,38 @@ export async function configure(ctx) {
     const authPath = codexAuthPath(ctx.home);
     const legacyConfig = legacyCodexConfigPath(ctx.home);
     const backups = [];
+    const originals = new Map();
     await fs.ensureDir(path.dirname(configPath));
     for (const file of [configPath, authPath, legacyConfig]) {
+        const exists = await fs.pathExists(file);
+        originals.set(file, { exists, content: exists ? await fs.readFile(file, 'utf8') : '' });
         const backup = await backupFile(file, ctx.home);
         if (backup)
             backups.push(backup);
     }
-    const existingConfig = await fs.readFile(configPath, 'utf8').catch(() => '');
-    await atomicWrite(configPath, mergeCodexConfig(existingConfig, ctx.baseUrl), 0o600);
-    await atomicWrite(authPath, codexAuth(ctx.apiKey), 0o600);
-    if (legacyConfig.endsWith('config.json') && await fs.pathExists(legacyConfig))
-        await fs.remove(legacyConfig);
-    const verification = await verifyCodexConfiguration(ctx);
-    if (!verification.ok)
-        throw new Error(`Codex configuration verification failed:\n${verification.errors.map(e => `- ${e}`).join('\n')}`);
+    const existingConfig = originals.get(configPath)?.content || '';
+    let verification;
+    try {
+        await atomicWrite(configPath, mergeCodexConfig(existingConfig, ctx.baseUrl, selectedModel(ctx)), 0o600);
+        let existingAuth = {};
+        try {
+            existingAuth = JSON.parse(originals.get(authPath)?.content || '{}');
+        }
+        catch { }
+        await atomicWrite(authPath, codexAuth(ctx.apiKey, existingAuth), 0o600);
+        verification = await verifyCodexConfiguration(ctx);
+        if (!verification.ok)
+            throw new Error(`Codex configuration verification failed:\n${verification.errors.map(e => `- ${e}`).join('\n')}`);
+    }
+    catch (error) {
+        for (const [file, original] of originals) {
+            if (original.exists)
+                await atomicWrite(file, original.content, 0o600);
+            else
+                await fs.remove(file).catch(() => undefined);
+        }
+        throw error;
+    }
     const warningText = verification.warnings.length ? ` Warnings: ${verification.warnings.join(' ')}` : '';
     const backupText = backups.length ? ` (backups: ${backups.join(', ')})` : '';
     return { id, name, changed: true, path: configPath, message: `configured and verified${backupText}.${warningText}` };

package/dist/configure/common.d.ts

@@ -1,4 +1,5 @@
 import { ConfigureContext, ConfigureResult, ClientId } from '../types/client.js';
+export declare function isScaleMaxManagedText(text: string): boolean;
 export declare function writeManagedConfig(ctx: ConfigureContext, id: ClientId, name: string, file: string, content: string): Promise<ConfigureResult>;
 export declare function writeMergedJsonConfig(ctx: ConfigureContext, id: ClientId, name: string, file: string, build: (existing: Record<string, unknown>) => string): Promise<ConfigureResult>;
 export declare function removeManagedConfig(ctx: ConfigureContext, id: ClientId, name: string, file: string): Promise<ConfigureResult>;

package/dist/configure/common.js

@@ -2,8 +2,16 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import { atomicWrite, backupFile, listBackups, readJson } from '../utils/fs.js';
 import { GENERATED_HEADER } from '../constants.js';
+export function isScaleMaxManagedText(text) {
+    return text.includes(GENERATED_HEADER) || text.includes('"scalemax.managedBy"') || text.includes('"managedBy": "ScaleMax CLI generated file"');
+}
 export async function writeManagedConfig(ctx, id, name, file, content) {
     await fs.ensureDir(path.dirname(file));
+    if (await fs.pathExists(file)) {
+        const current = await fs.readFile(file, 'utf8');
+        if (!isScaleMaxManagedText(current))
+            throw new Error(`Refusing to overwrite unmanaged configuration: ${file}`);
+    }
     const backup = await backupFile(file, ctx.home);
     await atomicWrite(file, content, 0o600);
     return { id, name, changed: true, path: file, message: backup ? `configured (backup: ${backup})` : 'configured' };
@@ -24,6 +32,11 @@ async function latestRestorableBackup(file, home) {
     return undefined;
 }
 export async function removeManagedConfig(ctx, id, name, file) {
+    if (!(await fs.pathExists(file)))
+        return { id, name, changed: false, path: file, message: 'no ScaleMax configuration found' };
+    const current = await fs.readFile(file, 'utf8').catch(() => '');
+    if (!isScaleMaxManagedText(current))
+        return { id, name, changed: false, path: file, message: 'left unmanaged configuration unchanged' };
     const restore = await latestRestorableBackup(file, ctx.home);
     if (restore) {
         await fs.ensureDir(path.dirname(file));
@@ -31,9 +44,6 @@ export async function removeManagedConfig(ctx, id, name, file) {
         await fs.chmod(file, 0o600).catch(() => undefined);
         return { id, name, changed: true, path: file, message: `restored backup ${restore}` };
     }
-    if (await fs.pathExists(file)) {
-        await fs.remove(file);
-        return { id, name, changed: true, path: file, message: 'removed ScaleMax configuration' };
-    }
-    return { id, name, changed: false, path: file, message: 'no ScaleMax configuration found' };
+    await fs.remove(file);
+    return { id, name, changed: true, path: file, message: 'removed ScaleMax configuration' };
 }

package/dist/configure/cursor-bundle.d.ts

@@ -21,6 +21,7 @@ export interface CursorBundlePatchResult {
     backupRoot?: string;
 }
 export declare function cursorAppPath(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string;
+export declare function resolveCursorAppPath(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, home: string, preferred?: string): Promise<string>;
 export declare function cursorBundlePaths(appPath: string): string[];
 export declare function sha256Buffer(value: Buffer | string): string;
 export declare function inspectCursorBundle(file: string): Promise<CursorBundleInspection>;

package/dist/configure/cursor-bundle.js

@@ -18,6 +18,46 @@ export function cursorAppPath(platform, env) {
         return '/Applications/Cursor.app';
     throw new Error(`Automatic Cursor BYOK setup is currently verified on macOS only (${platform} is not modified).`);
 }
+async function appLooksLikeCursor(appPath) {
+    if (!appPath.endsWith('.app'))
+        return false;
+    return (await Promise.all(CURSOR_BUNDLE_RELATIVE_PATHS.map(p => fs.pathExists(path.join(appPath, p))))).every(Boolean);
+}
+async function cursorAppCandidates(home, env) {
+    const roots = env.SCALEMAX_CURSOR_SEARCH_ROOTS ? env.SCALEMAX_CURSOR_SEARCH_ROOTS.split(path.delimiter).filter(Boolean) : ['/Applications', path.join(home, 'Applications')];
+    const candidates = roots.map(root => path.join(root, 'Cursor.app'));
+    for (const root of roots) {
+        let entries = [];
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (/cursor/i.test(entry) && entry.endsWith('.app'))
+                candidates.push(path.join(root, entry));
+        }
+    }
+    return Array.from(new Set(candidates));
+}
+export async function resolveCursorAppPath(platform, env, home, preferred) {
+    if (platform !== 'darwin')
+        throw new Error(`Automatic Cursor BYOK setup is currently verified on macOS only (${platform} is not modified).`);
+    if (env.SCALEMAX_CURSOR_APP_PATH)
+        return path.resolve(env.SCALEMAX_CURSOR_APP_PATH);
+    if (preferred && await appLooksLikeCursor(preferred))
+        return preferred;
+    const valid = [];
+    for (const candidate of await cursorAppCandidates(home, env))
+        if (await appLooksLikeCursor(candidate))
+            valid.push(candidate);
+    if (valid.length === 1)
+        return valid[0];
+    if (valid.length > 1)
+        throw new Error(`Multiple Cursor apps were found. Set SCALEMAX_CURSOR_APP_PATH to one of:\n${valid.map(v => `- ${v}`).join('\n')}`);
+    return '/Applications/Cursor.app';
+}
 export function cursorBundlePaths(appPath) { return CURSOR_BUNDLE_RELATIVE_PATHS.map(p => path.join(appPath, p)); }
 export function sha256Buffer(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
 function count(text, needle) { let n = 0, from = 0; while ((from = text.indexOf(needle, from)) !== -1) {
@@ -57,23 +97,40 @@ export async function patchCursorBundles(appPath, home, platform, env) {
         for (let i = 0; i < before.bundles.length; i++) {
             const b = before.bundles[i], relativePath = CURSOR_BUNDLE_RELATIVE_PATHS[i], backupPath = path.join(backupRoot, relativePath);
             await fs.ensureDir(path.dirname(backupPath), { mode: 0o700 });
+            const original = await fs.readFile(b.path, 'utf8');
+            if (sha256Buffer(original) !== b.sha256)
+                throw new Error(`Cursor changed during backup: ${b.path}`);
             await fs.copy(b.path, backupPath, { overwrite: false, errorOnExist: true, preserveTimestamps: true });
-            const mode = (await fs.stat(b.path)).mode & 0o777;
-            const original = await fs.readFile(b.path, 'utf8'), patched = original.replace(ORIGINAL, PATCHED);
+            const patched = original.replace(ORIGINAL, PATCHED);
             if (patched === original)
                 throw new Error(`Cursor patch anchor was not changed in ${b.path}`);
-            await atomicWrite(b.path, patched, mode);
             records.push({ path: b.path, relativePath, originalSha256: b.sha256, patchedSha256: sha256Buffer(patched), backupPath });
         }
+        for (const r of records) {
+            const original = await fs.readFile(r.path, 'utf8'), mode = (await fs.stat(r.path)).mode & 0o777;
+            await atomicWrite(r.path, original.replace(ORIGINAL, PATCHED), mode);
+        }
         const after = await inspectCursorBundles(appPath);
         if (after.status !== 'patched' || records.some((r, i) => r.patchedSha256 !== after.bundles[i].sha256))
             throw new Error('Cursor bundle postcondition failed.');
         return { status: 'patched', managed: true, records, backupRoot };
     }
     catch (error) {
-        for (const r of records.slice().reverse())
-            if (r.backupPath && await fs.pathExists(r.backupPath))
-                await fs.copy(r.backupPath, r.path, { overwrite: true, preserveTimestamps: true }).catch(() => undefined);
+        let rollbackError;
+        try {
+            for (const r of records)
+                if (r.backupPath && await fs.pathExists(r.backupPath)) {
+                    const mode = await fs.pathExists(r.path) ? (await fs.stat(r.path)).mode & 0o777 : 0o644;
+                    await atomicWrite(r.path, await fs.readFile(r.backupPath, 'utf8'), mode);
+                }
+            if (records.some(r => sha256Buffer(fs.readFileSync(r.path)) !== r.originalSha256))
+                throw new Error('rollback hash mismatch');
+        }
+        catch (e) {
+            rollbackError = e;
+        }
+        if (rollbackError)
+            throw new Error(`Cursor patch failed and rollback was incomplete: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
         throw error;
     }
 }

package/dist/configure/cursor-state.js

@@ -54,15 +54,16 @@ async function writeRows(db, state, secret) {
     if (result.exitCode !== 0)
         throw new Error('Unable to update Cursor protected state. No API key was printed.');
 }
+function sqliteDotPath(value) { return `"${value.replaceAll('"', '""')}"`; }
+async function sqliteBackup(db, backup) { const r = await execa('/usr/bin/sqlite3', [db, `.backup ${sqliteDotPath(backup)}`], { reject: false }); if (r.exitCode !== 0)
+    throw new Error('Unable to create a consistent Cursor SQLite backup.'); }
+async function sqliteRestore(db, backup) { const r = await execa('/usr/bin/sqlite3', [db, `.restore ${sqliteDotPath(backup)}`], { reject: false }); if (r.exitCode !== 0)
+    throw new Error('Unable to restore the Cursor SQLite backup.'); }
 async function keychainPassword() {
     const found = await execa('/usr/bin/security', ['find-generic-password', '-w', '-s', KEYCHAIN_SERVICE], { reject: false });
     if (found.exitCode === 0 && found.stdout)
         return found.stdout.trimEnd();
-    const password = crypto.randomBytes(32).toString('base64url');
-    const add = await execa('/usr/bin/security', ['add-generic-password', '-U', '-a', 'Cursor', '-s', KEYCHAIN_SERVICE, '-w', password], { reject: false });
-    if (add.exitCode !== 0)
-        throw new Error('Cursor Safe Storage is unavailable. Launch Cursor once, close it, and retry.');
-    return password;
+    throw new Error('Cursor Safe Storage is unavailable. Launch Cursor once, close it, and retry.');
 }
 export async function configureCursorState(home, platform, env, apiKey, baseUrl, models, backupRoot) {
     const dbPath = cursorStateDbPath(home, platform, env);
@@ -82,18 +83,18 @@ export async function configureCursorState(home, platform, env, apiKey, baseUrl,
     const originalSecret = await sqliteValue(dbPath, CURSOR_SECRET_KEY), configuredSecret = encryptCursorSecret(await keychainPassword(), apiKey);
     const backupPath = path.join(backupRoot, 'state.vscdb');
     await fs.ensureDir(path.dirname(backupPath), { mode: 0o700 });
-    await fs.copy(dbPath, backupPath, { overwrite: false, errorOnExist: true });
-    await fs.chmod(backupPath, 0o600).catch(() => undefined);
+    await sqliteBackup(dbPath, backupPath);
+    await fs.chmod(backupPath, 0o600);
     try {
         await writeRows(dbPath, configuredState, configuredSecret);
     }
     catch (error) {
-        await fs.copy(backupPath, dbPath, { overwrite: true });
+        await sqliteRestore(dbPath, backupPath);
         throw error;
     }
     const verifyState = await sqliteValue(dbPath, CURSOR_STATE_KEY), verifySecret = await sqliteValue(dbPath, CURSOR_SECRET_KEY);
     if (verifyState !== configuredState || verifySecret !== configuredSecret) {
-        await fs.copy(backupPath, dbPath, { overwrite: true });
+        await sqliteRestore(dbPath, backupPath);
         throw new Error('Cursor protected-state verification failed; original database restored.');
     }
     return { dbPath, backupPath, originalState, configuredState, originalSecret, configuredSecret, baseUrl: normalizeCursorBaseUrl(baseUrl), modelIds: configured.localProviderModelIds };
@@ -122,6 +123,7 @@ export async function restoreCursorState(record) {
     for (const key of ['useOpenAIKey', 'openAIBaseUrl', 'localProviderModelIds', 'availableDefaultModels2'])
         restoreField(key);
     const currentSecret = await sqliteValue(record.dbPath, CURSOR_SECRET_KEY), secret = currentSecret === record.configuredSecret ? record.originalSecret : currentSecret;
-    await writeRows(record.dbPath, JSON.stringify(current), secret);
-    return true;
+    const restoredState = JSON.stringify(current);
+    await writeRows(record.dbPath, restoredState, secret);
+    return await sqliteValue(record.dbPath, CURSOR_STATE_KEY) === restoredState && await sqliteValue(record.dbPath, CURSOR_SECRET_KEY) === secret;
 }

package/dist/configure/cursor.js

@@ -3,7 +3,7 @@ import fs from 'fs-extra';
 import { execa } from 'execa';
 import { scaleMaxDir, timestamp } from '../utils/paths.js';
 import { writeJsonAtomic, readJson } from '../utils/fs.js';
-import { cursorAppPath, inspectCursorBundles, patchCursorBundles, restoreCursorBundles } from './cursor-bundle.js';
+import { resolveCursorAppPath, inspectCursorBundles, patchCursorBundles, restoreCursorBundles } from './cursor-bundle.js';
 import { configureCursorState, restoreCursorState } from './cursor-state.js';
 const id = 'cursor', name = 'Cursor';
 function manifestPath(ctx) { return path.join(scaleMaxDir(ctx.home, ctx.platform, ctx.env), 'cursor', 'manifest.json'); }
@@ -13,17 +13,21 @@ async function cursorVersion(appPath) { try {
 catch {
     return undefined;
 } }
-export async function isCursorRunning(appPath) { const r = await execa('/usr/bin/pgrep', ['-f', `${appPath}/Contents/MacOS/Cursor`], { reject: false }); return r.exitCode === 0 && Boolean(r.stdout.trim()); }
-async function stopCursor(appPath) { await execa('/usr/bin/osascript', ['-e', 'tell application "Cursor" to quit'], { reject: false }); for (let i = 0; i < 30; i++) {
+export async function isCursorRunning(appPath) { const r = await execa('/usr/bin/pgrep', ['-f', `${appPath}/Contents/MacOS/`], { reject: false }); return r.exitCode === 0 && Boolean(r.stdout.trim()); }
+async function stopCursor(appPath) { await execa('/usr/bin/pkill', ['-TERM', '-f', `${appPath}/Contents/MacOS/`], { reject: false }); for (let i = 0; i < 30; i++) {
     if (!(await isCursorRunning(appPath)))
         return;
     await new Promise(r => setTimeout(r, 500));
 } throw new Error('Cursor is still running. Close Cursor completely and rerun `npx scalemax`.'); }
-async function launchCursor(appPath) { await execa('/usr/bin/open', ['-a', appPath], { reject: false }); }
+async function launchCursor(appPath) { const r = await execa('/usr/bin/open', ['-a', appPath], { reject: false }); if (r.exitCode !== 0)
+    throw new Error(`Cursor was configured but could not be relaunched: ${r.stderr || r.stdout || 'open failed'}`); }
 export async function configure(ctx) {
     if (ctx.platform !== 'darwin')
         return { id, name, changed: false, message: `automatic Cursor BYOK setup is currently verified on macOS only; ${ctx.platform} was not modified` };
-    const appPath = cursorAppPath(ctx.platform, ctx.env);
+    if (typeof process.geteuid === 'function' && process.geteuid() === 0)
+        throw new Error('Refusing to modify Cursor.app as root. Run `npx scalemax` as the signed-in macOS user.');
+    const prior = await readJson(manifestPath(ctx), undefined);
+    const appPath = await resolveCursorAppPath(ctx.platform, ctx.env, ctx.home, prior?.appPath);
     if (!(await fs.pathExists(appPath)))
         return { id, name, changed: false, path: appPath, message: 'Cursor.app was not found' };
     const inspection = await inspectCursorBundles(appPath);
@@ -37,7 +41,6 @@ export async function configure(ctx) {
             throw new Error('Close Cursor completely and rerun `npx scalemax`.');
         await stopCursor(appPath);
     }
-    const prior = await readJson(manifestPath(ctx), undefined);
     let patchResult, state;
     const stateBackupRoot = path.join(scaleMaxDir(ctx.home, ctx.platform, ctx.env), 'cursor', 'backups', timestamp());
     try {
@@ -45,12 +48,9 @@ export async function configure(ctx) {
         const backupRoot = patchResult.backupRoot || stateBackupRoot;
         await fs.ensureDir(backupRoot, { mode: 0o700 });
         state = await configureCursorState(ctx.home, ctx.platform, ctx.env, ctx.apiKey, ctx.baseUrl, ctx.models || [], backupRoot);
-        if (prior?.state) {
-            state.originalState = prior.state.originalState;
-            state.originalSecret = prior.state.originalSecret;
-        }
+        const manifestState = prior?.state ? { ...state, originalState: prior.state.originalState, originalSecret: prior.state.originalSecret } : state;
         const bundles = patchResult.managed ? patchResult.records : (prior?.bundleManaged ? prior.bundles : patchResult.records);
-        const manifest = { schemaVersion: 1, createdAt: new Date().toISOString(), appPath, version: await cursorVersion(appPath), bundleManaged: Boolean(patchResult.managed || prior?.bundleManaged), bundles, state };
+        const manifest = { schemaVersion: 1, createdAt: new Date().toISOString(), appPath, version: await cursorVersion(appPath), bundleManaged: Boolean(patchResult.managed || prior?.bundleManaged), bundles, state: manifestState };
         await writeJsonAtomic(manifestPath(ctx), manifest, 0o600);
         if (wasRunning)
             await launchCursor(appPath);
@@ -69,7 +69,7 @@ export async function configure(ctx) {
 export async function verify(ctx) {
     if (ctx.platform !== 'darwin')
         return { id, name, changed: false, message: 'verification is currently available on macOS only' };
-    const appPath = cursorAppPath(ctx.platform, ctx.env), inspection = await inspectCursorBundles(appPath), manifest = await readJson(manifestPath(ctx), undefined);
+    const manifest = await readJson(manifestPath(ctx), undefined), appPath = await resolveCursorAppPath(ctx.platform, ctx.env, ctx.home, manifest?.appPath), inspection = await inspectCursorBundles(appPath);
     if (inspection.status !== 'patched' || !manifest?.state?.modelIds?.length)
         throw new Error('Cursor local BYOK patch or protected model state is incomplete.');
     const live = new Set((ctx.models || []).map(m => m.id)), configured = new Set(manifest.state.modelIds), missing = [...live].filter(x => !configured.has(x));
@@ -85,7 +85,10 @@ export async function remove(ctx) {
         return { id, name, changed: false, path: file, message: 'no ScaleMax-managed Cursor manifest found' };
     if (await isCursorRunning(manifest.appPath))
         throw new Error('Close Cursor completely before removing its ScaleMax configuration.');
-    const stateRestored = await restoreCursorState(manifest.state), bundlesRestored = manifest.bundleManaged ? await restoreCursorBundles(manifest.bundles) : false;
+    const stateRestored = await restoreCursorState(manifest.state);
+    if (!stateRestored)
+        throw new Error('Cursor protected state was not fully restored; recovery manifest was kept for retry.');
+    const bundlesRestored = manifest.bundleManaged ? await restoreCursorBundles(manifest.bundles) : false;
     await fs.remove(file);
     return { id, name, changed: stateRestored || bundlesRestored, path: file, message: `removed protected BYOK state${bundlesRestored ? ' and restored original Cursor bundles' : ' (pre-existing external Cursor patch left unchanged)'}` };
 }

package/dist/configure/trae-solo.js

@@ -5,7 +5,7 @@ const id = 'trae-solo';
 const name = 'TRAE SOLO';
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    const content = jsonConfig(name, ctx.apiKey, ctx.baseUrl, { "officialSetup": ["Settings > Models > Add Model", "API format: OpenAI Chat Completions", "Request URL: https://api.scalemax.pro/v1/chat/completions or base URL https://api.scalemax.pro/v1", "Model ID: fable-5 or another ScaleMax model"], "recommendedModel": "fable-5" });
+    const content = jsonConfig(name, '$SCALEMAX_API_KEY', ctx.baseUrl, { "officialSetup": ["Settings > Models > Add Model", "API format: OpenAI Chat Completions", "Request URL: https://api.scalemax.pro/v1/chat/completions or base URL https://api.scalemax.pro/v1", "Model ID: fable-5 or another ScaleMax model"], "recommendedModel": "fable-5" });
     const result = await writeManagedConfig(ctx, id, name, file, content);
     return { ...result, message: 'setup guide written; enter these values in TRAE SOLO custom model settings' };
 }

package/dist/detect/common.js

@@ -1,28 +1,27 @@
 import fs from 'fs-extra';
 import { commandExists } from '../utils/exec.js';
 import { clientConfigPath, installHints } from '../configure/paths.js';
+import { GENERATED_HEADER } from '../constants.js';
 const commands = {
-    codex: ['codex'],
-    cursor: ['cursor'],
-    'trae-solo': ['trae', 'trae-solo'],
-    claude: ['claude'],
-    opencode: ['opencode'],
-    openclaw: ['openclaw'],
-    hermes: ['hermes'],
-    'cherry-studio': ['cherry-studio', 'cherrystudio'],
-    'api-code': []
+    codex: ['codex'], cursor: ['cursor'], 'trae-solo': ['trae', 'trae-solo'], claude: ['claude'], opencode: ['opencode'], openclaw: ['openclaw'], hermes: ['hermes'], 'cherry-studio': ['cherry-studio', 'cherrystudio'], 'api-code': []
 };
+const guiPathDetection = new Set(['trae-solo', 'cherry-studio']);
 export async function detectClient(ctx, id, name) {
-    const paths = [clientConfigPath(id, ctx.home, ctx.platform, ctx.env), ...installHints(id, ctx.home, ctx.platform, ctx.env)];
-    const pathHits = [];
-    for (const p of paths)
-        if (await fs.pathExists(p))
-            pathHits.push(p);
+    const config = clientConfigPath(id, ctx.home, ctx.platform, ctx.env);
     const cmdHits = [];
     for (const cmd of commands[id])
-        if (await commandExists(cmd))
+        if (await commandExists(cmd, ctx.env))
             cmdHits.push(`command:${cmd}`);
-    const hits = [...cmdHits, ...pathHits];
-    const alwaysAvailable = id === 'api-code';
-    return { id, name, installed: hits.length > 0 || alwaysAvailable, reason: hits.length || alwaysAvailable ? undefined : 'not detected', paths: hits };
+    const appHits = [];
+    if (guiPathDetection.has(id))
+        for (const p of installHints(id, ctx.home, ctx.platform, ctx.env))
+            if (!p.includes('.scalemax') && await fs.pathExists(p))
+                appHits.push(p);
+    let configured = false;
+    if (await fs.pathExists(config)) {
+        const text = await fs.readFile(config, 'utf8').catch(() => '');
+        configured = text.includes(GENERATED_HEADER) || text.includes('"scalemax.managedBy"');
+    }
+    const hits = [...cmdHits, ...appHits];
+    return { id, name, installed: hits.length > 0, configured, reason: hits.length ? undefined : 'not detected', paths: [...hits, ...(configured ? [config] : [])] };
 }

package/dist/detect/cursor.js

@@ -1,11 +1,13 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { scaleMaxDir } from '../utils/paths.js';
-import { cursorAppPath, inspectCursorBundles } from '../configure/cursor-bundle.js';
+import { resolveCursorAppPath, inspectCursorBundles } from '../configure/cursor-bundle.js';
 export async function detect(ctx) {
     if (ctx.platform !== 'darwin')
         return { id: 'cursor', name: 'Cursor', installed: false, configured: false, paths: [], reason: `automatic BYOK setup currently supports macOS only (${ctx.platform})` };
-    const appPath = cursorAppPath(ctx.platform, ctx.env), manifest = path.join(scaleMaxDir(ctx.home, ctx.platform, ctx.env), 'cursor', 'manifest.json');
+    const manifest = path.join(scaleMaxDir(ctx.home, ctx.platform, ctx.env), 'cursor', 'manifest.json');
+    const managed = await fs.readJson(manifest).catch(() => undefined);
+    const appPath = await resolveCursorAppPath(ctx.platform, ctx.env, ctx.home, managed?.appPath);
     if (!(await fs.pathExists(appPath)))
         return { id: 'cursor', name: 'Cursor', installed: false, configured: false, paths: [appPath], reason: 'Cursor.app not found' };
     try {

package/dist/index.js

@@ -31,6 +31,27 @@ function welcome() {
     console.log(chalk.cyan('╚══════════════════════════════╝'));
     console.log('\nThe fastest way to connect every AI coding client.\n');
 }
+function printHelp(command) {
+    const details = { update: 'Revalidate the API key and reconfigure every detected client.', remove: 'Restore backups or remove only ScaleMax-managed client configuration.', doctor: 'Validate the API key and verify detected client configuration.', models: 'List models available to the stored API key.', login: 'Store or replace the ScaleMax API key.', logout: 'Remove the locally stored ScaleMax API key.' };
+    if (command && details[command]) {
+        console.log(`Usage: scalemax ${command}\n\n${details[command]}`);
+        return;
+    }
+    console.log(`ScaleMax CLI
+
+Commands:
+  scalemax            Interactive installer
+  scalemax init       Interactive installer (alias for no-arg scalemax)
+  scalemax setup      Interactive installer (alias)
+  scalemax login      Store or replace API key
+  scalemax logout     Remove API key
+  scalemax doctor     Run diagnostics
+  scalemax models     List available models
+  scalemax update     Reconfigure detected clients
+  scalemax remove     Remove ScaleMax-generated configs
+  scalemax --version  Show installed version
+`);
+}
 async function runInteractiveInstaller() {
     welcome();
     await runSystemAudit();
@@ -42,17 +63,23 @@ async function runInteractiveInstaller() {
 }
 async function main() {
     if (!isNodeSupported()) {
-        console.error(chalk.red(`ScaleMax requires Node.js >=18.17. Current: ${process.versions.node}`));
+        console.error(chalk.red(`ScaleMax requires Node.js >=18.19. Current: ${process.versions.node}`));
         console.error(nodeUpgradeHint());
         process.exitCode = 1;
         return;
     }
-    const [, , command] = process.argv;
+    const [, , command, ...args] = process.argv;
     try {
         if (!command) {
             await runInteractiveInstaller();
             return;
         }
+        if (args.some(arg => arg === '--help' || arg === '-h')) {
+            printHelp(command);
+            return;
+        }
+        if (args.length)
+            throw new Error(`Unknown option for ${command}: ${args.join(' ')}`);
         switch (command) {
             case 'init':
             case 'setup':
@@ -82,20 +109,7 @@ async function main() {
                 break;
             case '--help':
             case '-h':
-                console.log(`ScaleMax CLI
-
-Commands:
-  scalemax            Interactive installer
-  scalemax init       Interactive installer (alias for no-arg scalemax)
-  scalemax setup      Interactive installer (alias)
-  scalemax login      Store or replace API key
-  scalemax logout     Remove API key
-  scalemax doctor     Run diagnostics
-  scalemax models     List available models
-  scalemax update     Reconfigure detected clients
-  scalemax remove     Remove ScaleMax-generated configs
-  scalemax --version  Show installed version
-`);
+                printHelp();
                 break;
             default: throw new Error(`Unknown command: ${command}`);
         }

package/dist/utils/api.js

@@ -27,7 +27,9 @@ async function request(path, apiKey, init = {}) {
     headers.set('Cache-Control', 'no-cache');
     if (!headers.has('Content-Type') && init.body)
         headers.set('Content-Type', 'application/json');
-    return fetch(`${SCALEMAX_BASE_URL}${path}`, { ...init, headers });
+    const timeout = AbortSignal.timeout(15000);
+    const signal = init.signal && typeof AbortSignal.any === 'function' ? AbortSignal.any([init.signal, timeout]) : timeout;
+    return fetch(`${SCALEMAX_BASE_URL}${path}`, { ...init, headers, signal });
 }
 export async function validateApiKey(apiKey) {
     try {
@@ -38,12 +40,16 @@ export async function validateApiKey(apiKey) {
         const keyMeta = { provider_scope: usage?.key?.provider_scope || 'both', mode: usage?.key?.mode, prefix: usage?.key?.prefix, label: usage?.key?.label };
         const modelsRes = await request('/models', apiKey);
         if (!modelsRes.ok)
-            return { ok: true, models: [], key: keyMeta, error: await friendlyError(modelsRes) };
+            return { ok: false, models: [], key: keyMeta, error: await friendlyError(modelsRes) };
         const data = await modelsRes.json();
-        return { ok: true, models: Array.isArray(data.data) ? data.data : [], key: keyMeta };
+        const models = Array.isArray(data.data) ? data.data : [];
+        if (!models.length)
+            return { ok: false, models: [], key: keyMeta, error: 'ScaleMax returned an empty model catalog.' };
+        return { ok: true, models, key: keyMeta };
     }
     catch (err) {
-        return { ok: false, models: [], error: err instanceof Error ? err.message : String(err) };
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, models: [], error: /abort|timeout/i.test(message) ? 'ScaleMax request timed out after 15 seconds.' : message };
     }
 }
 export async function testStreaming(apiKey, model) {

package/dist/utils/fs.js

@@ -1,13 +1,37 @@
 import fs from 'fs-extra';
+import fsp from 'node:fs/promises';
+import crypto from 'node:crypto';
 import path from 'node:path';
 import { backupDir, timestamp } from './paths.js';
 export async function exists(p) { return fs.pathExists(p); }
 export async function atomicWrite(file, content, mode = 0o600) {
     await fs.ensureDir(path.dirname(file));
-    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
-    await fs.writeFile(tmp, content, { mode });
-    await fs.rename(tmp, file);
-    await fs.chmod(file, mode).catch(() => undefined);
+    const existing = await fs.lstat(file).catch(() => undefined);
+    if (existing?.isSymbolicLink())
+        throw new Error(`Refusing to overwrite symlink: ${file}`);
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await fsp.open(tmp, 'wx', mode);
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fsp.rename(tmp, file);
+        await fsp.chmod(file, mode);
+        const dir = await fsp.open(path.dirname(file), 'r');
+        try {
+            await dir.sync();
+        }
+        finally {
+            await dir.close();
+        }
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await fsp.rm(tmp, { force: true }).catch(() => undefined);
+    }
 }
 export function backupNameFor(file) {
     const withoutDrive = file.replace(/^[A-Za-z]:[\\/]?/, '').replace(/^[\\/]+/, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalemax",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "vitest": "^2.1.8"
   },
   "engines": {
-    "node": ">=18.17"
+    "node": ">=18.19"
   },
   "keywords": [
     "scalemax",
@@ -62,11 +62,6 @@
   "license": "MIT",
   "author": "ScaleMax <support@scalemax.pro>",
   "homepage": "https://scalemax.pro",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/scalemax-pro/scalemax.git",
-    "directory": "packages/cli"
-  },
   "bugs": {
     "url": "https://scalemax.pro",
     "email": "support@scalemax.pro"