@dinoxx/dinox-cli 2.13.1 → 2.14.0

package/dist/requests/store.js

@@ -0,0 +1,190 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { getDataDir } from '../config/paths.js';
+import { DinoxError } from '../utils/errors.js';
+const RETENTION_MS = 24 * 60 * 60 * 1000;
+/** Ids the CLI generates only cover its own single retry; their output need not linger. */
+const AUTO_RETENTION_MS = 10 * 60 * 1000;
+export const AUTO_REQUEST_ID_PREFIX = 'auto:';
+const instanceId = randomUUID();
+const cleanedDirs = new Set();
+export function validateRequestId(key) {
+    if (typeof key !== 'string' || key.length < 1 || key.length > 128 || /[^A-Za-z0-9._:-]/.test(key)) {
+        throw new DinoxError('Request id must contain 1–128 characters from A-Z, a-z, 0-9, ., _, :, -.', { code: 'INVALID_ARGUMENT' });
+    }
+    return key;
+}
+/** Reads only options before the argument terminator. */
+export function requestIdFromArgv(argv) {
+    let key;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--')
+            break;
+        if (argv[i] === '--request-id')
+            key = validateRequestId(argv[++i] ?? '');
+        else if (argv[i].startsWith('--request-id='))
+            key = validateRequestId(argv[i].slice(13));
+    }
+    return key;
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function argvHash(argv) {
+    const filtered = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--') {
+            filtered.push(...argv.slice(i));
+            break;
+        }
+        if (argv[i] === '--request-id') {
+            i++;
+            continue;
+        }
+        if (argv[i].startsWith('--request-id='))
+            continue;
+        filtered.push(argv[i]);
+    }
+    return hash(JSON.stringify(filtered));
+}
+function ownerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function cleanup(dir) {
+    if (cleanedDirs.has(dir))
+        return;
+    cleanedDirs.add(dir);
+    const lockPath = path.join(dir, '.cleanup.lock');
+    let lock;
+    try {
+        lock = await fs.open(lockPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return;
+        throw error;
+    }
+    try {
+        for (const name of await fs.readdir(dir)) {
+            if (!/^[a-f0-9]{64}\.json$/.test(name))
+                continue;
+            const file = path.join(dir, name);
+            try {
+                const age = Date.now() - (await fs.stat(file)).mtimeMs;
+                if (age <= AUTO_RETENTION_MS)
+                    continue;
+                const record = JSON.parse(await fs.readFile(file, 'utf8'));
+                if (!record.auto && age <= RETENTION_MS)
+                    continue;
+                // Never expire a command that is still executing, even after 24 hours.
+                if (record.state === 'running' && ownerAlive(record.pid))
+                    continue;
+                await fs.unlink(file);
+            }
+            catch {
+                // Cleanup is best effort; another process may already have removed it.
+            }
+        }
+    }
+    finally {
+        await lock.close();
+        await fs.rm(lockPath, { force: true });
+    }
+}
+/** Claims once across processes and preserves the complete output for replay. */
+export async function runWithRequestId(key, argv, run, opts = {}) {
+    validateRequestId(key);
+    const dir = path.join(getDataDir(), 'requests');
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700);
+    await cleanup(dir);
+    const file = path.join(dir, `${hash(key)}.json`);
+    const record = {
+        version: 1, argvHash: argvHash(argv), state: 'running', auto: key.startsWith(AUTO_REQUEST_ID_PREFIX), pid: process.pid,
+        instanceId, startedAt: Date.now(),
+    };
+    const deadline = Date.now() + (opts.waitTimeoutMs ?? 300_000);
+    try {
+        const handle = await fs.open(file, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(record));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        while (true) {
+            let previous;
+            try {
+                previous = JSON.parse(await fs.readFile(file, 'utf8'));
+            }
+            catch (error) {
+                // A claimant may still be writing, or may have rejected and removed its claim.
+                if (error.code === 'ENOENT') {
+                    return runWithRequestId(key, argv, run, { ...opts, waitTimeoutMs: Math.max(0, deadline - Date.now()) });
+                }
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                if (Date.now() >= deadline) {
+                    throw new DinoxError('Request claim is not readable yet.', { code: 'REQUEST_IN_PROGRESS', recoverable: true });
+                }
+                await delay(opts.pollIntervalMs ?? 100);
+                continue;
+            }
+            if (previous.argvHash !== record.argvHash) {
+                throw new DinoxError('Request id was used with different arguments.', { code: 'REQUEST_ID_CONFLICT' });
+            }
+            if (previous.state === 'done' && previous.result)
+                return previous.result;
+            if (!ownerAlive(previous.pid)) {
+                throw new DinoxError('The earlier request stopped; its outcome is unknown.', {
+                    code: 'REQUEST_INTERRUPTED',
+                    suggestion: 'Verify the result, then retry with a new request id.',
+                });
+            }
+            if (Date.now() >= deadline) {
+                throw new DinoxError('The earlier request is still running.', {
+                    code: 'REQUEST_IN_PROGRESS', recoverable: true,
+                    suggestion: 'Rerun the exact same command with the same request id.',
+                });
+            }
+            await delay(opts.pollIntervalMs ?? 100);
+        }
+    }
+    let result;
+    try {
+        result = await run();
+    }
+    catch (error) {
+        await fs.unlink(file);
+        throw error;
+    }
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await fs.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({ ...record, state: 'done', finishedAt: Date.now(), result }));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+    return result;
+}

