vigthoria-cli 1.13.20 → 1.13.22

package/dist/commands/device.js

@@ -5,12 +5,11 @@ import * as path from 'path';
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { CH } from '../utils/logger.js';
+import { safeChildProcessEnv } from '../utils/secret-policy.js';
+import { CliCommandError, formatSuccessJson } from '../utils/command-contract.js';
 const execFileAsync = promisify(execFile);
 export class DeviceCommand {
-    logger;
-    constructor(_config, logger) {
-        this.logger = logger;
-    }
+    constructor(_config, _logger) { }
     async status(options = {}) {
         const adbPath = this.findAdbPath();
         const devices = adbPath ? await this.getDevices(adbPath) : [];
@@ -21,7 +20,7 @@ export class DeviceCommand {
             devices,
         };
         if (options.json) {
-            console.log(JSON.stringify(payload, null, 2));
+            console.log(formatSuccessJson('device status', payload));
             return;
         }
         console.log();
@@ -49,7 +48,7 @@ export class DeviceCommand {
         const adbPath = this.requireAdbPath();
         const devices = await this.getDevices(adbPath);
         if (options.json) {
-            console.log(JSON.stringify({ devices }, null, 2));
+            console.log(formatSuccessJson('device list', { devices }));
             return;
         }
         if (devices.length === 0) {
@@ -65,7 +64,7 @@ export class DeviceCommand {
         const deviceId = await this.resolveDeviceId(adbPath, options.device);
         const output = path.resolve(options.output || `vigthoria-android-screenshot-${this.timestamp()}.png`);
         const args = this.withDevice(deviceId, ['exec-out', 'screencap', '-p']);
-        const result = await execFileAsync(adbPath, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024 });
+        const result = await execFileAsync(adbPath, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024, env: safeChildProcessEnv() });
         fs.writeFileSync(output, result.stdout);
         console.log(chalk.green(`Saved screenshot: ${output}`));
     }
@@ -78,7 +77,7 @@ export class DeviceCommand {
         const adbPath = this.requireAdbPath();
         const deviceId = await this.resolveDeviceId(adbPath, options.device);
         const result = await this.runAdb(adbPath, this.withDevice(deviceId, ['install', '-r', resolvedApk]), 120000);
-        this.printResult(result, options.json);
+        this.printResult('device install', result, options.json);
     }
     async launch(packageName, options = {}) {
         if (!packageName)
@@ -89,7 +88,7 @@ export class DeviceCommand {
             ? ['shell', 'am', 'start', '-n', `${packageName}/${options.activity}`]
             : ['shell', 'monkey', '-p', packageName, '-c', 'android.intent.category.LAUNCHER', '1'];
         const result = await this.runAdb(adbPath, this.withDevice(deviceId, args));
-        this.printResult(result, options.json);
+        this.printResult('device launch', result, options.json);
     }
     async logs(options = {}) {
         const adbPath = this.requireAdbPath();
@@ -98,10 +97,23 @@ export class DeviceCommand {
         const args = this.withDevice(deviceId, options.follow ? ['logcat'] : ['logcat', '-d', '-t', lines]);
         if (options.follow) {
             await new Promise((resolve, reject) => {
-                const child = spawn(adbPath, args, { stdio: 'inherit' });
-                child.on('error', reject);
+                const child = spawn(adbPath, args, { stdio: 'inherit', env: safeChildProcessEnv() });
+                let interrupted = false;
+                const onInterrupt = () => {
+                    interrupted = true;
+                    child.kill('SIGINT');
+                };
+                process.once('SIGINT', onInterrupt);
+                const finish = () => process.removeListener('SIGINT', onInterrupt);
+                child.on('error', (error) => {
+                    finish();
+                    reject(error);
+                });
                 child.on('exit', (code) => {
-                    if (code && code !== 0)
+                    finish();
+                    if (interrupted)
+                        reject(new CliCommandError('Device log stream cancelled by user.', { code: 'DEVICE_LOGS_CANCELLED', category: 'cancelled' }));
+                    else if (code && code !== 0)
                         reject(new Error(`adb logcat exited with code ${code}`));
                     else
                         resolve();
@@ -110,26 +122,26 @@ export class DeviceCommand {
             return;
         }
         const result = await this.runAdb(adbPath, args, 30000, 8 * 1024 * 1024);
-        this.printResult(result, options.json);
+        this.printResult('device logs', result, options.json);
     }
     async tcpip(options = {}) {
         const adbPath = this.requireAdbPath();
         const deviceId = await this.resolveDeviceId(adbPath, options.device);
         const port = String(options.port || '5555');
         const result = await this.runAdb(adbPath, this.withDevice(deviceId, ['tcpip', port]));
-        this.printResult(result, options.json);
+        this.printResult('device tcpip', result, options.json);
     }
     async connect(address, options = {}) {
         if (!address)
             throw new Error('Device address is required, for example 192.168.1.30:5555.');
         const adbPath = this.requireAdbPath();
         const result = await this.runAdb(adbPath, ['connect', address]);
-        this.printResult(result, options.json);
+        this.printResult('device connect', result, options.json);
     }
     async disconnect(address, options = {}) {
         const adbPath = this.requireAdbPath();
         const result = await this.runAdb(adbPath, address ? ['disconnect', address] : ['disconnect']);
-        this.printResult(result, options.json);
+        this.printResult('device disconnect', result, options.json);
     }
     async getDevices(adbPath) {
         const result = await this.runAdb(adbPath, ['devices', '-l']);
@@ -176,7 +188,7 @@ export class DeviceCommand {
     }
     async runAdb(adbPath, args, timeout = 30000, maxBuffer = 1024 * 1024) {
         try {
-            const result = await execFileAsync(adbPath, args, { timeout, maxBuffer });
+            const result = await execFileAsync(adbPath, args, { timeout, maxBuffer, env: safeChildProcessEnv() });
             return { success: true, stdout: String(result.stdout || '').trim(), stderr: String(result.stderr || '').trim() };
         }
         catch (error) {
@@ -188,17 +200,21 @@ export class DeviceCommand {
             };
         }
     }
-    printResult(result, json = false) {
+    printResult(command, result, json = false) {
+        if (!result.success) {
+            throw new CliCommandError(result.stderr || `${command} failed`, {
+                code: 'DEVICE_COMMAND_FAILED',
+                details: { command, stdout: result.stdout },
+            });
+        }
         if (json) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(formatSuccessJson(command, result));
             return;
         }
         if (result.stdout)
             console.log(result.stdout);
         if (result.stderr)
             console.error(result.success ? chalk.gray(result.stderr) : chalk.red(result.stderr));
-        if (!result.success)
-            process.exitCode = 1;
     }
     requireAdbPath() {
         const adbPath = this.findAdbPath();

package/dist/commands/doctor-registration.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { Config } from '../utils/config.js';
+import type { Logger } from '../utils/logger.js';
+export declare function registerDoctorCommand(program: Command, config: Config, logger: Logger, version: string): void;

package/dist/commands/doctor-registration.js

@@ -0,0 +1,200 @@
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import axios from 'axios';
+import chalk from 'chalk';
+import { isIOSEnvironment, resolveClientOsSlug } from '../utils/clientManifest.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
+import { sanitizeUserFacingErrorText } from '../utils/api.js';
+import { getCliStateFile, isOfflineMode, isUpdateCheckSuppressed } from '../utils/cli-state.js';
+import { CliCommandError, formatSuccessJson } from '../utils/command-contract.js';
+export function registerDoctorCommand(program, config, logger, version) {
+    program
+        .command('doctor')
+        .description('Run local Vigthoria CLI diagnostics (no network calls unless --check-api)')
+        .option('--check-api', 'Also probe Vigthoria API reachability', false)
+        .option('--json', 'Emit machine-readable JSON output', false)
+        .action(async (options) => {
+        const apiUrl = String(config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
+        const modelsApiUrl = String(config.get('modelsApiUrl') || 'https://api.vigthoria.io').replace(/\/$/, '');
+        const offline = isOfflineMode();
+        const updateSuppressed = isUpdateCheckSuppressed();
+        const subscription = config.get('subscription') || { plan: null, status: null, expiresAt: null };
+        const iosSandbox = isIOSEnvironment();
+        const platformSupport = iosSandbox
+            ? 'experimental-mobile-terminal-sandbox'
+            : process.platform === 'darwin'
+                ? 'supported-macos-desktop'
+                : process.platform === 'win32' || process.platform === 'linux'
+                    ? 'supported-desktop'
+                    : 'unsupported';
+        const nodeMatch = process.versions.node.match(/^(\d+)\.(\d+)/);
+        const nodeCompatible = Boolean(nodeMatch && (Number(nodeMatch[1]) > 20
+            || (Number(nodeMatch[1]) === 20 && Number(nodeMatch[2]) >= 19)));
+        const runtimeRequire = createRequire(import.meta.url);
+        const requiredRuntimePackages = ['axios', 'commander', 'inquirer', 'ws'];
+        const missingRuntimePackages = requiredRuntimePackages.filter((name) => {
+            try {
+                runtimeRequire.resolve(name);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        });
+        const sessionsDir = path.join(os.homedir(), '.vigthoria', 'sessions');
+        let sessionStorageWritable = false;
+        let latestCheckpoint = null;
+        try {
+            fs.mkdirSync(sessionsDir, { recursive: true, mode: 0o700 });
+            const probePath = path.join(sessionsDir, `.doctor-${process.pid}-${Date.now()}.tmp`);
+            fs.writeFileSync(probePath, '{}', { encoding: 'utf8', mode: 0o600 });
+            fs.unlinkSync(probePath);
+            sessionStorageWritable = true;
+            const latestSessionFile = fs.readdirSync(sessionsDir)
+                .filter((name) => name.endsWith('.json') && name !== 'index.json')
+                .map((name) => ({ name, mtime: fs.statSync(path.join(sessionsDir, name)).mtimeMs }))
+                .sort((left, right) => right.mtime - left.mtime)[0]?.name;
+            if (latestSessionFile) {
+                const document = JSON.parse(fs.readFileSync(path.join(sessionsDir, latestSessionFile), 'utf8'));
+                const persisted = document?.data && typeof document.data === 'object' ? document.data : document;
+                const checkpoint = persisted?.activeAgentRun;
+                if (checkpoint && typeof checkpoint === 'object') {
+                    latestCheckpoint = {
+                        executionId: checkpoint.executionId || null,
+                        status: checkpoint.status || null,
+                        updatedAt: checkpoint.updatedAt || null,
+                        resumable: ['submitted', 'running', 'failed'].includes(String(checkpoint.status || '')),
+                    };
+                }
+            }
+        }
+        catch {
+            sessionStorageWritable = false;
+        }
+        const envToken = String(process.env.VIGTHORIA_AUTH_TOKEN || process.env.VIGTHORIA_TOKEN || '').trim();
+        const configuredToken = envToken || String(config.get('authToken') || '').trim();
+        const tokenSegments = configuredToken ? configuredToken.split('.').length : 0;
+        const report = {
+            cliVersion: version,
+            nodeVersion: process.version,
+            nodeCompatible,
+            runtimeDependencies: missingRuntimePackages.length === 0 ? 'complete' : `missing: ${missingRuntimePackages.join(', ')}`,
+            platform: `${process.platform} ${process.arch}`,
+            clientOs: resolveClientOsSlug(),
+            platformSupport,
+            platformLimitations: iosSandbox
+                ? 'Not a native iOS app. Requires an iSH-like Linux terminal with Node.js >=20.19, npm and filesystem access; Workbench and device tooling are unavailable.'
+                : null,
+            cwd: process.cwd(),
+            homeDir: os.homedir(),
+            configPath: config.getConfigPath(),
+            stateFile: getCliStateFile(),
+            apiUrl,
+            modelsApiUrl,
+            loggedIn: config.isAuthenticated(),
+            authToken: configuredToken
+                ? { present: true, source: envToken ? 'environment' : 'secure-config', structure: tokenSegments === 3 ? 'jwt' : 'opaque' }
+                : { present: false, source: null, structure: null },
+            sessionPersistence: {
+                directory: sessionsDir,
+                writable: sessionStorageWritable,
+                latestCheckpoint,
+            },
+            subscriptionPlan: subscription.plan || null,
+            subscriptionStatus: subscription.status || null,
+            offlineMode: offline,
+            updateCheckSuppressed: updateSuppressed,
+            envOverrides: {
+                VIGTHORIA_API_URL: process.env.VIGTHORIA_API_URL || null,
+                VIGTHORIA_V3_AGENT_URL: process.env.VIGTHORIA_V3_AGENT_URL || null,
+                VIGTHORIA_OFFLINE: process.env.VIGTHORIA_OFFLINE || null,
+                VIGTHORIA_TOKEN: process.env.VIGTHORIA_TOKEN ? '<set>' : null,
+                HYPERLOOP_SERVICE_KEY: process.env.HYPERLOOP_SERVICE_KEY ? '<set>' : null,
+                V3_SERVICE_KEY: process.env.V3_SERVICE_KEY ? '<set>' : null,
+            },
+        };
+        if (options.checkApi && !offline) {
+            const api = createAPIClient(config, logger);
+            if (configuredToken) {
+                try {
+                    const tokenCheck = await api.validateToken({ allowNetworkFailOpen: false, enforceTokenShape: true });
+                    report.authValidation = tokenCheck.valid ? 'authenticated' : `failed (${tokenCheck.error || 'invalid token'})`;
+                }
+                catch (error) {
+                    report.authValidation = `unreachable (${sanitizeUserFacingErrorText(error.message)})`;
+                }
+            }
+            else {
+                report.authValidation = 'not checked (login required)';
+            }
+            try {
+                const probe = await axios.get(`${apiUrl}/api/health`, { timeout: 12000, validateStatus: () => true });
+                report.apiHealth = probe.status >= 200 && probe.status < 400 ? 'online' : `status ${probe.status}`;
+            }
+            catch (error) {
+                report.apiHealth = `unreachable (${error.message})`;
+            }
+            try {
+                const probe = await axios.get(`${modelsApiUrl}/health`, { timeout: 12000, validateStatus: () => true });
+                const body = typeof probe.data === 'string' ? probe.data : JSON.stringify(probe.data || {});
+                report.modelsApiHealth = probe.status >= 200 && probe.status < 400
+                    ? 'online'
+                    : probe.status === 503 && /pre-release validation|closed/i.test(body)
+                        ? 'pre-release-closed (Agent mode uses the Coder gateway)'
+                        : `status ${probe.status}`;
+            }
+            catch (error) {
+                report.modelsApiHealth = `unreachable (${error.message})`;
+            }
+            if (configuredToken) {
+                try {
+                    const capabilities = await api.getCapabilityTruthStatus({ workspacePath: process.cwd() });
+                    report.agentInfrastructure = {
+                        overall: capabilities.overallOk ? 'online' : 'degraded',
+                        v3Agent: capabilities.v3Agent.ok ? 'online' : capabilities.v3Agent.error || 'offline',
+                        hyperLoop: capabilities.hyperLoop.ok ? 'online' : capabilities.hyperLoop.error || 'offline',
+                        repoMemory: capabilities.repoMemory.ok ? 'online' : capabilities.repoMemory.error || 'offline',
+                    };
+                }
+                catch (error) {
+                    report.agentInfrastructure = `unreachable (${sanitizeUserFacingErrorText(error.message)})`;
+                }
+            }
+        }
+        const printHumanReport = () => {
+            console.log(chalk.bold('Vigthoria CLI diagnostics'));
+            for (const [key, value] of Object.entries(report)) {
+                if (value && typeof value === 'object') {
+                    console.log(chalk.gray(`- ${key}:`));
+                    for (const [subKey, subVal] of Object.entries(value)) {
+                        console.log(chalk.gray(`    - ${subKey}: ${subVal ?? '(none)'}`));
+                    }
+                }
+                else {
+                    console.log(chalk.gray(`- ${key}: ${value ?? '(none)'}`));
+                }
+            }
+            if (!options.checkApi) {
+                console.log(chalk.gray('\nTip: pass --check-api to verify API reachability.'));
+            }
+        };
+        const requiredLocalChecksPassed = nodeCompatible && missingRuntimePackages.length === 0 && sessionStorageWritable;
+        const coderReachable = !options.checkApi || offline || report.apiHealth === 'online';
+        if (!requiredLocalChecksPassed || !coderReachable) {
+            if (!options.json)
+                printHumanReport();
+            throw new CliCommandError('One or more required doctor checks failed.', {
+                code: 'DOCTOR_CHECK_FAILED',
+                details: report,
+            });
+        }
+        if (options.json) {
+            console.log(formatSuccessJson('doctor', report));
+        }
+        else {
+            printHumanReport();
+        }
+    });
+}

package/dist/commands/edit.js

@@ -4,8 +4,9 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError } from '../utils/api.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
 import { FileUtils } from '../utils/files.js';
+import { CliCommandError, commandFailure } from '../utils/command-contract.js';
 export class EditCommand {
     config;
     logger;
@@ -14,26 +15,23 @@ export class EditCommand {
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
-        this.api = new APIClient(config, logger);
+        this.api = createAPIClient(config, logger);
         this.fileUtils = new FileUtils(process.cwd(), config.get('project').ignorePatterns);
     }
     async run(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         this.logger.section(`Editing: ${file.relativePath}`);
         console.log(chalk.gray(`Language: ${file.language} | Lines: ${file.lines}`));
@@ -43,13 +41,11 @@ export class EditCommand {
         if (!instruction) {
             // --apply requires --instruction to avoid hanging on non-interactive terminals
             if (options.apply) {
-                this.logger.error('The --apply flag requires --instruction. Example: vigthoria edit file.ts --apply --instruction "fix the bug"');
-                return;
+                throw new CliCommandError('The --apply flag requires --instruction. Example: vigthoria edit file.ts --apply --instruction "fix the bug"', { code: 'INVALID_OPTION_COMBINATION', category: 'usage' });
             }
             // Non-TTY stdin cannot prompt interactively
             if (!process.stdin.isTTY) {
-                this.logger.error('No --instruction provided and stdin is not interactive. Use: vigthoria edit file.ts --instruction "..."');
-                return;
+                throw new CliCommandError('No --instruction provided and stdin is not interactive. Use: vigthoria edit file.ts --instruction "..."', { code: 'INSTRUCTION_REQUIRED', category: 'usage' });
             }
             const answer = await inquirer.prompt([
                 {
@@ -100,15 +96,14 @@ Return the complete modified file content:`,
             // Extract code from response
             let modifiedCode = this.extractCode(response.message, file.language);
             if (!modifiedCode) {
-                this.logger.error('Failed to generate valid code changes');
-                return;
+                throw new CliCommandError('Failed to generate valid code changes', { code: 'EDIT_RESPONSE_INVALID' });
             }
             // Always deduplicate — extractCode only dedupes on the no-fence
             // fallback path, so fenced responses (the common case) need this.
             modifiedCode = this.deduplicateCode(modifiedCode);
             // Show diff and apply
             if (options.apply) {
-                await this.applyFix(file.path, file.content, modifiedCode);
+                await this.applyFix(file.path, modifiedCode);
             }
             else {
                 await this.showDiffAndConfirm(file.path, file.content, modifiedCode);
@@ -116,27 +111,23 @@ Return the complete modified file content:`,
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'EDIT_FAILED' });
         }
     }
     async fix(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         this.logger.section(`Fixing: ${file.relativePath}`);
         console.log(chalk.gray(`Fix type: ${options.type} | Language: ${file.language}`));
@@ -159,7 +150,7 @@ Return the complete modified file content:`,
                     console.log(chalk.yellow('1. Operator/character-level fix detected'));
                     console.log();
                     if (options.apply) {
-                        await this.applyFix(file.path, file.content, result.fixed);
+                        await this.applyFix(file.path, result.fixed);
                     }
                     else {
                         await this.showDiffAndConfirm(file.path, file.content, result.fixed);
@@ -180,7 +171,7 @@ Return the complete modified file content:`,
             });
             // Apply or confirm
             if (options.apply) {
-                await this.applyFix(file.path, file.content, result.fixed);
+                await this.applyFix(file.path, result.fixed);
             }
             else {
                 await this.showDiffAndConfirm(file.path, file.content, result.fixed);
@@ -188,8 +179,7 @@ Return the complete modified file content:`,
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'FIX_FAILED' });
         }
     }
     extractCode(response, language) {
@@ -359,10 +349,9 @@ Return the complete modified file content:`,
         });
         console.log();
         // Confirm
-        const showDiffs = this.config.get('preferences').showDiffs;
         const autoApply = this.config.get('preferences').autoApplyFixes;
         if (autoApply) {
-            await this.applyFix(filePath, original, modified);
+            await this.applyFix(filePath, modified);
             return;
         }
         // Non-TTY: show the diff but don't try to prompt — re-run with --apply
@@ -384,7 +373,7 @@ Return the complete modified file content:`,
         ]);
         switch (action) {
             case 'apply':
-                await this.applyFix(filePath, original, modified);
+                await this.applyFix(filePath, modified);
                 break;
             case 'view':
                 this.showFullDiff(original, modified);
@@ -397,7 +386,7 @@ Return the complete modified file content:`,
                     },
                 ]);
                 if (confirm) {
-                    await this.applyFix(filePath, original, modified);
+                    await this.applyFix(filePath, modified);
                 }
                 break;
             case 'discard':
@@ -463,7 +452,7 @@ Return the complete modified file content:`,
         console.log(chalk.gray('─'.repeat(60)));
         console.log();
     }
-    async applyFix(filePath, original, modified) {
+    async applyFix(filePath, modified) {
         // Create backup
         const backup = this.fileUtils.backupFile(filePath);
         if (backup) {
@@ -474,7 +463,7 @@ Return the complete modified file content:`,
             this.logger.success(`Changes applied to ${filePath}`);
         }
         else {
-            this.logger.error('Failed to write changes');
+            throw new CliCommandError(`Failed to write changes to ${filePath}`, { code: 'FILE_WRITE_FAILED' });
         }
     }
 }

package/dist/commands/explain.js

@@ -5,8 +5,9 @@ import chalk from 'chalk';
 import { Marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError } from '../utils/api.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
 import { FileUtils } from '../utils/files.js';
+import { CliCommandError, commandFailure } from '../utils/command-contract.js';
 export class ExplainCommand {
     config;
     logger;
@@ -16,7 +17,7 @@ export class ExplainCommand {
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
-        this.api = new APIClient(config, logger);
+        this.api = createAPIClient(config, logger);
         this.fileUtils = new FileUtils(process.cwd(), config.get('project').ignorePatterns);
         this.marked = new Marked();
         this.marked.use(markedTerminal({
@@ -29,20 +30,17 @@ export class ExplainCommand {
     async run(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         // Get code to explain
         let codeToExplain = file.content;
@@ -80,8 +78,7 @@ export class ExplainCommand {
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'EXPLAIN_FAILED' });
         }
     }
     /**

package/dist/commands/fork.d.ts

@@ -7,8 +7,7 @@ interface ForkOptions {
 }
 export declare class ForkCommand {
     private config;
-    private logger;
-    constructor(config: Config, logger: Logger);
+    constructor(config: Config, _logger: Logger);
     private getHeaders;
     private getBaseUrl;
     private resolveWorkspaceRoot;