@dinoxx/dinox-cli 1.0.21 → 1.1.0

package/dist/commands/runtime.js

@@ -1,10 +1,14 @@
 import { hydrateResolvedAuthIdentity } from '../auth/userInfo.js';
 import { loadConfig } from '../config/store.js';
 import { resolveConfig } from '../config/resolve.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../powersync/runtime.js';
+import { withExclusivePowerSync } from '../powersync/exclusiveRuntime.js';
+import { getStatusSnapshot, waitForIdleDataFlow, 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 { 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) {
@@ -25,17 +29,34 @@ 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);
     const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? baseConfig.sync.timeoutMs;
     const offline = Boolean(globals.offline);
+    const requireSync = Boolean(globals.requireSync);
     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,
@@ -43,34 +64,106 @@ export async function withCommandRuntime(source, run) {
             offline,
             timeoutMs,
             stale,
+            requireSync,
+            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) {
+        if (runtime.requireSync) {
+            const gate = evaluateSyncGate({
+                offline: true,
+                firstSyncStale: runtime.sync.firstSyncStale,
+                idle: false,
+                recentSync: false,
+                status: {
+                    connected: false,
+                    hasSynced: false,
+                    dataFlowStatus: {},
+                },
+            });
+            runtime.sync.gate = gate;
+            throw createSyncRequiredError(gate);
+        }
         return;
     }
-    await waitForIdleDataFlow(runtime.db, Math.min(runtime.timeoutMs, options.timeoutMs ?? PRE_SYNC_TIMEOUT_MS));
+    const idle = await waitForIdleDataFlow(runtime.db, Math.min(runtime.timeoutMs, options.timeoutMs ?? PRE_SYNC_TIMEOUT_MS));
+    runtime.sync.preSyncIdle = idle;
+    const recentSync = runtime.requireSync
+        ? await waitForLastSyncedAfter(runtime.db, runtime.sync.startedAtIso, Math.min(runtime.timeoutMs, options.timeoutMs ?? PRE_SYNC_TIMEOUT_MS))
+        : true;
+    runtime.sync.recentSync = recentSync;
     if (options.syncTokenIndex) {
         await syncNoteTokenIndex(runtime.db);
     }
+    const status = getStatusSnapshot(runtime.db);
+    const gate = evaluateSyncGate({
+        offline: runtime.offline,
+        firstSyncStale: runtime.sync.firstSyncStale,
+        idle,
+        recentSync,
+        status,
+    });
+    runtime.sync.gate = gate;
+    runtime.stale = !gate.ok;
+    if (runtime.requireSync && !gate.ok) {
+        throw createSyncRequiredError(gate, status);
+    }
 }
 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/globalOptions.d.ts

@@ -1,3 +1,4 @@
 export declare const FORMAT_OPTIONS: string[];
 export declare const OFFLINE_OPTIONS: string[];
+export declare const REQUIRE_SYNC_OPTIONS: string[];
 export declare const SYNC_TIMEOUT_OPTIONS: string[];

package/dist/commands/schema/globalOptions.js

@@ -1,3 +1,4 @@
 export const FORMAT_OPTIONS = ['--format <yaml|json>', '--json'];
 export const OFFLINE_OPTIONS = ['--offline'];
+export const REQUIRE_SYNC_OPTIONS = ['--require-sync'];
 export const SYNC_TIMEOUT_OPTIONS = ['--sync-timeout <ms>'];

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,12 +16,14 @@ 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 = [
     ['`--format <yaml|json>`', 'Structured output format. Prefer `json` for agent and script integrations.'],
     ['`--json`', 'Legacy alias for machine-readable YAML output. Keep only for backward compatibility.'],
     ['`--offline`', 'Skip sync, use local cache only'],
+    ['`--require-sync`', 'Fail if the local PowerSync cache cannot be confirmed fresh before reading'],
     ['`--sync-timeout <ms>`', 'Override default 300000 ms (5 min) sync/connect timeout'],
     ['`--verbose`', 'Enable verbose logging'],
 ];
@@ -89,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`.',
         ],
     },
@@ -112,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.',
@@ -133,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

@@ -1,13 +1,13 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
 import { registerCommandGroup } from '../descriptor/register.js';
-import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { buildStorageTestDryRunPreview, buildStorageUploadDryRunPreview } from '../writeDryRun.js';
 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, ...SYNC_TIMEOUT_OPTIONS];
+const STORAGE_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function runStorageList(context) {
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
@@ -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 {};