scalemax 0.1.22 → 0.1.23

package/README.md

@@ -113,13 +113,15 @@ Or ask one small question and exit:
 npx scalemax@latest helper-bot "Why is my ScaleMax API key rejected in Codex?"
 ```
 
-The helper uses the same stored key as the installer, verifies authentication, detects the API-credit or token-pack base URL automatically, and selects a model available to that key. Each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a specific model from `scalemax models`, use:
+The helper uses the same stored key as the installer, verifies authentication, and detects the API-credit or token-pack base URL automatically. General support questions default to `gpt-5.4` when that model is available to the key; each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a different model from `scalemax models`, use:
 
 ```bash
 npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"
 ```
 
-The helper is restricted to ScaleMax tasks, refuses unrelated requests, redacts ScaleMax-style secrets before requests and output, and never receives local shell or filesystem tools. Use `/help` inside the session for commands and `/quit` to exit.
+Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. For example, `setup vs code roo extension for claude` detects or installs the official Roo Code extension, writes its ScaleMax Claude profile with the stored key, verifies the handoff, and reports each step. The language model never generates or executes shell commands; only fixed ScaleMax client detection, configuration, verification, rollback, and the official Roo Code extension installer are available to the controller.
+
+The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use `/status` for non-secret connection details, `/help` for commands, and `/quit` to exit.
 
 ## Supported clients
 

package/dist/commands/helper-bot.d.ts

@@ -1,6 +1,7 @@
 import { type ChatCompletionOptions, type ChatCompletionResult, type ChatMessage, type ModelInfo } from '../utils/api.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { validateApiKey } from '../utils/api.js';
+import type { ClientDefinition } from '../types/client.js';
 export declare const SCALEMAX_HELPER_REFUSAL: string;
 export declare const SCALEMAX_HELPER_SYSTEM_PROMPT: string;
 export declare const SCALEMAX_HELPER_INVALID_PROVIDER_RESPONSE: string;
@@ -16,6 +17,7 @@ export interface HelperConnection {
     providerScope?: 'openai' | 'anthropic' | 'both';
     keyMode?: string;
     availableModels?: string[];
+    modelCatalog?: ModelInfo[];
 }
 export type HelperCompletion = (options: ChatCompletionOptions) => Promise<ChatCompletionResult>;
 export interface HelperBotDependencies {
@@ -23,6 +25,7 @@ export interface HelperBotDependencies {
     validateKey: typeof validateApiKey;
     complete: HelperCompletion;
     write: (message: string) => void;
+    clientCatalog: ClientDefinition[];
 }
 export declare function parseHelperBotArgs(args: string[]): HelperBotArgs;
 export declare function redactHelperSecrets(value: unknown, activeKey?: string): string;
@@ -38,4 +41,6 @@ export declare function helperConnectionSummary(connection: HelperConnection): s
 export declare function localHelperReply(question: string, connection: HelperConnection): string | undefined;
 export declare function selectHelperModel(models: ModelInfo[], requested?: string): string;
 export declare function requestHelperReply(question: string, history: ChatMessage[], connection: HelperConnection, complete?: HelperCompletion): Promise<string>;
+/** Execute only narrowly allowlisted ScaleMax client actions; never model-generated shell commands. */
+export declare function executeHelperAction(question: string, connection: HelperConnection, home: string, clientCatalog?: ClientDefinition[], write?: (message: string) => void): Promise<string | undefined>;
 export declare function helperBotCommand(args?: string[], home?: string, dependencies?: Partial<HelperBotDependencies>): Promise<void>;

package/dist/commands/helper-bot.js

@@ -1,6 +1,9 @@
 import chalk from 'chalk';
+import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { createChatCompletion } from '../utils/api.js';
+import { execa } from 'execa';
+import { clients } from '../clients.js';
+import { createChatCompletion, isAnthropicModel } from '../utils/api.js';
 import { redactApiKey } from '../utils/apiKey.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { homeDir } from '../utils/paths.js';
@@ -538,6 +541,9 @@ const CLAUDE_DESKTOP_PATTERN = /\bclaude\s+desktop\b/i;
 const CLAUDE_DESKTOP_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|gateway|base\s*url|api\s*key|connect(?:ion)?|third[- ]party|inference|field|install|verify)\b/i;
 const CODEX_CLI_PATTERN = /\bcodex(?:\s+cli)?\b/i;
 const CLIENT_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|base\s*url|api\s*key|connect(?:ion)?|provider|install|repair|verify|update)\b/i;
+const HELPER_MUTATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to|how\s+(?:do|can)\s+i)\s+)(?:set\s*up|setup|configure|connect|install|repair|fix|update|reconfigure)\b/i;
+const HELPER_VERIFICATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to)\s+)(?:verify|check|test|diagnose)\b/i;
+const ALL_CLIENTS_PATTERN = /\b(?:all|every)\b.{0,30}\b(?:client|provider|integration|app)s?\b/i;
 const KNOWN_CONTEXT_REASK_PATTERN = /(?:\b(?:need|send|provide|share|tell)\b.{0,100}\b(?:api\s*(?:key|endpoint)|base\s*url|operating\s+system|\bos\b|model\s+(?:name|catalog))\b|YOUR-SCALEMAX-ENDPOINT|your-key)/is;
 const PROVIDER_IDENTITY_OVERRIDE_PATTERNS = [
     /\bkiro\b/i,
@@ -558,7 +564,8 @@ const defaultDependencies = {
     loadKey: loadApiKey,
     validateKey: validateApiKey,
     complete: createChatCompletion,
-    write: message => console.log(message)
+    write: message => console.log(message),
+    clientCatalog: clients
 };
 export function parseHelperBotArgs(args) {
     let model;
@@ -630,9 +637,9 @@ Mandatory behavior:
 
 1. Treat the stored key, base URLs, operating system, provider scope, and model catalog as already known. Do not request them again.
 2. Never output placeholders such as YOUR-SCALEMAX-ENDPOINT or your-key when an exact known value can be used.
-3. Prefer the automatic CLI workflow. For an installed supported client, tell the user to exit the Helper with /quit, run \`scalemax update\`, then run \`scalemax doctor\` to verify it.
+3. The CLI controller executes recognized safe configuration and verification requests before asking the model. Do not claim that an unrecognized action was executed.
 4. The Helper request itself uses the stored customer key and therefore consumes the small number of tokens used by the selected Helper model. The key is never included in the prompt text.
-5. Do not claim you executed terminal commands. The Helper has no shell tools; give the shortest exact ScaleMax command sequence when user action is required.`;
+5. When user action is genuinely required, give the shortest exact instruction and clearly distinguish it from work already completed by the CLI controller.`;
 }
 export function helperConnectionSummary(connection) {
     return `Authenticated ${helperBillingMode(connection)} key · ${helperPlatformName(connection.platform)} · ${connection.providerScope || 'both'} scope · ${connection.baseUrl} · helper model ${connection.model}`;
@@ -685,7 +692,7 @@ export function selectHelperModel(models, requested) {
             throw new Error(`Model "${requested}" is not available to this API key. Run \`scalemax models\` to see available models.`);
         return exact.id;
     }
