@axhub/genie 0.1.8 → 0.2.0

package/server/cli.js

@@ -16,11 +16,18 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import { WebSocket } from 'ws';
+import {
+    DEFAULT_WORKING_DIRECTORY_ENV,
+    getConfiguredDefaultProjectPath,
+} from './utils/defaultWorkingDirectory.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const DEFAULT_EDITOR_TIMEOUT_MS = 15000;
 
 // ANSI color codes for terminal output
 const colors = {
@@ -72,10 +79,10 @@ function loadEnvFile() {
     }
 }
 
-// Get the database path (same logic as db.js)
-function getDatabasePath() {
+// Get the data file path (same logic as db.js)
+function getDataFilePath() {
     loadEnvFile();
-    return process.env.DATABASE_PATH || path.join(__dirname, 'database', 'auth.db');
+    return process.env.DATA_FILE_PATH || path.join(__dirname, 'database', 'state.json');
 }
 
 // Get the installation directory
@@ -95,6 +102,69 @@ function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+function getOpenCommand(url) {
+    if (!url) {
+        return null;
+    }
+
+    if (process.platform === 'darwin') {
+        return {
+            command: 'open',
+            args: [url],
+        };
+    }
+
+    if (process.platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'start', '', url],
+        };
+    }
+
+    return {
+        command: 'xdg-open',
+        args: [url],
+    };
+}
+
+function openBrowser(url) {
+    const openCommand = getOpenCommand(url);
+    if (!openCommand) {
+        return false;
+    }
+
+    try {
+        const child = spawn(openCommand.command, openCommand.args, {
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.unref();
+        return true;
+    } catch (error) {
+        console.warn(`${c.warn('[WARN]')} Failed to open browser automatically: ${error.message}`);
+        return false;
+    }
+}
+
+async function waitForRuntimeStatus(pid, timeoutMs = 10000) {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        const runtimeStatus = getRuntimeStatus();
+        if (
+            runtimeStatus.running &&
+            Number(runtimeStatus?.data?.pid) === pid &&
+            runtimeStatus?.data?.endpoint?.frontendUrl
+        ) {
+            return runtimeStatus.data;
+        }
+
+        await sleep(200);
+    }
+
+    return null;
+}
+
 function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0) {
         return false;
@@ -137,6 +207,18 @@ function getRuntimeStatus() {
     }
 }
 
+function resolveConfiguredDefaultProjectPathFromStatus(runtimeStatus) {
+    const runtimeConfiguredPath = typeof runtimeStatus?.data?.defaultProjectPath === 'string'
+        ? runtimeStatus.data.defaultProjectPath.trim()
+        : '';
+
+    if (runtimeConfiguredPath) {
+        return runtimeConfiguredPath;
+    }
+
+    return getConfiguredDefaultProjectPath() || null;
+}
+
 async function stopServer() {
     const runtimeStatus = getRuntimeStatus();
 
@@ -214,6 +296,337 @@ function buildEndpointFromEnv(port) {
     };
 }
 