package/dist/runCli.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(input: string[], onFatalError?: (error: unknown) => void): Promise<number>;
+export declare function printCliError(error: unknown, argv: string[]): number;

package/dist/runCli.js

@@ -0,0 +1,64 @@
+import { createCli } from './cli.js';
+import { buildStructuredErrorPayload, isDinoxError } from './utils/errors.js';
+import { clearRequestedStructuredOutputFormat, parseStructuredOutputFormatFromArgv, printError, printHumanReadableError, setRequestedStructuredOutputFormat, } from './utils/output.js';
+function normalizeArgv(argv) {
+    // pnpm/npm script forwarding can prepend a standalone "--".
+    if (argv[0] === '--') {
+        return argv.slice(1);
+    }
+    return argv;
+}
+function isVerbose(argv) {
+    return argv.includes('--verbose');
+}
+function isCommanderError(error) {
+    return Boolean(error)
+        && typeof error === 'object'
+        && typeof error.code === 'string'
+        && error.code.startsWith('commander.')
+        && typeof error.exitCode === 'number';
+}
+export async function runCli(input, onFatalError) {
+    const argv = normalizeArgv(input);
+    try {
+        await createCli().parseAsync(['node', process.argv[1] ?? 'dino', ...argv]);
+        return 0;
+    }
+    catch (error) {
+        onFatalError?.(error);
+        return printCliError(error, argv);
+    }
+}
+export function printCliError(error, argv) {
+    if (isCommanderError(error)) {
+        return error.exitCode === 0 ? 0 : 2;
+    }
+    let format = null;
+    try {
+        format = parseStructuredOutputFormatFromArgv(argv);
+    }
+    catch {
+        format = null;
+    }
+    const verbose = isVerbose(argv);
+    const payload = buildStructuredErrorPayload(error, verbose);
+    const exitCode = isDinoxError(error) ? error.exitCode : 1;
+    if (format) {
+        setRequestedStructuredOutputFormat(format);
+        printError(payload, format);
+        clearRequestedStructuredOutputFormat();
+        return exitCode;
+    }
+    printHumanReadableError(payload.message);
+    if (payload.suggested_action) {
+        printHumanReadableError(`suggested action: ${payload.suggested_action.command}`);
+        printHumanReadableError(`reason: ${payload.suggested_action.reason}`);
+    }
+    else if (payload.suggestion) {
+        printHumanReadableError(`suggestion: ${payload.suggestion}`);
+    }
+    if (verbose && payload.stack) {
+        printHumanReadableError(payload.stack);
+    }
+    return exitCode;
+}

package/dist/utils/argValue.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import { DinoxError } from './errors.js';
+import { resolveUserPath } from './requestContext.js';
 export async function readStringOrFile(value) {
     if (!value.startsWith('@')) {
         return value;
@@ -9,7 +10,7 @@ export async function readStringOrFile(value) {
         throw new DinoxError('Invalid @file syntax: expected @<path>');
     }
     try {
-        return await fs.readFile(filePath, 'utf8');
+        return await fs.readFile(resolveUserPath(filePath), 'utf8');
     }
     catch (error) {
         throw new DinoxError(`Failed to read file: ${filePath}`, { cause: error });

package/dist/utils/errorCodes.d.ts

@@ -47,6 +47,10 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "Another process is writing the CLI config.";
     };
+    readonly DAEMON_COMMAND_NOT_FORWARDABLE: {
+        readonly exitCode: 2;
+        readonly description: "The command must run in the CLI process.";
+    };
     readonly DAEMON_ERROR: {
         readonly exitCode: 5;
         readonly description: "The background daemon reported an error.";
@@ -79,6 +83,10 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "The service manager (launchd / systemd) rejected a daemon service operation.";
     };
+    readonly DAEMON_SERVICE_FOREIGN: {
+        readonly exitCode: 1;
+        readonly description: "The daemon service runs another dino install; it was left unchanged.";
+    };
     readonly DAEMON_SERVICE_UNSUPPORTED: {
         readonly exitCode: 5;
         readonly description: "The daemon cannot run as a login service on this platform or with this auth setup.";
@@ -343,6 +351,18 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "A property value does not match its definition.";
     };
+    readonly REQUEST_ID_CONFLICT: {
+        readonly exitCode: 2;
+        readonly description: "The request id was already used for different arguments.";
+    };
+    readonly REQUEST_INTERRUPTED: {
+        readonly exitCode: 1;
+        readonly description: "The earlier request owner exited; its outcome is unknown.";
+    };
+    readonly REQUEST_IN_PROGRESS: {
+        readonly exitCode: 1;
+        readonly description: "The earlier request is still running; retry with the same id.";
+    };
     readonly SAVED_VIEW_FILTER_CORRUPT: {
         readonly exitCode: 1;
         readonly description: "A stored saved view filter is corrupt.";

package/dist/utils/errorCodes.js

@@ -17,6 +17,7 @@ export const ERROR_CODES = {
     COMMAND_FAILED: { exitCode: 1, description: 'Generic command failure without a more specific code.' },
     CONFIG_INVALID_JSON: { exitCode: 1, description: 'The CLI config file is not valid JSON.' },
     CONFIG_WRITE_BUSY: { exitCode: 1, description: 'Another process is writing the CLI config.' },
+    DAEMON_COMMAND_NOT_FORWARDABLE: { exitCode: 2, description: 'The command must run in the CLI process.' },
     DAEMON_ERROR: { exitCode: 5, description: 'The background daemon reported an error.' },
     DAEMON_INSTANCE_CHANGED: { exitCode: 1, description: 'The daemon instance changed between requests.' },
     DAEMON_INSTANCE_MISMATCH: { exitCode: 1, description: 'The running daemon belongs to a different CLI version or account.' },
@@ -25,6 +26,7 @@ export const ERROR_CODES = {
     DAEMON_RELEASE_FAILED: { exitCode: 1, description: 'The daemon could not release database ownership.' },
     DAEMON_RELEASE_TIMEOUT: { exitCode: 1, description: 'The daemon did not release database ownership in time.' },
     DAEMON_SERVICE_FAILED: { exitCode: 1, description: 'The service manager (launchd / systemd) rejected a daemon service operation.' },
+    DAEMON_SERVICE_FOREIGN: { exitCode: 1, description: 'The daemon service runs another dino install; it was left unchanged.' },
     DAEMON_SERVICE_UNSUPPORTED: { exitCode: 5, description: 'The daemon cannot run as a login service on this platform or with this auth setup.' },
     DAEMON_STALE: { exitCode: 5, description: 'The daemon state is stale and needs a restart.' },
     DAEMON_START_FAILED: { exitCode: 5, description: 'The daemon process failed to start.' },
@@ -91,6 +93,9 @@ export const ERROR_CODES = {
     PROPERTY_UNIQUE_ID_TYPE_MISMATCH: { exitCode: 1, description: 'A unique-id setting was supplied for a different property type.' },
     PROPERTY_URL_INVALID: { exitCode: 1, description: 'A url property value is invalid.' },
     PROPERTY_VALUE_INVALID: { exitCode: 1, description: 'A property value does not match its definition.' },
+    REQUEST_ID_CONFLICT: { exitCode: 2, description: 'The request id was already used for different arguments.' },
+    REQUEST_INTERRUPTED: { exitCode: 1, description: 'The earlier request owner exited; its outcome is unknown.' },
+    REQUEST_IN_PROGRESS: { exitCode: 1, description: 'The earlier request is still running; retry with the same id.' },
     SAVED_VIEW_FILTER_CORRUPT: { exitCode: 1, description: 'A stored saved view filter is corrupt.' },
     SAVED_VIEW_FILTER_TOO_COMPLEX: { exitCode: 1, description: 'The saved view filter exceeds supported complexity.' },
     SAVED_VIEW_FILTER_VALUE_REQUIRED: { exitCode: 5, description: 'A saved view filter condition is missing its value.' },

package/dist/utils/output.d.ts

@@ -2,6 +2,8 @@ export type StructuredOutputFormat = 'yaml' | 'json';
 export type StructuredNoticeMap = Record<string, unknown>;
 export declare function toYaml(value: unknown): string;
 export declare function toJson(value: unknown): string;
+export declare function writeToStdout(text: string): void;
+export declare function writeToStderr(text: string): void;
 export declare function printHumanReadableLine(text: string): void;
 export declare function printHumanReadableBlock(text: string): void;
 export declare function printHumanReadableWarning(text: string): void;

package/dist/utils/output.js

@@ -1,6 +1,7 @@
 import { stringify as stringifyYaml } from 'yaml';
 import { DinoxError } from './errors.js';
 import { sanitizeForTerminal } from './terminalSanitization.js';
+import { requestContext } from './requestContext.js';
 let requestedStructuredOutputFormat = null;
 let pendingStructuredNoticeProvider = null;
 export function toYaml(value) {
@@ -12,10 +13,20 @@ export function toYaml(value) {
 export function toJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
-function writeToStdout(text) {
+export function writeToStdout(text) {
+    const context = requestContext.getStore();
+    if (context) {
+        context.stdout.push(text);
+        return;
+    }
     process.stdout.write(text);
 }
-function writeToStderr(text) {
+export function writeToStderr(text) {
+    const context = requestContext.getStore();
+    if (context) {
+        context.stderr.push(text);
+        return;
+    }
     process.stderr.write(text);
 }
 export function printHumanReadableLine(text) {
@@ -92,25 +103,38 @@ export function parseStructuredOutputFormatFromArgv(argv) {
     return explicitFormat ?? (hasLegacyJson ? 'yaml' : null);
 }
 export function setRequestedStructuredOutputFormat(format) {
+    const context = requestContext.getStore();
+    if (context) {
+        context.format = format;
+        return;
+    }
     requestedStructuredOutputFormat = format;
 }
 export function clearRequestedStructuredOutputFormat() {
-    requestedStructuredOutputFormat = null;
+    setRequestedStructuredOutputFormat(null);
 }
 export function getRequestedStructuredOutputFormat() {
-    return requestedStructuredOutputFormat;
+    const context = requestContext.getStore();
+    return context ? context.format : requestedStructuredOutputFormat;
 }
 export function setPendingStructuredNoticeProvider(provider) {
+    const context = requestContext.getStore();
+    if (context) {
+        context.noticeProvider = provider;
+        return;
+    }
     pendingStructuredNoticeProvider = provider;
 }
 export function clearPendingStructuredNoticeProvider() {
-    pendingStructuredNoticeProvider = null;
+    setPendingStructuredNoticeProvider(null);
 }
 function getPendingStructuredNotice() {
-    if (!pendingStructuredNoticeProvider) {
+    const context = requestContext.getStore();
+    const provider = context ? context.noticeProvider : pendingStructuredNoticeProvider;
+    if (!provider) {
         return null;
     }
-    return pendingStructuredNoticeProvider();
+    return provider();
 }
 export function printStructuredData(value, format = getRequestedStructuredOutputFormat()) {
     if (format === 'json') {

package/dist/utils/requestContext.d.ts

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { ResolvedDinoxConfig } from '../config/types.js';
+import type { StructuredNoticeMap, StructuredOutputFormat } from './output.js';
+export type RequestContext = {
+    stdout: string[];
+    stderr: string[];
+    format: StructuredOutputFormat | null;
+    noticeProvider: (() => StructuredNoticeMap | null) | null;
+    cwd: string;
+    daemon?: {
+        db: AbstractPowerSyncDatabase;
+        config: ResolvedDinoxConfig;
+        /**
+         * Set after the daemon reconnected (wake from sleep, network change): the
+         * stream is only known to be current once a checkpoint completes after it.
+         */
+        syncUnconfirmedSince?: () => string | null;
+    };
+};
+export declare const requestContext: AsyncLocalStorage<RequestContext>;
+export declare function resolveUserPath(p: string): string;
+export declare function assertStdinAvailable(): void;
+export declare const localCommandExecution: AsyncLocalStorage<boolean>;

package/dist/utils/requestContext.js

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import path from 'node:path';
+import { DinoxError } from './errors.js';
+export const requestContext = new AsyncLocalStorage();
+export function resolveUserPath(p) {
+    return path.resolve(requestContext.getStore()?.cwd ?? process.cwd(), p);
+}
+export function assertStdinAvailable() {
+    if (requestContext.getStore()?.daemon) {
+        throw new DinoxError('Reading stdin inside the daemon is not supported.', { code: 'USAGE_ERROR' });
+    }
+}
+export const localCommandExecution = new AsyncLocalStorage();

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {
+    "bench:startup": "node scripts/bench-startup.mjs",
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/add-shebang.mjs",
     "dev": "tsx src/dinox.ts",
     "prepublishOnly": "pnpm run skills:check && pnpm run build",