@livon/cli 0.27.0-rc.1

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+Third-Party Notices
+
+This package includes third-party software. The following licenses apply:
+
+------------------------------------------------------------------------------
+msgpackr
+------------------------------------------------------------------------------
+License: MIT
+
+Copyright (c) 2020 Kris Zyp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/livon.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/index.js').catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/index.cjs

@@ -0,0 +1,603 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+var __webpack_exports__ = {};
+const generate_namespaceObject = require("@livon/client/generate");
+const external_node_child_process_namespaceObject = require("node:child_process");
+const external_node_crypto_namespaceObject = require("node:crypto");
+const external_node_fs_namespaceObject = require("node:fs");
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const external_ws_namespaceObject = require("ws");
+var external_ws_default = /*#__PURE__*/ __webpack_require__.n(external_ws_namespaceObject);
+const external_msgpackr_namespaceObject = require("msgpackr");
+const RETRY_RESET_AFTER_CONNECTION = 'livon.retry.reset_after_connection';
+const createDefaultOptions = ()=>({
+        endpoint: '',
+        port: void 0,
+        out: '',
+        poll: void 0,
+        timeout: void 0,
+        event: '$explain',
+        method: 'POST',
+        headers: {},
+        payload: void 0
+    });
+const readOptionValue = ({ argv, index, arg })=>{
+    if (arg.includes('=')) return {
+        nextIndex: index + 1,
+        value: arg.split('=').slice(1).join('=')
+    };
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) return {
+        nextIndex: index + 1,
+        value: void 0
+    };
+    return {
+        nextIndex: index + 2,
+        value
+    };
+};
+const readCliArgs = ({ argv, index, options })=>{
+    const arg = argv[index];
+    if (!arg) return {
+        options,
+        command: []
+    };
+    if ('--' === arg) return {
+        options,
+        command: argv.slice(index + 1)
+    };
+    if (!arg.startsWith('-')) return {
+        options,
+        command: argv.slice(index)
+    };
+    if ('--no-event' === arg) return readCliArgs({
+        argv,
+        index: index + 1,
+        options: {
+            ...options,
+            event: void 0,
+            method: 'GET'
+        }
+    });
+    if (arg.startsWith('--endpoint')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                endpoint: value ?? ''
+            }
+        });
+    }
+    if (arg.startsWith('--out')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                out: value ?? ''
+            }
+        });
+    }
+    if (arg.startsWith('--poll')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                poll: value ? Number(value) : void 0
+            }
+        });
+    }
+    if (arg.startsWith('--timeout')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid --timeout value: ${value}`);
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    timeout: parsed
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--port')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid --port value: ${value}`);
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    port: parsed
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--event')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                event: value,
+                method: 'POST'
+            }
+        });
+    }
+    if (arg.startsWith('--method')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                method: value && 'GET' === value.toUpperCase() ? 'GET' : 'POST'
+            }
+        });
+    }
+    if (arg.startsWith('--header')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const [key, ...rest] = value.split(':');
+            if (key && rest.length > 0) return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    headers: {
+                        ...options.headers,
+                        [key.trim()]: rest.join(':').trim()
+                    }
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--payload')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) try {
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    payload: JSON.parse(value)
+                }
+            });
+        } catch (error) {
+            throw new Error(`Invalid JSON for --payload: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    return readCliArgs({
+        argv,
+        index: index + 1,
+        options
+    });
+};
+const readCliInput = (argv)=>{
+    const parsed = readCliArgs({
+        argv,
+        index: 0,
+        options: createDefaultOptions()
+    });
+    const options = {
+        ...parsed.options
+    };
+    if (!options.endpoint && options.port) options.endpoint = `ws://127.0.0.1:${options.port}/ws`;
+    if (!options.endpoint) throw new Error('Missing required --endpoint or --port');
+    if (options.port) options.endpoint = applyPortToEndpoint(options.endpoint, options.port);
+    if (!options.out) throw new Error('Missing required --out');
+    if (void 0 === options.event) throw new Error('Missing required --event for websocket mode.');
+    return {
+        options,
+        command: parsed.command
+    };
+};
+const applyPortToEndpoint = (endpoint, port)=>{
+    const url = new URL(endpoint);
+    if ('ws:' !== url.protocol && 'wss:' !== url.protocol) throw new Error('Endpoint must be ws:// or wss:// for websocket mode.');
+    url.port = String(port);
+    if (!url.pathname || '/' === url.pathname) url.pathname = '/ws';
+    return url.toString();
+};
+const hashAst = (ast)=>(0, external_node_crypto_namespaceObject.createHash)('sha256').update(JSON.stringify(ast)).digest('hex');
+const compactMetadata = (metadata)=>{
+    if (!metadata) return;
+    return Object.keys(metadata).length > 0 ? metadata : void 0;
+};
+const compactContext = (context)=>{
+    if (!context || 0 === Object.keys(context).length) return;
+    return context;
+};
+const encodePayload = (value)=>(0, external_msgpackr_namespaceObject.pack)(value);
+const decodePayload = (payload)=>payload ? (0, external_msgpackr_namespaceObject.unpack)(payload) : void 0;
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const binaryFromSocketData = (data)=>{
+    if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data));
+    if ('string' == typeof data) throw new Error('Expected binary WebSocket payload.');
+    if (data instanceof ArrayBuffer) return new Uint8Array(data);
+    if (Buffer.isBuffer(data)) return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return new Uint8Array(Buffer.from(data));
+};
+const ensureEvent = (value)=>{
+    if (!value) throw new Error('Missing required --event for websocket mode.');
+    return value;
+};
+const buildWireEnvelope = (input)=>{
+    const metadata = compactMetadata(input.metadata);
+    const context = compactContext(input.context);
+    const base = {
+        event: input.event,
+        metadata,
+        context: context ? encodePayload(context) : void 0
+    };
+    return {
+        ...base,
+        payload: encodePayload(input.payload)
+    };
+};
+const DEFAULT_TIMEOUT_MS = 30000;
+const CLIENT_GENERATOR_HASH = (0, generate_namespaceObject.getClientGeneratorFingerprint)();
+const fetchAst = async (options, etag)=>{
+    const endpoint = options.endpoint.trim();
+    if (!endpoint.startsWith('ws://') && !endpoint.startsWith('wss://')) throw new Error('Endpoint must be ws:// or wss:// for $explain.');
+    return new Promise((resolve, reject)=>{
+        const ws = new (external_ws_default())(endpoint, {
+            headers: options.headers
+        });
+        let resolved = false;
+        let hadConnection = false;
+        const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const timeout = setTimeout(()=>{
+            if (!resolved) {
+                resolved = true;
+                ws.close();
+                reject(new Error('Timed out waiting for $explain response.'));
+            }
+        }, timeoutMs);
+        const finish = (result)=>{
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+            ws.close();
+            resolve(result);
+        };
+        const fail = (error)=>{
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+            ws.close();
+            const retryAware = error;
+            if (hadConnection) retryAware[RETRY_RESET_AFTER_CONNECTION] = true;
+            reject(error);
+        };
+        ws.on('error', (error)=>{
+            fail(error);
+        });
+        ws.on('open', ()=>{
+            hadConnection = true;
+            const eventName = ensureEvent(options.event);
+            const request = buildWireEnvelope({
+                event: eventName,
+                payload: options.payload ?? null,
+                metadata: etag ? {
+                    ifNoneMatch: etag
+                } : void 0
+            });
+            ws.send((0, external_msgpackr_namespaceObject.pack)(request));
+        });
+        ws.on('message', (data)=>{
+            let parsed;
+            try {
+                parsed = (0, external_msgpackr_namespaceObject.unpack)(binaryFromSocketData(data));
+            } catch  {
+                return;
+            }
+            if (!isRecord(parsed)) return;
+            const envelope = parsed;
+            if (envelope.event && envelope.event !== options.event) return;
+            if (envelope.error) {
+                const decoded = decodePayload(envelope.error);
+                const message = decoded && 'object' == typeof decoded && 'message' in decoded ? String(decoded.message ?? 'Explain error') : 'Explain error';
+                fail(new Error(message));
+                return;
+            }
+            const payload = envelope.payload ? decodePayload(envelope.payload) : parsed;
+            if (!payload || 'object' != typeof payload) return;
+            const response = payload;
+            if (response.notModified) return void finish({
+                notModified: true,
+                etag: response.etag ?? etag
+            });
+            if ('ast' in response) finish({
+                ast: response.ast,
+                checksum: response.checksum,
+                schemaVersion: response.schemaVersion,
+                generatedAt: response.generatedAt,
+                etag: response.etag ?? response.checksum ?? etag
+            });
+        });
+    });
+};
+const resolveOutputPaths = (out)=>{
+    const isFile = external_node_path_default().extname(out).length > 0;
+    const outDir = isFile ? external_node_path_default().dirname(out) : out;
+    const astFile = external_node_path_default().join(outDir, 'ast.ts');
+    const clientFile = isFile ? out : external_node_path_default().join(outDir, 'client.ts');
+    const checksumFile = external_node_path_default().join(outDir, '.livon.client.checksum');
+    return {
+        outDir,
+        astFile,
+        clientFile,
+        checksumFile
+    };
+};
+const readCachedChecksum = async (checksumFile)=>{
+    const raw = (await external_node_fs_namespaceObject.promises.readFile(checksumFile, 'utf8').catch(()=>'')).trim();
+    if (!raw) return {};
+    if (raw.startsWith('{')) try {
+        const parsed = JSON.parse(raw);
+        const generatorHash = 'string' == typeof parsed.generatorHash ? parsed.generatorHash : void 0;
+        const etag = 'string' == typeof parsed.etag ? parsed.etag : void 0;
+        return {
+            generatorHash,
+            etag
+        };
+    } catch  {}
+    const legacyVersionSeparator = raw.indexOf(':');
+    if (raw.startsWith('client-generator-') && legacyVersionSeparator > 0) {
+        const etag = raw.slice(legacyVersionSeparator + 1).trim();
+        return {
+            etag: etag || void 0
+        };
+    }
+    return {
+        etag: raw
+    };
+};
+const writeClientFiles = async (ast, options, meta)=>{
+    const { outDir, astFile, clientFile, checksumFile } = resolveOutputPaths(options.out);
+    await external_node_fs_namespaceObject.promises.mkdir(outDir, {
+        recursive: true
+    });
+    const previous = await readCachedChecksum(checksumFile);
+    const checksum = meta?.checksum ?? hashAst(ast);
+    const etagBase = (meta?.etag ?? checksum).trim();
+    const hasSameGenerator = previous.generatorHash === CLIENT_GENERATOR_HASH;
+    const hasSameEtag = previous.etag === etagBase;
+    if (hasSameGenerator && hasSameEtag) return {
+        updated: false,
+        checksum,
+        etag: etagBase,
+        schemaVersion: meta?.schemaVersion,
+        generatedAt: meta?.generatedAt
+    };
+    const generated = (0, generate_namespaceObject.generateClientFiles)({
+        ast: ast
+    });
+    const astSource = generated.files[generated.astFile];
+    const clientSource = generated.files[generated.clientFile];
+    if (!astSource || !clientSource) throw new Error('Generated client sources were empty.');
+    await external_node_fs_namespaceObject.promises.writeFile(astFile, astSource, 'utf8');
+    await external_node_fs_namespaceObject.promises.writeFile(clientFile, clientSource, 'utf8');
+    await external_node_fs_namespaceObject.promises.writeFile(checksumFile, JSON.stringify({
+        generatorHash: CLIENT_GENERATOR_HASH,
+        etag: etagBase
+    }), 'utf8');
+    return {
+        updated: true,
+        checksum,
+        etag: etagBase,
+        schemaVersion: meta?.schemaVersion,
+        generatedAt: meta?.generatedAt
+    };
+};
+const startCommandRuntime = ({ command })=>{
+    const [commandName, ...commandArgs] = command;
+    if (!commandName) throw new Error('Missing command to run after livon sync.');
+    const child = (0, external_node_child_process_namespaceObject.spawn)(commandName, commandArgs, {
+        stdio: 'inherit',
+        env: process.env
+    });
+    const stopChild = ()=>{
+        if (child.killed) return;
+        child.kill('SIGTERM');
+    };
+    process.on('exit', stopChild);
+    process.on('SIGINT', ()=>{
+        stopChild();
+        process.exit(130);
+    });
+    process.on('SIGTERM', ()=>{
+        stopChild();
+        process.exit(143);
+    });
+    const waitForExit = new Promise((resolve, reject)=>{
+        child.on('error', (error)=>{
+            reject(error);
+        });
+        child.on('exit', (code, signal)=>{
+            const exitCode = 'number' == typeof code ? code : signal ? 1 : 0;
+            if (0 !== exitCode) console.error(`livon: linked command exited with code ${exitCode}`);
+            resolve(exitCode);
+            process.exit(exitCode);
+        });
+    });
+    return {
+        waitForExit
+    };
+};
+const run = async ()=>{
+    const cli = readCliInput(process.argv.slice(2));
+    const options = cli.options;
+    const commandRuntimeInput = cli.command.length > 0 ? {
+        command: cli.command
+    } : void 0;
+    let commandRuntime;
+    const ensureCommandRuntime = ()=>{
+        if (!commandRuntimeInput || commandRuntime) return;
+        commandRuntime = startCommandRuntime(commandRuntimeInput);
+    };
+    const execute = async ()=>{
+        const { checksumFile } = resolveOutputPaths(options.out);
+        const cached = await readCachedChecksum(checksumFile);
+        const useCachedEtag = cached.generatorHash === CLIENT_GENERATOR_HASH;
+        const cachedEtag = useCachedEtag ? cached.etag : void 0;
+        const result = await fetchAst(options, cachedEtag);
+        if (result.notModified) return;
+        if (void 0 === result.ast) throw new Error('Explain response missing AST.');
+        const writeResult = await writeClientFiles(result.ast, options, {
+            checksum: result.checksum,
+            etag: result.etag,
+            schemaVersion: result.schemaVersion,
+            generatedAt: result.generatedAt
+        });
+        if (writeResult.updated) {
+            const meta = [];
+            if (writeResult.schemaVersion) meta.push(`schema ${writeResult.schemaVersion}`);
+            if (writeResult.generatedAt) meta.push(`generated ${writeResult.generatedAt}`);
+            const metaInfo = meta.length > 0 ? `, ${meta.join(', ')}` : '';
+            console.log(`livon: client updated (checksum ${writeResult.checksum}${metaInfo})`);
+        }
+    };
+    const withRetry = async (action)=>{
+        const maxAttempts = 20;
+        const baseDelay = 250;
+        const runAttempt = async (attempt, resetApplied)=>{
+            try {
+                await action();
+                return;
+            } catch (error) {
+                const retryAware = error;
+                const shouldReset = Boolean(retryAware?.[RETRY_RESET_AFTER_CONNECTION]) && !resetApplied;
+                const nextAttempt = shouldReset ? 1 : attempt + 1;
+                const nextResetApplied = shouldReset ? true : resetApplied;
+                if (nextAttempt >= maxAttempts) throw new Error('livon: giving up after repeated retries');
+                const wait = baseDelay * Math.min(nextAttempt, 10);
+                console.warn(`livon: attempt ${nextAttempt}/${maxAttempts} failed: ${error instanceof Error ? error.message : String(error)} – retrying in ${wait}ms`);
+                await new Promise((resolve)=>setTimeout(resolve, wait));
+                await runAttempt(nextAttempt, nextResetApplied);
+            }
+        };
+        await runAttempt(0, false);
+    };
+    if (options.poll && options.poll > 0) {
+        let inFlight = false;
+        const tick = async ()=>{
+            if (inFlight) return;
+            inFlight = true;
+            try {
+                await withRetry(execute);
+                ensureCommandRuntime();
+            } catch (error) {
+                console.error('livon: poll error', error);
+            } finally{
+                inFlight = false;
+                setTimeout(tick, options.poll);
+            }
+        };
+        await tick();
+        return;
+    }
+    await withRetry(execute);
+    ensureCommandRuntime();
+    if (commandRuntime) {
+        const commandExitCode = await commandRuntime.waitForExit;
+        process.exit(commandExitCode);
+    }
+};
+run().catch((error)=>{
+    console.error(error);
+    process.exit(1);
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,574 @@
+import { generateClientFiles, getClientGeneratorFingerprint } from "@livon/client/generate";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises } from "node:fs";
+import node_path from "node:path";
+import ws_0 from "ws";
+import { pack, unpack } from "msgpackr";
+const RETRY_RESET_AFTER_CONNECTION = 'livon.retry.reset_after_connection';
+const createDefaultOptions = ()=>({
+        endpoint: '',
+        port: void 0,
+        out: '',
+        poll: void 0,
+        timeout: void 0,
+        event: '$explain',
+        method: 'POST',
+        headers: {},
+        payload: void 0
+    });
+const readOptionValue = ({ argv, index, arg })=>{
+    if (arg.includes('=')) return {
+        nextIndex: index + 1,
+        value: arg.split('=').slice(1).join('=')
+    };
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) return {
+        nextIndex: index + 1,
+        value: void 0
+    };
+    return {
+        nextIndex: index + 2,
+        value
+    };
+};
+const readCliArgs = ({ argv, index, options })=>{
+    const arg = argv[index];
+    if (!arg) return {
+        options,
+        command: []
+    };
+    if ('--' === arg) return {
+        options,
+        command: argv.slice(index + 1)
+    };
+    if (!arg.startsWith('-')) return {
+        options,
+        command: argv.slice(index)
+    };
+    if ('--no-event' === arg) return readCliArgs({
+        argv,
+        index: index + 1,
+        options: {
+            ...options,
+            event: void 0,
+            method: 'GET'
+        }
+    });
+    if (arg.startsWith('--endpoint')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                endpoint: value ?? ''
+            }
+        });
+    }
+    if (arg.startsWith('--out')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                out: value ?? ''
+            }
+        });
+    }
+    if (arg.startsWith('--poll')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                poll: value ? Number(value) : void 0
+            }
+        });
+    }
+    if (arg.startsWith('--timeout')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid --timeout value: ${value}`);
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    timeout: parsed
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--port')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid --port value: ${value}`);
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    port: parsed
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--event')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                event: value,
+                method: 'POST'
+            }
+        });
+    }
+    if (arg.startsWith('--method')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options: {
+                ...options,
+                method: value && 'GET' === value.toUpperCase() ? 'GET' : 'POST'
+            }
+        });
+    }
+    if (arg.startsWith('--header')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) {
+            const [key, ...rest] = value.split(':');
+            if (key && rest.length > 0) return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    headers: {
+                        ...options.headers,
+                        [key.trim()]: rest.join(':').trim()
+                    }
+                }
+            });
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    if (arg.startsWith('--payload')) {
+        const { value, nextIndex } = readOptionValue({
+            argv,
+            index,
+            arg
+        });
+        if (value) try {
+            return readCliArgs({
+                argv,
+                index: nextIndex,
+                options: {
+                    ...options,
+                    payload: JSON.parse(value)
+                }
+            });
+        } catch (error) {
+            throw new Error(`Invalid JSON for --payload: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return readCliArgs({
+            argv,
+            index: nextIndex,
+            options
+        });
+    }
+    return readCliArgs({
+        argv,
+        index: index + 1,
+        options
+    });
+};
+const readCliInput = (argv)=>{
+    const parsed = readCliArgs({
+        argv,
+        index: 0,
+        options: createDefaultOptions()
+    });
+    const options = {
+        ...parsed.options
+    };
+    if (!options.endpoint && options.port) options.endpoint = `ws://127.0.0.1:${options.port}/ws`;
+    if (!options.endpoint) throw new Error('Missing required --endpoint or --port');
+    if (options.port) options.endpoint = applyPortToEndpoint(options.endpoint, options.port);
+    if (!options.out) throw new Error('Missing required --out');
+    if (void 0 === options.event) throw new Error('Missing required --event for websocket mode.');
+    return {
+        options,
+        command: parsed.command
+    };
+};
+const applyPortToEndpoint = (endpoint, port)=>{
+    const url = new URL(endpoint);
+    if ('ws:' !== url.protocol && 'wss:' !== url.protocol) throw new Error('Endpoint must be ws:// or wss:// for websocket mode.');
+    url.port = String(port);
+    if (!url.pathname || '/' === url.pathname) url.pathname = '/ws';
+    return url.toString();
+};
+const hashAst = (ast)=>createHash('sha256').update(JSON.stringify(ast)).digest('hex');
+const compactMetadata = (metadata)=>{
+    if (!metadata) return;
+    return Object.keys(metadata).length > 0 ? metadata : void 0;
+};
+const compactContext = (context)=>{
+    if (!context || 0 === Object.keys(context).length) return;
+    return context;
+};
+const encodePayload = (value)=>pack(value);
+const decodePayload = (payload)=>payload ? unpack(payload) : void 0;
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const binaryFromSocketData = (data)=>{
+    if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data));
+    if ('string' == typeof data) throw new Error('Expected binary WebSocket payload.');
+    if (data instanceof ArrayBuffer) return new Uint8Array(data);
+    if (Buffer.isBuffer(data)) return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return new Uint8Array(Buffer.from(data));
+};
+const ensureEvent = (value)=>{
+    if (!value) throw new Error('Missing required --event for websocket mode.');
+    return value;
+};
+const buildWireEnvelope = (input)=>{
+    const metadata = compactMetadata(input.metadata);
+    const context = compactContext(input.context);
+    const base = {
+        event: input.event,
+        metadata,
+        context: context ? encodePayload(context) : void 0
+    };
+    return {
+        ...base,
+        payload: encodePayload(input.payload)
+    };
+};
+const DEFAULT_TIMEOUT_MS = 30000;
+const CLIENT_GENERATOR_HASH = getClientGeneratorFingerprint();
+const fetchAst = async (options, etag)=>{
+    const endpoint = options.endpoint.trim();
+    if (!endpoint.startsWith('ws://') && !endpoint.startsWith('wss://')) throw new Error('Endpoint must be ws:// or wss:// for $explain.');
+    return new Promise((resolve, reject)=>{
+        const ws = new ws_0(endpoint, {
+            headers: options.headers
+        });
+        let resolved = false;
+        let hadConnection = false;
+        const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const timeout = setTimeout(()=>{
+            if (!resolved) {
+                resolved = true;
+                ws.close();
+                reject(new Error('Timed out waiting for $explain response.'));
+            }
+        }, timeoutMs);
+        const finish = (result)=>{
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+            ws.close();
+            resolve(result);
+        };
+        const fail = (error)=>{
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+            ws.close();
+            const retryAware = error;
+            if (hadConnection) retryAware[RETRY_RESET_AFTER_CONNECTION] = true;
+            reject(error);
+        };
+        ws.on('error', (error)=>{
+            fail(error);
+        });
+        ws.on('open', ()=>{
+            hadConnection = true;
+            const eventName = ensureEvent(options.event);
+            const request = buildWireEnvelope({
+                event: eventName,
+                payload: options.payload ?? null,
+                metadata: etag ? {
+                    ifNoneMatch: etag
+                } : void 0
+            });
+            ws.send(pack(request));
+        });
+        ws.on('message', (data)=>{
+            let parsed;
+            try {
+                parsed = unpack(binaryFromSocketData(data));
+            } catch  {
+                return;
+            }
+            if (!isRecord(parsed)) return;
+            const envelope = parsed;
+            if (envelope.event && envelope.event !== options.event) return;
+            if (envelope.error) {
+                const decoded = decodePayload(envelope.error);
+                const message = decoded && 'object' == typeof decoded && 'message' in decoded ? String(decoded.message ?? 'Explain error') : 'Explain error';
+                fail(new Error(message));
+                return;
+            }
+            const payload = envelope.payload ? decodePayload(envelope.payload) : parsed;
+            if (!payload || 'object' != typeof payload) return;
+            const response = payload;
+            if (response.notModified) return void finish({
+                notModified: true,
+                etag: response.etag ?? etag
+            });
+            if ('ast' in response) finish({
+                ast: response.ast,
+                checksum: response.checksum,
+                schemaVersion: response.schemaVersion,
+                generatedAt: response.generatedAt,
+                etag: response.etag ?? response.checksum ?? etag
+            });
+        });
+    });
+};
+const resolveOutputPaths = (out)=>{
+    const isFile = node_path.extname(out).length > 0;
+    const outDir = isFile ? node_path.dirname(out) : out;
+    const astFile = node_path.join(outDir, 'ast.ts');
+    const clientFile = isFile ? out : node_path.join(outDir, 'client.ts');
+    const checksumFile = node_path.join(outDir, '.livon.client.checksum');
+    return {
+        outDir,
+        astFile,
+        clientFile,
+        checksumFile
+    };
+};
+const readCachedChecksum = async (checksumFile)=>{
+    const raw = (await promises.readFile(checksumFile, 'utf8').catch(()=>'')).trim();
+    if (!raw) return {};
+    if (raw.startsWith('{')) try {
+        const parsed = JSON.parse(raw);
+        const generatorHash = 'string' == typeof parsed.generatorHash ? parsed.generatorHash : void 0;
+        const etag = 'string' == typeof parsed.etag ? parsed.etag : void 0;
+        return {
+            generatorHash,
+            etag
+        };
+    } catch  {}
+    const legacyVersionSeparator = raw.indexOf(':');
+    if (raw.startsWith('client-generator-') && legacyVersionSeparator > 0) {
+        const etag = raw.slice(legacyVersionSeparator + 1).trim();
+        return {
+            etag: etag || void 0
+        };
+    }
+    return {
+        etag: raw
+    };
+};
+const writeClientFiles = async (ast, options, meta)=>{
+    const { outDir, astFile, clientFile, checksumFile } = resolveOutputPaths(options.out);
+    await promises.mkdir(outDir, {
+        recursive: true
+    });
+    const previous = await readCachedChecksum(checksumFile);
+    const checksum = meta?.checksum ?? hashAst(ast);
+    const etagBase = (meta?.etag ?? checksum).trim();
+    const hasSameGenerator = previous.generatorHash === CLIENT_GENERATOR_HASH;
+    const hasSameEtag = previous.etag === etagBase;
+    if (hasSameGenerator && hasSameEtag) return {
+        updated: false,
+        checksum,
+        etag: etagBase,
+        schemaVersion: meta?.schemaVersion,
+        generatedAt: meta?.generatedAt
+    };
+    const generated = generateClientFiles({
+        ast: ast
+    });
+    const astSource = generated.files[generated.astFile];
+    const clientSource = generated.files[generated.clientFile];
+    if (!astSource || !clientSource) throw new Error('Generated client sources were empty.');
+    await promises.writeFile(astFile, astSource, 'utf8');
+    await promises.writeFile(clientFile, clientSource, 'utf8');
+    await promises.writeFile(checksumFile, JSON.stringify({
+        generatorHash: CLIENT_GENERATOR_HASH,
+        etag: etagBase
+    }), 'utf8');
+    return {
+        updated: true,
+        checksum,
+        etag: etagBase,
+        schemaVersion: meta?.schemaVersion,
+        generatedAt: meta?.generatedAt
+    };
+};
+const startCommandRuntime = ({ command })=>{
+    const [commandName, ...commandArgs] = command;
+    if (!commandName) throw new Error('Missing command to run after livon sync.');
+    const child = spawn(commandName, commandArgs, {
+        stdio: 'inherit',
+        env: process.env
+    });
+    const stopChild = ()=>{
+        if (child.killed) return;
+        child.kill('SIGTERM');
+    };
+    process.on('exit', stopChild);
+    process.on('SIGINT', ()=>{
+        stopChild();
+        process.exit(130);
+    });
+    process.on('SIGTERM', ()=>{
+        stopChild();
+        process.exit(143);
+    });
+    const waitForExit = new Promise((resolve, reject)=>{
+        child.on('error', (error)=>{
+            reject(error);
+        });
+        child.on('exit', (code, signal)=>{
+            const exitCode = 'number' == typeof code ? code : signal ? 1 : 0;
+            if (0 !== exitCode) console.error(`livon: linked command exited with code ${exitCode}`);
+            resolve(exitCode);
+            process.exit(exitCode);
+        });
+    });
+    return {
+        waitForExit
+    };
+};
+const run = async ()=>{
+    const cli = readCliInput(process.argv.slice(2));
+    const options = cli.options;
+    const commandRuntimeInput = cli.command.length > 0 ? {
+        command: cli.command
+    } : void 0;
+    let commandRuntime;
+    const ensureCommandRuntime = ()=>{
+        if (!commandRuntimeInput || commandRuntime) return;
+        commandRuntime = startCommandRuntime(commandRuntimeInput);
+    };
+    const execute = async ()=>{
+        const { checksumFile } = resolveOutputPaths(options.out);
+        const cached = await readCachedChecksum(checksumFile);
+        const useCachedEtag = cached.generatorHash === CLIENT_GENERATOR_HASH;
+        const cachedEtag = useCachedEtag ? cached.etag : void 0;
+        const result = await fetchAst(options, cachedEtag);
+        if (result.notModified) return;
+        if (void 0 === result.ast) throw new Error('Explain response missing AST.');
+        const writeResult = await writeClientFiles(result.ast, options, {
+            checksum: result.checksum,
+            etag: result.etag,
+            schemaVersion: result.schemaVersion,
+            generatedAt: result.generatedAt
+        });
+        if (writeResult.updated) {
+            const meta = [];
+            if (writeResult.schemaVersion) meta.push(`schema ${writeResult.schemaVersion}`);
+            if (writeResult.generatedAt) meta.push(`generated ${writeResult.generatedAt}`);
+            const metaInfo = meta.length > 0 ? `, ${meta.join(', ')}` : '';
+            console.log(`livon: client updated (checksum ${writeResult.checksum}${metaInfo})`);
+        }
+    };
+    const withRetry = async (action)=>{
+        const maxAttempts = 20;
+        const baseDelay = 250;
+        const runAttempt = async (attempt, resetApplied)=>{
+            try {
+                await action();
+                return;
+            } catch (error) {
+                const retryAware = error;
+                const shouldReset = Boolean(retryAware?.[RETRY_RESET_AFTER_CONNECTION]) && !resetApplied;
+                const nextAttempt = shouldReset ? 1 : attempt + 1;
+                const nextResetApplied = shouldReset ? true : resetApplied;
+                if (nextAttempt >= maxAttempts) throw new Error('livon: giving up after repeated retries');
+                const wait = baseDelay * Math.min(nextAttempt, 10);
+                console.warn(`livon: attempt ${nextAttempt}/${maxAttempts} failed: ${error instanceof Error ? error.message : String(error)} – retrying in ${wait}ms`);
+                await new Promise((resolve)=>setTimeout(resolve, wait));
+                await runAttempt(nextAttempt, nextResetApplied);
+            }
+        };
+        await runAttempt(0, false);
+    };
+    if (options.poll && options.poll > 0) {
+        let inFlight = false;
+        const tick = async ()=>{
+            if (inFlight) return;
+            inFlight = true;
+            try {
+                await withRetry(execute);
+                ensureCommandRuntime();
+            } catch (error) {
+                console.error('livon: poll error', error);
+            } finally{
+                inFlight = false;
+                setTimeout(tick, options.poll);
+            }
+        };
+        await tick();
+        return;
+    }
+    await withRetry(execute);
+    ensureCommandRuntime();
+    if (commandRuntime) {
+        const commandExitCode = await commandRuntime.waitForExit;
+        process.exit(commandExitCode);
+    }
+};
+run().catch((error)=>{
+    console.error(error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@livon/cli",
+  "version": "0.27.0-rc.1",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "bin": {
+    "livon": "bin/livon.js"
+  },
+  "dependencies": {
+    "msgpackr": "latest",
+    "ws": "latest",
+    "@livon/client": "0.27.0-rc.1",
+    "@livon/config": "0.27.0-rc.1"
+  },
+  "devDependencies": {
+    "@rslib/core": "latest",
+    "@types/ws": "latest",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "@types/node": "latest",
+    "eslint": "9.0.0",
+    "typescript": "latest",
+    "@livon/config": "0.27.0-rc.1"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "build:watch": "rslib dev",
+    "dev": "true",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "true",
+    "test:unit": "true",
+    "test:integration": "true"
+  }
+}