+function discoverApiBaseUrl() {
+    const runtimeStatus = getRuntimeStatus();
+    const runtimePort = runtimeStatus?.data?.port;
+    const configuredPort = process.env.PORT || '32123';
+    const displayPort = runtimeStatus.running && runtimePort ? runtimePort : configuredPort;
+    const envEndpoint = buildEndpointFromEnv(displayPort);
+    const runtimeEndpoint = runtimeStatus?.data?.endpoint || {};
+    return String(runtimeEndpoint.apiBaseUrl || envEndpoint.apiBaseUrl || '').trim();
+}
+
+function normalizeApiBaseUrl(value) {
+    return String(value || '').trim().replace(/\/+$/, '');
+}
+
+function deriveExternalAgentWebSocketUrl(apiBaseUrl, apiKey) {
+    const normalizedApiBaseUrl = normalizeApiBaseUrl(apiBaseUrl);
+    if (!normalizedApiBaseUrl) {
+        throw new Error('api base URL is required');
+    }
+
+    const url = new URL(normalizedApiBaseUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/agent/ws`;
+    url.search = '';
+    if (apiKey) {
+        url.searchParams.set('apiKey', apiKey);
+    }
+    return url.toString();
+}
+
+function createRequestId(prefix = 'editor') {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `${prefix}_${crypto.randomUUID()}`;
+    }
+    return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function parseCommaSeparatedList(value) {
+    return String(value || '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+
+function parsePositiveInteger(value, label) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const next = Number(value);
+    if (!Number.isInteger(next) || next <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+    return next;
+}
+
+function buildEditorSuccessResponse({ requestId, channel = null, targetClientId = null, data = {} }) {
+    return {
+        ok: true,
+        requestId,
+        channel,
+        targetClientId,
+        data,
+    };
+}
+
+function buildEditorErrorResponse({ requestId, channel = null, targetClientId = null, code, message }) {
+    return {
+        ok: false,
+        requestId,
+        channel,
+        targetClientId,
+        error: {
+            code,
+            message,
+        },
+    };
+}
+
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+
+async function sendEditorWebSocketRequest({ apiBaseUrl, apiKey, message, timeoutMs }) {
+    const wsUrl = deriveExternalAgentWebSocketUrl(apiBaseUrl, apiKey);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const socket = new WebSocket(wsUrl);
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+                socket.close();
+            }
+        };
+        const finish = (callback) => (value) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            callback(value);
+        };
+        const timer = setTimeout(() => {
+            finish(reject)(new Error(`Timed out waiting for response to ${message.type}`));
+        }, timeoutMs);
+
+        socket.on('open', () => {
+            socket.send(JSON.stringify(message));
+        });
+
+        socket.on('message', (rawMessage) => {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(String(rawMessage));
+            } catch {
+                return;
+            }
+            if (parsed?.requestId !== message.requestId) {
+                return;
+            }
+
+            if (parsed?.type === 'integration.error') {
+                const payload = parsed.payload || {};
+                const error = new Error(payload.message || 'Integration request failed');
+                error.code = payload.code || 'INTEGRATION_ERROR';
+                finish(reject)(error);
+                return;
+            }
+
+            if (parsed?.type === 'agent.error') {
+                const error = new Error(parsed.error || 'Agent request failed');
+                error.code = 'AGENT_ERROR';
+                finish(reject)(error);
+                return;
+            }
+
+            if (parsed?.type === 'integration.ack') {
+                return;
+            }
+
+            finish(resolve)(parsed);
+        });
+
+        socket.on('error', (error) => {
+            const nextError = new Error(`WebSocket request failed: ${error.message}`);
+            nextError.code = 'CONNECTION_ERROR';
+            finish(reject)(nextError);
+        });
+
+        socket.on('close', () => {
+            if (!settled) {
+                const error = new Error('WebSocket closed before a response was received');
+                error.code = 'CONNECTION_CLOSED';
+                finish(reject)(error);
+            }
+        });
+    });
+}
+
+function resolveOutputDirPath(outputDir) {
+    return path.resolve(outputDir || process.cwd());
+}
+
+function requireOption(options, key, message) {
+    const value = typeof options[key] === 'string' ? options[key].trim() : options[key];
+    if (!value) {
+        throw new Error(message);
+    }
+    return value;
+}
+
+function buildTaskRef(options) {
+    const requestId = typeof options.taskRequestId === 'string' ? options.taskRequestId.trim() : '';
+    const sessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
+    const provider = typeof options.provider === 'string' ? options.provider.trim() : '';
+    if (!requestId && !sessionId && !provider) {
+        return null;
+    }
+    return {
+        ...(requestId ? { requestId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(provider ? { provider } : {}),
+    };
+}
+
+function buildEditorRequest(positionals, options) {
+    const scope = {
+        requestId: createRequestId('editor'),
+        channel: typeof options.channel === 'string' ? options.channel.trim() : null,
+        targetClientId: typeof options.targetClientId === 'string' ? options.targetClientId.trim() : null,
+    };
+    const commandPath = positionals.join(' ');
+
+    if (commandPath === 'editor clients list') {
+        return {
+            ...scope,
+            message: {
+                type: 'integration.editor.clients.list',
+                requestId: scope.requestId,
+                payload: {
+                    ...(scope.channel ? { channel: scope.channel } : {}),
+                    ...(options.clientId ? { clientId: String(options.clientId).trim() } : {}),
+                },
+            },
+        };
+    }
+
+    const channel = requireOption(options, 'channel', '--channel is required for editor commands');
+    const targetClientId = requireOption(options, 'targetClientId', '--target-client-id is required for editor commands');
+
+    if (commandPath === 'editor snapshot') {
+        return {
+            requestId: scope.requestId,
+            channel,
+            targetClientId,
+            message: {
+                type: 'integration.editor.snapshot.get',
+                requestId: scope.requestId,
+                payload: { channel, targetClientId },
+            },
+        };
+    }
+
+    if (commandPath === 'editor nodes list') {
+        return {
+            requestId: scope.requestId,
+            channel,
+            targetClientId,
+            message: {
+                type: 'integration.editor.nodes.list',
+                requestId: scope.requestId,
+                payload: {
+                    channel,
+                    targetClientId,
+                    ...(options.status ? { status: parseCommaSeparatedList(options.status) } : {}),
+                    ...(options.elementKey ? { elementKey: String(options.elementKey).trim() } : {}),
+                    ...(options.limit ? { limit: parsePositiveInteger(options.limit, '--limit') } : {}),
+                },
+            },
+        };
+    }
+
+    if (commandPath === 'editor node screenshot') {
+        return {
+            requestId: scope.requestId,
+            channel,
+            targetClientId,
+            message: {
+                type: 'integration.editor.node.screenshot.get',
+                requestId: scope.requestId,
+                payload: {
+                    channel,
+                    targetClientId,
+                    elementKey: requireOption(options, 'elementKey', '--element-key is required'),
+                    downloadPath: resolveOutputDirPath(options.outputDir),
+                },
+            },
+        };
+    }
+
+    if (commandPath === 'editor context-images export') {
+        return {
+            requestId: scope.requestId,
+            channel,
+            targetClientId,
+            message: {
+                type: 'integration.editor.context-images.get',
+                requestId: scope.requestId,
+                payload: {
+                    channel,
+                    targetClientId,
+                    downloadPath: resolveOutputDirPath(options.outputDir),
+                },
+            },
+        };
+    }
+
+    if (commandPath === 'editor editing set') {
+        return {
+            requestId: scope.requestId,
+            channel,
+            targetClientId,
+            message: {
+                type: 'integration.editor.editing.set',
+                requestId: scope.requestId,
+                payload: {
+                    channel,
+                    targetClientId,
+                    elementKey: requireOption(options, 'elementKey', '--element-key is required'),
+                    state: requireOption(options, 'state', '--state is required'),
+                    ...(buildTaskRef(options) ? { taskRef: buildTaskRef(options) } : {}),
+                },
+            },
+        };
+    }
+
+    throw new Error(`Unknown editor command: ${commandPath}`);
+}
+
+async function runEditorCommand(positionals, options) {
+    const apiBaseUrl = normalizeApiBaseUrl(options.apiBase || discoverApiBaseUrl());
+    if (!apiBaseUrl) {
+        throw new Error('Unable to discover API base URL. Please pass --api-base explicitly.');
+    }
+
+    const editorRequest = buildEditorRequest(positionals, options);
+    const timeoutMs = parsePositiveInteger(options.timeoutMs || DEFAULT_EDITOR_TIMEOUT_MS, '--timeout-ms') || DEFAULT_EDITOR_TIMEOUT_MS;
+
+    try {
+        const response = await sendEditorWebSocketRequest({
+            apiBaseUrl,
+            apiKey: options.apiKey,
+            message: editorRequest.message,
+            timeoutMs,
+        });
+        printJson(buildEditorSuccessResponse({
+            requestId: editorRequest.requestId,
+            channel: editorRequest.channel,
+            targetClientId: editorRequest.targetClientId,
+            data: response?.payload || {},
+        }));
+    } catch (error) {
+        printJson(buildEditorErrorResponse({
+            requestId: editorRequest.requestId,
+            channel: editorRequest.channel,
+            targetClientId: editorRequest.targetClientId,
+            code: error.code || 'EDITOR_REQUEST_FAILED',
+            message: error.message,
+        }));
+        process.exit(1);
+    }
+}
+
 // Show status command
 function showStatus(options = {}) {
     const runtimeStatus = getRuntimeStatus();
@@ -227,6 +640,7 @@ function showStatus(options = {}) {
         frontendUrl: runtimeEndpoint.frontendUrl || envEndpoint.frontendUrl,
         apiBaseUrl: runtimeEndpoint.apiBaseUrl || envEndpoint.apiBaseUrl,
     };
+    const defaultProjectPath = resolveConfiguredDefaultProjectPathFromStatus(runtimeStatus);
 
     const statusPayload = {
         running: !!runtimeStatus.running,
@@ -234,6 +648,7 @@ function showStatus(options = {}) {
         port: Number(displayPort),
         startedAt: runtimeStatus?.data?.startedAt || null,
         statusFile: runtimeStatus.statusPath,
+        defaultProjectPath,
         endpoint,
     };
 
@@ -253,15 +668,15 @@ function showStatus(options = {}) {
     console.log(`\n${c.info('[INFO]')} Installation Directory:`);
     console.log(`       ${c.dim(installDir)}`);
 
-    // Database location
-    const dbPath = getDatabasePath();
-    const dbExists = fs.existsSync(dbPath);
-    console.log(`\n${c.info('[INFO]')} Database Location:`);
-    console.log(`       ${c.dim(dbPath)}`);
-    console.log(`       Status: ${dbExists ? c.ok('[OK] Exists') : c.warn('[WARN] Not created yet (will be created on first run)')}`);
+    // Data file location
+    const dataFilePath = getDataFilePath();
+    const dataFileExists = fs.existsSync(dataFilePath);
+    console.log(`\n${c.info('[INFO]')} Data File Location:`);
+    console.log(`       ${c.dim(dataFilePath)}`);
+    console.log(`       Status: ${dataFileExists ? c.ok('[OK] Exists') : c.warn('[WARN] Not created yet (will be created on first run)')}`);
 
-    if (dbExists) {
-        const stats = fs.statSync(dbPath);
+    if (dataFileExists) {
+        const stats = fs.statSync(dataFilePath);
         console.log(`       Size: ${c.dim((stats.size / 1024).toFixed(2) + ' KB')}`);
         console.log(`       Modified: ${c.dim(stats.mtime.toLocaleString())}`);
     }
@@ -288,6 +703,7 @@ function showStatus(options = {}) {
         console.log(`       Started: ${c.dim(runtimeStartedAt ? new Date(runtimeStartedAt).toLocaleString() : '(unknown)')}`);
     }
 
+    console.log(`       Default Project Path: ${c.dim(defaultProjectPath || '(not configured)')}`);
     console.log(`       Environment: ${c.dim(endpoint.environment || '(not configured)')}`);
     console.log(`       Frontend URL: ${c.dim(endpoint.frontendUrl || '(not configured)')}`);
     console.log(`       API Base URL: ${c.dim(endpoint.apiBaseUrl || '(not configured)')}`);
@@ -295,7 +711,8 @@ function showStatus(options = {}) {
     // Environment variables
     console.log(`\n${c.info('[INFO]')} Configuration:`);
     console.log(`       PORT: ${c.bright(configuredPort)} ${c.dim(process.env.PORT ? '' : '(default)')}`);
-    console.log(`       DATABASE_PATH: ${c.dim(process.env.DATABASE_PATH || '(using default location)')}`);
+    console.log(`       DATA_FILE_PATH: ${c.dim(process.env.DATA_FILE_PATH || '(using default location)')}`);
+    console.log(`       ${DEFAULT_WORKING_DIRECTORY_ENV}: ${c.dim(getConfiguredDefaultProjectPath() || '(using process working directory)')}`);
     console.log(`       CLAUDE_CLI_PATH: ${c.dim(process.env.CLAUDE_CLI_PATH || 'claude (default)')}`);
     console.log(`       CONTEXT_WINDOW: ${c.dim(process.env.CONTEXT_WINDOW || '160000 (default)')}`);
 
@@ -316,7 +733,7 @@ function showStatus(options = {}) {
     console.log('\n' + c.dim('═'.repeat(60)));
     console.log(`\n${c.tip('[TIP]')} Hints:`);
     console.log(`      ${c.dim('>')} Use ${c.bright('axhub-genie --port 8080')} to run on a custom port`);
-    console.log(`      ${c.dim('>')} Use ${c.bright('axhub-genie --database-path /path/to/db')} for custom database`);
+    console.log(`      ${c.dim('>')} Use ${c.bright('axhub-genie --data-file-path /path/to/state.json')} for custom data file`);
     console.log(`      ${c.dim('>')} Run ${c.bright('axhub-genie help')} for all options`);
     console.log(`      ${c.dim('>')} Access the UI at http://localhost:${displayPort}\n`);
 }
@@ -335,32 +752,57 @@ Commands:
   start          Start the Axhub Genie server (default)
   stop           Stop the running Axhub Genie server
   status         Show configuration and data locations
+  editor         Query or control a connected web editor frontend
   update         Update to the latest version
   help           Show this help information
   version        Show version information
 
 Options:
   -p, --port <port>           Set server port (default: 32123)
-  --database-path <path>      Set custom database location
-  --json                      Output status as JSON (for scripts)
+  --data-file-path <path>      Set custom data file location
+  --cwd <path>                 Set default working directory for agent/API requests
+  --workdir <path>             Alias for --cwd
+  --default-project-path <path> Alias for --cwd
+  --no-open                   Do not open the homepage automatically after start
+  --json                      Output JSON (status or editor commands)
+  --api-base <url>            Override API base URL for editor commands
+  --api-key <key>             API key for /api/agent/ws editor commands
+  --channel <name>            Integration channel for editor commands
+  --target-client-id <id>     Target frontend client ID for editor commands
+  --client-id <id>            Optional client filter for editor clients list
+  --element-key <key>         Target element key for editor node commands
+  --status <values>           Comma-separated status filters for editor nodes list
+  --state <editing|idle>      Target editing state for editor editing set
+  --limit <n>                 Maximum number of nodes returned by editor nodes list
+  --output-dir <path>         Download directory for screenshot/image export commands
+  --timeout-ms <ms>           Timeout for editor WebSocket requests (default: ${DEFAULT_EDITOR_TIMEOUT_MS})
   -h, --help                  Show this help information
   -v, --version               Show version information
 
 Examples:
   $ axhub-genie                        # Start with defaults
   $ axhub-genie --port 8080            # Start on port 8080
+  $ axhub-genie --cwd /path/to/repo    # Start with a default working directory
   $ axhub-genie -p 3000                # Short form for port
   $ axhub-genie start --port 4000      # Explicit start command
   $ axhub-genie stop                   # Stop running server
   $ axhub-genie status                 # Show configuration
   $ axhub-genie status --json          # Get machine-readable status
+  $ axhub-genie editor clients list --channel project-a
+  $ axhub-genie editor snapshot --channel project-a --target-client-id figma-123
+  $ axhub-genie editor nodes list --channel project-a --target-client-id figma-123 --status pending-dispatch,dirty
+  $ axhub-genie editor node screenshot --channel project-a --target-client-id figma-123 --element-key hero-card --output-dir .
+  $ axhub-genie editor context-images export --channel project-a --target-client-id figma-123
+  $ axhub-genie editor editing set --channel project-a --target-client-id figma-123 --element-key hero-card --state editing
 
 Environment Variables:
   PORT                Set server port (default: 32123)
-  DATABASE_PATH       Set custom database location
+  DATA_FILE_PATH       Set custom data file location
+  ${DEFAULT_WORKING_DIRECTORY_ENV}  Set default working directory for agent/API requests
   CLAUDE_CLI_PATH     Set custom Claude CLI path
   CONTEXT_WINDOW      Set context window size (default: 160000)
   AXHUB_GENIE_STATUS_PATH  Set runtime status file path
+  AXHUB_GENIE_NO_OPEN  Set to true to disable auto-opening the homepage
 
 Documentation:
   ${packageJson.homepage || 'https://github.com/siteboon/claudecodeui'}
@@ -440,11 +882,30 @@ async function startServer() {
 
     // Import and run the server
     await import('./index.js');
+
+    if (process.env.AXHUB_GENIE_NO_OPEN === 'true') {
+        return;
+    }
+
+    const runtimeData = await waitForRuntimeStatus(process.pid);
+    if (!runtimeData) {
+        console.log(`${c.warn('[WARN]')} Server started, but homepage could not be opened automatically because runtime status was not ready in time.`);
+        return;
+    }
+
+    const frontendUrl = runtimeData?.endpoint?.frontendUrl || runtimeData?.url;
+    const opened = openBrowser(frontendUrl);
+
+    if (opened) {
+        console.log(`${c.info('[INFO]')} Opened homepage: ${c.dim(frontendUrl)}`);
+    } else {
+        console.log(`${c.tip('[TIP]')} Open the homepage manually: ${c.bright(frontendUrl)}`);
+    }
 }
 
 // Parse CLI arguments
 function parseArgs(args) {
-    const parsed = { command: 'start', options: {} };
+    const parsed = { positionals: [], options: {} };
 
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -453,18 +914,84 @@ function parseArgs(args) {
             parsed.options.port = args[++i];
         } else if (arg.startsWith('--port=')) {
             parsed.options.port = arg.split('=')[1];
-        } else if (arg === '--database-path') {
-            parsed.options.databasePath = args[++i];
-        } else if (arg.startsWith('--database-path=')) {
-            parsed.options.databasePath = arg.split('=')[1];
+        } else if (arg === '--cwd' || arg === '--workdir' || arg === '--default-project-path') {
+            parsed.options.defaultProjectPath = args[++i];
+        } else if (arg.startsWith('--cwd=')) {
+            parsed.options.defaultProjectPath = arg.split('=')[1];
+        } else if (arg.startsWith('--workdir=')) {
+            parsed.options.defaultProjectPath = arg.split('=')[1];
+        } else if (arg.startsWith('--default-project-path=')) {
+            parsed.options.defaultProjectPath = arg.split('=')[1];
+        } else if (arg === '--data-file-path') {
+            parsed.options.dataFilePath = args[++i];
+        } else if (arg.startsWith('--data-file-path=')) {
+            parsed.options.dataFilePath = arg.split('=')[1];
+        } else if (arg === '--api-base') {
+            parsed.options.apiBase = args[++i];
+        } else if (arg.startsWith('--api-base=')) {
+            parsed.options.apiBase = arg.split('=')[1];
+        } else if (arg === '--api-key') {
+            parsed.options.apiKey = args[++i];
+        } else if (arg.startsWith('--api-key=')) {
+            parsed.options.apiKey = arg.split('=')[1];
+        } else if (arg === '--channel') {
+            parsed.options.channel = args[++i];
+        } else if (arg.startsWith('--channel=')) {
+            parsed.options.channel = arg.split('=')[1];
+        } else if (arg === '--target-client-id') {
+            parsed.options.targetClientId = args[++i];
+        } else if (arg.startsWith('--target-client-id=')) {
+            parsed.options.targetClientId = arg.split('=')[1];
+        } else if (arg === '--client-id') {
+            parsed.options.clientId = args[++i];
+        } else if (arg.startsWith('--client-id=')) {
+            parsed.options.clientId = arg.split('=')[1];
+        } else if (arg === '--element-key') {
+            parsed.options.elementKey = args[++i];
+        } else if (arg.startsWith('--element-key=')) {
+            parsed.options.elementKey = arg.split('=')[1];
+        } else if (arg === '--status') {
+            parsed.options.status = args[++i];
+        } else if (arg.startsWith('--status=')) {
+            parsed.options.status = arg.split('=')[1];
+        } else if (arg === '--state') {
+            parsed.options.state = args[++i];
+        } else if (arg.startsWith('--state=')) {
+            parsed.options.state = arg.split('=')[1];
+        } else if (arg === '--limit') {
+            parsed.options.limit = args[++i];
+        } else if (arg.startsWith('--limit=')) {
+            parsed.options.limit = arg.split('=')[1];
+        } else if (arg === '--output-dir') {
+            parsed.options.outputDir = args[++i];
+        } else if (arg.startsWith('--output-dir=')) {
+            parsed.options.outputDir = arg.split('=')[1];
+        } else if (arg === '--timeout-ms') {
+            parsed.options.timeoutMs = args[++i];
+        } else if (arg.startsWith('--timeout-ms=')) {
+            parsed.options.timeoutMs = arg.split('=')[1];
+        } else if (arg === '--session-id') {
+            parsed.options.sessionId = args[++i];
+        } else if (arg.startsWith('--session-id=')) {
+            parsed.options.sessionId = arg.split('=')[1];
+        } else if (arg === '--provider') {
+            parsed.options.provider = args[++i];
+        } else if (arg.startsWith('--provider=')) {
+            parsed.options.provider = arg.split('=')[1];
+        } else if (arg === '--task-request-id') {
+            parsed.options.taskRequestId = args[++i];
+        } else if (arg.startsWith('--task-request-id=')) {
+            parsed.options.taskRequestId = arg.split('=')[1];
         } else if (arg === '--json') {
             parsed.options.json = true;
+        } else if (arg === '--no-open') {
+            parsed.options.noOpen = true;
         } else if (arg === '--help' || arg === '-h') {
-            parsed.command = 'help';
+            parsed.options.help = true;
         } else if (arg === '--version' || arg === '-v') {
-            parsed.command = 'version';
+            parsed.options.version = true;
         } else if (!arg.startsWith('-')) {
-            parsed.command = arg;
+            parsed.positionals.push(arg);
         }
     }
 
@@ -476,20 +1003,38 @@ async function main() {
     loadEnvFile();
 
     const args = process.argv.slice(2);
-    const { command, options } = parseArgs(args);
+    const { positionals, options } = parseArgs(args);
+    const command = options.help
+        ? 'help'
+        : options.version
+            ? 'version'
+            : positionals[0] || 'start';
 
     // Apply CLI options to environment variables
     if (options.port) {
         process.env.PORT = options.port;
     }
-    if (options.databasePath) {
-        process.env.DATABASE_PATH = options.databasePath;
+    if (options.dataFilePath) {
+        process.env.DATA_FILE_PATH = options.dataFilePath;
+    }
+    if (options.defaultProjectPath) {
+        process.env[DEFAULT_WORKING_DIRECTORY_ENV] = path.resolve(options.defaultProjectPath);
     }
 
     switch (command) {
         case 'start':
+            if (positionals[0] === 'editor') {
+                await runEditorCommand(positionals, options);
+                break;
+            }
+            if (options.noOpen) {
+                process.env.AXHUB_GENIE_NO_OPEN = 'true';
+            }
             await startServer();
             break;
+        case 'editor':
+            await runEditorCommand(positionals, options);
+            break;
         case 'status':
         case 'info':
             showStatus(options);
@@ -517,8 +1062,21 @@ async function main() {
     }
 }
 
-// Run the CLI
-main().catch(error => {
-    console.error('\n❌ Error:', error.message);
-    process.exit(1);
-});
+const isDirectExecution = process.argv[1] && path.resolve(process.argv[1]) === __filename;
+
+if (isDirectExecution) {
+    main().catch(error => {
+        console.error('\n❌ Error:', error.message);
+        process.exit(1);
+    });
+}
+
+export {
+    buildEditorRequest,
+    buildEditorSuccessResponse,
+    buildEditorErrorResponse,
+    deriveExternalAgentWebSocketUrl,
+    normalizeApiBaseUrl,
+    parseArgs,
+    runEditorCommand,
+};