@dinoxx/dinox-cli 1.0.20 → 1.0.21

package/dist/commands/notes/metadataMutation.js

@@ -0,0 +1,127 @@
+import { withPowerSyncWriteTransaction } from '../../powersync/runtime.js';
+import { DinoxError } from '../../utils/errors.js';
+import { nowIsoUtc } from '../../utils/time.js';
+import { parseStoredTags, parseZettelBoxIds } from './repo.js';
+function normalizeDistinct(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        const normalized = value.trim();
+        const key = normalized.toLowerCase();
+        if (!normalized || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(normalized);
+    }
+    return result;
+}
+function sameOrdered(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function keySet(values) {
+    return new Set(values.map((value) => value.trim().toLowerCase()).filter(Boolean));
+}
+function applyListOperation(current, values, operation) {
+    const normalizedValues = normalizeDistinct(values);
+    if (operation === 'replace') {
+        return normalizedValues;
+    }
+    if (operation === 'add') {
+        return normalizeDistinct([...current, ...normalizedValues]);
+    }
+    const removeKeys = keySet(normalizedValues);
+    return current.filter((value) => !removeKeys.has(value.trim().toLowerCase()));
+}
+function assertMutationInput(input) {
+    const ids = normalizeDistinct(input.ids);
+    if (ids.length === 0) {
+        throw new DinoxError('At least one note id is required');
+    }
+    const values = normalizeDistinct(input.values);
+    if (values.length === 0 && input.operation !== 'replace') {
+        const option = input.operation === 'add' ? '--add' : '--remove';
+        throw new DinoxError(`${option} requires at least one ${input.field === 'tags' ? 'tag' : 'box'}`);
+    }
+    return {
+        ids,
+        values,
+        displayValues: normalizeDistinct(input.displayValues ?? input.values),
+    };
+}
+async function loadNoteMetadataState(db, ids) {
+    const rowsById = new Map();
+    const chunkSize = 500;
+    for (let index = 0; index < ids.length; index += chunkSize) {
+        const batch = ids.slice(index, index + chunkSize);
+        const placeholders = batch.map(() => '?').join(', ');
+        const rows = await db.getAll(`
+      SELECT id, title, tags, zettel_boxes, is_del
+      FROM c_note
+      WHERE id IN (${placeholders})
+      `, batch);
+        for (const row of rows) {
+            const id = row.id?.trim() ?? '';
+            if (!id || rowsById.has(id)) {
+                continue;
+            }
+            rowsById.set(id, row);
+        }
+    }
+    return rowsById;
+}
+export async function planNoteMetadataMutation(db, input) {
+    const { ids, values, displayValues } = assertMutationInput(input);
+    const stateById = await loadNoteMetadataState(db, ids);
+    const missing = ids.filter((id) => !stateById.has(id));
+    if (missing.length > 0) {
+        throw new DinoxError(`Notes not found: ${missing.join(', ')}`);
+    }
+    const results = ids.map((id) => {
+        const note = stateById.get(id);
+        if (typeof note.is_del === 'number' && note.is_del !== 0) {
+            throw new DinoxError(`Note has been deleted: ${id}`);
+        }
+        const before = input.field === 'tags'
+            ? parseStoredTags(note.tags)
+            : parseZettelBoxIds(note.zettel_boxes);
+        const after = applyListOperation(before, values, input.operation);
+        return {
+            id,
+            title: note.title ?? '',
+            before,
+            after,
+            changed: !sameOrdered(before, after),
+        };
+    });
+    return {
+        field: input.field,
+        operation: input.operation,
+        values,
+        displayValues,
+        total: results.length,
+        changedCount: results.filter((item) => item.changed).length,
+        results,
+    };
+}
+export async function applyNoteMetadataMutation(db, plan) {
+    const changed = plan.results.filter((item) => item.changed);
+    if (changed.length === 0) {
+        return plan;
+    }
+    await withPowerSyncWriteTransaction(db, async (tx) => {
+        const timestamp = nowIsoUtc();
+        for (const item of changed) {
+            const column = plan.field === 'tags' ? 'tags' : 'zettel_boxes';
+            await tx.execute(`
+        UPDATE c_note
+        SET ${column} = ?, updated_at = ?, version = COALESCE(version, 0) + 1
+        WHERE id = ?
+        `, [JSON.stringify(item.after), timestamp, item.id]);
+        }
+    });
+    return plan;
+}

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

@@ -45,6 +45,23 @@ export type NoteDetail = {
     content_md: string | null;
     zettel_boxes: string[];
 };
+export type NoteExportItem = {
+    id: string;
+    created_at: string | null;
+    updated_at: string | null;
+    title: string | null;
+    type: string | null;
+    source: string | null;
+    summary: string | null;
+    tags: string[];
+    is_del: number | null;
+    is_starred: boolean;
+    content_md: string;
+    content_text: string | null;
+    content_json: unknown;
+    box_ids: string[];
+    boxes: string[];
+};
 export type NoteContext = {
     id: string;
     title: string;
@@ -84,6 +101,7 @@ export declare function getNoteContext(db: AbstractPowerSyncDatabase, id: string
 export declare function getNotePreview(db: AbstractPowerSyncDatabase, id: string, requestedLines: number): Promise<NotePreview | null>;
 export declare function getNoteDetails(db: AbstractPowerSyncDatabase, ids: string[]): Promise<NoteDetail[]>;
 export declare function getNoteDetail(db: AbstractPowerSyncDatabase, id: string): Promise<NoteDetail | null>;
+export declare function getNoteExportItems(db: AbstractPowerSyncDatabase, ids: string[]): Promise<NoteExportItem[]>;
 export declare function createNote(db: AbstractPowerSyncDatabase, input: {
     id: string;
     title: string;
@@ -100,6 +118,7 @@ export declare function createNote(db: AbstractPowerSyncDatabase, input: {
 }>;
 export declare function validateTagsForCreate(db: AbstractPowerSyncDatabase, requestedTags: string[]): Promise<string[]>;
 export declare function validateTagsForUpdate(db: AbstractPowerSyncDatabase, requestedTags: string[]): Promise<string[]>;
+export declare function validateTagsForBulk(db: AbstractPowerSyncDatabase, requestedTags: string[]): Promise<string[]>;
 export declare function parseStoredTags(raw: string | null): string[];
 export declare function updateNote(db: AbstractPowerSyncDatabase, input: {
     id: string;
@@ -111,5 +130,6 @@ export declare function assertNotesUpdatable(db: AbstractPowerSyncDatabase, note
 export declare function resolveZettelBoxIdsForCreate(db: AbstractPowerSyncDatabase, requestedNames: string[]): Promise<string[]>;
 export declare function resolveZettelBoxIdsForSearch(db: AbstractPowerSyncDatabase, requestedNames: string[]): Promise<string[]>;
 export declare function resolveZettelBoxIdsForUpdate(db: AbstractPowerSyncDatabase, requestedNames: string[]): Promise<string[]>;
+export declare function resolveZettelBoxIdsForBulk(db: AbstractPowerSyncDatabase, requestedNames: string[]): Promise<string[]>;
 export declare function softDeleteNote(db: AbstractPowerSyncDatabase, id: string): Promise<void>;
 export {};

package/dist/commands/notes/repo.js

@@ -1,7 +1,7 @@
 import { DinoxError } from '../../utils/errors.js';
 import { nowIsoUtc } from '../../utils/time.js';
 import { tokenizeWithJieba } from '../../utils/tokenize.js';
-import { listBoxes } from '../boxes/repo.js';
+import { canonicalizeBoxPath, listBoxes } from '../boxes/repo.js';
 import { listTags } from '../tags/repo.js';
 import { buildNoteSearchSqlFilter } from './searchSql.js';
 const MAX_SEARCH_SUMMARY_CHARS = 200;
@@ -199,7 +199,7 @@ async function loadZettelBoxNameMap(db, ids) {
         const batch = ids.slice(i, i + chunkSize);
         const placeholders = batch.map(() => '?').join(', ');
         const rows = await db.getAll(`
-      SELECT id, name
+      SELECT id, name, path
       FROM c_zettel_box
       WHERE (is_del IS NULL OR is_del = 0)
         AND id IN (${placeholders})
@@ -209,7 +209,8 @@ async function loadZettelBoxNameMap(db, ids) {
             if (!id) {
                 continue;
             }
-            map.set(id, row.name?.trim() ?? '');
+            const path = canonicalizeBoxPath(row.path ?? row.name ?? '');
+            map.set(id, path || row.name?.trim() || '');
         }
     }
     return map;
@@ -645,6 +646,41 @@ function mapNoteDetailRow(note, boxNameMap) {
         zettel_boxes: zettelBoxes,
     };
 }
+function parseStoredJsonValue(raw) {
+    const value = raw?.trim() ?? '';
+    if (!value) {
+        return null;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return raw;
+    }
+}
+function mapNoteExportRow(note, boxNameMap) {
+    const boxIds = parseZettelBoxIds(note.zettel_boxes_raw);
+    const boxes = boxIds
+        .map((boxId) => boxNameMap.get(boxId))
+        .filter((name) => typeof name === 'string' && name.length > 0);
+    return {
+        id: note.id,
+        created_at: note.created_at,
+        updated_at: note.updated_at,
+        title: note.title,
+        type: note.type,
+        source: note.source,
+        summary: note.summary,
+        tags: parseStoredTags(note.tags),
+        is_del: note.is_del,
+        is_starred: normalizeStoredStarred(note.is_starred),
+        content_md: note.content_md ?? '',
+        content_text: note.content_text,
+        content_json: parseStoredJsonValue(note.content_json),
+        box_ids: boxIds,
+        boxes,
+    };
+}
 export async function getNoteDetails(db, ids) {
     const targetIds = Array.from(new Set(ids
         .map((id) => id.trim())
@@ -696,6 +732,57 @@ export async function getNoteDetail(db, id) {
     const details = await getNoteDetails(db, [id]);
     return details[0] ?? null;
 }
+export async function getNoteExportItems(db, ids) {
+    const targetIds = Array.from(new Set(ids
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0)));
+    if (targetIds.length === 0) {
+        return [];
+    }
+    const noteRowsById = new Map();
+    const chunkSize = 500;
+    for (let index = 0; index < targetIds.length; index += chunkSize) {
+        const batch = targetIds.slice(index, index + chunkSize);
+        const placeholders = batch.map(() => '?').join(', ');
+        const rows = await db.getAll(`
+      SELECT
+        id,
+        created_at,
+        updated_at,
+        title,
+        type,
+        source,
+        tags,
+        summary,
+        is_del,
+        is_starred,
+        content_md,
+        content_text,
+        content_json,
+        zettel_boxes AS zettel_boxes_raw
+      FROM c_note
+      WHERE id IN (${placeholders})
+      `, batch);
+        for (const row of rows) {
+            const id = row.id?.trim() ?? '';
+            if (!id || noteRowsById.has(id)) {
+                continue;
+            }
+            noteRowsById.set(id, row);
+        }
+    }
+    const allBoxIds = Array.from(new Set(Array.from(noteRowsById.values()).flatMap((row) => parseZettelBoxIds(row.zettel_boxes_raw))));
+    const boxNameMap = await loadZettelBoxNameMap(db, allBoxIds);
+    const items = [];
+    for (const id of targetIds) {
+        const row = noteRowsById.get(id);
+        if (!row) {
+            continue;
+        }
+        items.push(mapNoteExportRow(row, boxNameMap));
+    }
+    return items;
+}
 export async function createNote(db, input) {
     const userId = input.userId.trim();
     if (!userId) {
@@ -790,14 +877,19 @@ export async function createNote(db, input) {
 function normalizeLookupKey(value) {
     return value.trim().toLowerCase();
 }
+function normalizeZettelBoxLookupKey(value) {
+    return canonicalizeBoxPath(value).toLowerCase();
+}
 function buildZettelBoxRetryQuestion(intent, type) {
     const command = intent === 'search'
         ? 'dino note search'
         : intent === 'update'
             ? 'dino note update'
-            : 'dino note create';
+            : intent === 'bulk'
+                ? 'dino note bulk'
+                : 'dino note create';
     if (type === 'ambiguous') {
-        return `Do you want to specify unique box names (or IDs) and retry \`${command}\`?`;
+        return `Do you want to specify box paths and retry \`${command}\`?`;
     }
     return `Do you want to add these missing boxes and retry \`${command}\`?`;
 }
@@ -807,6 +899,9 @@ export async function validateTagsForCreate(db, requestedTags) {
 export async function validateTagsForUpdate(db, requestedTags) {
     return validateTagsForWrite(db, requestedTags, 'dino note update');
 }
+export async function validateTagsForBulk(db, requestedTags) {
+    return validateTagsForWrite(db, requestedTags, 'dino note bulk');
+}
 async function validateTagsForWrite(db, requestedTags, retryCommand) {
     if (requestedTags.length === 0) {
         return [];
@@ -1013,30 +1108,43 @@ export async function resolveZettelBoxIdsForSearch(db, requestedNames) {
 export async function resolveZettelBoxIdsForUpdate(db, requestedNames) {
     return resolveZettelBoxIdsByName(db, requestedNames, 'update');
 }
+export async function resolveZettelBoxIdsForBulk(db, requestedNames) {
+    return resolveZettelBoxIdsByName(db, requestedNames, 'bulk');
+}
 async function resolveZettelBoxIdsByName(db, requestedNames, intent) {
     if (requestedNames.length === 0) {
         return [];
     }
     const boxes = await listBoxes(db);
-    const availableNames = Array.from(new Set(boxes.map((box) => box.name.trim()).filter(Boolean)));
+    const availablePaths = Array.from(new Set(boxes.map((box) => box.path.trim()).filter(Boolean)));
+    const boxByPath = new Map();
     const boxByName = new Map();
     for (const box of boxes) {
         const name = box.name.trim();
-        const key = normalizeLookupKey(name);
-        if (!key) {
+        const path = canonicalizeBoxPath(box.path || name);
+        const pathKey = normalizeZettelBoxLookupKey(path);
+        if (pathKey && !boxByPath.has(pathKey)) {
+            boxByPath.set(pathKey, box.id);
+        }
+        const nameKey = normalizeLookupKey(name);
+        if (!nameKey) {
             continue;
         }
-        const current = boxByName.get(key);
+        const current = boxByName.get(nameKey);
         if (!current) {
-            boxByName.set(key, {
+            boxByName.set(nameKey, {
                 name,
                 ids: [box.id],
+                paths: path ? [path] : [],
             });
             continue;
         }
         if (!current.ids.includes(box.id)) {
             current.ids.push(box.id);
         }
+        if (path && !current.paths.includes(path)) {
+            current.paths.push(path);
+        }
     }
     const resolvedIds = [];
     const seenIds = new Set();
@@ -1044,11 +1152,19 @@ async function resolveZettelBoxIdsByName(db, requestedNames, intent) {
     const ambiguous = [];
     const seenAmbiguous = new Set();
     for (const requested of requestedNames) {
-        const key = normalizeLookupKey(requested);
-        if (!key) {
+        const pathKey = normalizeZettelBoxLookupKey(requested);
+        if (!pathKey) {
+            continue;
+        }
+        const pathMatchId = boxByPath.get(pathKey);
+        if (pathMatchId) {
+            if (!seenIds.has(pathMatchId)) {
+                seenIds.add(pathMatchId);
+                resolvedIds.push(pathMatchId);
+            }
             continue;
         }
-        const lookup = boxByName.get(key);
+        const lookup = boxByName.get(normalizeLookupKey(requested));
         if (!lookup) {
             missing.push(requested);
             continue;
@@ -1060,6 +1176,7 @@ async function resolveZettelBoxIdsByName(db, requestedNames, intent) {
                 ambiguous.push({
                     name: requested,
                     ids: lookup.ids,
+                    paths: lookup.paths,
                 });
             }
             continue;
@@ -1071,22 +1188,22 @@ async function resolveZettelBoxIdsByName(db, requestedNames, intent) {
         }
     }
     if (ambiguous.length > 0) {
-        throw new DinoxError(`Ambiguous zettel box names: ${ambiguous.map((item) => `${item.name} -> [${item.ids.join(', ')}]`).join('; ')}`, {
+        throw new DinoxError(`Ambiguous zettel box names: ${ambiguous.map((item) => `${item.name} -> [${item.paths.join(', ')}]`).join('; ')}`, {
             details: {
                 type: 'ambiguous_zettel_boxes',
                 ambiguous,
-                availableNamesSample: availableNames.slice(0, 20),
+                availablePathsSample: availablePaths.slice(0, 20),
                 question: buildZettelBoxRetryQuestion(intent, 'ambiguous'),
             },
         });
     }
     if (missing.length > 0) {
-        throw new DinoxError(`Unknown zettel box names: ${missing.join(', ')}`, {
+        throw new DinoxError(`Unknown zettel box paths or names: ${missing.join(', ')}`, {
             details: {
                 type: 'missing_zettel_boxes',
                 missing,
-                availableCount: availableNames.length,
-                availableNamesSample: availableNames.slice(0, 20),
+                availableCount: availablePaths.length,
+                availablePathsSample: availablePaths.slice(0, 20),
                 question: buildZettelBoxRetryQuestion(intent, 'missing'),
             },
         });

package/dist/commands/notes/runtime.d.ts

@@ -1,15 +1,6 @@
 import type { Command } from 'commander';
-import type { AbstractPowerSyncDatabase } from '@powersync/common';
-import { loadConfig } from '../../config/store.js';
-import { resolveConfig } from '../../config/resolve.js';
-export type NoteCommandRuntime = {
-    db: AbstractPowerSyncDatabase;
-    config: ReturnType<typeof resolveConfig>;
-    rawConfig: Awaited<ReturnType<typeof loadConfig>>;
-    offline: boolean;
-    timeoutMs: number;
-    stale: boolean;
-};
+import { type CommandRuntime } from '../runtime.js';
+export type NoteCommandRuntime = CommandRuntime;
 export declare function parseNoteType(value: unknown): 'note' | 'crawl';
 export declare function parseSearchLimit(value: unknown): number;
 export declare function parseSearchOffset(value: unknown): number;
@@ -24,5 +15,5 @@ export type ParsedSearchListInput = {
 };
 export declare function parseSearchListInput(value: string, optionName: string): Promise<ParsedSearchListInput>;
 export declare function parseTargetNoteIds(idArg: string | undefined, idsOption: string | undefined, commandName: 'detail' | 'update'): Promise<string[]>;
-export declare function syncBeforeNoteCommand(db: AbstractPowerSyncDatabase, offline: boolean, timeoutMs: number): Promise<void>;
+export declare function syncBeforeNoteCommand(runtime: CommandRuntime): Promise<void>;
 export declare function withNoteDatabase(command: Command, run: (runtime: NoteCommandRuntime) => Promise<void>): Promise<void>;

package/dist/commands/notes/runtime.js

@@ -1,10 +1,6 @@
-import { loadConfig } from '../../config/store.js';
-import { resolveConfig } from '../../config/resolve.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
-import { syncNoteTokenIndex } from '../../powersync/tokenIndex.js';
 import { readStringOrFile } from '../../utils/argValue.js';
 import { DinoxError } from '../../utils/errors.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
+import { syncBeforeCommand, withCommandRuntime, } from '../runtime.js';
 const DEFAULT_NOTE_SEARCH_LIMIT = 50;
 const MAX_NOTE_SEARCH_LIMIT = 500;
 export function parseNoteType(value) {
@@ -155,31 +151,9 @@ export async function parseTargetNoteIds(idArg, idsOption, commandName) {
     }
     return ids;
 }
-export async function syncBeforeNoteCommand(db, offline, timeoutMs) {
-    if (offline) {
-        return;
-    }
-    await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
-    await syncNoteTokenIndex(db);
+export async function syncBeforeNoteCommand(runtime) {
+    await syncBeforeCommand(runtime, { syncTokenIndex: true });
 }
 export async function withNoteDatabase(command, run) {
-    const globals = command.optsWithGlobals?.() ?? {};
-    const rawConfig = await loadConfig();
-    const config = resolveConfig(rawConfig);
-    const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
-    const offline = Boolean(globals.offline);
-    const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-    try {
-        await run({
-            db,
-            config,
-            rawConfig,
-            offline,
-            timeoutMs,
-            stale,
-        });
-    }
-    finally {
-        await db.close().catch(() => undefined);
-    }
+    await withCommandRuntime(command, run);
 }

package/dist/commands/notes/searchSql.js

@@ -432,7 +432,7 @@ async function buildZettelBoxIdLookup(ast, resolveZettelBoxNames) {
     }
     const ids = await resolveZettelBoxNames(uniqueNames);
     if (ids.length !== uniqueNames.length) {
-        throw new DinoxError('Failed to resolve zettel box names in --sql expression');
+        throw new DinoxError('Failed to resolve zettel box paths or names in --sql expression');
     }
     const lookup = new Map();
     for (let i = 0; i < uniqueNames.length; i += 1) {

package/dist/commands/prompt/index.js

@@ -1,41 +1,17 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
-import { loadConfig } from '../../config/store.js';
-import { resolveConfig } from '../../config/resolve.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
-import { syncNoteTokenIndex } from '../../powersync/tokenIndex.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { buildPromptAddDryRunPreview } from '../writeDryRun.js';
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
+import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
 import { addPrompt, inspectAddPrompt, listPrompts } from './repo.js';
 const PROMPT_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
-async function syncBeforePromptCommand(db, offline, timeoutMs) {
-    if (offline) {
-        return;
-    }
-    await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
-    await syncNoteTokenIndex(db);
-}
-async function withPromptDb(context, run) {
-    const rawConfig = await loadConfig();
-    const config = resolveConfig(rawConfig);
-    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? config.sync.timeoutMs;
-    const offline = Boolean(context.globals.offline);
-    const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-    try {
-        await run({ db, config, rawConfig, offline, timeoutMs, stale });
-    }
-    finally {
-        await db.close().catch(() => undefined);
-    }
-}
 async function runPromptList(context) {
-    await withPromptDb(context, async ({ db, offline, timeoutMs }) => {
-        await syncBeforePromptCommand(db, offline, timeoutMs);
-        printSuccess((await listPrompts(db)).map((prompt) => ({
+    await withCommandRuntime(context, async (runtime) => {
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess((await listPrompts(runtime.db)).map((prompt) => ({
             name: prompt.name,
             prompt: prompt.cmd,
         })));
@@ -51,14 +27,14 @@ async function runPromptAdd(context) {
         throw new DinoxError('Prompt text is required. Use `dino prompt add --name <name> --prompt <text>`.');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withPromptDb(context, async ({ db, config, rawConfig, offline, timeoutMs, stale }) => {
-        const identity = await resolveAuthIdentity(rawConfig, config);
-        await syncBeforePromptCommand(db, offline, timeoutMs);
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildPromptAddDryRunPreview({
-                config,
-                offline,
-                ...(await inspectAddPrompt(db, {
+                config: runtime.config,
+                offline: runtime.offline,
+                ...(await inspectAddPrompt(runtime.db, {
                     name,
                     cmd,
                     userId: identity.userId,
@@ -66,20 +42,16 @@ async function runPromptAdd(context) {
             }));
             return;
         }
-        const result = await addPrompt(db, {
+        const result = await addPrompt(runtime.db, {
             name,
             cmd,
             userId: identity.userId,
         });
-        if (!offline && !config.powersync.uploadBaseUrl) {
-            printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
-        }
-        if (!offline) {
-            await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
-        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
         const payload = {
             ok: true,
-            stale: offline ? true : stale,
+            stale: commandStale(runtime),
             id: result.id,
             name: result.name,
             prompt: result.cmd,
@@ -90,9 +62,7 @@ async function runPromptAdd(context) {
             return;
         }
         printHumanReadableLine(result.id);
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; results may be stale');
-        }
+        printStaleCacheWarning(runtime, 'warning: sync timed out; results may be stale');
     });
 }
 export const promptCommandGroup = {

package/dist/commands/prompt/repo.js

@@ -71,7 +71,7 @@ export async function addPrompt(db, input) {
         throw new DinoxError(`c_cmd table is missing required columns: ${missingRequired.join(', ')}`);
     }
     if (columnNames.has('user_id') && !userId) {
-        throw new DinoxError('c_cmd insert requires user_id. Missing persisted userId. Run `dino auth login` first.');
+        throw new DinoxError('c_cmd insert requires user_id. Missing resolved userId. Run `dino auth login` first, or set DINOX_TOKEN and run an online command so the CLI can resolve the token identity.');
     }
     const rows = await listPromptRowsForWrite(db, columnNames);
     const samePromptRows = rows.filter((row) => {
@@ -181,7 +181,7 @@ export async function inspectAddPrompt(db, input) {
         throw new DinoxError(`c_cmd table is missing required columns: ${missingRequired.join(', ')}`);
     }
     if (columnNames.has('user_id') && !userId) {
-        throw new DinoxError('c_cmd insert requires user_id. Missing persisted userId. Run `dino auth login` first.');
+        throw new DinoxError('c_cmd insert requires user_id. Missing resolved userId. Run `dino auth login` first, or set DINOX_TOKEN and run an online command so the CLI can resolve the token identity.');
     }
     const rows = await listPromptRowsForWrite(db, columnNames);
     const samePromptRows = rows.filter((row) => {

package/dist/commands/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { Command } from 'commander';
+import { loadConfig } from '../config/store.js';
+import type { ResolvedDinoxConfig } from '../config/types.js';
+import type { CommandExecutionContext } from './descriptor/types.js';
+export type CommandRuntime = {
+    db: AbstractPowerSyncDatabase;
+    config: ResolvedDinoxConfig;
+    rawConfig: Awaited<ReturnType<typeof loadConfig>>;
+    offline: boolean;
+    timeoutMs: number;
+    stale: boolean;
+};
+type RuntimeSource = CommandExecutionContext | Command | Record<string, unknown>;
+export declare function commandStale(runtime: Pick<CommandRuntime, 'offline' | 'stale'>): boolean;
+export declare function withCommandRuntime<T>(source: RuntimeSource, run: (runtime: CommandRuntime) => Promise<T>): Promise<T>;
+export declare function syncBeforeCommand(runtime: CommandRuntime, options?: {
+    syncTokenIndex?: boolean;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function waitForMutationUpload(runtime: CommandRuntime, options?: {
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function printUploadDisabledWarning(runtime: CommandRuntime, message?: string): void;
+export declare function printStaleCacheWarning(runtime: CommandRuntime, message?: string): void;
+export {};