@dinoxx/dinox-cli 1.0.22 → 1.1.0

package/dist/dinox.js

@@ -18,9 +18,26 @@ async function main() {
 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';
+}
 main().catch((error) => {
+    if (isCommanderError(error)) {
+        process.exitCode = error.exitCode === 0 ? 0 : 2;
+        return;
+    }
     const argv = normalizeArgv(process.argv.slice(2));
-    const format = parseStructuredOutputFormatFromArgv(argv);
+    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;
@@ -32,6 +49,13 @@ main().catch((error) => {
         return;
     }
     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);
     }

package/dist/powersync/connector.js

@@ -39,9 +39,8 @@ export async function fetchCredentialsWithAuthorization({ authorization, endpoin
         ? createTimeoutSignal(timeoutMs)
         : null;
     const requestSignal = mergeAbortSignals([signal, timeout?.signal]);
-    let response;
     try {
-        response = await fetch(credentialsUrl, {
+        const response = await fetch(credentialsUrl, {
             method: 'GET',
             headers: {
                 Authorization: toAuthorizationHeaderValue(authorization),
@@ -49,6 +48,36 @@ export async function fetchCredentialsWithAuthorization({ authorization, endpoin
             },
             signal: requestSignal,
         });
+        if (!response.ok) {
+            let errorText = '';
+            try {
+                errorText = await response.text();
+            }
+            catch (error) {
+                if (requestSignal?.aborted) {
+                    throw error;
+                }
+            }
+            throw new Error(`Received ${response.status} from ${credentialsUrl}: ${errorText}`);
+        }
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch (error) {
+            if (requestSignal?.aborted) {
+                throw error;
+            }
+        }
+        const token = payload?.token ?? payload?.data?.token ?? null;
+        const endpointFromPayload = payload?.endpoint ?? payload?.data?.endpoint ?? null;
+        if (!token) {
+            throw new Error('PowerSync credential response did not include a token');
+        }
+        return {
+            endpoint: endpointFromPayload ?? endpoint,
+            token,
+        };
     }
     catch (error) {
         if (timeout?.signal.aborted && !signal?.aborted) {
@@ -59,18 +88,4 @@ export async function fetchCredentialsWithAuthorization({ authorization, endpoin
     finally {
         timeout?.cancel();
     }
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => '');
-        throw new Error(`Received ${response.status} from ${credentialsUrl}: ${errorText}`);
-    }
-    const payload = await response.json().catch(() => null);
-    const token = payload?.token ?? payload?.data?.token ?? null;
-    const endpointFromPayload = payload?.endpoint ?? payload?.data?.endpoint ?? null;
-    if (!token) {
-        throw new Error('PowerSync credential response did not include a token');
-    }
-    return {
-        endpoint: endpointFromPayload ?? endpoint,
-        token,
-    };
 }

package/dist/powersync/exclusiveRuntime.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedDinoxConfig } from '../config/types.js';
+import { withDaemonExclusiveAccess } from '../daemon/lifecycle.js';
+import { printHumanReadableWarning } from '../utils/output.js';
+import { closePowerSyncAndReleaseOwner, connectPowerSync, type ConnectResult } from './runtime.js';
+type ExclusivePowerSyncDependencies = {
+    withDaemonExclusiveAccess: typeof withDaemonExclusiveAccess;
+    connectPowerSync: typeof connectPowerSync;
+    closePowerSyncAndReleaseOwner: typeof closePowerSyncAndReleaseOwner;
+    printWarning: typeof printHumanReadableWarning;
+};
+export declare function withExclusivePowerSync<T>(args: {
+    config: ResolvedDinoxConfig;
+    offline: boolean;
+    timeoutMs: number;
+    waitForInitialSync?: boolean;
+    expectedTokenFingerprint?: string | null;
+    cleanupFailureMode?: 'warn' | 'throw';
+}, run: (connected: ConnectResult) => Promise<T>, overrides?: Partial<ExclusivePowerSyncDependencies>): Promise<T>;
+export {};

package/dist/powersync/exclusiveRuntime.js

@@ -0,0 +1,42 @@
+import { withDaemonExclusiveAccess } from '../daemon/lifecycle.js';
+import { printHumanReadableWarning } from '../utils/output.js';
+import { closePowerSyncAndReleaseOwner, connectPowerSync, } from './runtime.js';
+const exclusivePowerSyncDependencies = {
+    withDaemonExclusiveAccess,
+    connectPowerSync,
+    closePowerSyncAndReleaseOwner,
+    printWarning: printHumanReadableWarning,
+};
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function withExclusivePowerSync(args, run, overrides = {}) {
+    const dependencies = { ...exclusivePowerSyncDependencies, ...overrides };
+    const { cleanupFailureMode, ...connectArgs } = args;
+    return dependencies.withDaemonExclusiveAccess(args.config, args.timeoutMs, async (daemonLifecycle) => {
+        const connected = await dependencies.connectPowerSync(connectArgs);
+        let outcome;
+        try {
+            outcome = { ok: true, value: await run(connected) };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+        let cleanupError;
+        try {
+            await dependencies.closePowerSyncAndReleaseOwner(connected.db, connected.releaseOwner);
+        }
+        catch (error) {
+            cleanupError = error;
+            daemonLifecycle.suppressRestore();
+            dependencies.printWarning(`warning: failed to close the local PowerSync runtime safely: ${errorMessage(error)}`);
+        }
+        if (!outcome.ok) {
+            throw outcome.error;
+        }
+        if (cleanupError && cleanupFailureMode === 'throw') {
+            throw cleanupError;
+        }
+        return outcome.value;
+    });
+}

package/dist/powersync/runtime.d.ts

@@ -5,7 +5,13 @@ export type ConnectResult = {
     db: PowerSyncDatabase;
     dbPath: string;
     stale: boolean;
+    releaseOwner: () => Promise<void>;
 };
+type ClosablePowerSyncDatabase = {
+    close: () => Promise<void>;
+};
+export declare function acquirePowerSyncOwnerLease(dbPath: string, timeoutMs: number): Promise<() => Promise<void>>;
+export declare function closePowerSyncAndReleaseOwner(db: ClosablePowerSyncDatabase, releaseOwner: () => Promise<void>): Promise<void>;
 export declare function getStatusSnapshot(db: AbstractPowerSyncDatabase): {
     connected: boolean;
     connecting: boolean;
@@ -25,14 +31,28 @@ export declare function getStatusSnapshot(db: AbstractPowerSyncDatabase): {
     };
     raw: SyncStatusOptions;
 };
-export declare function openPowerSyncDatabase(userId?: string | null): Promise<{
-    db: PowerSyncDatabase;
-    dbPath: string;
-}>;
 export declare function connectPowerSync(args: {
     config: ResolvedDinoxConfig;
     offline: boolean;
     timeoutMs: number;
+    waitForInitialSync?: boolean;
+    expectedTokenFingerprint?: string | null;
 }): Promise<ConnectResult>;
 export declare function waitForIdleDataFlow(db: AbstractPowerSyncDatabase, timeoutMs: number): Promise<boolean>;
+export declare function waitForLastSyncedAfter(db: AbstractPowerSyncDatabase, startedAtIso: string, timeoutMs: number): Promise<boolean>;
+export type UploadQueueWaitResult = {
+    ok: boolean;
+    pendingCount: number | null;
+    uploadError?: {
+        name: string;
+        message: string;
+    };
+    queueError?: {
+        name: string;
+        message: string;
+    };
+    timedOut: boolean;
+};
+export declare function waitForUploadQueueEmpty(db: AbstractPowerSyncDatabase, timeoutMs: number): Promise<UploadQueueWaitResult>;
 export declare function withPowerSyncWriteTransaction<T>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<T>): Promise<T>;
+export {};

package/dist/powersync/runtime.js

@@ -2,11 +2,87 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { PowerSyncDatabase } from '@powersync/node';
 import { getDataDir, getPowerSyncDbPath } from '../config/paths.js';
+import { resolveConfig } from '../config/resolve.js';
+import { loadConfig } from '../config/store.js';
 import { DinoxError } from '../utils/errors.js';
 import { createTimeoutSignal } from '../utils/abort.js';
+import { acquireExclusiveSqliteLease } from '../utils/sqliteLease.js';
 import { AppSchema } from './schema/index.js';
 import { PowerSyncConnector, fetchCredentialsWithAuthorization } from './connector.js';
 import { createPowerSyncUploadHandler } from './uploader.js';
+const OWNER_LEASE_WAIT_MAX_MS = 10_000;
+const retainedFailedPowerSyncClosures = new Set();
+function retainFailedPowerSyncClosure(db, releaseOwner, dbClosed) {
+    for (const retained of retainedFailedPowerSyncClosures) {
+        if (retained.db === db && retained.releaseOwner === releaseOwner) {
+            retained.dbClosed ||= dbClosed;
+            return;
+        }
+    }
+    retainedFailedPowerSyncClosures.add({ db, releaseOwner, dbClosed });
+}
+function findFailedPowerSyncClosure(db, releaseOwner) {
+    for (const retained of retainedFailedPowerSyncClosures) {
+        if (retained.db === db && retained.releaseOwner === releaseOwner) {
+            return retained;
+        }
+    }
+    return undefined;
+}
+function forgetFailedPowerSyncClosure(db, releaseOwner) {
+    for (const retained of retainedFailedPowerSyncClosures) {
+        if (retained.db === db && retained.releaseOwner === releaseOwner) {
+            retainedFailedPowerSyncClosures.delete(retained);
+        }
+    }
+}
+function ownerLeasePath(dbPath) {
+    return `${dbPath}.owner.sqlite`;
+}
+export async function acquirePowerSyncOwnerLease(dbPath, timeoutMs) {
+    const lockPath = ownerLeasePath(dbPath);
+    return acquireExclusiveSqliteLease({
+        lockPath,
+        timeoutMs,
+        maxWaitMs: OWNER_LEASE_WAIT_MAX_MS,
+        createBusyError: () => new DinoxError('Another Dinox process owns the PowerSync runtime for this account.', {
+            code: 'POWERSYNC_OWNER_BUSY',
+            details: { dbPath },
+            suggestion: 'Wait for the other Dinox command to finish, then retry.',
+            recoverable: true,
+        }),
+    });
+}
+export async function closePowerSyncAndReleaseOwner(db, releaseOwner) {
+    const retained = findFailedPowerSyncClosure(db, releaseOwner);
+    if (!retained?.dbClosed) {
+        try {
+            await db.close();
+        }
+        catch (error) {
+            retainFailedPowerSyncClosure(db, releaseOwner, false);
+            throw error;
+        }
+    }
+    try {
+        await releaseOwner();
+    }
+    catch (error) {
+        retainFailedPowerSyncClosure(db, releaseOwner, true);
+        throw error;
+    }
+    forgetFailedPowerSyncClosure(db, releaseOwner);
+}
+async function throwAfterPowerSyncCleanup(operationError, db, releaseOwner) {
+    try {
+        await closePowerSyncAndReleaseOwner(db, releaseOwner);
+    }
+    catch {
+        // Preserve the actionable operation failure. The cleanup helper keeps the
+        // owner lease held whenever database close did not complete safely.
+    }
+    throw operationError;
+}
 async function ensureDataDir() {
     const dir = getDataDir();
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });
@@ -34,7 +110,7 @@ export function getStatusSnapshot(db) {
         raw,
     };
 }
-export async function openPowerSyncDatabase(userId) {
+async function createPowerSyncDatabase(userId) {
     await ensureDataDir();
     const dbPath = getPowerSyncDbPath(userId);
     await fs.mkdir(path.dirname(dbPath), { recursive: true, mode: 0o700 });
@@ -44,52 +120,107 @@ export async function openPowerSyncDatabase(userId) {
             dbFilename: dbPath,
         },
     });
-    // Ensure initialization errors surface early.
-    await db.init();
     return { db, dbPath };
 }
 function assertConfigured(config) {
     if (!config.auth.authorization) {
-        throw new DinoxError('Not logged in. Run: dino auth login <token>');
+        throw new DinoxError('Not logged in. Set DINOX_TOKEN or pipe a token to `dino auth login --token-stdin`.');
     }
 }
 export async function connectPowerSync(args) {
-    const { db, dbPath } = await openPowerSyncDatabase(args.config.auth.userId);
-    if (args.offline) {
-        return { db, dbPath, stale: true };
-    }
-    assertConfigured(args.config);
-    const uploader = args.config.powersync.uploadBaseUrl
-        ? createPowerSyncUploadHandler({
-            authorization: args.config.auth.authorization,
-            uploadBaseUrl: args.config.powersync.uploadBaseUrl,
-            uploadV4Path: args.config.powersync.uploadV4Path,
-            uploadV2Path: args.config.powersync.uploadV2Path,
-            timeoutMs: args.timeoutMs,
-        })
-        : undefined;
-    const connector = new PowerSyncConnector(async () => {
-        return fetchCredentialsWithAuthorization({
-            authorization: args.config.auth.authorization,
-            endpoint: args.config.powersync.endpoint,
-            credentialsUrl: args.config.powersync.tokenEndpoint,
-            timeoutMs: args.timeoutMs,
-        });
-    }, uploader);
-    await db.connect(connector);
-    const { signal, cancel } = createTimeoutSignal(args.timeoutMs);
+    if (!args.offline) {
+        assertConfigured(args.config);
+    }
+    const dbPath = getPowerSyncDbPath(args.config.auth.userId);
+    await fs.mkdir(path.dirname(dbPath), { recursive: true, mode: 0o700 });
+    const releaseOwner = await acquirePowerSyncOwnerLease(dbPath, args.timeoutMs);
+    if (args.expectedTokenFingerprint !== undefined) {
+        try {
+            const currentAuth = resolveConfig(await loadConfig()).auth;
+            const currentTokenFingerprint = currentAuth.tokenFingerprint ?? null;
+            const expectedUserId = args.config.auth.userId ?? null;
+            const currentUserId = currentAuth.userId ?? null;
+            const persistedUserChanged = currentUserId !== null && currentUserId !== expectedUserId;
+            if (currentTokenFingerprint !== args.expectedTokenFingerprint || persistedUserChanged) {
+                throw new DinoxError('Authentication changed while waiting for the local database.', {
+                    code: 'AUTH_STATE_CHANGED',
+                    details: { dbPath, expectedUserId, currentUserId },
+                    suggestion: 'Retry the command so it uses the current login.',
+                    recoverable: true,
+                });
+            }
+        }
+        catch (error) {
+            try {
+                await releaseOwner();
+            }
+            catch {
+                // Preserve the authentication/configuration failure that triggered cleanup.
+            }
+            throw error;
+        }
+    }
+    let db = null;
     try {
-        await db.waitForFirstSync(signal);
-        return { db, dbPath, stale: signal.aborted };
+        ({ db } = await createPowerSyncDatabase(args.config.auth.userId));
+        await db.init();
     }
     catch (error) {
-        if (signal.aborted) {
-            return { db, dbPath, stale: true };
+        if (!db) {
+            try {
+                await releaseOwner();
+            }
+            catch {
+                // Preserve the database construction failure that triggered cleanup.
+            }
+            throw error;
         }
-        throw error;
+        return throwAfterPowerSyncCleanup(error, db, releaseOwner);
     }
-    finally {
-        cancel();
+    if (args.offline) {
+        return { db, dbPath, stale: true, releaseOwner };
+    }
+    try {
+        const uploader = args.config.powersync.uploadBaseUrl
+            ? createPowerSyncUploadHandler({
+                authorization: args.config.auth.authorization,
+                uploadBaseUrl: args.config.powersync.uploadBaseUrl,
+                uploadV4Path: args.config.powersync.uploadV4Path,
+                uploadV2Path: args.config.powersync.uploadV2Path,
+                timeoutMs: args.timeoutMs,
+            })
+            : undefined;
+        const connector = new PowerSyncConnector(async () => {
+            return fetchCredentialsWithAuthorization({
+                authorization: args.config.auth.authorization,
+                endpoint: args.config.powersync.endpoint,
+                credentialsUrl: args.config.powersync.tokenEndpoint,
+                timeoutMs: args.timeoutMs,
+            });
+        }, uploader);
+        await db.connect(connector);
+        if (args.waitForInitialSync === false) {
+            const status = getStatusSnapshot(db);
+            return { db, dbPath, stale: !status.connected || !status.hasSynced, releaseOwner };
+        }
+        const { signal, cancel } = createTimeoutSignal(args.timeoutMs);
+        try {
+            await db.waitForFirstSync(signal);
+            const status = getStatusSnapshot(db);
+            return { db, dbPath, stale: signal.aborted || !status.connected, releaseOwner };
+        }
+        catch (error) {
+            if (signal.aborted) {
+                return { db, dbPath, stale: true, releaseOwner };
+            }
+            throw error;
+        }
+        finally {
+            cancel();
+        }
+    }
+    catch (error) {
+        return throwAfterPowerSyncCleanup(error, db, releaseOwner);
     }
 }
 export async function waitForIdleDataFlow(db, timeoutMs) {
@@ -97,7 +228,32 @@ export async function waitForIdleDataFlow(db, timeoutMs) {
     try {
         await db.waitForStatus(status => {
             const flow = status.dataFlowStatus;
-            return !flow.downloading && !flow.uploading;
+            return Boolean(status.connected) && !flow.downloading && !flow.uploading;
+        }, signal);
+        return !signal.aborted;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        cancel();
+    }
+}
+export async function waitForLastSyncedAfter(db, startedAtIso, timeoutMs) {
+    const startedAtMs = Date.parse(startedAtIso);
+    if (!Number.isFinite(startedAtMs)) {
+        return false;
+    }
+    const status = getStatusSnapshot(db);
+    if (status.connected && status.lastSyncedAt && Date.parse(status.lastSyncedAt) >= startedAtMs) {
+        return true;
+    }
+    const { signal, cancel } = createTimeoutSignal(timeoutMs);
+    try {
+        await db.waitForStatus((nextStatus) => {
+            const value = nextStatus.lastSyncedAt;
+            const lastSyncedAt = value instanceof Date ? value.toISOString() : value ?? null;
+            return Boolean(nextStatus.connected && lastSyncedAt && Date.parse(lastSyncedAt) >= startedAtMs);
         }, signal);
         return !signal.aborted;
     }
@@ -108,6 +264,48 @@ export async function waitForIdleDataFlow(db, timeoutMs) {
         cancel();
     }
 }
+export async function waitForUploadQueueEmpty(db, timeoutMs) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    let pendingCount = Number.POSITIVE_INFINITY;
+    while (Date.now() <= deadline) {
+        const status = getStatusSnapshot(db);
+        try {
+            const stats = await db.getUploadQueueStats(false);
+            pendingCount = stats.count;
+            if (status.dataFlowStatus.uploadError) {
+                return {
+                    ok: false,
+                    pendingCount,
+                    uploadError: status.dataFlowStatus.uploadError,
+                    timedOut: false,
+                };
+            }
+            if (stats.count === 0) {
+                return { ok: true, pendingCount: 0, timedOut: false };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                pendingCount: Number.isFinite(pendingCount) ? pendingCount : null,
+                ...(status.dataFlowStatus.uploadError
+                    ? { uploadError: status.dataFlowStatus.uploadError }
+                    : {}),
+                queueError: {
+                    name: error instanceof Error ? error.name : 'Error',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+                timedOut: false,
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return {
+        ok: false,
+        pendingCount: Number.isFinite(pendingCount) ? pendingCount : null,
+        timedOut: true,
+    };
+}
 export async function withPowerSyncWriteTransaction(db, run) {
     const txDb = db;
     if (typeof txDb.writeTransaction === 'function') {

package/dist/powersync/syncGate.d.ts

@@ -1,6 +1,6 @@
 import type { SyncStatusOptions } from '@powersync/common';
 import { DinoxError } from '../utils/errors.js';
-export type SyncGateFailureReason = 'offline' | 'first-sync-timeout' | 'data-flow-timeout' | 'not-synced' | 'download-error';
+export type SyncGateFailureReason = 'offline' | 'first-sync-timeout' | 'checkpoint-timeout' | 'data-flow-timeout' | 'not-connected' | 'not-synced' | 'download-error';
 export type SyncGateResult = {
     ok: boolean;
     reasons: SyncGateFailureReason[];
@@ -9,7 +9,9 @@ export type SyncGateInput = {
     offline: boolean;
     firstSyncStale: boolean;
     idle: boolean;
+    recentSync?: boolean;
     status: {
+        connected: boolean;
         hasSynced: boolean;
         dataFlowStatus: {
             downloadError?: {

package/dist/powersync/syncGate.js

@@ -7,12 +7,18 @@ export function evaluateSyncGate(input) {
             reasons: ['offline'],
         };
     }
-    if (input.firstSyncStale) {
+    if (input.firstSyncStale && !input.status.hasSynced) {
         reasons.push('first-sync-timeout');
     }
+    if (input.recentSync === false) {
+        reasons.push('checkpoint-timeout');
+    }
     if (!input.idle) {
         reasons.push('data-flow-timeout');
     }
+    if (!input.status.connected) {
+        reasons.push('not-connected');
+    }
     if (!input.status.hasSynced) {
         reasons.push('not-synced');
     }

package/dist/powersync/tokenIndex.d.ts

@@ -10,8 +10,19 @@ export type NoteTokenIndexResult = {
         id: string;
     };
 };
+export type NoteTokenIndexInspection = {
+    notes: number;
+    ftsRows: number;
+    metaRows: number;
+    missingRows: number;
+    extraRows: number;
+    drift: number;
+    ftsAvailable: boolean;
+};
 export declare function syncNoteTokenIndex(db: AbstractPowerSyncDatabase, options?: {
     batchSize?: number;
     nowIso?: () => string;
     tokenize?: (text: string, limit?: number) => string[];
 }): Promise<NoteTokenIndexResult>;
+export declare function inspectNoteTokenIndex(db: AbstractPowerSyncDatabase): Promise<NoteTokenIndexInspection>;
+export declare function rebuildNoteTokenIndex(db: AbstractPowerSyncDatabase, options?: Parameters<typeof syncNoteTokenIndex>[1]): Promise<NoteTokenIndexResult>;