@dinoxx/dinox-cli 1.0.22 → 1.1.1

package/dist/commands/runtime.js

@@ -1,11 +1,15 @@
 import { hydrateResolvedAuthIdentity } from '../auth/userInfo.js';
 import { loadConfig } from '../config/store.js';
 import { resolveConfig } from '../config/resolve.js';
-import { connectPowerSync, getStatusSnapshot, waitForIdleDataFlow } from '../powersync/runtime.js';
+import { withExclusivePowerSync } from '../powersync/exclusiveRuntime.js';
+import { getStatusSnapshot, waitForDownloadIdle, waitForLastSyncedAfter, waitForUploadQueueEmpty, } from '../powersync/runtime.js';
 import { createSyncRequiredError, evaluateSyncGate } from '../powersync/syncGate.js';
 import { syncNoteTokenIndex } from '../powersync/tokenIndex.js';
-import { printHumanReadableLine } from '../utils/output.js';
+import { createTimeoutSignal } from '../utils/abort.js';
+import { DinoxError } from '../utils/errors.js';
+import { printHumanReadableWarning } from '../utils/output.js';
 import { parseSyncTimeoutMs } from '../utils/syncTimeout.js';
+import { parseWriteDurability } from './writeDurability.js';
 const PRE_SYNC_TIMEOUT_MS = 10_000;
 const POST_WRITE_IDLE_TIMEOUT_MS = 5_000;
 function isCommandExecutionContext(source) {
@@ -26,7 +30,19 @@ function resolveGlobals(source) {
 export function commandStale(runtime) {
     return runtime.offline ? true : runtime.stale;
 }
+export function resolveWriteDurabilityForRuntime(runtime, value) {
+    const durability = parseWriteDurability(value);
+    if (runtime.offline && durability === 'uploaded') {
+        throw new DinoxError('--durability uploaded cannot be used with --offline', {
+            code: 'USAGE_ERROR',
+            suggestion: 'Remove --offline or use --durability local for local-only writes.',
+            recoverable: true,
+        });
+    }
+    return durability;
+}
 export async function withCommandRuntime(source, run) {
+    const startedAtIso = new Date().toISOString();
     const globals = resolveGlobals(source);
     const rawConfig = await loadConfig();
     const baseConfig = resolveConfig(rawConfig);
@@ -36,8 +52,12 @@ export async function withCommandRuntime(source, run) {
     const { config } = offline
         ? { config: baseConfig }
         : await hydrateResolvedAuthIdentity(baseConfig, { timeoutMs });
-    const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-    try {
+    return withExclusivePowerSync({
+        config,
+        offline,
+        timeoutMs,
+        expectedTokenFingerprint: config.auth.tokenFingerprint ?? null,
+    }, async ({ db, stale }) => {
         return await run({
             db,
             config,
@@ -49,13 +69,12 @@ export async function withCommandRuntime(source, run) {
             sync: {
                 firstSyncStale: stale,
                 preSyncIdle: null,
+                recentSync: null,
                 gate: null,
+                startedAtIso,
             },
         });
-    }
-    finally {
-        await db.close().catch(() => undefined);
-    }
+    });
 }
 export async function syncBeforeCommand(runtime, options = {}) {
     if (runtime.offline) {
@@ -64,7 +83,9 @@ export async function syncBeforeCommand(runtime, options = {}) {
                 offline: true,
                 firstSyncStale: runtime.sync.firstSyncStale,
                 idle: false,
+                recentSync: false,
                 status: {
+                    connected: false,
                     hasSynced: false,
                     dataFlowStatus: {},
                 },
@@ -74,16 +95,31 @@ export async function syncBeforeCommand(runtime, options = {}) {
         }
         return;
     }
-    const idle = await waitForIdleDataFlow(runtime.db, Math.min(runtime.timeoutMs, options.timeoutMs ?? PRE_SYNC_TIMEOUT_MS));
-    runtime.sync.preSyncIdle = idle;
+    const timeoutMs = Math.min(runtime.timeoutMs, options.timeoutMs ?? PRE_SYNC_TIMEOUT_MS);
+    const deadlineAtMs = Date.now() + timeoutMs;
+    const remainingTimeoutMs = () => Math.max(0, deadlineAtMs - Date.now());
+    const recentSync = runtime.requireSync
+        ? await waitForLastSyncedAfter(runtime.db, runtime.sync.startedAtIso, Math.max(1, remainingTimeoutMs()))
+        : true;
+    runtime.sync.recentSync = recentSync;
+    const downloadIdle = await waitForDownloadIdle(runtime.db, Math.max(1, remainingTimeoutMs()));
+    runtime.sync.preSyncIdle = downloadIdle;
+    let indexComplete;
     if (options.syncTokenIndex) {
-        await syncNoteTokenIndex(runtime.db);
+        const indexTimeoutMs = remainingTimeoutMs();
+        const timeout = indexTimeoutMs > 0 ? createTimeoutSignal(indexTimeoutMs) : null;
+        const tokenIndex = await syncNoteTokenIndex(runtime.db, {
+            signal: timeout?.signal ?? AbortSignal.abort(),
+        }).finally(() => timeout?.cancel());
+        indexComplete = tokenIndex.complete;
     }
     const status = getStatusSnapshot(runtime.db);
     const gate = evaluateSyncGate({
         offline: runtime.offline,
         firstSyncStale: runtime.sync.firstSyncStale,
-        idle,
+        idle: downloadIdle,
+        indexComplete,
+        recentSync,
         status,
     });
     runtime.sync.gate = gate;
@@ -93,18 +129,52 @@ export async function syncBeforeCommand(runtime, options = {}) {
     }
 }
 export async function waitForMutationUpload(runtime, options = {}) {
+    const requestedDurability = resolveWriteDurabilityForRuntime(runtime, options.durability);
     if (runtime.offline) {
-        return;
+        return { durability: 'local', upload_queue_remaining: null };
     }
-    await waitForIdleDataFlow(runtime.db, Math.min(runtime.timeoutMs, options.timeoutMs ?? POST_WRITE_IDLE_TIMEOUT_MS));
-}
-export function printUploadDisabledWarning(runtime, message = 'warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now') {
-    if (!runtime.offline && !runtime.config.powersync.uploadBaseUrl) {
-        printHumanReadableLine(message);
+    const result = await waitForUploadQueueEmpty(runtime.db, Math.min(runtime.timeoutMs, options.timeoutMs
+        ?? (runtime.requireSync || requestedDurability === 'uploaded'
+            ? runtime.timeoutMs
+            : POST_WRITE_IDLE_TIMEOUT_MS)));
+    if (result.ok) {
+        return { durability: 'uploaded', upload_queue_remaining: 0 };
+    }
+    const uploadError = result.uploadError
+        ? { name: result.uploadError.name, message: result.uploadError.message }
+        : undefined;
+    const details = {
+        pendingCount: result.pendingCount,
+        timedOut: result.timedOut,
+        ...(uploadError ? { uploadError } : {}),
+        ...(result.queueError ? { queueError: result.queueError } : {}),
+    };
+    const message = result.queueError
+        ? `Changes were saved locally, but the upload queue could not be verified: ${result.queueError.message}`
+        : result.uploadError
+            ? `Changes were saved locally, but upload failed: ${result.uploadError.message}`
+            : `Changes were saved locally, but ${result.pendingCount ?? 'an unknown number of'} pending upload(s) did not finish before timeout.`;
+    if (runtime.requireSync || requestedDurability === 'uploaded') {
+        throw new DinoxError(message, {
+            code: 'UPLOAD_PENDING',
+            details,
+            suggestion: 'Check network connectivity and retry with a larger --sync-timeout.',
+            suggestedAction: {
+                command: 'dino doctor --fix --format json',
+                reason: 'Inspect sync health and wait for pending local uploads before retrying the write.',
+            },
+            recoverable: true,
+        });
     }
+    printHumanReadableWarning(`warning: ${message}`);
+    return {
+        durability: 'local',
+        upload_queue_remaining: result.pendingCount,
+        ...(uploadError ? { upload_error: uploadError } : {}),
+    };
 }
 export function printStaleCacheWarning(runtime, message = 'warning: sync timed out; local cache may be stale') {
     if (runtime.stale && !runtime.offline) {
-        printHumanReadableLine(message);
+        printHumanReadableWarning(message);
     }
 }

package/dist/commands/schema/renderSkills.js

@@ -4,6 +4,7 @@ import { listCommandSchemas } from './spec.js';
 const SECTION_ORDER = [
     { title: 'Auth', paths: ['auth.login', 'auth.logout', 'auth.status'] },
     { title: 'Daemon', paths: ['daemon.start', 'daemon.status', 'daemon.restart', 'daemon.stop'] },
+    { title: 'Doctor', paths: ['doctor'] },
     { title: 'Sync', paths: ['sync'] },
     { title: 'Schema', paths: ['schema'] },
     { title: 'Update CLI', paths: ['update'] },
@@ -15,6 +16,7 @@ const SECTION_ORDER = [
     { title: 'Storage', paths: ['storage.list', 'storage.test', 'storage.upload', 'storage.stats'] },
     { title: 'Config', paths: ['config.get', 'config.set'] },
     { title: 'Info', paths: ['info'] },
+    { title: 'Metadata', paths: ['meta.stats', 'meta.schema'] },
     { title: 'Graph', paths: ['graph.backlinks', 'graph.outlinks', 'graph.related', 'graph.stats'] },
 ];
 const GLOBAL_OPTIONS = [
@@ -90,7 +92,7 @@ const GENERATED_COMMAND_SECTIONS = {
             'Use `--boxes` for public box filters.',
             'Prefer `--fields id,title,summary,tags,created_at,boxes,is_starred` when the user only needs search metadata.',
             'Use `note export` for backup or migration; Markdown exports include frontmatter, JSON exports preserve note metadata and content JSON.',
-            'Use `note content-read` immediately before `note patch`; the returned readToken, content hash, block index, outline, and resolved hashtag paths are the required edit context.',
+            'Use `note content-read` immediately before `note patch`; the returned single-use readToken, content hash, block index, outline, and resolved hashtag paths are the required edit context. Run `content-read` again after every patch attempt.',
             '`--sql` remains storage-oriented and still uses the field name `zettel_boxes`.',
         ],
     },
@@ -113,7 +115,7 @@ const GENERATED_COMMAND_SECTIONS = {
             '`note update` is for explicit note ids and full metadata replacement. It is not an append command.',
             '`note tag` and `note move` are explicit-id incremental organizers: add/remove preserves existing values, replace overwrites the whole list.',
             '`note move` changes zettel box membership only; it does not move files or note content.',
-            '`note patch` is only for structured content edits. Run `note content-read` immediately before it, pass `--read-token` for real writes, and use `--allow-protected-replace` only after reviewing protected blocks.',
+            '`note patch` is only for structured content edits. Run `note content-read` immediately before it and pass `--read-token` for real writes. The token is single-use and is consumed before any real patch attempt, so run `content-read` again after every failed attempt. Use `--allow-protected-replace` only after reviewing protected blocks.',
             '`note bulk` is for filter-based batch metadata organization; it never accepts `--sql`, and real writes require `--confirm --expected-count <n>`.',
             'Prefer `note star` / `note unstar` for pure starring changes, and `note update` when multiple fields change together.',
             'Run the same command with `--dry-run --format json` first.',
@@ -134,6 +136,7 @@ const GENERATED_COMMAND_SECTIONS = {
         notes: [
             'Run the same command with `--dry-run` first.',
             'For append, prefer explicit `--note-id` unless the user confirms the default target behavior.',
+            'For update, pass the `note_id` returned by todo search as `--note-id` when available; broad task lookup is bounded and refuses truncated results. Legacy ids bind to the searched task snapshot, so search again after the note changes.',
         ],
     },
 };

package/dist/commands/schema/spec.js

@@ -4,8 +4,10 @@ import { commandSchemasFromGroupDescriptor } from '../descriptor/register.js';
 import { standaloneCommandSchemaFromDescriptor } from '../descriptor/register.js';
 import { configCommandGroup } from '../config/index.js';
 import { daemonCommandGroup } from '../../daemon/index.js';
+import { doctorCommandDescriptor } from '../doctor.js';
 import { graphCommandGroup } from '../graph/index.js';
 import { infoCommandDescriptor } from '../info/index.js';
+import { metaCommandGroup } from '../meta/index.js';
 import { noteCommandGroup } from '../notes/index.js';
 import { promptCommandGroup } from '../prompt/index.js';
 import { schemaCommandMetadata } from './commandMetadata.js';
@@ -18,10 +20,12 @@ export const COMMAND_SCHEMAS = [
     ...commandSchemasFromGroupDescriptor(authCommandGroup),
     ...commandSchemasFromGroupDescriptor(configCommandGroup),
     ...commandSchemasFromGroupDescriptor(daemonCommandGroup),
+    standaloneCommandSchemaFromDescriptor(doctorCommandDescriptor),
     standaloneCommandSchemaFromDescriptor(syncCommandDescriptor),
     standaloneCommandSchemaFromDescriptor({ ...schemaCommandMetadata, action: async () => undefined }),
     standaloneCommandSchemaFromDescriptor(infoCommandDescriptor),
     standaloneCommandSchemaFromDescriptor(updateCommandDescriptor),
+    ...commandSchemasFromGroupDescriptor(metaCommandGroup),
     ...commandSchemasFromGroupDescriptor(tagCommandGroup),
     ...commandSchemasFromGroupDescriptor(boxCommandGroup),
     ...commandSchemasFromGroupDescriptor(promptCommandGroup),

package/dist/commands/storage/index.js

@@ -5,7 +5,7 @@ import { buildStorageTestDryRunPreview, buildStorageUploadDryRunPreview } from '
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
+import { commandStale, printStaleCacheWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
 import { getStorageStats, inspectStorageTest, inspectStorageUpload, listStorageConfigs, parseStorageUploadCategory, testStorageUpload, uploadFileToStorage, } from './repo.js';
 const STORAGE_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function runStorageList(context) {
@@ -24,6 +24,9 @@ async function runStorageUpload(context) {
         throw new DinoxError('File path is required. Use `dino storage upload <file>`.');
     }
     const options = context.options;
+    if (options.overwrite && !options.key?.trim()) {
+        throw new DinoxError('--overwrite requires an explicit --key.');
+    }
     const category = parseStorageUploadCategory(options.category ?? 'files');
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     await withCommandRuntime(context, async (runtime) => {
@@ -49,6 +52,7 @@ async function runStorageUpload(context) {
                 storageKey: plan.storageKey,
                 storageUrl: plan.storageUrl,
                 selectionSource: plan.selectionSource,
+                overwrite: options.overwrite === true,
             }));
             return;
         }
@@ -58,8 +62,8 @@ async function runStorageUpload(context) {
             category,
             storageId: options.storageId,
             key: options.key,
+            overwrite: options.overwrite,
         });
-        printUploadDisabledWarning(runtime, 'warning: upload disabled (powersync.uploadBaseUrl is unset); resource metadata is local-only for now');
         await waitForMutationUpload(runtime);
         const payload = {
             ok: true,
@@ -219,6 +223,7 @@ export const storageCommandGroup = {
                 { flags: '--storage-id <id>', description: 'Explicit storage config id (otherwise use active custom config)', type: 'string' },
                 { flags: '--category <kind>', description: 'Upload category: images|audios|files|videos', type: 'string', defaultValue: 'files', enum: ['images', 'audios', 'files', 'videos'] },
                 { flags: '--key <string>', description: 'Explicit object key override', type: 'string' },
+                { flags: '--overwrite', description: 'Replace existing objects addressed by an explicit --key', type: 'boolean' },
                 { flags: '--dry-run', description: 'Preview the upload target and resource record without uploading', type: 'boolean' },
             ],
             schema: {
@@ -234,6 +239,7 @@ export const storageCommandGroup = {
                 examples: [
                     'dino storage upload ./report.pdf --format json --dry-run',
                     'dino storage upload ./photo.jpg --category images --storage-id <id> --format json',
+                    'dino storage upload ./report.pdf --key imports/report.pdf --overwrite --format json',
                 ],
             },
             action: runStorageUpload,

package/dist/commands/storage/repo.d.ts

@@ -113,6 +113,7 @@ type UploadObjectInput = {
     key: string;
     contentType: string;
     contentLength: number;
+    overwrite: boolean;
     storage: StoredCustomStorageConfig;
 };
 type UploadObjectResult = {
@@ -124,6 +125,7 @@ type UploadDeps = {
     deleteObject?: (input: {
         bucket: string;
         key: string;
+        etag?: string | null;
         storage: StoredCustomStorageConfig;
     }) => Promise<void>;
     uploadBytes?: (input: {
@@ -131,6 +133,7 @@ type UploadDeps = {
         bucket: string;
         key: string;
         contentType: string;
+        overwrite?: boolean;
         storage: StoredCustomStorageConfig;
     }) => Promise<UploadObjectResult>;
 };
@@ -158,5 +161,6 @@ export declare function uploadFileToStorage(db: AbstractPowerSyncDatabase, input
     category: StorageUploadCategory;
     storageId?: string;
     key?: string;
+    overwrite?: boolean;
 }, deps?: UploadDeps): Promise<StorageUploadResult>;
 export {};