@dinoxx/dinox-cli 1.1.1 → 2.1.0

package/dist/commands/writeConfirmation.d.ts

@@ -0,0 +1,13 @@
+export type ConfirmedWriteOptions = {
+    dryRun?: boolean;
+    confirm?: boolean;
+    expectedCount?: number | null;
+};
+export declare function parseExpectedCount(value: unknown): number | null;
+export declare function assertConfirmedWrite(args: {
+    operation: string;
+    schemaPath: string;
+    actualCount: number;
+    options?: ConfirmedWriteOptions;
+}): void;
+export declare function assertWriteConfirmationProvided(operation: string, options?: ConfirmedWriteOptions): void;

package/dist/commands/writeConfirmation.js

@@ -0,0 +1,54 @@
+import { DinoxError } from '../utils/errors.js';
+export function parseExpectedCount(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    if (typeof value !== 'string') {
+        throw new DinoxError('--expected-count must be a non-negative integer');
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new DinoxError('--expected-count must be a non-negative integer');
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new DinoxError('--expected-count must be a non-negative integer');
+    }
+    return parsed;
+}
+export function assertConfirmedWrite(args) {
+    if (args.options?.dryRun) {
+        return;
+    }
+    const options = args.options;
+    assertWriteConfirmationProvided(args.operation, options);
+    const expectedCount = options?.expectedCount;
+    if (expectedCount === undefined || expectedCount === null) {
+        throw new DinoxError(`${args.operation} requires --expected-count <n> for writes`);
+    }
+    if (expectedCount !== args.actualCount) {
+        throw new DinoxError(`--expected-count ${expectedCount} does not match current affected record count ${args.actualCount}`, {
+            code: 'PRECONDITION_FAILED',
+            details: {
+                expectedCount,
+                actualCount: args.actualCount,
+            },
+            suggestion: `Re-run the merge with --dry-run, review changes.affected_count, then retry with the matching count. See \`dino schema ${args.schemaPath} --format json\`.`,
+            suggestedAction: {
+                command: `dino schema ${args.schemaPath} --format json`,
+                reason: 'Review the merge guard contract, then run a fresh dry-run before retrying.',
+            },
+        });
+    }
+}
+export function assertWriteConfirmationProvided(operation, options) {
+    if (options?.dryRun) {
+        return;
+    }
+    if (!options?.confirm) {
+        throw new DinoxError(`${operation} requires --confirm for writes`);
+    }
+    if (options.expectedCount === undefined || options.expectedCount === null) {
+        throw new DinoxError(`${operation} requires --expected-count <n> for writes`);
+    }
+}

package/dist/config/resolve.js

@@ -2,8 +2,7 @@ import crypto from 'node:crypto';
 import { POWERSYNC_DEFAULT_ENDPOINT, POWERSYNC_DEFAULT_TOKEN_ENDPOINT, POWERSYNC_DEFAULT_UPLOAD_BASE_URL, } from './serviceEndpoints.js';
 import { normalizeAuthToken, readEnvAuthToken } from '../utils/authToken.js';
 import { parseSyncTimeoutMs } from '../utils/syncTimeout.js';
-const DEFAULT_UPLOAD_V4_PATH = '/powersync/v4/uploadData';
-const DEFAULT_UPLOAD_V2_PATH = '/powersync/v2/uploadData';
+const DEFAULT_UPLOAD_PATH = '/powersync/v6/uploadData';
 const DEFAULT_SYNC_TIMEOUT_MS = 300_000;
 function nonEmptyString(value) {
     if (typeof value !== 'string') {
@@ -24,8 +23,7 @@ export function fingerprintDaemonRuntimeConfig(config) {
             endpoint: config.powersync.endpoint,
             tokenEndpoint: config.powersync.tokenEndpoint,
             uploadBaseUrl: config.powersync.uploadBaseUrl,
-            uploadV4Path: config.powersync.uploadV4Path,
-            uploadV2Path: config.powersync.uploadV2Path,
+            uploadPath: config.powersync.uploadPath,
         },
         sync: {
             timeoutMs: config.sync.timeoutMs,
@@ -40,13 +38,11 @@ export function resolveConfig(raw) {
     const fileEmail = nonEmptyString(raw.auth?.email ?? undefined) ?? raw.auth?.email ?? undefined;
     const fileUserInfoSyncedAt = nonEmptyString(raw.auth?.userInfoSyncedAt);
     const fileTokenEndpoint = nonEmptyString(raw.powersync?.tokenEndpoint);
-    const fileUploadV4Path = nonEmptyString(raw.powersync?.uploadV4Path);
-    const fileUploadV2Path = nonEmptyString(raw.powersync?.uploadV2Path);
+    const fileUploadPath = nonEmptyString(raw.powersync?.uploadPath);
     const fileTimeoutMs = parseSyncTimeoutMs(raw.sync?.timeoutMs, { invalid: 'undefined' });
     const envAuth = readEnvAuthToken();
     const envTokenEndpoint = nonEmptyString(process.env.DINOX_POWERSYNC_TOKEN_ENDPOINT) ?? nonEmptyString(process.env.POWERSYNC_TOKEN_ENDPOINT);
-    const envUploadV4Path = nonEmptyString(process.env.DINOX_POWERSYNC_UPLOAD_V4_PATH);
-    const envUploadV2Path = nonEmptyString(process.env.DINOX_POWERSYNC_UPLOAD_V2_PATH);
+    const envUploadPath = nonEmptyString(process.env.DINOX_POWERSYNC_UPLOAD_PATH);
     const envTimeoutMs = parseSyncTimeoutMs(process.env.DINOX_SYNC_TIMEOUT_MS, { invalid: 'undefined' });
     const effectiveAuth = envAuth ?? fileAuth;
     const canReusePersistedIdentity = !envAuth || envAuth === fileAuth;
@@ -63,8 +59,7 @@ export function resolveConfig(raw) {
             endpoint: POWERSYNC_DEFAULT_ENDPOINT,
             tokenEndpoint: envTokenEndpoint ?? fileTokenEndpoint ?? POWERSYNC_DEFAULT_TOKEN_ENDPOINT,
             uploadBaseUrl: POWERSYNC_DEFAULT_UPLOAD_BASE_URL,
-            uploadV4Path: envUploadV4Path ?? fileUploadV4Path ?? DEFAULT_UPLOAD_V4_PATH,
-            uploadV2Path: envUploadV2Path ?? fileUploadV2Path ?? DEFAULT_UPLOAD_V2_PATH,
+            uploadPath: envUploadPath ?? fileUploadPath ?? DEFAULT_UPLOAD_PATH,
         },
         sync: {
             timeoutMs: envTimeoutMs ?? fileTimeoutMs ?? DEFAULT_SYNC_TIMEOUT_MS,

package/dist/config/types.d.ts

@@ -21,10 +21,8 @@ export type DinoxConfig = {
         tokenEndpoint?: string;
         /** Base URL for upload endpoints. */
         uploadBaseUrl?: string;
-        /** Defaults to /powersync/v4/uploadData */
-        uploadV4Path?: string;
-        /** Defaults to /powersync/v2/uploadData */
-        uploadV2Path?: string;
+        /** Batch upload endpoint path. Defaults to /powersync/v6/uploadData */
+        uploadPath?: string;
     };
     sync?: {
         /** Default sync/connect timeout in milliseconds. */
@@ -45,8 +43,7 @@ export type ResolvedDinoxConfig = {
         endpoint: string;
         tokenEndpoint: string;
         uploadBaseUrl: string;
-        uploadV4Path: string;
-        uploadV2Path: string;
+        uploadPath: string;
     };
     sync: {
         timeoutMs: number;

package/dist/constants/links.d.ts

@@ -1 +1,18 @@
-export declare const SKILLS_REPO_URL = "https://github.com/ryzencool/dinox-cli/tree/main/skills";
+export declare const SKILLS_REPO_SLUG = "ryzencool/dinox-cli-skills";
+export declare const SKILLS_REPO_URL = "https://github.com/ryzencool/dinox-cli-skills";
+export declare const SKILLS_INSTALLER_NAME = "skills";
+export declare const SKILLS_INSTALLER_VERSION = "1.5.16";
+export declare const SKILLS_INSTALL_AGENTS: readonly ["codex", "claude-code", "hermes-agent", "openclaw"];
+export type SkillsInstallerMetadata = {
+    name: typeof SKILLS_INSTALLER_NAME;
+    version: typeof SKILLS_INSTALLER_VERSION;
+};
+export type SkillsReleaseMetadata = {
+    repository: string;
+    version: string;
+    tag: string;
+    release: string;
+    installer: SkillsInstallerMetadata;
+    installCommand: string;
+};
+export declare function getSkillsReleaseMetadata(version: string): SkillsReleaseMetadata;

package/dist/constants/links.js

@@ -1 +1,26 @@
-export const SKILLS_REPO_URL = 'https://github.com/ryzencool/dinox-cli/tree/main/skills';
+export const SKILLS_REPO_SLUG = 'ryzencool/dinox-cli-skills';
+export const SKILLS_REPO_URL = `https://github.com/${SKILLS_REPO_SLUG}`;
+export const SKILLS_INSTALLER_NAME = 'skills';
+export const SKILLS_INSTALLER_VERSION = '1.5.16';
+export const SKILLS_INSTALL_AGENTS = Object.freeze([
+    'codex',
+    'claude-code',
+    'hermes-agent',
+    'openclaw',
+]);
+export function getSkillsReleaseMetadata(version) {
+    const normalizedVersion = version.trim();
+    const tag = `v${normalizedVersion}`;
+    const agentFlags = SKILLS_INSTALL_AGENTS.map((agent) => `-a ${agent}`).join(' ');
+    return {
+        repository: SKILLS_REPO_URL,
+        version: normalizedVersion,
+        tag,
+        release: `${SKILLS_REPO_URL}/tree/${encodeURIComponent(tag)}`,
+        installer: {
+            name: SKILLS_INSTALLER_NAME,
+            version: SKILLS_INSTALLER_VERSION,
+        },
+        installCommand: `npx --yes ${SKILLS_INSTALLER_NAME}@${SKILLS_INSTALLER_VERSION} add ${SKILLS_REPO_SLUG}#${tag} -g ${agentFlags} --skill '*' -y`,
+    };
+}

package/dist/contract/snapshot.d.ts

@@ -0,0 +1,30 @@
+export type ContractOption = {
+    name: string;
+    required: boolean;
+    type?: string;
+    enum?: string[];
+};
+export type ContractCommand = {
+    path: string;
+    command: string;
+    risk: string;
+    auth: string;
+    arguments: Array<{
+        name: string;
+        required: boolean;
+    }>;
+    options: ContractOption[];
+    outputFields: string[];
+    outputMetaFields: string[];
+};
+export type CliContractSnapshot = {
+    contractVersion: 1;
+    cliVersion: string;
+    commands: ContractCommand[];
+    errorCodes: Record<string, number>;
+};
+export declare function buildContractSnapshot(cliVersion: string): CliContractSnapshot;
+export declare function renderContractSnapshot(snapshot: CliContractSnapshot): string;
+/** Changes that can break an existing agent or script that relied on the previous contract. */
+export declare function findBreakingChanges(previous: CliContractSnapshot, next: CliContractSnapshot): string[];
+export declare function majorVersion(version: string): number;

package/dist/contract/snapshot.js

@@ -0,0 +1,114 @@
+// Machine-readable snapshot of the agent-facing CLI contract: command paths, arguments,
+// options, risk/auth, structured output fields, and error codes with exit statuses.
+// The committed copy (contract/cli-contract.json) makes every contract change visible in
+// review, and `findBreakingChanges` refuses breaking changes without a major version bump.
+import { listCommandSchemas } from '../commands/schema/spec.js';
+import { ERROR_CODES } from '../utils/errorCodes.js';
+const RISK_ORDER = ['read', 'write', 'high-risk-write'];
+function flagOf(optionName) {
+    return optionName.match(/--[a-z0-9][a-z0-9-]*/i)?.[0] ?? optionName;
+}
+export function buildContractSnapshot(cliVersion) {
+    const commands = listCommandSchemas()
+        .map((schema) => ({
+        path: schema.path,
+        command: schema.command,
+        risk: schema.risk,
+        auth: schema.auth,
+        arguments: (schema.arguments ?? []).map((argument) => ({ name: argument.name, required: argument.required })),
+        options: (schema.options ?? [])
+            .map((option) => ({
+            name: option.name,
+            required: option.required === true,
+            ...(option.type ? { type: option.type } : {}),
+            ...(option.enum ? { enum: [...option.enum] } : {}),
+        }))
+            .sort((left, right) => flagOf(left.name).localeCompare(flagOf(right.name))),
+        outputFields: [...(schema.output.fields ?? [])],
+        outputMetaFields: [...(schema.output.metaFields ?? [])],
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    const errorCodes = Object.fromEntries(Object.keys(ERROR_CODES).sort().map((code) => [code, ERROR_CODES[code].exitCode]));
+    return { contractVersion: 1, cliVersion, commands, errorCodes };
+}
+export function renderContractSnapshot(snapshot) {
+    return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+/** Changes that can break an existing agent or script that relied on the previous contract. */
+export function findBreakingChanges(previous, next) {
+    const changes = [];
+    const nextCommands = new Map(next.commands.map((command) => [command.path, command]));
+    for (const before of previous.commands) {
+        const after = nextCommands.get(before.path);
+        if (!after) {
+            changes.push(`command ${before.path} was removed`);
+            continue;
+        }
+        if (after.command !== before.command) {
+            changes.push(`command ${before.path} changed invocation from \`${before.command}\` to \`${after.command}\``);
+        }
+        if (RISK_ORDER.indexOf(after.risk) > RISK_ORDER.indexOf(before.risk)) {
+            changes.push(`command ${before.path} risk escalated from ${before.risk} to ${after.risk}`);
+        }
+        if (before.auth !== 'required' && after.auth === 'required') {
+            changes.push(`command ${before.path} now requires auth`);
+        }
+        const requiredArgsBefore = before.arguments.filter((argument) => argument.required).length;
+        const requiredArgsAfter = after.arguments.filter((argument) => argument.required).length;
+        if (requiredArgsAfter > requiredArgsBefore) {
+            changes.push(`command ${before.path} gained a required positional argument`);
+        }
+        if (after.arguments.length < before.arguments.length) {
+            changes.push(`command ${before.path} lost a positional argument`);
+        }
+        const optionsAfter = new Map(after.options.map((option) => [flagOf(option.name), option]));
+        for (const option of before.options) {
+            const flag = flagOf(option.name);
+            const updated = optionsAfter.get(flag);
+            if (!updated) {
+                changes.push(`option ${before.path} ${flag} was removed`);
+                continue;
+            }
+            if (!option.required && updated.required) {
+                changes.push(`option ${before.path} ${flag} became required`);
+            }
+            if (option.type && updated.type && option.type !== updated.type) {
+                changes.push(`option ${before.path} ${flag} changed type from ${option.type} to ${updated.type}`);
+            }
+            for (const value of option.enum ?? []) {
+                if (updated.enum && !updated.enum.includes(value)) {
+                    changes.push(`option ${before.path} ${flag} no longer accepts ${value}`);
+                }
+            }
+        }
+        for (const option of after.options) {
+            if (option.required && !before.options.some((previousOption) => flagOf(previousOption.name) === flagOf(option.name))) {
+                changes.push(`option ${before.path} ${flagOf(option.name)} was added as required`);
+            }
+        }
+        for (const field of before.outputFields) {
+            if (!after.outputFields.includes(field)) {
+                changes.push(`output field ${before.path}.${field} was removed`);
+            }
+        }
+        for (const field of before.outputMetaFields) {
+            if (!after.outputMetaFields.includes(field)) {
+                changes.push(`output meta field ${before.path}.${field} was removed`);
+            }
+        }
+    }
+    for (const [code, exitCode] of Object.entries(previous.errorCodes)) {
+        const updated = next.errorCodes[code];
+        if (updated === undefined) {
+            changes.push(`error code ${code} was removed`);
+        }
+        else if (updated !== exitCode) {
+            changes.push(`error code ${code} exit status changed from ${exitCode} to ${updated}`);
+        }
+    }
+    return changes;
+}
+export function majorVersion(version) {
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    return Number.isFinite(major) ? major : 0;
+}

package/dist/daemon/client.d.ts

@@ -2,13 +2,13 @@ import type { DaemonPingResult, DaemonShutdownResult } from './types.js';
 export declare function sendDaemonRequest(method: string, params?: unknown, requestOptions?: {
     timeoutMs?: number;
 }): Promise<unknown>;
-export declare function isDaemonRunning(): Promise<boolean>;
+export declare function isDaemonRunning(timeoutMs?: number): Promise<boolean>;
 /**
  * Ping the daemon and return its handshake payload (version + connected identity),
  * or null when no daemon is reachable. Callers use this to detect a stale daemon
  * (wrong version or wrong account) rather than only "running / not running".
  */
-export declare function getDaemonInfo(): Promise<DaemonPingResult | null>;
+export declare function getDaemonInfo(timeoutMs?: number): Promise<DaemonPingResult | null>;
 /**
  * Whether a reachable daemon matches the current CLI version and signed-in account.
  * A mismatch means the daemon was started by an older build or a different user and

package/dist/daemon/client.js

@@ -1,10 +1,32 @@
 import { request as httpRequest } from 'node:http';
 import { existsSync } from 'node:fs';
 import { getDaemonSocketPath, isLegacyDaemonProcess, isProcessRunning, readPid, removePid, } from './pid.js';
-import { DinoxError } from '../utils/errors.js';
+import { remainingDeadlineMs } from '../utils/deadline.js';
+import { DinoxError, wireErrorCode } from '../utils/errors.js';
 const DEFAULT_DAEMON_REQUEST_TIMEOUT_MS = 10_000;
 const MAX_DAEMON_RESPONSE_BYTES = 5 * 1024 * 1024;
+function normalizedTimeoutMs(timeoutMs, fallbackMs) {
+    return Number.isFinite(timeoutMs)
+        ? Math.max(0, Math.floor(timeoutMs))
+        : fallbackMs;
+}
+function createDaemonReleaseTimeoutError(message) {
+    return new DinoxError(message, {
+        code: 'DAEMON_RELEASE_TIMEOUT',
+        suggestion: 'Run `dino daemon stop`, then retry the command.',
+        recoverable: true,
+    });
+}
+async function waitForNextPoll(deadlineAtMs, intervalMs) {
+    const waitMs = remainingDeadlineMs(deadlineAtMs, Math.max(0, intervalMs));
+    if (waitMs <= 0) {
+        return false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.max(1, waitMs)));
+    return true;
+}
 export async function sendDaemonRequest(method, params, requestOptions = {}) {
+    const timeoutMs = Math.max(1, normalizedTimeoutMs(requestOptions.timeoutMs ?? DEFAULT_DAEMON_REQUEST_TIMEOUT_MS, DEFAULT_DAEMON_REQUEST_TIMEOUT_MS));
     const request = {
         id: Date.now().toString(),
         method,
@@ -12,10 +34,14 @@ export async function sendDaemonRequest(method, params, requestOptions = {}) {
     };
     return new Promise((resolve, reject) => {
         let settled = false;
+        let deadlineTimer;
         const finalize = (error, value) => {
             if (settled)
                 return;
             settled = true;
+            if (deadlineTimer) {
+                clearTimeout(deadlineTimer);
+            }
             if (error) {
                 reject(error);
                 return;
@@ -32,7 +58,7 @@ export async function sendDaemonRequest(method, params, requestOptions = {}) {
                 'Content-Type': 'application/json',
                 'Content-Length': Buffer.byteLength(data),
             },
-            timeout: requestOptions.timeoutMs ?? DEFAULT_DAEMON_REQUEST_TIMEOUT_MS,
+            timeout: timeoutMs,
         };
         const req = httpRequest(options, (res) => {
             const statusCode = res.statusCode ?? 0;
@@ -70,6 +96,10 @@ export async function sendDaemonRequest(method, params, requestOptions = {}) {
             req.destroy(new Error('Daemon request timed out'));
         });
         req.on('error', (error) => finalize(error));
+        deadlineTimer = setTimeout(() => {
+            req.destroy(new Error('Daemon request timed out'));
+        }, timeoutMs);
+        deadlineTimer.unref?.();
         req.write(data);
         req.end();
     });
@@ -84,7 +114,7 @@ function toDaemonError(error) {
     if (isStructuredDaemonError(error)) {
         if (error.name === 'DinoxError' || error.code !== 'INTERNAL_ERROR') {
             return new DinoxError(error.message, {
-                code: error.code,
+                code: wireErrorCode(error.code),
                 details: error.details,
                 suggestion: error.suggestion,
                 suggestedAction: error.suggested_action,
@@ -97,17 +127,17 @@ function toDaemonError(error) {
     }
     return new Error(typeof error === 'string' && error.trim() ? error : 'Unknown error');
 }
-export async function isDaemonRunning() {
-    return (await getDaemonInfo()) !== null;
+export async function isDaemonRunning(timeoutMs) {
+    return (await getDaemonInfo(timeoutMs)) !== null;
 }
 /**
  * Ping the daemon and return its handshake payload (version + connected identity),
  * or null when no daemon is reachable. Callers use this to detect a stale daemon
  * (wrong version or wrong account) rather than only "running / not running".
  */
-export async function getDaemonInfo() {
+export async function getDaemonInfo(timeoutMs) {
     try {
-        const result = await sendDaemonRequest('ping');
+        const result = await sendDaemonRequest('ping', undefined, { timeoutMs });
         if (result && typeof result === 'object') {
             const info = result;
             return {
@@ -147,25 +177,38 @@ export function isLegacyDaemonInfo(info) {
     return info.pid === 0 && info.instanceId.length === 0;
 }
 export async function shutdownLegacyDaemon(initialInfo, timeoutMs = 5_000) {
+    const maximumTimeoutMs = normalizedTimeoutMs(timeoutMs, 5_000);
+    const deadlineAtMs = Date.now() + maximumTimeoutMs;
+    const remainingTimeoutMs = () => remainingDeadlineMs(deadlineAtMs, maximumTimeoutMs);
+    const requireRemainingTimeoutMs = () => {
+        const remainingMs = remainingTimeoutMs();
+        if (remainingMs <= 0) {
+            throw createDaemonReleaseTimeoutError('Timed out while verifying the legacy daemon process.');
+        }
+        return remainingMs;
+    };
     const pidInfo = readPid();
-    if (!isLegacyDaemonInfo(initialInfo)
-        || !pidInfo
-        || pidInfo.instanceId !== null
-        || !isProcessRunning(pidInfo.pid)
-        || !await isLegacyDaemonProcess(pidInfo.pid, initialInfo.uptime)) {
+    const legacyProcessVerified = Boolean(isLegacyDaemonInfo(initialInfo)
+        && pidInfo
+        && pidInfo.instanceId === null
+        && isProcessRunning(pidInfo.pid)
+        && await isLegacyDaemonProcess(pidInfo.pid, initialInfo.uptime, requireRemainingTimeoutMs()));
+    if (!legacyProcessVerified
+        || !pidInfo) {
         throw new DinoxError('A legacy daemon is responding, but its process identity could not be verified safely.', {
             code: 'DAEMON_LEGACY_UNVERIFIED',
             suggestion: 'Inspect the daemon PID and command line, stop that process manually, then retry.',
             recoverable: true,
         });
     }
-    const confirmedInfo = await getDaemonInfo();
+    const confirmedInfo = await getDaemonInfo(requireRemainingTimeoutMs());
     const confirmedPidInfo = readPid();
-    if (!confirmedInfo
-        || !isLegacyDaemonInfo(confirmedInfo)
-        || confirmedPidInfo?.pid !== pidInfo.pid
-        || confirmedPidInfo.instanceId !== null
-        || !await isLegacyDaemonProcess(pidInfo.pid, confirmedInfo.uptime)) {
+    const confirmedLegacyProcess = Boolean(confirmedInfo
+        && isLegacyDaemonInfo(confirmedInfo)
+        && confirmedPidInfo?.pid === pidInfo.pid
+        && confirmedPidInfo.instanceId === null
+        && await isLegacyDaemonProcess(pidInfo.pid, confirmedInfo.uptime, requireRemainingTimeoutMs()));
+    if (!confirmedLegacyProcess) {
         throw new DinoxError('The legacy daemon changed while its process identity was being verified.', {
             code: 'DAEMON_INSTANCE_CHANGED',
             suggestion: 'Retry after checking `dino daemon status`.',
@@ -183,9 +226,8 @@ export async function shutdownLegacyDaemon(initialInfo, timeoutMs = 5_000) {
             recoverable: true,
         });
     }
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const current = await getDaemonInfo();
+    while (remainingTimeoutMs() > 0) {
+        const current = await getDaemonInfo(requireRemainingTimeoutMs());
         const processRunning = isProcessRunning(pidInfo.pid);
         if (!current && !processRunning) {
             removePid(undefined, { expectedPid: pidInfo.pid });
@@ -199,37 +241,46 @@ export async function shutdownLegacyDaemon(initialInfo, timeoutMs = 5_000) {
                 recoverable: true,
             });
         }
-        await new Promise((resolve) => setTimeout(resolve, 100));
+        if (!await waitForNextPoll(deadlineAtMs, 100)) {
+            break;
+        }
     }
-    throw new DinoxError('Timed out waiting for the verified legacy daemon to stop.', {
-        code: 'DAEMON_RELEASE_TIMEOUT',
-        suggestion: 'Inspect the daemon PID and stop that process manually before retrying.',
-        recoverable: true,
-    });
+    throw createDaemonReleaseTimeoutError('Timed out waiting for the verified legacy daemon to stop.');
 }
 /** Poll until the daemon answers a ping or the timeout elapses. */
 export async function waitForDaemonReady(timeoutMs = 5_000, intervalMs = 250) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (await isDaemonRunning()) {
+    const maximumTimeoutMs = normalizedTimeoutMs(timeoutMs, 5_000);
+    const deadlineAtMs = Date.now() + maximumTimeoutMs;
+    while (true) {
+        const remainingMs = remainingDeadlineMs(deadlineAtMs, maximumTimeoutMs);
+        if (remainingMs <= 0) {
+            return false;
+        }
+        if (await isDaemonRunning(remainingMs)) {
             return true;
         }
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        if (!await waitForNextPoll(deadlineAtMs, intervalMs)) {
+            return false;
+        }
     }
-    return isDaemonRunning();
 }
 /** Poll until the daemon answers with the expected authenticated identity. */
 export async function waitForFreshDaemon(expectedVersion, expectedUserId, expectedTokenFingerprint, expectedRuntimeConfigFingerprint, timeoutMs = 5_000, intervalMs = 250) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const info = await getDaemonInfo();
+    const maximumTimeoutMs = normalizedTimeoutMs(timeoutMs, 5_000);
+    const deadlineAtMs = Date.now() + maximumTimeoutMs;
+    while (true) {
+        const remainingMs = remainingDeadlineMs(deadlineAtMs, maximumTimeoutMs);
+        if (remainingMs <= 0) {
+            return false;
+        }
+        const info = await getDaemonInfo(remainingMs);
         if (info && isDaemonFresh(info, expectedVersion, expectedUserId, expectedTokenFingerprint, expectedRuntimeConfigFingerprint)) {
             return true;
         }
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        if (!await waitForNextPoll(deadlineAtMs, intervalMs)) {
+            return false;
+        }
     }
-    const info = await getDaemonInfo();
-    return Boolean(info && isDaemonFresh(info, expectedVersion, expectedUserId, expectedTokenFingerprint, expectedRuntimeConfigFingerprint));
 }
 /** Request shutdown of one exact daemon instance and reject if the socket changed owners. */
 export async function requestDaemonShutdown(expectedInstanceId, timeoutMs = 2_000) {
@@ -255,7 +306,17 @@ export async function requestDaemonShutdown(expectedInstanceId, timeoutMs = 2_00
 }
 /** Stop a reachable daemon before another process acquires the exclusive PowerSync owner lease. */
 export async function shutdownDaemonForExclusiveAccess(timeoutMs = 5_000, expectedInstanceId) {
-    const info = await getDaemonInfo();
+    const maximumTimeoutMs = normalizedTimeoutMs(timeoutMs, 5_000);
+    const deadlineAtMs = Date.now() + maximumTimeoutMs;
+    const remainingTimeoutMs = () => remainingDeadlineMs(deadlineAtMs, maximumTimeoutMs);
+    const requireRemainingTimeoutMs = () => {
+        const remainingMs = remainingTimeoutMs();
+        if (remainingMs <= 0) {
+            throw createDaemonReleaseTimeoutError('Timed out waiting for the daemon to release the PowerSync runtime.');
+        }
+        return remainingMs;
+    };
+    const info = await getDaemonInfo(requireRemainingTimeoutMs());
     if (!info) {
         const pidInfo = readPid();
         const socketExists = process.platform !== 'win32' && existsSync(getDaemonSocketPath());
@@ -269,7 +330,7 @@ export async function shutdownDaemonForExclusiveAccess(timeoutMs = 5_000, expect
         return false;
     }
     if (isLegacyDaemonInfo(info)) {
-        return shutdownLegacyDaemon(info, timeoutMs);
+        return shutdownLegacyDaemon(info, requireRemainingTimeoutMs());
     }
     if (expectedInstanceId && info.instanceId !== expectedInstanceId) {
         throw new DinoxError('Daemon instance changed before exclusive access could be acquired.', {
@@ -280,7 +341,7 @@ export async function shutdownDaemonForExclusiveAccess(timeoutMs = 5_000, expect
         });
     }
     try {
-        await requestDaemonShutdown(info.instanceId, Math.min(timeoutMs, 2_000));
+        await requestDaemonShutdown(info.instanceId, Math.min(requireRemainingTimeoutMs(), 2_000));
     }
     catch (error) {
         throw new DinoxError('The running daemon could not release the PowerSync runtime.', {
@@ -290,21 +351,14 @@ export async function shutdownDaemonForExclusiveAccess(timeoutMs = 5_000, expect
             recoverable: true,
         });
     }
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const current = await getDaemonInfo();
+    while (remainingTimeoutMs() > 0) {
+        const current = await getDaemonInfo(requireRemainingTimeoutMs());
         if (!current || current.instanceId !== info.instanceId) {
             return true;
         }
-        await new Promise((resolve) => setTimeout(resolve, 100));
-    }
-    const current = await getDaemonInfo();
-    if (!current || current.instanceId !== info.instanceId) {
-        return true;
+        if (!await waitForNextPoll(deadlineAtMs, 100)) {
+            break;
+        }
     }
-    throw new DinoxError('Timed out waiting for the daemon to release the PowerSync runtime.', {
-        code: 'DAEMON_RELEASE_TIMEOUT',
-        suggestion: 'Run `dino daemon stop`, then retry the command.',
-        recoverable: true,
-    });
+    throw createDaemonReleaseTimeoutError('Timed out waiting for the daemon to release the PowerSync runtime.');
 }

package/dist/daemon/index.d.ts

@@ -8,14 +8,16 @@ type DaemonStartResult = {
     detached: boolean;
     alreadyRunning: boolean;
 };
+type DaemonStartOptions = {
+    quiet?: boolean;
+    timeoutMs?: number;
+};
 type DaemonStopResult = {
     stopped: boolean;
     wasRunning: boolean;
     stalePidFile: boolean;
 };
-export declare function startDaemonLocked(port: number, detached: boolean, options?: {
-    quiet?: boolean;
-}): Promise<DaemonStartResult>;
+export declare function startDaemonLocked(port: number, detached: boolean, options?: DaemonStartOptions): Promise<DaemonStartResult>;
 /** Caller must hold the daemon start lock. */
 export declare function stopDaemonLocked(): Promise<DaemonStopResult>;
 export declare function stopDaemon(): Promise<DaemonStopResult>;