@dinoxx/dinox-cli 1.0.20 → 1.0.22

package/dist/commands/notes/actions.js

@@ -5,9 +5,10 @@ import { generateId } from '../../utils/id.js';
 import { convertMarkdownToNoteContent } from '../../utils/tiptapMarkdown.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
 import { DinoxError } from '../../utils/errors.js';
-import { waitForIdleDataFlow } from '../../powersync/runtime.js';
+import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, waitForMutationUpload, } from '../runtime.js';
 import { createNote, getNote, getNoteContext, getNoteDetails, getNotePreview, assertNotesUpdatable, resolveZettelBoxIdsForCreate, resolveZettelBoxIdsForSearch, resolveZettelBoxIdsForUpdate, searchNotes, softDeleteNote, updateNote, validateTagsForCreate, validateTagsForUpdate, } from './repo.js';
 import { buildNoteCreateDryRunPreview, buildNoteDeleteDryRunPreview, buildNoteUpdateDryRunPreview, } from './dryRun.js';
+import { applyNoteMetadataMutation, planNoteMetadataMutation, } from './metadataMutation.js';
 import { parseNoteSearchFields, projectNoteSearchFields } from './searchOutput.js';
 import { parseCreatedAtRange } from './searchTime.js';
 import { buildNoteSearchResponse, normalizeDaysForMeta } from './searchResponse.js';
@@ -39,13 +40,11 @@ function toPublicNote(note) {
         ...(zettel_boxes !== undefined ? { boxes: zettel_boxes } : {}),
     };
 }
-async function settleMutation(db, timeoutMs) {
-    await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
-}
 async function executeNoteUpdateOperation(args) {
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withNoteDatabase(args.command, async ({ db, config, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(args.command, async (runtime) => {
+        const { db, config, offline } = runtime;
+        await syncBeforeNoteCommand(runtime);
         const ids = await parseTargetNoteIds(args.id, args.idsOption, 'update');
         const hasTags = typeof args.tagsOption === 'string';
         const hasBoxes = typeof args.boxOption === 'string';
@@ -85,12 +84,8 @@ async function executeNoteUpdateOperation(args) {
             }));
         }
         const updatedCount = results.filter((item) => item.updated).length;
-        if (!offline && !config.powersync.uploadBaseUrl) {
-            printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
-        }
-        if (!offline) {
-            await settleMutation(db, timeoutMs);
-        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
         const payload = {
             ok: true,
             total: results.length,
@@ -102,7 +97,7 @@ async function executeNoteUpdateOperation(args) {
                 boxes: item.zettelBoxIds,
                 is_starred: item.is_starred,
             })),
-            stale: offline ? true : stale,
+            stale: commandStale(runtime),
         };
         if (structuredOutput) {
             printSuccess(payload);
@@ -125,15 +120,101 @@ async function executeNoteUpdateOperation(args) {
         else {
             printHumanReadableLine(`Updated ${updatedCount}/${results.length} notes`);
         }
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; local cache may be stale');
+        printStaleCacheWarning(runtime);
+    });
+}
+function selectMetadataOperation(options) {
+    const candidates = [
+        ['--add', options.add],
+        ['--remove', options.remove],
+        ['--replace', options.replace],
+    ].filter((entry) => typeof entry[1] === 'string');
+    if (candidates.length !== 1) {
+        throw new DinoxError('Provide exactly one of --add, --remove, or --replace');
+    }
+    const [optionName, rawValues] = candidates[0];
+    return {
+        operation: optionName === '--add' ? 'add' : optionName === '--remove' ? 'remove' : 'replace',
+        rawValues,
+        optionName,
+    };
+}
+async function executeNoteMetadataListOperation(args) {
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withNoteDatabase(args.command, async (runtime) => {
+        const { db, config, offline } = runtime;
+        await syncBeforeNoteCommand(runtime);
+        const ids = await parseTargetNoteIds(args.id, args.idsOption, 'update');
+        const selected = selectMetadataOperation(args.options);
+        const requestedValues = await parseStringListInput(selected.rawValues, selected.optionName);
+        const values = args.field === 'tags'
+            ? await validateTagsForUpdate(db, requestedValues)
+            : await resolveZettelBoxIdsForUpdate(db, requestedValues);
+        const plan = await planNoteMetadataMutation(db, {
+            ids,
+            field: args.field,
+            operation: selected.operation,
+            values,
+            displayValues: requestedValues,
+        });
+        if (args.options.dryRun) {
+            printDryRunPreview({
+                dry_run: true,
+                command: args.commandName,
+                action: args.actionName,
+                risk: 'write',
+                summary: `Preview ${args.field} ${selected.operation} for ${plan.total} note(s); ${plan.changedCount} note(s) would change.`,
+                warnings: [
+                    ...(offline ? ['Execution would run in offline mode and only use the local cache.'] : []),
+                    ...(!offline && !config.powersync.uploadBaseUrl
+                        ? ['Execution would be local-only because powersync.uploadBaseUrl is unset.']
+                        : []),
+                ],
+                inputs: {
+                    ids,
+                    operation: selected.operation,
+                    [args.field]: args.field === 'tags' ? values : requestedValues,
+                },
+                targets: plan.results.map((item) => ({ id: item.id, title: item.title })),
+                changes: plan.results.map((item) => ({
+                    id: item.id,
+                    title: item.title,
+                    [`${args.field}_from`]: item.before,
+                    [`${args.field}_to`]: item.after,
+                    changed: item.changed,
+                })),
+            });
+            return;
+        }
+        await applyNoteMetadataMutation(db, plan);
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = {
+            ok: true,
+            field: args.field,
+            operation: selected.operation,
+            total: plan.total,
+            updatedCount: plan.changedCount,
+            results: plan.results.map((item) => ({
+                id: item.id,
+                updated: item.changed,
+                [args.field]: item.after,
+            })),
+            stale: commandStale(runtime),
+        };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
         }
+        printHumanReadableLine(`Updated ${plan.changedCount}/${plan.total} notes`);
+        printStaleCacheWarning(runtime);
     });
 }
 export async function runNoteSearch({ command, options, args }) {
     const searchOptions = options;
-    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db } = runtime;
+        await syncBeforeNoteCommand(runtime);
         const keyword = args.query?.trim() ?? '';
         const tagsExpression = typeof searchOptions.tags === 'string' ? searchOptions.tags.trim() : '';
         const { createdAtFrom, createdAtTo } = parseCreatedAtRange({
@@ -167,7 +248,7 @@ export async function runNoteSearch({ command, options, args }) {
             query: keyword,
             notes: projectNoteSearchFields(rows.slice(offset, offset + limit), fields),
             totalCount: rows.length,
-            stale: offline ? true : stale,
+            stale: commandStale(runtime),
             includeDeleted: Boolean(searchOptions.includeDeleted),
             limit,
             offset,
@@ -191,8 +272,9 @@ export async function runNoteGet({ command, options, args }) {
         throw new DinoxError('Note id is required');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db } = runtime;
+        await syncBeforeNoteCommand(runtime);
         if (getOptions.contextOnly) {
             const context = await getNoteContext(db, id);
             if (!context) {
@@ -202,7 +284,7 @@ export async function runNoteGet({ command, options, args }) {
                     recoverable: true,
                 });
             }
-            printSuccess({ stale: offline ? true : stale, note: toPublicNoteContext(context) });
+            printSuccess({ stale: commandStale(runtime), note: toPublicNoteContext(context) });
             return;
         }
         const note = await getNote(db, id);
@@ -214,12 +296,10 @@ export async function runNoteGet({ command, options, args }) {
             });
         }
         if (structuredOutput) {
-            printSuccess({ stale, note: toPublicNote(note) });
+            printSuccess({ stale: commandStale(runtime), note: toPublicNote(note) });
             return;
         }
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; result may be stale');
-        }
+        printStaleCacheWarning(runtime, 'warning: sync timed out; result may be stale');
         printHumanReadableLine(`${note.id}`);
         printHumanReadableLine(`title: ${note.title ?? ''}`);
         if (note.updated_at) {
@@ -239,8 +319,9 @@ export async function runNotePreview({ command, options, args }) {
     if (!id) {
         throw new DinoxError('Note id is required');
     }
-    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db } = runtime;
+        await syncBeforeNoteCommand(runtime);
         const preview = await getNotePreview(db, id, parsePreviewLineCount(previewOptions.lines));
         if (!preview) {
             throw new DinoxError(`Note not found: ${id}`, {
@@ -249,13 +330,14 @@ export async function runNotePreview({ command, options, args }) {
                 recoverable: true,
             });
         }
-        printSuccess({ stale: offline ? true : stale, note: preview });
+        printSuccess({ stale: commandStale(runtime), note: preview });
     });
 }
 export async function runNoteDetail({ command, options, args }) {
     const detailOptions = options;
-    await withNoteDatabase(command, async ({ db, offline, timeoutMs }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db } = runtime;
+        await syncBeforeNoteCommand(runtime);
         const ids = await parseTargetNoteIds(args.id, detailOptions.ids, 'detail');
         const notes = await getNoteDetails(db, ids);
         const foundIds = new Set(notes.map((note) => note.id));
@@ -270,9 +352,10 @@ export async function runNoteDetail({ command, options, args }) {
 export async function runNoteCreate({ command, options }) {
     const createOptions = options;
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withNoteDatabase(command, async ({ db, rawConfig, config, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
-        const identity = await resolveAuthIdentity(rawConfig, config);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db, config, offline } = runtime;
+        await syncBeforeNoteCommand(runtime);
+        const identity = await resolveAuthIdentity(config);
         const contentMd = await parseStringInput(String(createOptions.content));
         const canonicalContentMd = await canonicalizeBidlinksInMarkdown(db, contentMd, identity.userId);
         const { contentJson, contentText } = convertMarkdownToNoteContent(canonicalContentMd);
@@ -309,21 +392,15 @@ export async function runNoteCreate({ command, options }) {
             zettelBoxIds: await resolveZettelBoxIdsForCreate(db, boxNames),
             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 settleMutation(db, timeoutMs);
-        }
-        const payload = { ok: true, id, stale: offline ? true : stale };
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = { ok: true, id, stale: commandStale(runtime) };
         if (structuredOutput) {
             printSuccess(payload);
             return;
         }
         printHumanReadableLine(id);
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; local cache may be stale');
-        }
+        printStaleCacheWarning(runtime);
     });
 }
 export async function runNoteDelete({ command, options, args }) {
@@ -333,28 +410,23 @@ export async function runNoteDelete({ command, options, args }) {
         throw new DinoxError('Note id is required');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withNoteDatabase(command, async ({ db, config, offline, timeoutMs, stale }) => {
-        await syncBeforeNoteCommand(db, offline, timeoutMs);
+    await withNoteDatabase(command, async (runtime) => {
+        const { db, config, offline } = runtime;
+        await syncBeforeNoteCommand(runtime);
         if (Boolean(deleteOptions.dryRun)) {
             printDryRunPreview(await buildNoteDeleteDryRunPreview({ db, config, offline, id }));
             return;
         }
         await softDeleteNote(db, id);
-        if (!offline && !config.powersync.uploadBaseUrl) {
-            printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
-        }
-        if (!offline) {
-            await settleMutation(db, timeoutMs);
-        }
-        const payload = { ok: true, id, stale: offline ? true : stale };
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = { ok: true, id, stale: commandStale(runtime) };
         if (structuredOutput) {
             printSuccess(payload);
             return;
         }
         printHumanReadableLine('OK');
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; local cache may be stale');
-        }
+        printStaleCacheWarning(runtime);
     });
 }
 export async function runNoteUpdate({ command, options, args }) {
@@ -373,6 +445,28 @@ export async function runNoteUpdate({ command, options, args }) {
         actionName: 'update_note',
     });
 }
+export async function runNoteTag({ command, options, args }) {
+    await executeNoteMetadataListOperation({
+        command,
+        id: args.id,
+        idsOption: options.ids,
+        options: options,
+        field: 'tags',
+        commandName: 'dino note tag',
+        actionName: 'mutate_note_tags',
+    });
+}
+export async function runNoteMove({ command, options, args }) {
+    await executeNoteMetadataListOperation({
+        command,
+        id: args.id,
+        idsOption: options.ids,
+        options: options,
+        field: 'boxes',
+        commandName: 'dino note move',
+        actionName: 'mutate_note_boxes',
+    });
+}
 export async function runNoteStar({ command, options, args }) {
     const starOptions = options;
     await executeNoteUpdateOperation({

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

@@ -0,0 +1,34 @@
+import type { CommandExecutionContext } from '../descriptor/types.js';
+import type { NoteMetadataListField, NoteMetadataOperation } from './metadataMutation.js';
+type NoteBulkOptions = {
+    tags?: string;
+    from?: string;
+    to?: string;
+    days?: string;
+    starred?: string;
+    boxes?: string;
+    all?: boolean;
+    tagAdd?: string;
+    tagRemove?: string;
+    tagReplace?: string;
+    boxAdd?: string;
+    boxRemove?: string;
+    boxReplace?: string;
+    expectedCount?: string;
+    confirm?: boolean;
+    dryRun?: boolean;
+};
+type NoteBulkMutationSelection = {
+    field: NoteMetadataListField;
+    operation: NoteMetadataOperation;
+    rawValues: string;
+    optionName: '--tag-add' | '--tag-remove' | '--tag-replace' | '--box-add' | '--box-remove' | '--box-replace';
+};
+export declare function selectBulkMutation(options: NoteBulkOptions): NoteBulkMutationSelection;
+export declare function parseExpectedCount(value: unknown): number | null;
+export declare function assertBulkTargetFilter(input: {
+    query: string;
+    options: NoteBulkOptions;
+}): void;
+export declare function runNoteBulk({ command, options, args }: CommandExecutionContext): Promise<void>;
+export {};

package/dist/commands/notes/bulk.js

@@ -0,0 +1,204 @@
+import { printDryRunPreview } from '../../utils/dryRun.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
+import { DinoxError } from '../../utils/errors.js';
+import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, waitForMutationUpload, } from '../runtime.js';
+import { resolveZettelBoxIdsForBulk, resolveZettelBoxIdsForSearch, searchNotes, validateTagsForBulk, } from './repo.js';
+import { applyNoteMetadataMutation, planNoteMetadataMutation, } from './metadataMutation.js';
+import { parseCreatedAtRange } from './searchTime.js';
+import { normalizeDaysForMeta, } from './searchResponse.js';
+import { parseSearchListInput, parseStarredOption, parseStringListInput, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
+const BULK_PREVIEW_LIMIT = 100;
+export function selectBulkMutation(options) {
+    const candidates = [
+        { optionName: '--tag-add', field: 'tags', operation: 'add', rawValues: options.tagAdd },
+        { optionName: '--tag-remove', field: 'tags', operation: 'remove', rawValues: options.tagRemove },
+        { optionName: '--tag-replace', field: 'tags', operation: 'replace', rawValues: options.tagReplace },
+        { optionName: '--box-add', field: 'boxes', operation: 'add', rawValues: options.boxAdd },
+        { optionName: '--box-remove', field: 'boxes', operation: 'remove', rawValues: options.boxRemove },
+        { optionName: '--box-replace', field: 'boxes', operation: 'replace', rawValues: options.boxReplace },
+    ];
+    const selected = candidates.filter((entry) => typeof entry.rawValues === 'string');
+    if (selected.length !== 1) {
+        throw new DinoxError('Provide exactly one bulk mutation option: --tag-add, --tag-remove, --tag-replace, --box-add, --box-remove, or --box-replace');
+    }
+    return selected[0];
+}
+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;
+}
+function hasConcreteTargetFilter(input) {
+    const { query, options } = input;
+    return Boolean(query ||
+        options.tags ||
+        options.from ||
+        options.to ||
+        options.days ||
+        options.starred ||
+        options.boxes);
+}
+export function assertBulkTargetFilter(input) {
+    const hasFilter = hasConcreteTargetFilter(input);
+    if (input.options.all && hasFilter) {
+        throw new DinoxError('--all cannot be combined with other target filters');
+    }
+    if (!input.options.all && !hasFilter) {
+        throw new DinoxError('Provide at least one target filter or --all for note bulk');
+    }
+}
+function buildExecutionWarnings(input) {
+    const warnings = [];
+    if (input.offline) {
+        warnings.push('Execution would run in offline mode and only use the local cache.');
+    }
+    if (!input.offline && !input.uploadEnabled) {
+        warnings.push('Execution would be local-only because powersync.uploadBaseUrl is unset.');
+    }
+    if (input.total > BULK_PREVIEW_LIMIT) {
+        warnings.push(`Preview is truncated to the first ${BULK_PREVIEW_LIMIT} matched notes.`);
+    }
+    return warnings;
+}
+function previewItems(items) {
+    return items.slice(0, BULK_PREVIEW_LIMIT);
+}
+export async function runNoteBulk({ command, options, args }) {
+    const bulkOptions = options;
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withNoteDatabase(command, async (runtime) => {
+        const { db, config, offline } = runtime;
+        await syncBeforeNoteCommand(runtime);
+        const query = args.query?.trim() ?? '';
+        assertBulkTargetFilter({ query, options: bulkOptions });
+        const selected = selectBulkMutation(bulkOptions);
+        const requestedValues = await parseStringListInput(selected.rawValues, selected.optionName);
+        const values = selected.field === 'tags'
+            ? await validateTagsForBulk(db, requestedValues)
+            : await resolveZettelBoxIdsForBulk(db, requestedValues);
+        const tagsExpression = typeof bulkOptions.tags === 'string' ? bulkOptions.tags.trim() : '';
+        const { createdAtFrom, createdAtTo } = parseCreatedAtRange({
+            from: bulkOptions.from,
+            to: bulkOptions.to,
+            days: bulkOptions.days,
+        });
+        const starred = typeof bulkOptions.starred === 'string'
+            ? parseStarredOption(bulkOptions.starred, '--starred')
+            : undefined;
+        const boxInput = typeof bulkOptions.boxes === 'string' ? bulkOptions.boxes : '';
+        const parsedBoxInput = boxInput
+            ? await parseSearchListInput(boxInput, '--boxes')
+            : { values: [], isExplicitEmptyArray: false };
+        const zettelBoxIds = await resolveZettelBoxIdsForSearch(db, parsedBoxInput.values);
+        const matches = await searchNotes(db, query, {
+            includeDeleted: false,
+            tagsExpression: tagsExpression || undefined,
+            createdAtFrom,
+            createdAtTo,
+            starred,
+            zettelBoxIds,
+            matchEmptyZettelBoxes: parsedBoxInput.isExplicitEmptyArray,
+        });
+        const ids = matches.map((note) => note.id);
+        if (ids.length === 0) {
+            throw new DinoxError('No active notes matched the bulk filters');
+        }
+        const plan = await planNoteMetadataMutation(db, {
+            ids,
+            field: selected.field,
+            operation: selected.operation,
+            values,
+            displayValues: requestedValues,
+        });
+        const expectedCount = parseExpectedCount(bulkOptions.expectedCount);
+        const filterMeta = {
+            query,
+            tags_expression: tagsExpression || null,
+            created_at_range: createdAtFrom || createdAtTo
+                ? { from: createdAtFrom ?? null, to: createdAtTo ?? null }
+                : null,
+            days: normalizeDaysForMeta(bulkOptions.days) ?? null,
+            starred: typeof starred === 'boolean' ? starred : null,
+            box_names: parsedBoxInput.values,
+            box_ids: zettelBoxIds,
+            match_empty_boxes: parsedBoxInput.isExplicitEmptyArray,
+            all: Boolean(bulkOptions.all),
+        };
+        if (bulkOptions.dryRun) {
+            printDryRunPreview({
+                dry_run: true,
+                command: 'dino note bulk',
+                action: 'bulk_mutate_note_metadata',
+                risk: 'high-risk-write',
+                summary: `Preview bulk ${selected.field} ${selected.operation} for ${plan.total} matched note(s); ${plan.changedCount} note(s) would change.`,
+                warnings: buildExecutionWarnings({
+                    offline,
+                    uploadEnabled: Boolean(config.powersync.uploadBaseUrl),
+                    total: plan.total,
+                }),
+                inputs: {
+                    filters: filterMeta,
+                    operation: selected.operation,
+                    field: selected.field,
+                    [selected.field]: selected.field === 'tags' ? values : requestedValues,
+                    expected_count: expectedCount,
+                    preview_limit: BULK_PREVIEW_LIMIT,
+                    preview_truncated: plan.total > BULK_PREVIEW_LIMIT,
+                },
+                targets: previewItems(plan.results).map((item) => ({ id: item.id, title: item.title })),
+                changes: previewItems(plan.results).map((item) => ({
+                    id: item.id,
+                    title: item.title,
+                    [`${selected.field}_from`]: item.before,
+                    [`${selected.field}_to`]: item.after,
+                    changed: item.changed,
+                })),
+            });
+            return;
+        }
+        if (!bulkOptions.confirm) {
+            throw new DinoxError('Bulk writes require --confirm');
+        }
+        if (expectedCount === null) {
+            throw new DinoxError('Bulk writes require --expected-count <n>');
+        }
+        if (expectedCount !== plan.total) {
+            throw new DinoxError(`--expected-count ${expectedCount} does not match current target count ${plan.total}`);
+        }
+        await applyNoteMetadataMutation(db, plan);
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = {
+            ok: true,
+            field: selected.field,
+            operation: selected.operation,
+            total: plan.total,
+            updatedCount: plan.changedCount,
+            filters: filterMeta,
+            results: plan.results.map((item) => ({
+                id: item.id,
+                updated: item.changed,
+                [selected.field]: item.after,
+            })),
+            stale: commandStale(runtime),
+        };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine(`Updated ${plan.changedCount}/${plan.total} notes`);
+        printStaleCacheWarning(runtime);
+    });
+}

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

@@ -0,0 +1,95 @@
+export type TiptapNode = {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: TiptapNode[];
+    marks?: Array<Record<string, unknown>>;
+    text?: string;
+    [key: string]: unknown;
+};
+export type NoteContentEditMode = 'text' | 'inlineAtom' | 'atomicBlock' | 'container' | 'unsupported';
+export type NoteContentBlockDescriptor = {
+    anchorId: string;
+    hasStableAnchor: boolean;
+    nodeIndex: number;
+    nodeRange: string;
+    type: string;
+    editMode: NoteContentEditMode;
+    level: number | null;
+    text: string;
+    textPreview: string;
+    textHash: string;
+    nodeHash: string;
+    charCount: number;
+    attrs?: Record<string, unknown>;
+};
+export type NoteContentOutlineItem = {
+    path: string;
+    level: number;
+    nodeRange: string;
+    contentHash: string;
+};
+export type NoteContentProjection = {
+    document: TiptapNode;
+    contentJson: string;
+    contentMd: string;
+    contentText: string;
+    hashtags: string[];
+    images: string[];
+    bidLinks: Array<{
+        id: string;
+        type: string;
+    }>;
+};
+export type HashtagReferenceResolver = (input: {
+    id: string;
+    path: string;
+}) => {
+    id: string;
+    path: string;
+} | null;
+export type NoteContentProjectionOptions = {
+    resolveHashtagReference?: HashtagReferenceResolver;
+};
+export type JsonPatchOperation = {
+    kind: 'appendSection';
+    heading: string;
+    content: string;
+} | {
+    kind: 'appendToHeading';
+    headingPath: string;
+    content: string;
+} | {
+    kind: 'replaceSection';
+    headingPath: string;
+    content: string;
+    allowProtectedReplace?: boolean;
+} | {
+    kind: 'replaceBlock';
+    match: string;
+    content: string;
+    allowProtectedReplace?: boolean;
+};
+export type JsonPatchPlan = {
+    operation: JsonPatchOperation['kind'];
+    changed: boolean;
+    beforeHash: string;
+    afterHash: string;
+    beforeContent: string;
+    afterContent: string;
+    beforeBlocks: NoteContentBlockDescriptor[];
+    afterBlocks: NoteContentBlockDescriptor[];
+    beforeProjection: NoteContentProjection;
+    afterProjection: NoteContentProjection;
+    target?: Record<string, unknown>;
+};
+export declare function parseStoredNoteDocument(input: {
+    contentJson: string | null;
+    contentMd: string | null;
+}): TiptapNode;
+export declare function buildNoteContentBlocks(document: TiptapNode): NoteContentBlockDescriptor[];
+export declare function buildNoteContentOutline(document: TiptapNode): NoteContentOutlineItem[];
+export declare function getNoteContentHash(document: TiptapNode): string;
+export declare function serializeNoteContentMarkdown(document: TiptapNode): string;
+export declare function projectNoteContent(document: TiptapNode, options?: NoteContentProjectionOptions): NoteContentProjection;
+export declare function applyJsonPatchToDocument(document: TiptapNode, operation: JsonPatchOperation, options?: NoteContentProjectionOptions): JsonPatchPlan;
+export declare function withStableBlockAnchors(document: TiptapNode): TiptapNode;