-    const preferred = ['gpt-5.6-luna', 'claude-haiku-4-5-20251001', 'fable-5', 'gpt-5.6-terra', 'gpt-5.6-sol'];
+    const preferred = ['gpt-5.4', 'gpt-5.4-mini', 'claude-haiku-4-5-20251001', 'gpt-5.6-luna', 'fable-5', 'gpt-5.6-terra', 'gpt-5.6-sol'];
     for (const id of preferred) {
         const match = models.find(model => model.id.toLowerCase() === id);
         if (match)
@@ -731,8 +738,170 @@ For automatic configuration, exit with \`/quit\`, run \`scalemax update\`, then
     }
     return reply;
 }
+const HELPER_CLIENT_PATTERNS = [
+    { id: 'roo-code', pattern: /\b(?:roo(?:\s+code)?|roo\s+(?:extension|plugin)|vscode\s+roo|vs\s+code\s+roo)\b/i },
+    { id: 'openclaw', pattern: /\bopen\s*claw\b/i },
+    { id: 'opencode', pattern: /\bopen\s*code\b/i },
+    { id: 'cherry-studio', pattern: /\bcherry\s*studio\b/i },
+    { id: 'api-code', pattern: /\bapi\s*code\b/i },
+    { id: 'trae-solo', pattern: /\btrae(?:\s+solo)?\b/i },
+    { id: 'cursor', pattern: /\bcursor\b/i },
+    { id: 'hermes', pattern: /\bhermes\b/i },
+    { id: 'codex', pattern: /\bcodex(?:\s+cli)?\b/i },
+    { id: 'claude', pattern: /\bclaude\s+code\b/i }
+];
+function helperActionKind(question) {
+    if (HELPER_MUTATION_PATTERN.test(question))
+        return 'configure';
+    if (HELPER_VERIFICATION_PATTERN.test(question))
+        return 'verify';
+    return undefined;
+}
+function helperActionTarget(question) {
+    if (CLAUDE_DESKTOP_PATTERN.test(question))
+        return undefined;
+    if (ALL_CLIENTS_PATTERN.test(question))
+        return 'all';
+    return HELPER_CLIENT_PATTERNS.find(candidate => candidate.pattern.test(question))?.id;
+}
+function requestedProviderScope(question, target) {
+    if (/\b(?:both|openai\s*\+\s*claude|claude\s*\+\s*openai)\b/i.test(question))
+        return 'both';
+    if (/\b(?:claude|anthropic)\b/i.test(question))
+        return 'anthropic';
+    if (/\b(?:openai|chatgpt|gpt)\b/i.test(question) || target === 'codex')
+        return 'openai';
+    return undefined;
+}
+function actionModels(connection, requestedScope) {
+    const catalog = connection.modelCatalog?.length
+        ? connection.modelCatalog
+        : (connection.availableModels || []).map(id => ({ id }));
+    if (!requestedScope || requestedScope === 'both')
+        return catalog;
+    return catalog.filter(model => requestedScope === 'anthropic' ? isAnthropicModel(model) : !isAnthropicModel(model));
+}
+function hasRooCodeExtension(paths) {
+    return paths.some(candidate => /^rooveterinaryinc\.roo-cline-/i.test(path.basename(candidate)));
+}
+async function installRooCodeExtension(ctx, client, write) {
+    let detection = await client.detect(ctx);
+    if (hasRooCodeExtension(detection.paths))
+        return;
+    if (!detection.executable)
+        throw new Error('VS Code and the Roo Code extension were not detected. Install VS Code first, then retry this request.');
+    write('→ Installing the official Roo Code extension in VS Code…');
+    const result = await execa('code', ['--install-extension', 'RooVeterinaryInc.roo-cline', '--force'], {
+        env: ctx.env,
+        reject: false,
+        all: true
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`Roo Code extension installation failed: ${result.all?.trim() || `code exited with ${result.exitCode}`}`);
+    detection = await client.detect(ctx);
+    if (!hasRooCodeExtension(detection.paths))
+        throw new Error('VS Code reported a successful Roo Code installation, but the extension could not be detected afterward. Restart VS Code and retry.');
+    write('✓ Roo Code extension installed and detected.');
+}
+async function runOneHelperClientAction(kind, client, connection, home, requestedScope, write) {
+    const models = actionModels(connection, requestedScope);
+    if (!models.length)
+        throw new Error(`The authenticated key does not expose ${requestedScope === 'anthropic' ? 'Claude' : requestedScope === 'openai' ? 'OpenAI' : 'compatible'} models for ${client.name}. No configuration was changed.`);
+    if (client.id === 'codex' && models.every(isAnthropicModel))
+        throw new Error('Codex requires an OpenAI-compatible model, but this key exposes only Claude models. No configuration was changed.');
+    if (client.id === 'cursor' && connection.platform !== 'darwin')
+        throw new Error(`Automatic Cursor configuration is currently verified on macOS only. ${helperPlatformName(connection.platform)} was not modified.`);
+    const ctx = {
+        home,
+        platform: connection.platform || process.platform,
+        env: process.env,
+        apiKey: connection.apiKey,
+        baseUrl: connection.baseUrl,
+        providerScope: requestedScope || connection.providerScope || 'both',
+        models,
+        interactive: false,
+        allowAppModification: false
+    };
+    write(`→ Detecting ${client.name}…`);
+    let detection = await client.detect(ctx);
+    if (kind === 'configure' && client.id === 'roo-code') {
+        await installRooCodeExtension(ctx, client, write);
+        detection = await client.detect(ctx);
+    }
+    if (!detection.installed)
+        throw new Error(`${client.name} was not detected. No configuration was changed.`);
+    write(`✓ ${client.name} detected.`);
+    if (kind === 'verify') {
+        if (!client.verify) {
+            if (!detection.configured)
+                throw new Error(`${client.name} is installed but its ScaleMax configuration was not detected.`);
+            return `✓ ${client.name} ScaleMax configuration is present.`;
+        }
+        write(`→ Verifying ${client.name}…`);
+        const verified = await client.verify(ctx);
+        return `✓ ${client.name} ${verified.message}`;
+    }
+    write(`→ Configuring ${client.name} with the authenticated stored key…`);
+    const configured = await client.configure(ctx);
+    write(`✓ ${client.name} ${configured.message}`);
+    if (client.verify) {
+        write(`→ Verifying ${client.name} configuration…`);
+        try {
+            const verified = await client.verify(ctx);
+            write(`✓ ${client.name} ${verified.message}`);
+        }
+        catch (error) {
+            if (configured.changed) {
+                write(`→ Verification failed; removing the incomplete ScaleMax-managed ${client.name} configuration…`);
+                await client.remove(ctx).catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    else {
+        detection = await client.detect(ctx);
+        if (!detection.configured)
+            throw new Error(`${client.name} configuration was written but could not be detected afterward.`);
+        write(`✓ ${client.name} configuration detected after write.`);
+    }
+    const activation = client.id === 'roo-code' ? ' Reload VS Code once so Roo Code imports the verified ScaleMax profile.' : '';
+    return `✅ Successfully completed: ${client.name} is configured and locally verified.${activation}`;
+}
+/** Execute only narrowly allowlisted ScaleMax client actions; never model-generated shell commands. */
+export async function executeHelperAction(question, connection, home, clientCatalog = clients, write = message => console.log(message)) {
+    const cleanQuestion = redactHelperSecrets(question.trim(), connection.apiKey);
+    if (!isScaleMaxHelperQuestion(cleanQuestion))
+        return undefined;
+    const kind = helperActionKind(cleanQuestion);
+    const target = helperActionTarget(cleanQuestion);
+    if (!kind || !target)
+        return undefined;
+    const scope = requestedProviderScope(cleanQuestion, target);
+    const selected = target === 'all'
+        ? clientCatalog.filter(client => client.id !== 'cursor')
+        : clientCatalog.filter(client => client.id === target);
+    if (!selected.length)
+        throw new Error('The requested ScaleMax integration is not supported by this CLI build.');
+    write(`✓ Stored ${helperBillingMode(connection)} key is authenticated; secrets remain hidden.`);
+    const completed = [];
+    const failures = [];
+    for (const client of selected) {
+        try {
+            completed.push(await runOneHelperClientAction(kind, client, connection, home, scope, write));
+        }
+        catch (error) {
+            const message = redactHelperSecrets(error instanceof Error ? error.message : String(error), connection.apiKey);
+            if (target !== 'all')
+                throw new Error(message);
+            failures.push(`${client.name}: ${message}`);
+        }
+    }
+    if (!completed.length)
+        throw new Error(`No ScaleMax client action completed.\n${failures.map(item => `- ${item}`).join('\n')}`);
+    return `${completed.join('\n')}${failures.length ? `\n\nSkipped or failed:\n${failures.map(item => `- ${item}`).join('\n')}` : ''}`;
+}
 function printSessionHelp(write) {
-    write('Commands: /help shows this help; /status shows the authenticated non-secret connection details; /quit exits. Ask only ScaleMax installation, configuration, authentication, or troubleshooting questions.');
+    write('Commands: /help shows this help; /status shows the authenticated non-secret connection details; /quit exits. Setup, repair, and verification requests for supported clients are executed automatically with progress notifications.');
 }
 export async function helperBotCommand(args = [], home = homeDir(), dependencies = {}) {
     const deps = { ...defaultDependencies, ...dependencies };
@@ -751,10 +920,15 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
         platform: process.platform,
         providerScope: validation.key?.provider_scope || 'both',
         keyMode: validation.key?.mode,
-        availableModels: validation.models.map(item => item.id)
+        availableModels: validation.models.map(item => item.id),
+        modelCatalog: validation.models
+    };
+    const respond = async (question, history) => {
+        const action = await executeHelperAction(question, connection, home, deps.clientCatalog, deps.write);
+        return action || requestHelperReply(question, history, connection, deps.complete);
     };
     if (options.question) {
-        deps.write(await requestHelperReply(options.question, [], connection, deps.complete));
+        deps.write(await respond(options.question, []));
         return;
     }
     if (!process.stdin.isTTY)
@@ -787,7 +961,7 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
                 continue;
             }
             try {
-                const reply = await requestHelperReply(input, history, connection, deps.complete);
+                const reply = await respond(input, history);
                 deps.write(reply);
                 if (reply !== SCALEMAX_HELPER_REFUSAL) {
                     history.push({ role: 'user', content: redactHelperSecrets(input, key) }, { role: 'assistant', content: reply });

package/dist/index.js

@@ -34,7 +34,7 @@ function welcome() {
 }
 function printHelp(command) {
     if (command === 'helper-bot') {
-        console.log('Usage: scalemax helper-bot [--model <id>] ["question"]\n\nOpen the ScaleMax-only installation, configuration, authentication, and troubleshooting assistant.');
+        console.log('Usage: scalemax helper-bot [--model <id>] ["question"]\n\nExecute safe ScaleMax setup and verification actions, or open the ScaleMax-only troubleshooting assistant.');
         return;
     }
     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.' };
@@ -52,7 +52,7 @@ Commands:
   scalemax logout     Remove API key
   scalemax doctor     Run diagnostics
   scalemax models     List available models
-  scalemax helper-bot Open the ScaleMax Helper
+  scalemax helper-bot Execute setup actions or open the ScaleMax Helper
   scalemax update     Reconfigure detected clients
   scalemax remove     Remove ScaleMax-generated configs
   scalemax --version  Show installed version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalemax",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {