@jackwener/opencli 1.6.10 → 1.7.1

package/dist/src/daemon.js

@@ -15,16 +15,15 @@
  *
  * Lifecycle:
  *   - Auto-spawned by opencli on first browser command
- *   - Auto-exits after idle timeout (default 4h, configurable via OPENCLI_DAEMON_TIMEOUT)
+ *   - Persistent — stays alive until explicit shutdown, SIGTERM, or uninstall
  *   - Listens on localhost:19825
  */
 import { createServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
-import { DEFAULT_DAEMON_PORT, DEFAULT_DAEMON_IDLE_TIMEOUT } from './constants.js';
+import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { EXIT_CODES } from './errors.js';
-import { IdleManager } from './idle-manager.js';
+import { log } from './logger.js';
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const IDLE_TIMEOUT = Number(process.env.OPENCLI_DAEMON_TIMEOUT ?? DEFAULT_DAEMON_IDLE_TIMEOUT);
 // ─── State ───────────────────────────────────────────────────────────
 let extensionWs = null;
 let extensionVersion = null;
@@ -36,11 +35,6 @@ function pushLog(entry) {
     if (logBuffer.length > LOG_BUFFER_SIZE)
         logBuffer.shift();
 }
-// ─── Idle auto-exit ──────────────────────────────────────────────────
-const idleManager = new IdleManager(IDLE_TIMEOUT, () => {
-    console.error('[daemon] Idle timeout (no CLI requests + no Extension), shutting down');
-    process.exit(EXIT_CODES.SUCCESS);
-});
 // ─── HTTP Server ─────────────────────────────────────────────────────
 const MAX_BODY = 1024 * 1024; // 1 MB — commands are tiny; this prevents OOM
 function readBody(req) {
@@ -118,7 +112,6 @@ async function handleRequest(req, res) {
             extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
             extensionVersion,
             pending: pending.size,
-            lastCliRequestTime: idleManager.lastCliRequestTime,
             memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
             port: PORT,
         });
@@ -144,7 +137,6 @@ async function handleRequest(req, res) {
         return;
     }
     if (req.method === 'POST' && url === '/command') {
-        idleManager.onCliRequest();
         try {
             const body = JSON.parse(await readBody(req));
             if (!body.id) {
@@ -193,10 +185,9 @@ const wss = new WebSocketServer({
     },
 });
 wss.on('connection', (ws) => {
-    console.error('[daemon] Extension connected');
+    log.info('[daemon] Extension connected');
     extensionWs = ws;
     extensionVersion = null; // cleared until hello message arrives
-    idleManager.setExtensionConnected(true);
     // ── Heartbeat: ping every 15s, close if 2 pongs missed ──
     let missedPongs = 0;
     const heartbeatInterval = setInterval(() => {
@@ -205,7 +196,7 @@ wss.on('connection', (ws) => {
             return;
         }
         if (missedPongs >= 2) {
-            console.error('[daemon] Extension heartbeat lost, closing connection');
+            log.warn('[daemon] Extension heartbeat lost, closing connection');
             clearInterval(heartbeatInterval);
             ws.terminate();
             return;
@@ -226,8 +217,12 @@ wss.on('connection', (ws) => {
             }
             // Handle log messages from extension
             if (msg.type === 'log') {
-                const prefix = msg.level === 'error' ? '❌' : msg.level === 'warn' ? '⚠️' : '📋';
-                console.error(`${prefix} [ext] ${msg.msg}`);
+                if (msg.level === 'error')
+                    log.error(`[ext] ${msg.msg}`);
+                else if (msg.level === 'warn')
+                    log.warn(`[ext] ${msg.msg}`);
+                else
+                    log.info(`[ext] ${msg.msg}`);
                 pushLog({ level: msg.level, msg: msg.msg, ts: msg.ts ?? Date.now() });
                 return;
             }
@@ -244,12 +239,11 @@ wss.on('connection', (ws) => {
         }
     });
     ws.on('close', () => {
-        console.error('[daemon] Extension disconnected');
+        log.info('[daemon] Extension disconnected');
         clearInterval(heartbeatInterval);
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
-            idleManager.setExtensionConnected(false);
             // Reject all pending requests since the extension is gone
             for (const [id, p] of pending) {
                 clearTimeout(p.timer);
@@ -263,7 +257,6 @@ wss.on('connection', (ws) => {
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
-            idleManager.setExtensionConnected(false);
             // Reject pending requests in case 'close' does not follow this 'error'
             for (const [, p] of pending) {
                 clearTimeout(p.timer);
@@ -275,15 +268,14 @@ wss.on('connection', (ws) => {
 });
 // ─── Start ───────────────────────────────────────────────────────────
 httpServer.listen(PORT, '127.0.0.1', () => {
-    console.error(`[daemon] Listening on http://127.0.0.1:${PORT}`);
-    idleManager.onCliRequest();
+    log.info(`[daemon] Listening on http://127.0.0.1:${PORT}`);
 });
 httpServer.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {
-        console.error(`[daemon] Port ${PORT} already in use — another daemon is likely running. Exiting.`);
+        log.error(`[daemon] Port ${PORT} already in use — another daemon is likely running. Exiting.`);
         process.exit(EXIT_CODES.SERVICE_UNAVAIL);
     }
-    console.error('[daemon] Server error:', err.message);
+    log.error(`[daemon] Server error: ${err.message}`);
     process.exit(EXIT_CODES.GENERIC_ERROR);
 });
 // Graceful shutdown

package/dist/src/diagnostic.d.ts

@@ -47,10 +47,9 @@ export declare function redactText(text: string): string;
  * Resolve the editable source file path for an adapter.
  *
  * Priority:
- * 1. cmd.source (set for FS-scanned YAML/TS and manifest lazy-loaded TS)
- * 2. cmd._modulePath (set for manifest lazy-loaded TS, points to dist/)
+ * 1. cmd.source (set for FS-scanned JS and manifest lazy-loaded JS)
+ * 2. cmd._modulePath (set for manifest lazy-loaded JS)
  *
- * For dist/ paths, attempt to map back to the original .ts source file.
  * Skip manifest: prefixed pseudo-paths (YAML commands inlined in manifest).
  */
 export declare function resolveAdapterSourcePath(cmd: InternalCliCommand): string | undefined;

package/dist/src/diagnostic.js

@@ -12,7 +12,6 @@
  * - Total output is capped to MAX_DIAGNOSTIC_BYTES
  */
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { CliError, getErrorMessage } from './errors.js';
 import { fullName } from './registry.js';
 // ── Size budgets ─────────────────────────────────────────────────────────────
@@ -141,9 +140,9 @@ function redactNetworkRequest(req) {
     if (redacted.responseHeaders && typeof redacted.responseHeaders === 'object') {
         redacted.responseHeaders = redactHeaders(redacted.responseHeaders);
     }
-    // Truncate response body
+    // Redact and truncate response body
     if (typeof redacted.body === 'string') {
-        redacted.body = truncate(redacted.body, MAX_REQUEST_BODY_CHARS);
+        redacted.body = redactText(truncate(redacted.body, MAX_REQUEST_BODY_CHARS));
     }
     if ('responseBody' in redacted) {
         redacted.responseBody = sanitizeCapturedValue(redacted.responseBody);
@@ -167,10 +166,9 @@ function withTimeout(promise, ms, fallback) {
  * Resolve the editable source file path for an adapter.
  *
  * Priority:
- * 1. cmd.source (set for FS-scanned YAML/TS and manifest lazy-loaded TS)
- * 2. cmd._modulePath (set for manifest lazy-loaded TS, points to dist/)
+ * 1. cmd.source (set for FS-scanned JS and manifest lazy-loaded JS)
+ * 2. cmd._modulePath (set for manifest lazy-loaded JS)
  *
- * For dist/ paths, attempt to map back to the original .ts source file.
  * Skip manifest: prefixed pseudo-paths (YAML commands inlined in manifest).
  */
 export function resolveAdapterSourcePath(cmd) {
@@ -183,26 +181,11 @@ export function resolveAdapterSourcePath(cmd) {
         candidates.push(cmd._modulePath);
     }
     for (const candidate of candidates) {
-        // Try to map dist/ compiled JS back to source .ts
-        const sourceTs = mapDistToSource(candidate);
-        if (sourceTs && fs.existsSync(sourceTs))
-            return sourceTs;
-        // Try the candidate directly (YAML files, user clis, etc.)
         if (fs.existsSync(candidate))
             return candidate;
     }
     return candidates[0]; // Return best guess even if file doesn't exist
 }
-/** Map a dist/clis/xxx.js path back to clis/xxx.ts source. */
-function mapDistToSource(filePath) {
-    // dist/clis/site/command.js → clis/site/command.ts
-    const normalized = filePath.replace(/\\/g, '/');
-    const distClisMatch = normalized.match(/^(.*)\/dist\/clis\/(.+)\.js$/);
-    if (distClisMatch) {
-        return path.join(distClisMatch[1], 'clis', distClisMatch[2] + '.ts');
-    }
-    return null;
-}
 // ── Diagnostic collection ────────────────────────────────────────────────────
 /** Whether diagnostic mode is enabled. */
 export function isDiagnosticEnabled() {

package/dist/src/diagnostic.test.js

@@ -83,12 +83,12 @@ describe('redactText', () => {
 });
 describe('resolveAdapterSourcePath', () => {
     it('returns source when it is a real file path (not manifest:)', () => {
-        const cmd = makeCmd({ source: '/home/user/.opencli/clis/arxiv/search.ts' });
-        expect(resolveAdapterSourcePath(cmd)).toBe('/home/user/.opencli/clis/arxiv/search.ts');
+        const cmd = makeCmd({ source: '/home/user/.opencli/clis/arxiv/search.js' });
+        expect(resolveAdapterSourcePath(cmd)).toBe('/home/user/.opencli/clis/arxiv/search.js');
     });
     it('skips manifest: pseudo-paths and falls back to _modulePath', () => {
-        const cmd = makeCmd({ source: 'manifest:arxiv/search', _modulePath: '/pkg/dist/clis/arxiv/search.js' });
-        // Should try to map dist→source, but since files don't exist on disk, returns _modulePath
+        const cmd = makeCmd({ source: 'manifest:arxiv/search', _modulePath: '/pkg/clis/arxiv/search.js' });
+        // Should try to map to source, but since files don't exist on disk, returns _modulePath
         const result = resolveAdapterSourcePath(cmd);
         expect(result).toBeDefined();
         expect(result).not.toContain('manifest:');
@@ -97,12 +97,11 @@ describe('resolveAdapterSourcePath', () => {
         const cmd = makeCmd({ source: 'manifest:test/cmd' });
         expect(resolveAdapterSourcePath(cmd)).toBeUndefined();
     });
-    it('prefers _modulePath mapped to .ts over dist .js', () => {
-        // This test verifies the mapping logic without requiring files on disk
-        const cmd = makeCmd({ _modulePath: '/project/dist/clis/site/cmd.js' });
+    it('returns _modulePath when it is the only path available', () => {
+        const cmd = makeCmd({ _modulePath: '/project/clis/site/cmd.js' });
         const result = resolveAdapterSourcePath(cmd);
-        // Since neither .ts nor .js exists, returns _modulePath as best guess
-        expect(result).toBe('/project/dist/clis/site/cmd.js');
+        // Since file doesn't exist, returns _modulePath as best guess
+        expect(result).toBe('/project/clis/site/cmd.js');
     });
 });
 describe('buildRepairContext', () => {

package/dist/src/discovery.d.ts

@@ -1,9 +1,9 @@
 /**
- * CLI discovery: finds TS CLI definitions and registers them.
+ * CLI discovery: finds JS CLI definitions and registers them.
  *
  * Supports two modes:
  * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
- *    registers commands instantly. TS modules are loaded lazily only
+ *    registers commands instantly. JS modules are loaded lazily only
  *    when their command is executed.
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */

package/dist/src/discovery.js

@@ -1,9 +1,9 @@
 /**
- * CLI discovery: finds TS CLI definitions and registers them.
+ * CLI discovery: finds JS CLI definitions and registers them.
  *
  * Supports two modes:
  * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
- *    registers commands instantly. TS modules are loaded lazily only
+ *    registers commands instantly. JS modules are loaded lazily only
  *    when their command is executed.
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
@@ -146,7 +146,6 @@ async function loadFromManifest(manifestPath, clisDir) {
         for (const entry of manifest) {
             if (!entry.modulePath)
                 continue;
-            const strategy = parseStrategy(entry.strategy ?? 'cookie');
             const modulePath = path.resolve(clisDir, entry.modulePath);
             const cmd = {
                 site: entry.site,
@@ -154,8 +153,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                 aliases: entry.aliases,
                 description: entry.description ?? '',
                 domain: entry.domain,
-                strategy,
-                browser: entry.browser ?? true,
+                strategy: parseStrategy(entry.strategy),
+                browser: entry.browser,
                 args: entry.args ?? [],
                 columns: entry.columns,
                 pipeline: entry.pipeline,
@@ -167,6 +166,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 _lazy: true,
                 _modulePath: modulePath,
             };
+            // normalizeCommand inside registerCommand handles strategy → browser/navigateBefore
             registerCommand(cmd);
         }
         return true;
@@ -196,11 +196,14 @@ async function discoverClisFromFs(dir) {
         await Promise.all(files.map(async (file) => {
             const filePath = path.join(siteDir, file);
             if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-                log.warn(`Ignoring YAML adapter ${filePath} — YAML format is no longer supported. Convert to TypeScript using cli() from '@jackwener/opencli/registry'.`);
+                log.warn(`Ignoring YAML adapter ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
                 return;
             }
-            if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
-                (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
+            if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+                log.warn(`Ignoring TypeScript adapter ${filePath} — .ts adapters are no longer loaded. Rename to .js or convert to JavaScript.`);
+                return;
+            }
+            if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js')) {
                 if (!(await isCliModule(filePath)))
                     return;
                 await import(pathToFileURL(filePath).href).catch((err) => {
@@ -241,7 +244,7 @@ async function discoverPluginDir(dir, site) {
     await Promise.all(files.map(async (file) => {
         const filePath = path.join(dir, file);
         if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-            log.warn(`Ignoring YAML plugin ${filePath} — YAML format is no longer supported. Convert to TypeScript using cli() from '@jackwener/opencli/registry'.`);
+            log.warn(`Ignoring YAML plugin ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
             return;
         }
         if (file.endsWith('.js') && !file.endsWith('.d.js')) {

package/dist/src/doctor.js

@@ -3,7 +3,7 @@
  *
  * Simplified for the daemon-based architecture.
  */
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { BrowserBridge } from './browser/index.js';
 import { getDaemonHealth, listSessions } from './browser/daemon-client.js';
@@ -101,54 +101,54 @@ export async function runBrowserDoctor(opts = {}) {
     };
 }
 export function renderBrowserDoctorReport(report) {
-    const lines = [chalk.bold(`opencli v${report.cliVersion ?? 'unknown'} doctor`) + chalk.dim(` (${getRuntimeLabel()})`), ''];
+    const lines = [styleText('bold', `opencli v${report.cliVersion ?? 'unknown'} doctor`) + styleText('dim', ` (${getRuntimeLabel()})`), ''];
     // Daemon status
     const daemonIcon = report.daemonFlaky
-        ? chalk.yellow('[WARN]')
-        : report.daemonRunning ? chalk.green('[OK]') : chalk.red('[MISSING]');
+        ? styleText('yellow', '[WARN]')
+        : report.daemonRunning ? styleText('green', '[OK]') : styleText('red', '[MISSING]');
     const daemonLabel = report.daemonFlaky
         ? 'unstable (running during live check, then stopped)'
         : report.daemonRunning ? `running on port ${DEFAULT_DAEMON_PORT}` : 'not running';
     lines.push(`${daemonIcon} Daemon: ${daemonLabel}`);
     // Extension status
     const extIcon = report.extensionFlaky
-        ? chalk.yellow('[WARN]')
-        : report.extensionConnected ? chalk.green('[OK]') : chalk.yellow('[MISSING]');
-    const extVersion = report.extensionVersion ? chalk.dim(` (v${report.extensionVersion})`) : '';
+        ? styleText('yellow', '[WARN]')
+        : report.extensionConnected ? styleText('green', '[OK]') : styleText('yellow', '[MISSING]');
+    const extVersion = report.extensionVersion ? styleText('dim', ` (v${report.extensionVersion})`) : '';
     const extLabel = report.extensionFlaky
         ? 'unstable (connected during live check, then disconnected)'
         : report.extensionConnected ? 'connected' : 'not connected';
     lines.push(`${extIcon} Extension: ${extLabel}${extVersion}`);
     // Connectivity
     if (report.connectivity) {
-        const connIcon = report.connectivity.ok ? chalk.green('[OK]') : chalk.red('[FAIL]');
+        const connIcon = report.connectivity.ok ? styleText('green', '[OK]') : styleText('red', '[FAIL]');
         const detail = report.connectivity.ok
             ? `connected in ${(report.connectivity.durationMs / 1000).toFixed(1)}s`
             : `failed (${report.connectivity.error ?? 'unknown'})`;
         lines.push(`${connIcon} Connectivity: ${detail}`);
     }
     else {
-        lines.push(`${chalk.dim('[SKIP]')} Connectivity: skipped (--no-live)`);
+        lines.push(`${styleText('dim', '[SKIP]')} Connectivity: skipped (--no-live)`);
     }
     if (report.sessions) {
-        lines.push('', chalk.bold('Sessions:'));
+        lines.push('', styleText('bold', 'Sessions:'));
         if (report.sessions.length === 0) {
-            lines.push(chalk.dim('  • no active automation sessions'));
+            lines.push(styleText('dim', '  • no active automation sessions'));
         }
         else {
             for (const session of report.sessions) {
-                lines.push(chalk.dim(`  • ${session.workspace} → window ${session.windowId}, tabs=${session.tabCount}, idle=${Math.ceil(session.idleMsRemaining / 1000)}s`));
+                lines.push(styleText('dim', `  • ${session.workspace} → window ${session.windowId}, tabs=${session.tabCount}, idle=${Math.ceil(session.idleMsRemaining / 1000)}s`));
             }
         }
     }
     if (report.issues.length) {
-        lines.push('', chalk.yellow('Issues:'));
+        lines.push('', styleText('yellow', 'Issues:'));
         for (const issue of report.issues) {
-            lines.push(chalk.dim(`  • ${issue}`));
+            lines.push(styleText('dim', `  • ${issue}`));
         }
     }
     else if (report.daemonRunning && report.extensionConnected) {
-        lines.push('', chalk.green('Everything looks good!'));
+        lines.push('', styleText('green', 'Everything looks good!'));
     }
     return lines.join('\n');
 }

package/dist/src/download/index.js

@@ -11,6 +11,7 @@ import { URL } from 'node:url';
 import { isBinaryInstalled } from '../external.js';
 import { getErrorMessage } from '../errors.js';
 import { fetchWithNodeNetwork } from '../node-network.js';
+import { log } from '../logger.js';
 /** Check if yt-dlp is available in PATH. */
 export function checkYtdlp() {
     return isBinaryInstalled('yt-dlp');
@@ -206,7 +207,7 @@ export async function ytdlpDownload(url, destPath, options = {}) {
                 args.push('--cookies', cookiesFile);
             }
             else {
-                console.error(`[download] Cookies file not found: ${cookiesFile}, falling back to browser cookies`);
+                log.warn(`[download] Cookies file not found: ${cookiesFile}, falling back to browser cookies`);
                 args.push('--cookies-from-browser', 'chrome');
             }
         }

package/dist/src/download/progress.js

@@ -1,7 +1,7 @@
 /**
  * Download progress display: terminal progress bars, status updates.
  */
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 /**
  * Format bytes as human-readable string (KB, MB, GB).
  */
@@ -35,7 +35,7 @@ export function formatDuration(ms) {
  * Create a simple progress bar for terminal display.
  */
 export function createProgressBar(filename, index, total) {
-    const prefix = chalk.dim(`[${index + 1}/${total}]`);
+    const prefix = styleText('dim', `[${index + 1}/${total}]`);
     const truncatedName = filename.length > 40 ? filename.slice(0, 37) + '...' : filename;
     return {
         update(current, totalBytes, label) {
@@ -46,12 +46,12 @@ export function createProgressBar(filename, index, total) {
             process.stderr.write(`\r${prefix} ${truncatedName} ${bar} ${percent}% ${size}${extra}`);
         },
         complete(success, message) {
-            const icon = success ? chalk.green('✓') : chalk.red('✗');
-            const msg = message ? ` ${chalk.dim(message)}` : '';
+            const icon = success ? styleText('green', '✓') : styleText('red', '✗');
+            const msg = message ? ` ${styleText('dim', message)}` : '';
             process.stderr.write(`\r${prefix} ${icon} ${truncatedName}${msg}\n`);
         },
         fail(error) {
-            process.stderr.write(`\r${prefix} ${chalk.red('✗')} ${truncatedName} ${chalk.red(error)}\n`);
+            process.stderr.write(`\r${prefix} ${styleText('red', '✗')} ${truncatedName} ${styleText('red', error)}\n`);
         },
     };
 }
@@ -61,7 +61,7 @@ export function createProgressBar(filename, index, total) {
 function createBar(percent, width = 20) {
     const filled = Math.round((percent / 100) * width);
     const empty = width - filled;
-    return chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(empty));
+    return styleText('cyan', '█'.repeat(filled)) + styleText('dim', '░'.repeat(empty));
 }
 /**
  * Multi-file download progress tracker.
@@ -98,19 +98,19 @@ export class DownloadProgressTracker {
         const elapsed = formatDuration(Date.now() - this.startTime);
         const parts = [];
         if (this.completed > 0) {
-            parts.push(chalk.green(`${this.completed} downloaded`));
+            parts.push(styleText('green', `${this.completed} downloaded`));
         }
         if (this.skipped > 0) {
-            parts.push(chalk.yellow(`${this.skipped} skipped`));
+            parts.push(styleText('yellow', `${this.skipped} skipped`));
         }
         if (this.failed > 0) {
-            parts.push(chalk.red(`${this.failed} failed`));
+            parts.push(styleText('red', `${this.failed} failed`));
         }
         return `${parts.join(', ')} in ${elapsed}`;
     }
     finish() {
         if (this.verbose) {
-            process.stderr.write(`\n${chalk.bold('Download complete:')} ${this.getSummary()}\n`);
+            process.stderr.write(`\n${styleText('bold', 'Download complete:')} ${this.getSummary()}\n`);
         }
     }
 }

package/dist/src/engine.test.js

@@ -15,8 +15,8 @@ describe('discoverClis', () => {
     it('imports only CLI command modules during filesystem discovery', async () => {
         const tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-discovery-'));
         const siteDir = path.join(tempRoot, 'temp-site');
-        const helperPath = path.join(siteDir, 'helper.ts');
-        const commandPath = path.join(siteDir, 'hello.ts');
+        const helperPath = path.join(siteDir, 'helper.js');
+        const commandPath = path.join(siteDir, 'hello.js');
         try {
             await fs.promises.mkdir(siteDir, { recursive: true });
             await fs.promises.writeFile(helperPath, `
@@ -48,7 +48,7 @@ cli({
         const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-manifest-fallback-'));
         const distDir = path.join(tempBuildRoot, 'dist');
         const siteDir = path.join(distDir, 'fallback-site');
-        const commandPath = path.join(siteDir, 'hello.ts');
+        const commandPath = path.join(siteDir, 'hello.js');
         const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
         try {
             await fs.promises.mkdir(siteDir, { recursive: true });
@@ -75,7 +75,7 @@ cli({
         const tempOpencliRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-user-clis-'));
         const userClisDir = path.join(tempOpencliRoot, 'clis');
         const siteDir = path.join(userClisDir, 'legacy-site');
-        const commandPath = path.join(siteDir, 'hello.ts');
+        const commandPath = path.join(siteDir, 'hello.js');
         try {
             await ensureUserCliCompatShims(tempOpencliRoot);
             await fs.promises.mkdir(siteDir, { recursive: true });

package/dist/src/errors.d.ts

@@ -70,7 +70,21 @@ export declare class EmptyResultError extends CliError {
 export declare class SelectorError extends CliError {
     constructor(selector: string, hint?: string);
 }
+export declare class PluginError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/** Structured error output — unified contract for all consumers (AI agents, scripts, humans). */
+export interface ErrorEnvelope {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        help?: string;
+        exitCode: number;
+        stack?: string;
+    };
+}
 /** Extract a human-readable message from an unknown caught value. */
 export declare function getErrorMessage(error: unknown): string;
-/** Error code → emoji mapping for CLI output rendering. */
-export declare const ERROR_ICONS: Record<string, string>;
+/** Build an ErrorEnvelope from any caught value. */
+export declare function toEnvelope(err: unknown): ErrorEnvelope;

package/dist/src/errors.js

@@ -96,24 +96,36 @@ export class SelectorError extends CliError {
         super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.', EXIT_CODES.GENERIC_ERROR);
     }
 }
+export class PluginError extends CliError {
+    constructor(message, hint) {
+        super('PLUGIN', message, hint, EXIT_CODES.GENERIC_ERROR);
+    }
+}
 // ── Utilities ───────────────────────────────────────────────────────────────
 /** Extract a human-readable message from an unknown caught value. */
 export function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-/** Error code → emoji mapping for CLI output rendering. */
-export const ERROR_ICONS = {
-    AUTH_REQUIRED: '🔒',
-    BROWSER_CONNECT: '🔌',
-    TIMEOUT: '⏱ ',
-    ARGUMENT: '❌',
-    EMPTY_RESULT: '📭',
-    SELECTOR: '🔍',
-    COMMAND_EXEC: '💥',
-    ADAPTER_LOAD: '📦',
-    NETWORK: '🌐',
-    API_ERROR: '🚫',
-    RATE_LIMITED: '⏳',
-    PAGE_CHANGED: '🔄',
-    CONFIG: '⚙️ ',
-};
+/** Build an ErrorEnvelope from any caught value. */
+export function toEnvelope(err) {
+    if (err instanceof CliError) {
+        return {
+            ok: false,
+            error: {
+                code: err.code,
+                message: err.message,
+                ...(err.hint ? { help: err.hint } : {}),
+                exitCode: err.exitCode,
+            },
+        };
+    }
+    const msg = getErrorMessage(err);
+    return {
+        ok: false,
+        error: {
+            code: 'UNKNOWN',
+            message: msg,
+            exitCode: EXIT_CODES.GENERIC_ERROR,
+        },
+    };
+}

package/dist/src/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { CliError, BrowserConnectError, AdapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, SelectorError, } from './errors.js';
+import { CliError, BrowserConnectError, AdapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, SelectorError, toEnvelope, } from './errors.js';
 describe('Error type hierarchy', () => {
     it('all error types extend CliError', () => {
         const errors = [
@@ -57,3 +57,40 @@ describe('Error type hierarchy', () => {
         expect(err.code).toBe('BROWSER_CONNECT');
     });
 });
+describe('toEnvelope', () => {
+    it('converts CliError to structured envelope', () => {
+        const err = new AuthRequiredError('bilibili.com');
+        const envelope = toEnvelope(err);
+        expect(envelope).toEqual({
+            ok: false,
+            error: {
+                code: 'AUTH_REQUIRED',
+                message: 'Not logged in to bilibili.com',
+                help: expect.stringContaining('https://bilibili.com'),
+                exitCode: 77,
+            },
+        });
+    });
+    it('converts CliError without hint (omits help field)', () => {
+        const err = new CommandExecutionError('Something broke');
+        const envelope = toEnvelope(err);
+        expect(envelope.error.code).toBe('COMMAND_EXEC');
+        expect(envelope.error).not.toHaveProperty('help');
+    });
+    it('converts unknown Error to UNKNOWN envelope', () => {
+        const envelope = toEnvelope(new Error('random failure'));
+        expect(envelope).toEqual({
+            ok: false,
+            error: {
+                code: 'UNKNOWN',
+                message: 'random failure',
+                exitCode: 1,
+            },
+        });
+    });
+    it('converts non-Error values to UNKNOWN envelope', () => {
+        const envelope = toEnvelope('string error');
+        expect(envelope.error.code).toBe('UNKNOWN');
+        expect(envelope.error.message).toBe('string error');
+    });
+});

package/dist/src/execution.d.ts

@@ -11,4 +11,7 @@
  */
 import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
 export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
-export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean): Promise<unknown>;
+export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
+    prepared?: boolean;
+}): Promise<unknown>;
+export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;