edge-ai-client-ts 1.0.0

package/dist/buffer/disk-queue.js

@@ -0,0 +1,370 @@
+/**
+ * Disk-backed offline buffer queue — TypeScript parallel of
+ * `edge-client/src/buffer/queue.rs` (in-memory queue with the disk-persist
+ * half) and `edge-client/src/buffer/disk_dump.rs` (AES-256-GCM envelope).
+ *
+ * This is the OFFLINE RESILIENCE LAYER: when the WS connection is down,
+ * stream frames are durably written to disk; on reconnect they replay in
+ * order; no frames lost on crash.
+ *
+ * ## On-disk format (mirrors Rust `DiskDumper`)
+ *
+ *   [KEY_VERSION: 1 byte][AES-256-GCM nonce: 12 bytes][ciphertext + auth tag: 16 bytes]
+ *
+ * The plaintext is a JSON-encoded array of {@link QueueEntry} objects
+ * (`{ msg_id, timestamp, bytes }`), where `bytes` is base64-encoded.
+ *
+ * ## Atomic-write invariant (the project's hardest-won guarantee)
+ *
+ *   1. Serialize entries → encrypt → write to `<dir>/.buffer.queue.enc.tmp`
+ *   2. `fsync` the temp file
+ *   3. `rename` tmp → `<dir>/buffer.queue.enc`
+ *
+ * Crash safety: a tmp file left on disk after a crash is half-written; we
+ * delete it on next lazy-load. The main file is either fully written or
+ * absent (the rename is atomic on POSIX and on Windows since Node 14+).
+ *
+ * ## Concurrency
+ *
+ * In-process serialization via a Promise-chain mutex. Cross-process locking
+ * is intentionally NOT implemented (would require `proper-lockfile` or
+ * similar; omitted to keep the dependency surface minimal — the in-process
+ * case is the common path).
+ *
+ * ## Dedup
+ *
+ * `append` silently skips when an entry with the same `msg_id` is already
+ * buffered. The Rust `BufferQueue::push` does not dedup, but the disk queue
+ * MUST dedup to avoid sending the same `msg_id` twice to the relay on
+ * reconnect (relay-side ACKs would otherwise race).
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { encrypt, decrypt, KEY_VERSION } from '../crypto/aes-gcm.js';
+/** Default cap — 50 MiB. Matches Rust `BufferConfig::default().max_memory_mb`. */
+export const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+/** Filename of the encrypted queue blob (relative to `dir`). */
+export const QUEUE_FILE_NAME = 'buffer.queue.enc';
+/** Filename of the atomic-write temp file (relative to `dir`). */
+export const QUEUE_TMP_NAME = `.${QUEUE_FILE_NAME}.tmp`;
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/** Thrown by {@link DiskBufferQueue.append} when the cap would be exceeded. */
+export class BufferFullError extends Error {
+    currentBytes;
+    maxBytes;
+    constructor(currentBytes, maxBytes) {
+        super(`Buffer full: ${currentBytes} bytes would exceed cap of ${maxBytes} bytes`);
+        this.name = 'BufferFullError';
+        this.currentBytes = currentBytes;
+        this.maxBytes = maxBytes;
+    }
+}
+// ---------------------------------------------------------------------------
+// DiskBufferQueue
+// ---------------------------------------------------------------------------
+/**
+ * Single-file, AES-256-GCM-encrypted, FIFO buffer queue.
+ *
+ * Append-only on the hot path. `drain()` consumes every entry in FIFO order,
+ * hands each to a handler, and deletes the on-disk file when the handler
+ * completes successfully. `peek()` and `size()` are non-mutating.
+ */
+export class DiskBufferQueue {
+    dir;
+    filePath;
+    tmpPath;
+    key;
+    maxBytes;
+    /** In-memory cache. Loaded lazily on first op. */
+    entries = [];
+    loaded = false;
+    /** Promise-chain mutex for in-process serialization. */
+    mutex = Promise.resolve();
+    constructor(opts) {
+        if (!(opts.key instanceof Uint8Array)) {
+            throw new Error('DiskBufferQueue: key must be a Uint8Array');
+        }
+        if (opts.key.length !== 32) {
+            throw new Error(`DiskBufferQueue: key must be 32 bytes (AES-256), got ${opts.key.length}`);
+        }
+        if (typeof opts.dir !== 'string' || opts.dir.length === 0) {
+            throw new Error('DiskBufferQueue: dir must be a non-empty string');
+        }
+        const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+        if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+            throw new Error(`DiskBufferQueue: maxBytes must be a positive finite number, got ${maxBytes}`);
+        }
+        this.dir = opts.dir;
+        this.key = opts.key;
+        this.maxBytes = maxBytes;
+        this.filePath = path.join(this.dir, QUEUE_FILE_NAME);
+        this.tmpPath = path.join(this.dir, QUEUE_TMP_NAME);
+    }
+    /**
+     * Append an entry to the queue. Skips silently when `entry.msg_id` is
+     * already buffered (dedup invariant). Throws {@link BufferFullError} when
+     * the serialized envelope would exceed `maxBytes`.
+     */
+    async append(entry) {
+        return this.withLock(async () => {
+            await this.ensureLoaded();
+            this.assertValidEntry(entry);
+            // Dedup: skip if msg_id already buffered.
+            if (this.entries.some((e) => e.msg_id === entry.msg_id)) {
+                return;
+            }
+            const projected = this.projectedBytesAfterAppend(entry);
+            if (projected > this.maxBytes) {
+                throw new BufferFullError(projected, this.maxBytes);
+            }
+            // Defensive copy of bytes — caller may mutate after the await.
+            this.entries.push({
+                msg_id: entry.msg_id,
+                timestamp: entry.timestamp,
+                bytes: new Uint8Array(entry.bytes),
+            });
+            await this.persist();
+        });
+    }
+    /**
+     * Return up to `limit` entries (FIFO order) without removing them.
+     * Defensive copy — callers may freely mutate the returned bytes.
+     */
+    async peek(limit) {
+        return this.withLock(async () => {
+            await this.ensureLoaded();
+            if (!Number.isInteger(limit) || limit < 0) {
+                throw new Error(`DiskBufferQueue.peek: limit must be a non-negative integer, got ${limit}`);
+            }
+            return this.entries.slice(0, limit).map(cloneEntry);
+        });
+    }
+    /** Return the number of entries currently buffered. */
+    async size() {
+        return this.withLock(async () => {
+            await this.ensureLoaded();
+            return this.entries.length;
+        });
+    }
+    /**
+     * Delete all entries and the on-disk file. Idempotent — succeeds whether
+     * the file exists or not.
+     */
+    async clear() {
+        return this.withLock(async () => {
+            await this.ensureLoaded();
+            this.entries = [];
+            await this.unlinkIfExists(this.filePath);
+        });
+    }
+    /**
+     * Invoke `handler(entry)` for every entry in FIFO order, then delete the
+     * on-disk file. Returns the number of entries processed. If the handler
+     * throws, the entries remain on disk for a future `drain()` retry
+     * (at-least-once semantics — matches the Rust offline-queue contract).
+     */
+    async drain(handler) {
+        return this.withLock(async () => {
+            await this.ensureLoaded();
+            let count = 0;
+            for (const entry of this.entries) {
+                await handler(cloneEntry(entry));
+                count += 1;
+            }
+            this.entries = [];
+            await this.unlinkIfExists(this.filePath);
+            return count;
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Private: lazy init / crash recovery / persistence
+    // -------------------------------------------------------------------------
+    /**
+     * Lazily create the dir, recover from a prior crash (delete tmp), and
+     * load existing entries. Runs at most once per queue instance.
+     */
+    async ensureLoaded() {
+        if (this.loaded) {
+            return;
+        }
+        await fs.mkdir(this.dir, { recursive: true });
+        // Crash recovery: a leftover .tmp means the previous process died
+        // mid-write. The main file is either whole (atomic rename completed)
+        // or absent — the tmp can never have valid data on its own.
+        await this.unlinkIfExists(this.tmpPath);
+        // Load existing entries.
+        let raw;
+        try {
+            raw = await fs.readFile(this.filePath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT') {
+                this.entries = [];
+                this.loaded = true;
+                return;
+            }
+            throw err;
+        }
+        const result = decrypt(raw, this.key);
+        this.entries = deserializeEntries(result.plaintext);
+        this.loaded = true;
+    }
+    /**
+     * Encrypt + atomic-write the in-memory entry list to disk.
+     *
+     * Sequence (mirrors Rust `atomic_write` in `disk_dump.rs:159-186`):
+     *   1. encrypt(plaintext) → `[version][nonce][ciphertext][tag]`
+     *   2. open tmp with mode 0600 (defense in depth — encryption protects
+     *      contents either way)
+     *   3. write blob + fsync the file (force kernel buffers to disk)
+     *   4. rename tmp → final path (atomic on POSIX, atomic on Win since Node 14+)
+     */
+    async persist() {
+        const plaintext = serializeEntries(this.entries);
+        const encrypted = encrypt(this.key, plaintext);
+        let handle;
+        try {
+            handle = await fs.open(this.tmpPath, 'w', 0o600);
+            await handle.writeFile(encrypted);
+            await handle.sync();
+        }
+        catch (err) {
+            if (handle !== undefined) {
+                await handle.close();
+                handle = undefined;
+            }
+            // Best-effort tmp cleanup so a failed write doesn't leave junk.
+            await this.unlinkIfExists(this.tmpPath);
+            throw err;
+        }
+        finally {
+            if (handle !== undefined) {
+                await handle.close();
+            }
+        }
+        try {
+            await fs.rename(this.tmpPath, this.filePath);
+        }
+        catch (err) {
+            // Clean up tmp on rename failure to avoid leaving junk for next startup.
+            await this.unlinkIfExists(this.tmpPath);
+            throw err;
+        }
+    }
+    projectedBytesAfterAppend(entry) {
+        return serializedByteLength(this.entries) + serializedEntryByteLength(entry);
+    }
+    /** Serialize operations via a Promise chain (in-process mutex). */
+    withLock(fn) {
+        // Run `fn` after the previous operation settles (success OR failure —
+        // we never want a rejected op to poison the lock for future calls).
+        const run = this.mutex.then(fn, fn);
+        this.mutex = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    assertValidEntry(entry) {
+        if (typeof entry.msg_id !== 'string' || entry.msg_id.length === 0) {
+            throw new Error('DiskBufferQueue.append: entry.msg_id must be a non-empty string');
+        }
+        if (typeof entry.timestamp !== 'number' || !Number.isFinite(entry.timestamp)) {
+            throw new Error('DiskBufferQueue.append: entry.timestamp must be a finite number');
+        }
+        if (!(entry.bytes instanceof Uint8Array)) {
+            throw new Error('DiskBufferQueue.append: entry.bytes must be a Uint8Array');
+        }
+    }
+    async unlinkIfExists(target) {
+        try {
+            await fs.unlink(target);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT') {
+                throw err;
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Serialize all entries to a compact JSON string. `bytes` is base64-encoded
+ * so the result is pure ASCII (avoids `\uXXXX` expansion of arbitrary Uint8
+ * payloads) and round-trips losslessly.
+ */
+function serializeEntries(entries) {
+    const wire = entries.map((e) => ({
+        msg_id: e.msg_id,
+        timestamp: e.timestamp,
+        bytes: Buffer.from(e.bytes).toString('base64'),
+    }));
+    return JSON.stringify(wire);
+}
+/** Inverse of {@link serializeEntries}. Throws on malformed data. */
+function deserializeEntries(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`DiskBufferQueue: queue file contains invalid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('DiskBufferQueue: queue file root must be an array');
+    }
+    return parsed.map((raw, idx) => parseEntry(raw, idx));
+}
+function parseEntry(raw, idx) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error(`DiskBufferQueue: entry ${idx} is not an object`);
+    }
+    const rec = raw;
+    if (typeof rec['msg_id'] !== 'string' || rec['msg_id'].length === 0) {
+        throw new Error(`DiskBufferQueue: entry ${idx} has invalid msg_id`);
+    }
+    if (typeof rec['timestamp'] !== 'number' ||
+        !Number.isFinite(rec['timestamp'])) {
+        throw new Error(`DiskBufferQueue: entry ${idx} has invalid timestamp`);
+    }
+    if (typeof rec['bytes'] !== 'string') {
+        throw new Error(`DiskBufferQueue: entry ${idx} has invalid bytes (expected base64 string)`);
+    }
+    // Base64 of any byte sequence is always valid base64; Buffer.from will
+    // silently truncate if the string is malformed, so we accept the decoded
+    // length without a strict validator here.
+    const buf = Buffer.from(rec['bytes'], 'base64');
+    return {
+        msg_id: rec['msg_id'],
+        timestamp: rec['timestamp'],
+        bytes: new Uint8Array(buf),
+    };
+}
+/** Byte length of an entry as it would appear in the JSON envelope. */
+function serializedEntryByteLength(entry) {
+    return Buffer.byteLength(JSON.stringify({
+        msg_id: entry.msg_id,
+        timestamp: entry.timestamp,
+        bytes: Buffer.from(entry.bytes).toString('base64'),
+    }), 'utf8');
+}
+function serializedByteLength(entries) {
+    let total = 0;
+    for (const e of entries) {
+        total += serializedEntryByteLength(e);
+    }
+    return total;
+}
+function cloneEntry(entry) {
+    return {
+        msg_id: entry.msg_id,
+        timestamp: entry.timestamp,
+        bytes: new Uint8Array(entry.bytes),
+    };
+}
+// Re-export the on-disk format version so tests + ops tools can verify it
+// without re-importing from the crypto module.
+export { KEY_VERSION };

package/dist/cli/devices.d.ts

@@ -0,0 +1 @@
+export declare function listDevices(limit: number): Promise<number>;

package/dist/cli/devices.js

@@ -0,0 +1,61 @@
+/**
+ * `devices` subcommand — list devices owned by current operator.
+ * Mirrors `edge-client/src/cli/devices.rs`.
+ */
+import { loadSettings } from '../config/settings.js';
+import { loadDeviceSecret } from '../config/settings.js';
+export async function listDevices(limit) {
+    if (!Number.isInteger(limit) || limit <= 0) {
+        console.error('ec-ts devices: invalid --limit');
+        return 1;
+    }
+    const settings = loadSettings();
+    if (!settings.owner_operator_id) {
+        console.error('ec-ts devices: not enrolled (run `ec-ts enroll --key <KEY>` first)');
+        return 2;
+    }
+    const secret = loadDeviceSecret();
+    if (!secret) {
+        console.error('ec-ts devices: device secret missing');
+        return 3;
+    }
+    const httpUrl = settings.server.ws_url
+        .replace(/^wss:/, 'https:')
+        .replace(/^ws:/, 'http:')
+        .replace(/\/edge$/, '')
+        .replace(/\/$/, '');
+    const url = `${httpUrl}/api/devices?operator_id=${encodeURIComponent(settings.owner_operator_id)}&limit=${limit}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            headers: { 'X-Device-Secret': secret },
+        });
+    }
+    catch (e) {
+        console.error(`ec-ts devices: network error: ${String(e)}`);
+        return 4;
+    }
+    if (!resp.ok) {
+        console.error(`ec-ts devices: HTTP ${resp.status}`);
+        return 5;
+    }
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        console.error('ec-ts devices: non-JSON response');
+        return 6;
+    }
+    const items = body.items ?? [];
+    if (items.length === 0) {
+        console.log('(no devices)');
+        return 0;
+    }
+    console.log(`Devices (${items.length}):`);
+    for (const d of items) {
+        const last = d.last_seen_ms ? new Date(d.last_seen_ms).toISOString() : 'never';
+        console.log(`  ${d.id}\t${d.display_name ?? d.machine_id}\t${d.status ?? '?'}\tlast-seen: ${last}`);
+    }
+    return 0;
+}

package/dist/cli/enroll.d.ts

@@ -0,0 +1,2 @@
+/** Validate the API key with the relay and persist settings + secrets. */
+export declare function enroll(apiKey: string): Promise<number>;

package/dist/cli/enroll.js

@@ -0,0 +1,89 @@
+/**
+ * `enroll` subcommand — bind this edge node to an operator account.
+ * Mirrors `edge-client/src/cli/enroll.rs`.
+ *
+ * Validates the operator API key against the relay's enroll endpoint
+ * (HTTPS POST to `<ws_url>/api/devices/enroll` rewritten to HTTP) and on
+ * success writes `machine_id`, `ws_url`, `owner_operator_id`, `default_agent_id`,
+ * and the encrypted secrets file.
+ */
+import { defaultSettings, saveSettings, storeDeviceSecret, loadSettings, } from '../config/settings.js';
+import { generateMachineId } from '../config/settings.js';
+/** Validate the API key with the relay and persist settings + secrets. */
+export async function enroll(apiKey) {
+    if (!apiKey || typeof apiKey !== 'string' || apiKey.length < 8) {
+        console.error('ec-ts enroll: invalid API key (must be at least 8 chars)');
+        return 1;
+    }
+    // 1. Determine the relay URL — try existing settings first, else fall back to a sane default.
+    let settings;
+    try {
+        settings = loadSettings();
+    }
+    catch {
+        settings = defaultSettings();
+    }
+    const relayUrl = settings.server.ws_url;
+    const enrollUrl = relayUrl
+        .replace(/^wss:/, 'https:')
+        .replace(/^ws:/, 'http:')
+        .replace(/\/edge$/, '')
+        .replace(/\/$/, '') + '/api/devices/enroll';
+    // 2. POST to the relay to validate the key.
+    let resp;
+    try {
+        resp = await fetch(enrollUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Operator-Key': apiKey,
+            },
+            body: JSON.stringify({
+                machine_id: settings.machine_id ?? generateMachineId(),
+                agent_id: settings.agent.default_agent_id,
+                platform: process.platform,
+                hostname: (await import('node:os')).hostname(),
+            }),
+        });
+    }
+    catch (e) {
+        console.error(`ec-ts enroll: network error: ${String(e)}`);
+        return 2;
+    }
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => '');
+        console.error(`ec-ts enroll: relay rejected key (HTTP ${resp.status}): ${text.slice(0, 200)}`);
+        return 3;
+    }
+    // 3. Parse response: `{ operator_id, agent_id, machine_id }`.
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        console.error('ec-ts enroll: relay returned non-JSON');
+        return 4;
+    }
+    const operatorId = body.operator_id;
+    if (!operatorId) {
+        console.error('ec-ts enroll: relay response missing operator_id');
+        return 5;
+    }
+    // 4. Persist settings + secrets. NEVER log the api key.
+    settings.owner_operator_id = operatorId;
+    settings.agent.default_agent_id = body.agent_id ?? settings.agent.default_agent_id;
+    settings.machine_id = body.machine_id ?? settings.machine_id ?? generateMachineId();
+    try {
+        saveSettings(settings);
+        storeDeviceSecret(apiKey);
+    }
+    catch (e) {
+        console.error(`ec-ts enroll: failed to persist settings: ${String(e)}`);
+        return 6;
+    }
+    console.log(`ec-ts: enrolled as operator ${operatorId}`);
+    console.log(`  machine_id: ${settings.machine_id}`);
+    console.log(`  agent_id:   ${settings.agent.default_agent_id}`);
+    console.log(`  relay:      ${settings.server.ws_url}`);
+    return 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,10 @@
+export interface DispatchResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+}
+/**
+ * Parse argv and dispatch to the appropriate subcommand.
+ * Returns the process exit code. When no subcommand is given, defaults to `run`.
+ */
+export declare function dispatch(argv: string[]): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,116 @@
+/**
+ * CLI dispatch — mirrors `edge-client/src/cli/mod.rs`.
+ *
+ * Subcommands:
+ *  - run       (default) start the daemon
+ *  - enroll    bind this edge node to an operator account
+ *  - whoami    show local identity (operator_id, machine_id, ws_url)
+ *  - status    show daemon + relay contact status
+ *  - devices   list devices owned by current operator
+ *  - messages  list recent LLM conversation messages (operator-scoped)
+ *
+ * All control commands load `Settings` from disk via `loadSettings()` and call
+ * the relay over HTTP fetch. The `run` subcommand starts the long-running
+ * daemon (WS connect, session manager, buffer queue, heartbeat).
+ */
+import { Command } from 'commander';
+import { runDaemon } from './run.js';
+import { enroll } from './enroll.js';
+import { whoami } from './whoami.js';
+import { status } from './status.js';
+import { listDevices } from './devices.js';
+import { listMessages } from './messages.js';
+/**
+ * Parse argv and dispatch to the appropriate subcommand.
+ * Returns the process exit code. When no subcommand is given, defaults to `run`.
+ */
+export async function dispatch(argv) {
+    const program = new Command();
+    // exitOverride() makes commander throw a CommanderError instead of calling
+    // process.exit(0/1) on --version / --help / parse errors. This keeps the
+    // dispatcher testable and embeddable (no silent process termination).
+    program.exitOverride();
+    program
+        .name('ec-ts')
+        .description('Edge-client TypeScript (Model 1) — Edge AI Agent fleet daemon')
+        .version('7.0.0');
+    program
+        .command('run')
+        .description('Start the edge-client daemon (default if no subcommand)')
+        .action(async () => {
+        const code = await runDaemon();
+        process.exitCode = code;
+    });
+    program
+        .command('enroll')
+        .description('Bind this edge node to an operator account by pasting the per-operator API key')
+        .requiredOption('-k, --key <key>', 'operator API key (paste from dashboard)')
+        .action(async (opts) => {
+        const code = await enroll(opts.key);
+        process.exitCode = code;
+    });
+    program
+        .command('whoami')
+        .description('Show this edge node\'s local identity (no network calls)')
+        .action(async () => {
+        const code = await whoami();
+        process.exitCode = code;
+    });
+    program
+        .command('status')
+        .description('Show daemon + relay contact status')
+        .action(async () => {
+        const code = await status();
+        process.exitCode = code;
+    });
+    program
+        .command('devices')
+        .description('List devices owned by current operator')
+        .option('-l, --limit <n>', 'max devices to list', '50')
+        .action(async (opts) => {
+        const code = await listDevices(Number(opts.limit));
+        process.exitCode = code;
+    });
+    program
+        .command('messages')
+        .description('List recent LLM conversation messages (operator-scoped)')
+        .option('-l, --limit <n>', 'max messages to list', '50')
+        .action(async (opts) => {
+        const code = await listMessages(Number(opts.limit));
+        process.exitCode = code;
+    });
+    try {
+        // Commander expects argv in `[execPath, scriptPath, ...args]` form (mirrors process.argv).
+        // Callers like tests often pass just `[...args]`, so normalize here.
+        const normalizedArgv = argv.length >= 2 && typeof argv[0] === 'string' && (argv[0].startsWith('/') || argv[0].includes('\\') || argv[0] === 'node')
+            ? argv
+            : ['node', 'ec-ts', ...argv];
+        await program.parseAsync(normalizedArgv);
+        // process.exitCode can be string|number|undefined (signals); coerce to number for the contract.
+        const ec = process.exitCode;
+        return typeof ec === 'number' ? ec : 0;
+    }
+    catch (e) {
+        // Commander throws CommanderError for --version / --help / unknown commands.
+        // Map to a clean exit code per CLI convention.
+        const err = e;
+        // Commander throws CommanderError for --help / --version / unknown commands.
+        // Help/version should always map to exit code 0 (it's an informational display,
+        // not an error), regardless of what exitCode commander attached to the error.
+        const HELP_LIKE_CODES = new Set([
+            'commander.help',
+            'commander.helpDisplayed',
+            'commander.version',
+            'commander.versionDisplayed',
+        ]);
+        if (err && typeof err.code === 'string' && HELP_LIKE_CODES.has(err.code)) {
+            return 0;
+        }
+        if (err && typeof err.code === 'string' && err.code.startsWith('commander.')) {
+            // Other commander errors (unknownCommand, missingArgument, etc.) → exit 1.
+            return 1;
+        }
+        console.error('ec-ts: unexpected error:', e);
+        return 1;
+    }
+}

package/dist/cli/messages.d.ts

@@ -0,0 +1 @@
+export declare function listMessages(limit: number): Promise<number>;