smithue-cli 0.8.0

package/README.md

@@ -0,0 +1,146 @@
+# smithue-cli
+
+Stateless command line interface for the SmithUE Unreal Engine plugin.
+
+## For AI Agents
+
+### Quick Deploy
+- **Windows**: `npm install -g smithue-cli`
+- **macOS**: `npm install -g smithue-cli`
+- **Linux**: `npm install -g smithue-cli`
+
+*Note: The v1 plugin server is Windows-only. The CLI npm package installs on any OS, but requires a Windows machine running the UE editor.*
+
+### Prerequisites check
+Ensure Node.js 18+ is installed. Run `node -v` to check.
+
+### Verification
+Run this command to check if the CLI can find your running Unreal Engine project:
+```powershell
+smithue-cli status
+```
+
+### Fault tree (if things go wrong)
+1. **Editor not running**: Start Unreal Engine and verify the SmithUE plugin is active.
+2. **Multiple instances**: If you have two editors open, the CLI needs help. Use `smithue-cli status` to see PIDs, then pass `--pid <number>` to your command.
+3. **Stale portfile**: If the editor crashed, a `.port` file might remain in `%LOCALAPPDATA%\.smithue\`. Run `smithue-cli prune` to clean up dead files.
+4. **Connection refused**: Check if your firewall blocks local port traffic. SmithUE only listens on 127.0.0.1.
+
+## Installation
+Standard installation via npm:
+```bash
+npm install -g smithue-cli
+```
+Or run directly without installing:
+```bash
+npx smithue-cli <command>
+```
+
+## Subcommands
+
+| Command | Description |
+|---|---|
+| `exec` | Run a remote command in UE |
+| `list` | List available domains or objects |
+| `search` | Find assets or objects by string |
+| `status` | Show running UE instances and their ports |
+| `batch` | Run multiple read-only commands sequentially |
+| `upgrade` | Update the CLI to the latest version via npm |
+| `prune` | Remove stale port files from crashed instances |
+| `purge` | Remove the entire `.smithue` directory (full uninstall cleanup) |
+
+## Output Modes
+
+By default, `smithue-cli` outputs pretty-printed JSON (2-space indent).
+
+- `--terse` — Minified JSON (no whitespace). Recommended for AI agents to save tokens.
+- `--out <file>` — Write result to file; stdout is silent. Useful for large responses.
+- Combined: `smithue-cli status --terse --out result.json`
+
+## Batch Mode
+
+Run multiple read-only commands in a single call:
+
+```bash
+smithue-cli batch "status" "list"
+```
+
+Returns a JSON array: `[{command, ok, data?, error?}, ...]`
+
+Supported commands: `status`, `list`, `search`. Sequential execution only.
+
+## Upgrading
+
+```bash
+smithue-cli upgrade
+```
+
+Updates `smithue-cli` to the latest version via npm. A warning is printed to stderr if the CLI version does not match the plugin version.
+
+## AI Agent Integration
+
+Recommended flags for AI agent usage:
+
+```bash
+# Minified output saves tokens
+smithue-cli status --terse
+
+# Write large responses to file, keep context clean
+smithue-cli list --out tools.json
+
+# Multiple queries in one call
+smithue-cli batch "status" "list" --terse
+```
+
+## Examples
+List all Material assets:
+```bash
+smithue-cli list Material
+```
+
+Search for blueprints:
+```bash
+smithue-cli search blueprint
+```
+
+Execute a custom action:
+```bash
+smithue-cli exec my_action '{"key": "value"}'
+```
+
+## Security Notes
+- Binds to 127.0.0.1 only. No external network exposure.
+- Port files in `%LOCALAPPDATA%\.smithue` are ACL-restricted to the current Windows user.
+
+## Uninstall
+
+Use `purge` to fully clean up after removing SmithUE. Unlike `prune` (which removes stale port files during normal use), `purge` deletes the entire `%LOCALAPPDATA%\.smithue\` directory as the final step of uninstalling the CLI.
+
+```bash
+smithue-cli purge          # interactive: lists files and asks for confirmation
+smithue-cli purge --dry-run  # preview what would be deleted
+smithue-cli purge -y       # non-interactive full purge (CI/scripts)
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--force` | Skip liveness check; delete all files including non-portfiles |
+| `--dry-run` | Show what would be deleted without making changes |
+| `-y, --yes` | Skip the confirmation prompt (required when stdin is not a TTY) |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (including cancelled and dry-run) |
+| 1 | Non-interactive context without `-y` |
+| 2 | `LOCALAPPDATA` not set (Windows-only command) |
+| 3 | `.smithue` is a symlink or junction — refused for safety |
+
+For routine cleanup of stale portfiles without removing the directory, use `smithue-cli prune` instead.
+
+## Known Limitations
+- Version 1 is Windows-only due to portfile path conventions.
+- No persistent configuration files. Use environment variables like `SMITHUE_PORT` or `SMITHUE_PID` for overrides.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readdir, readFile, unlink } from 'fs/promises';
+import { createRequire } from 'module';
+import { join } from 'path';
+import { execCommand } from './commands/exec.js';
+import { listCommand } from './commands/list.js';
+import { searchCommand } from './commands/search.js';
+import { statusCommand } from './commands/status.js';
+import { purge } from './commands/purge.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { batchCommand } from './commands/batch.js';
+import { printResult, printError, setOutputOptions } from './output.js';
+const program = new Command();
+const require = createRequire(import.meta.url);
+const { version: cliVersion } = require('../package.json');
+program
+    .name('smithue')
+    .description('CLI for SmithUE Unreal Engine plugin')
+    .version(cliVersion)
+    .option('--pid <pid>', 'target SmithUE instance by PID', parseInt)
+    .option('--project <path>', 'target SmithUE instance by project path')
+    .option('--port <port>', 'connect directly to port (skip discovery)', parseInt)
+    .option('--terse', 'emit minified JSON output')
+    .option('--out <file>', 'write result to file instead of stdout');
+program.hook('preAction', () => {
+    const opts = program.opts();
+    setOutputOptions({ terse: opts.terse, outPath: opts.out });
+});
+// ---------------------------------------------------------------------------
+// exec
+// ---------------------------------------------------------------------------
+program
+    .command('exec <command> [params]')
+    .description('Execute a SmithUE command')
+    .action(async (command, params) => {
+    const globals = program.opts();
+    let parsedParams = {};
+    if (params) {
+        try {
+            parsedParams = JSON.parse(params);
+        }
+        catch {
+            printError(new Error(`params must be valid JSON, got: ${params}`));
+            return;
+        }
+    }
+    await execCommand(command, parsedParams, { ...globals, cliVersion });
+});
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+program
+    .command('list [domain]')
+    .description('List available tools, optionally filtered by domain')
+    .action(async (domain) => {
+    const globals = program.opts();
+    await listCommand(domain, { ...globals, cliVersion });
+});
+// ---------------------------------------------------------------------------
+// search
+// ---------------------------------------------------------------------------
+program
+    .command('search <keyword>')
+    .description('Search tools by keyword')
+    .action(async (keyword) => {
+    const globals = program.opts();
+    await searchCommand(keyword, { ...globals, cliVersion });
+});
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+program
+    .command('status')
+    .description('Get SmithUE editor status')
+    .option('--wait <seconds>', 'wait up to N seconds for editor to be ready', parseInt)
+    .action(async (cmdOpts) => {
+    const globals = program.opts();
+    await statusCommand({ ...globals, wait: cmdOpts.wait, cliVersion });
+});
+// ---------------------------------------------------------------------------
+// prune
+// ---------------------------------------------------------------------------
+program
+    .command('prune')
+    .description('Remove stale portfiles for SmithUE instances that are no longer running')
+    .action(async () => {
+    const localAppData = process.env['LOCALAPPDATA'];
+    if (!localAppData) {
+        printResult({ scanned: 0, pruned: 0, kept: 0 });
+        return;
+    }
+    const dir = join(localAppData, '.smithue');
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        printResult({ scanned: 0, pruned: 0, kept: 0 });
+        return;
+    }
+    const portFiles = entries.filter((e) => e.endsWith('.port'));
+    let scanned = 0;
+    let pruned = 0;
+    let kept = 0;
+    for (const entry of portFiles) {
+        const filePath = join(dir, entry);
+        scanned++;
+        let port;
+        try {
+            const content = await readFile(filePath, 'utf8');
+            const data = JSON.parse(content);
+            port = data.port;
+            if (!Number.isInteger(port) || port <= 0)
+                throw new Error('bad port');
+        }
+        catch {
+            // malformed portfile - treat as stale
+            try {
+                await unlink(filePath);
+            }
+            catch { /* best effort */ }
+            pruned++;
+            continue;
+        }
+        let alive = false;
+        try {
+            await fetch(`http://127.0.0.1:${port}/ready`, {
+                signal: AbortSignal.timeout(1000),
+            });
+            // any HTTP response = server is alive (including 503 during startup)
+            alive = true;
+        }
+        catch {
+            alive = false;
+        }
+        if (alive) {
+            kept++;
+        }
+        else {
+            try {
+                await unlink(filePath);
+            }
+            catch {
+                // best effort
+            }
+            pruned++;
+        }
+    }
+    printResult({ scanned, pruned, kept });
+});
+// ---------------------------------------------------------------------------
+// purge
+// ---------------------------------------------------------------------------
+program
+    .command('purge')
+    .description('Remove the .smithue directory entirely (full uninstall cleanup)')
+    .option('--force', 'skip liveness check and delete all files including unknown ones')
+    .option('--dry-run', 'show what would be deleted without modifying anything')
+    .option('-y, --yes', 'skip confirmation prompt (required for non-interactive use)')
+    .action(async (cmdOpts) => {
+    await purge({
+        force: cmdOpts.force ?? false,
+        dryRun: cmdOpts.dryRun ?? false,
+        yes: cmdOpts.yes ?? false,
+    });
+});
+// ---------------------------------------------------------------------------
+// upgrade
+// ---------------------------------------------------------------------------
+program
+    .command('upgrade')
+    .description('Update smithue-cli globally via npm')
+    .action(async () => {
+    await upgradeCommand();
+});
+// ---------------------------------------------------------------------------
+// batch
+// ---------------------------------------------------------------------------
+program
+    .command('batch [commands...]')
+    .description('Execute multiple read-only commands sequentially')
+    .action(async (commands = []) => {
+    const globals = program.opts();
+    await batchCommand(commands, globals);
+});
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+await program.parseAsync(process.argv);

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+import type { SmithUEExecuteResponse, SmithUEToolSchema } from './types.js';
+export interface SmithUEClientConfig {
+    host: string;
+    port: number;
+    timeout?: number;
+}
+export declare class SmithUEClient {
+    private host;
+    private port;
+    private timeout;
+    constructor(config: SmithUEClientConfig);
+    private get baseUrl();
+    private headers;
+    private fetchJson;
+    private postJson;
+    private getJson;
+    private normalizeRequestError;
+    execute(command: string, params?: Record<string, unknown>): Promise<SmithUEExecuteResponse>;
+    executeCommand(command: string, params?: Record<string, unknown>): Promise<SmithUEExecuteResponse>;
+    ping(): Promise<{
+        message: string;
+    }>;
+    listTools(domain?: string): Promise<SmithUEToolSchema[]>;
+    getReady(): Promise<{
+        ready: boolean;
+        version?: string;
+        pie_active?: boolean;
+    }>;
+    isConnected(): Promise<boolean>;
+    executeWithFailover(command: string, params?: Record<string, unknown>): Promise<SmithUEExecuteResponse>;
+    private mapErrorCodeToSmithUEError;
+    private startAsyncTask;
+    private isAsyncTaskComplete;
+    private isRecord;
+    private sleep;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,mBAAmB;IAMvC,OAAO,KAAK,OAAO,GAElB;IAED,OAAO,CAAC,OAAO;YAID,SAAS;YAwBT,QAAQ;YAQR,OAAO;IAOrB,OAAO,CAAC,qBAAqB;IAqBvB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAa/F,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAItG,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAKpC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAUxD,QAAQ,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAI/E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAS/B,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,sBAAsB,CAAC;IA6ClC,OAAO,CAAC,0BAA0B;YAmBpB,cAAc;IAe5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,QAAQ;YAIF,KAAK;CAGpB"}

package/dist/client.js

@@ -0,0 +1,184 @@
+import { SmithUEError } from './portfile.js';
+export class SmithUEClient {
+    host;
+    port;
+    timeout;
+    constructor(config) {
+        this.host = config.host;
+        this.port = config.port;
+        this.timeout = config.timeout ?? 30000;
+    }
+    get baseUrl() {
+        return `http://${this.host}:${this.port}`;
+    }
+    headers() {
+        return { 'Content-Type': 'application/json' };
+    }
+    async fetchJson(path, init, timeoutMs) {
+        const ms = timeoutMs ?? this.timeout;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), ms);
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                throw new Error(`SmithUE plugin returned HTTP ${response.status}. Body: ${body.slice(0, 200)}`);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async postJson(path, body, timeoutMs) {
+        return this.fetchJson(path, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        }, timeoutMs);
+    }
+    async getJson(path, timeoutMs) {
+        return this.fetchJson(path, {
+            method: 'GET',
+            headers: this.headers(),
+        }, timeoutMs);
+    }
+    normalizeRequestError(err, command) {
+        const msg = err.message ?? '';
+        if (msg.includes('ECONNREFUSED') ||
+            msg.includes('fetch failed') ||
+            msg.includes('Failed to fetch') ||
+            msg.includes('ENOTFOUND') ||
+            msg.includes('connect ECONNREFUSED')) {
+            return new Error(`SmithUE plugin unreachable at ${this.host}:${this.port}. Start UE Editor with SmithUE plugin enabled.`);
+        }
+        if (err.name === 'AbortError') {
+            return new Error(`SmithUE plugin timed out. Command: ${command} (port: ${this.port})`);
+        }
+        return err instanceof Error ? err : new Error(String(err));
+    }
+    async execute(command, params = {}) {
+        try {
+            const data = await this.postJson('/api/v1/execute', { command, params });
+            if (data.status === 'error') {
+                throw this.mapErrorCodeToSmithUEError(data);
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof SmithUEError)
+                throw err;
+            throw this.normalizeRequestError(err, command);
+        }
+    }
+    async executeCommand(command, params = {}) {
+        return this.execute(command, params);
+    }
+    async ping() {
+        const res = await this.execute('ping', {});
+        return res.data;
+    }
+    async listTools(domain) {
+        const res = await this.execute('list_tools', domain ? { domain } : {});
+        if (domain) {
+            const data = res.data;
+            return data.tools;
+        }
+        // no domain filter - server returns {domains: [...]} not tools
+        return [];
+    }
+    async getReady() {
+        return this.getJson('/ready');
+    }
+    async isConnected() {
+        try {
+            await this.ping();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async executeWithFailover(command, params = {}) {
+        const syncTimeout = parseInt(process.env.SMITHUE_SYNC_TIMEOUT || '10000', 10);
+        const asyncTimeout = parseInt(process.env.SMITHUE_ASYNC_TIMEOUT || '120000', 10);
+        try {
+            return await this.postJson('/api/v1/execute', { command, params }, syncTimeout)
+                .then((data) => {
+                if (data.status === 'error')
+                    throw this.mapErrorCodeToSmithUEError(data);
+                return data;
+            });
+        }
+        catch (err) {
+            if (err instanceof SmithUEError)
+                throw err;
+            if (err.name !== 'AbortError') {
+                throw this.normalizeRequestError(err, command);
+            }
+        }
+        const taskId = await this.startAsyncTask(command, params);
+        const startedAt = Date.now();
+        let delayMs = 500;
+        while (Date.now() - startedAt <= asyncTimeout) {
+            const remainingMs = asyncTimeout - (Date.now() - startedAt);
+            if (remainingMs <= 0)
+                break;
+            const poll = await this.getJson(`/api/v1/async/${encodeURIComponent(taskId)}`, remainingMs);
+            if (poll.status === 'error') {
+                if (poll.error?.startsWith('Unknown task_id:')) {
+                    throw new Error('Task lost — server may have restarted');
+                }
+                throw this.mapErrorCodeToSmithUEError(poll);
+            }
+            const data = poll.data;
+            if (this.isAsyncTaskComplete(data)) {
+                return { status: 'success', data: data.result };
+            }
+            await this.sleep(Math.min(delayMs, Math.max(asyncTimeout - (Date.now() - startedAt), 0)));
+            delayMs = Math.min(delayMs * 2, 4000);
+        }
+        throw new Error(`Async task timed out after ${Math.ceil(asyncTimeout / 1000)}s`);
+    }
+    mapErrorCodeToSmithUEError(data) {
+        const msg = data.error ?? 'SmithUE command failed';
+        switch (data.error_code) {
+            case 'STALE_NID':
+                return new SmithUEError(msg, 5);
+            case 'PIE_LOCKED':
+            case 'ASSET_NOT_FOUND':
+            case 'INVALID_REQUEST':
+                return new SmithUEError(msg, 3);
+            case 'PAYLOAD_TOO_LARGE':
+                return new SmithUEError(msg, 1);
+            case 'INTERNAL_ERROR':
+            case 'EDITOR_NOT_READY':
+                return new SmithUEError(msg, 4);
+            default:
+                return new SmithUEError(msg, 3);
+        }
+    }
+    async startAsyncTask(command, params) {
+        const data = await this.postJson('/api/v1/async', { command, params });
+        if (data.status === 'error') {
+            throw this.mapErrorCodeToSmithUEError(data);
+        }
+        const taskId = data.data?.task_id;
+        if (typeof taskId !== 'string' || taskId.length === 0) {
+            throw new Error('SmithUE async task did not return a task_id');
+        }
+        return taskId;
+    }
+    isAsyncTaskComplete(data) {
+        return data?.completed === true && this.isRecord(data.result);
+    }
+    isRecord(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/commands/batch.d.ts

@@ -0,0 +1,13 @@
+export interface GlobalOpts {
+    pid?: number;
+    project?: string;
+    port?: number;
+}
+export type BatchResult = {
+    command: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+};
+export declare function batchCommand(commands: string[], opts: GlobalOpts): Promise<void>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/commands/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/commands/batch.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAIF,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiEtF"}

package/dist/commands/batch.js

@@ -0,0 +1,64 @@
+import { SmithUEClient } from '../client.js';
+import { discoverPort } from '../portfile.js';
+import { printResult, printError } from '../output.js';
+const ALLOWED_COMMANDS = ['status', 'list', 'search'];
+export async function batchCommand(commands, opts) {
+    // Short-circuit for empty list — no connection needed
+    if (commands.length === 0) {
+        printResult([]);
+        return;
+    }
+    try {
+        const discovered = await discoverPort(opts);
+        const client = new SmithUEClient({ host: '127.0.0.1', port: discovered.port });
+        const results = [];
+        for (const cmdEntry of commands) {
+            const parts = cmdEntry.trim().split(/\s+/);
+            const cmd = parts[0];
+            if (!ALLOWED_COMMANDS.includes(cmd)) {
+                results.push({
+                    command: cmdEntry,
+                    ok: false,
+                    error: `${cmd} is not allowed in batch mode. Allowed commands: ${ALLOWED_COMMANDS.join(', ')}`,
+                });
+                continue;
+            }
+            try {
+                let data;
+                if (cmd === 'status') {
+                    data = await client.getReady();
+                }
+                else if (cmd === 'list') {
+                    const domain = parts[1];
+                    data = await client.listTools(domain);
+                }
+                else if (cmd === 'search') {
+                    const query = parts.slice(1).join(' ').toLowerCase();
+                    const domains = await client.listTools();
+                    const matches = [];
+                    for (const domainTool of domains) {
+                        const domainName = domainTool.name;
+                        const tools = await client.listTools(domainName);
+                        for (const tool of tools) {
+                            const name = tool.name ?? '';
+                            const description = tool.description ?? '';
+                            if (name.toLowerCase().includes(query) || description.toLowerCase().includes(query)) {
+                                matches.push({ domain: domainName, name, description });
+                            }
+                        }
+                    }
+                    data = matches;
+                }
+                results.push({ command: cmdEntry, ok: true, data });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                results.push({ command: cmdEntry, ok: false, error: message });
+            }
+        }
+        printResult(results);
+    }
+    catch (err) {
+        printError(err);
+    }
+}

package/dist/commands/exec.d.ts

@@ -0,0 +1,6 @@
+import { type DiscoverOpts } from '../portfile.js';
+export interface ExecOpts extends DiscoverOpts {
+    cliVersion?: string;
+}
+export declare function execCommand(command: string, params: Record<string, unknown>, opts?: ExecOpts): Promise<void>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/commands/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/commands/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKjE,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE,QAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/commands/exec.js

@@ -0,0 +1,18 @@
+import { discoverPort } from '../portfile.js';
+import { SmithUEClient } from '../client.js';
+import { printResult, printError } from '../output.js';
+import { checkVersionCompat } from '../version-check.js';
+export async function execCommand(command, params, opts = {}) {
+    try {
+        const discovered = await discoverPort(opts);
+        if (opts.cliVersion)
+            checkVersionCompat(opts.cliVersion, discovered.plugin_version);
+        const { port } = discovered;
+        const client = new SmithUEClient({ host: '127.0.0.1', port });
+        const result = await client.executeCommand(command, params);
+        printResult(result);
+    }
+    catch (err) {
+        printError(err);
+    }
+}