@dinoxx/dinox-cli 1.0.20 → 1.0.22

package/dist/commands/notes/descriptors.js

@@ -1,7 +1,10 @@
 import { registerCommandGroup } from '../descriptor/register.js';
-import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
-import { runNoteCreate, runNoteDelete, runNoteDetail, runNoteGet, runNotePreview, runNoteSearch, runNoteStar, runNoteUnstar, runNoteUpdate, } from './actions.js';
-const NOTE_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { runNoteCreate, runNoteDelete, runNoteDetail, runNoteGet, runNoteMove, runNotePreview, runNoteSearch, runNoteStar, runNoteTag, runNoteUnstar, runNoteUpdate, } from './actions.js';
+import { runNoteBulk as runNoteBulkAction } from './bulk.js';
+import { runNoteContentRead, runNotePatch } from './contentPatchCommand.js';
+import { runNoteExport } from './export.js';
+const NOTE_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 export const noteCommandGroup = {
     name: 'note',
     description: 'Manage notes',
@@ -16,7 +19,7 @@ export const noteCommandGroup = {
                 { flags: '--to <date>', description: 'created_at end (YYYY-MM-DD or ISO datetime)', type: 'string' },
                 { flags: '--days <n>', description: 'Recent N days by created_at; mutually exclusive with --from/--to', type: 'number' },
                 { flags: '--starred <true|false>', description: 'Filter by starred status', type: 'string', enum: ['true', 'false'] },
-                { flags: '--boxes <string|@file>', description: 'Box names (JSON array/comma list), or [] for empty boxes', type: 'string' },
+                { flags: '--boxes <string|@file>', description: 'Box paths or unique names (JSON array/comma list), or [] for empty boxes', type: 'string' },
                 { flags: '--sql <expr>', description: 'SQL-like expression over id/content_md/summary/tags/zettel_boxes/created_at/type/is_starred', type: 'string' },
                 { flags: '--limit <n>', description: 'Maximum returned notes', type: 'number' },
                 { flags: '--offset <n>', description: 'Result offset for pagination', type: 'number', defaultValue: 0 },
@@ -35,21 +38,6 @@ export const noteCommandGroup = {
                     fields: ['id', 'title', 'summary', 'tags', 'created_at', 'boxes', 'is_starred'],
                     metaFields: ['query', 'returned_count', 'total_count', 'stale', 'pagination', 'fields', 'applied_filters'],
                 },
-                mcp: {
-                    toolName: 'dinox_search_notes',
-                    description: 'Search notes by keyword, tags, date range, or SQL expression',
-                    properties: [
-                        { name: 'query', type: 'string', description: 'Search keyword' },
-                        { name: 'tags', type: 'string', description: 'Tag expression (AND/OR/NOT)' },
-                        { name: 'from', type: 'string', description: 'Start date (YYYY-MM-DD)' },
-                        { name: 'to', type: 'string', description: 'End date (YYYY-MM-DD)' },
-                        { name: 'days', type: 'number', description: 'Recent N days' },
-                        { name: 'boxes', type: 'string[]', description: 'Box names' },
-                        { name: 'limit', type: 'number', description: 'Max results (default: 50)' },
-                        { name: 'offset', type: 'number', description: 'Result offset (default: 0)' },
-                        { name: 'fields', type: 'string[]', description: 'Returned fields: id,title,summary,tags,created_at,boxes,is_starred' },
-                    ],
-                },
                 examples: [
                     'dino note search "AI" --days 7 --format json',
                     'dino note search --tags "(work OR life) AND NOT archived" --format json',
@@ -111,15 +99,59 @@ export const noteCommandGroup = {
                     summary: 'One full note object or an ordered array of note objects',
                     fields: ['id', 'title', 'content_md', 'content_text', 'content_json', 'tags', 'boxes', 'created_at', 'updated_at', 'is_del'],
                 },
-                mcp: {
-                    toolName: 'dinox_get_note',
-                    description: 'Get note details by ID',
-                    properties: [{ name: 'id', type: 'string', description: 'Note ID', required: true }],
-                },
                 examples: ['dino note detail <id> --format json', 'dino note detail --ids @/tmp/note-ids.txt --format json'],
             },
             action: runNoteDetail,
         },
+        {
+            name: 'export',
+            description: 'Export one or more notes as Markdown or JSON for backup and migration',
+            arguments: [{ syntax: '[id]', description: 'Optional note id when exporting a single note' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--type <markdown|json>', description: 'Export format: markdown or json', type: 'string', defaultValue: 'markdown', enum: ['markdown', 'json'] },
+                { flags: '--output <path>', description: 'Output file for one note, or output directory for multiple notes', type: 'string' },
+                { flags: '--overwrite', description: 'Replace existing export files when --output is used', type: 'boolean' },
+                { flags: '--include-deleted', description: 'Allow exporting soft-deleted notes', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.export',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Export payload or file write acknowledgement for note backup/migration',
+                    fields: ['format', 'count', 'notes', 'files', 'stale'],
+                },
+                examples: [
+                    'dino note export <id> --type markdown --output /tmp/dinox-export',
+                    'dino note export --ids @/tmp/note-ids.txt --type json --output /tmp/dinox-export --format json',
+                ],
+            },
+            action: runNoteExport,
+        },
+        {
+            name: 'content-read',
+            description: 'Read note content context and issue a short-lived token required before content patching',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [
+                { flags: '--include-content', description: 'Include full markdown content in the response', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.content-read',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Note content read context with readToken, base hash, heading outline, block index, and derived metadata',
+                    fields: ['noteId', 'title', 'readToken', 'readTokenExpiresAt', 'base', 'outline', 'blocks', 'derived', 'content', 'stale'],
+                },
+                examples: ['dino note content-read <id> --include-content --format json'],
+            },
+            action: runNoteContentRead,
+        },
         {
             name: 'create',
             description: 'Create a new note from markdown content',
@@ -128,7 +160,7 @@ export const noteCommandGroup = {
                 { flags: '--content <string|@file>', description: 'Markdown content', required: true, type: 'string' },
                 { flags: '--type <note|crawl>', description: 'Note type: note or crawl', type: 'string', defaultValue: 'crawl', enum: ['note', 'crawl'] },
                 { flags: '--tags <string|@file>', description: 'Tag list (JSON array or comma/newline-separated)', type: 'string' },
-                { flags: '--boxes <string|@file>', description: 'Box names (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--boxes <string|@file>', description: 'Box paths or unique names (JSON array or comma/newline-separated)', type: 'string' },
                 { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
             ],
             schema: {
@@ -141,29 +173,19 @@ export const noteCommandGroup = {
                     summary: 'Creation acknowledgement with the new note id',
                     fields: ['id', 'stale'],
                 },
-                mcp: {
-                    toolName: 'dinox_create_note',
-                    description: 'Create a new note',
-                    properties: [
-                        { name: 'title', type: 'string', description: 'Note title', required: true },
-                        { name: 'content', type: 'string', description: 'Markdown content', required: true },
-                        { name: 'tags', type: 'string[]', description: 'Tags' },
-                        { name: 'boxes', type: 'string[]', description: 'Zettel boxes' },
-                    ],
-                },
                 examples: ['dino note create --title "Weekly note" --content @/tmp/note.md --type note --format json'],
             },
             action: runNoteCreate,
         },
         {
             name: 'update',
-            description: 'Full-replace note tags, boxes, and/or starred state',
-            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note update' }],
+            description: 'Full-replace note metadata for explicit note ids',
+            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note full replacement' }],
             options: [
                 { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
-                { flags: '--tags <string|@file>', description: 'Full-replace tag list; use [] to clear', type: 'string' },
-                { flags: '--boxes <string|@file>', description: 'Full-replace box names; use [] to clear', type: 'string' },
-                { flags: '--starred <true|false>', description: 'Set starred status', type: 'string', enum: ['true', 'false'] },
+                { flags: '--tags <string|@file>', description: 'Replace the entire tag list; use [] to clear all tags', type: 'string' },
+                { flags: '--boxes <string|@file>', description: 'Replace the entire box list; use [] to clear all boxes', type: 'string' },
+                { flags: '--starred <true|false>', description: 'Replace the starred state', type: 'string', enum: ['true', 'false'] },
                 { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
             ],
             schema: {
@@ -173,13 +195,143 @@ export const noteCommandGroup = {
                 globalOptions: NOTE_GLOBAL_OPTIONS,
                 output: {
                     type: 'structured',
-                    summary: 'Mutation result with per-note update status',
+                    summary: 'Explicit-id full metadata replacement result with per-note status',
                     fields: ['total', 'updatedCount', 'results', 'stale'],
                 },
-                examples: ['dino note update <id> --tags "work,ai" --format json', 'dino note update --ids @/tmp/note-ids.txt --boxes "Inbox" --format json'],
+                examples: [
+                    'dino note update <id> --tags "work,ai" --format json --dry-run',
+                    'dino note update --ids @/tmp/note-ids.txt --boxes "Inbox" --starred true --format json',
+                ],
             },
             action: runNoteUpdate,
         },
+        {
+            name: 'tag',
+            description: 'Incrementally organize note tags for explicit note ids',
+            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note tag organization' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--add <string|@file>', description: 'Tags to add without removing existing tags', type: 'string' },
+                { flags: '--remove <string|@file>', description: 'Tags to remove while preserving the rest', type: 'string' },
+                { flags: '--replace <string|@file>', description: 'Replace the entire tag list; use [] to clear all tags', type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.tag',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Explicit-id incremental tag organization result with per-note status',
+                    fields: ['field', 'operation', 'total', 'updatedCount', 'results', 'stale'],
+                },
+                examples: [
+                    'dino note tag <id> --add "AI,work" --format json --dry-run',
+                    'dino note tag --ids @/tmp/note-ids.txt --remove "Inbox" --format json --dry-run',
+                ],
+            },
+            action: runNoteTag,
+        },
+        {
+            name: 'move',
+            description: 'Incrementally organize note zettel boxes for explicit note ids',
+            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note box organization' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--add <string|@file>', description: 'Box paths or unique names to add without removing existing boxes', type: 'string' },
+                { flags: '--remove <string|@file>', description: 'Box paths or unique names to remove while preserving the rest', type: 'string' },
+                { flags: '--replace <string|@file>', description: 'Replace the entire box list; use [] to clear all boxes', type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.move',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Explicit-id incremental box organization result with per-note status',
+                    fields: ['field', 'operation', 'total', 'updatedCount', 'results', 'stale'],
+                },
+                examples: [
+                    'dino note move <id> --add "Work/Inbox" --format json --dry-run',
+                    'dino note move --ids @/tmp/note-ids.txt --replace "Project/AI" --format json --dry-run',
+                ],
+            },
+            action: runNoteMove,
+        },
+        {
+            name: 'patch',
+            description: 'Patch note content structure after a required content-read token',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [
+                { flags: '--append-section <heading>', description: 'Append a new level-2 section at the end of the note', type: 'string' },
+                { flags: '--append-to-heading <path>', description: 'Append content to an existing heading path', type: 'string' },
+                { flags: '--replace-section <path>', description: 'Replace the body of an existing heading path', type: 'string' },
+                { flags: '--replace-block', description: 'Replace one exact markdown block matched by --match', type: 'boolean' },
+                { flags: '--match <string|@file>', description: 'Exact markdown to replace when using --replace-block', type: 'string' },
+                { flags: '--content <string|@file>', description: 'Markdown content to insert', type: 'string' },
+                { flags: '--read-token <token>', description: 'Required for real writes; returned by note content-read', type: 'string' },
+                { flags: '--allow-protected-replace', description: 'Allow replace operations to affect media, table, container, or unknown blocks after reviewing content-read output', type: 'boolean' },
+                { flags: '--dry-run', description: 'Preview the patch without writing', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.patch',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Structured content edit result with content hashes, block context, and synchronized derived metadata',
+                    fields: ['noteId', 'title', 'operation', 'changed', 'saved', 'beforeHash', 'afterHash', 'target', 'derived', 'stale'],
+                },
+                examples: [
+                    'dino note content-read <id> --format json',
+                    'dino note patch <id> --append-section "复盘" --content @/tmp/section.md --read-token <token> --format json',
+                ],
+            },
+            action: runNotePatch,
+        },
+        {
+            name: 'bulk',
+            description: 'Bulk organize note tags or boxes using safe search filters',
+            arguments: [{ syntax: '[query]', description: 'Optional keyword filter for target notes' }],
+            options: [
+                { flags: '--tags <expr>', description: 'Target filter: tag expression with AND/OR/NOT, or [] for empty tags', type: 'string' },
+                { flags: '--from <date>', description: 'Target filter: created_at start (YYYY-MM-DD or ISO datetime)', type: 'string' },
+                { flags: '--to <date>', description: 'Target filter: created_at end (YYYY-MM-DD or ISO datetime)', type: 'string' },
+                { flags: '--days <n>', description: 'Target filter: recent N days by created_at; mutually exclusive with --from/--to', type: 'number' },
+                { flags: '--starred <true|false>', description: 'Target filter: starred status', type: 'string', enum: ['true', 'false'] },
+                { flags: '--boxes <string|@file>', description: 'Target filter: box paths or unique names, or [] for empty boxes', type: 'string' },
+                { flags: '--all', description: 'Target all active notes; required when no other target filter is provided', type: 'boolean' },
+                { flags: '--tag-add <string|@file>', description: 'Tags to add to every matched note', type: 'string' },
+                { flags: '--tag-remove <string|@file>', description: 'Tags to remove from every matched note', type: 'string' },
+                { flags: '--tag-replace <string|@file>', description: 'Replace the entire tag list on every matched note; use [] to clear all tags', type: 'string' },
+                { flags: '--box-add <string|@file>', description: 'Box paths or unique names to add to every matched note', type: 'string' },
+                { flags: '--box-remove <string|@file>', description: 'Box paths or unique names to remove from every matched note', type: 'string' },
+                { flags: '--box-replace <string|@file>', description: 'Replace the entire box list on every matched note; use [] to clear all boxes', type: 'string' },
+                { flags: '--expected-count <n>', description: 'Required for real writes; must equal the current matched note count', type: 'number' },
+                { flags: '--confirm', description: 'Required for real writes after reviewing a dry run', type: 'boolean' },
+                { flags: '--dry-run', description: 'Preview matched targets and changes without executing', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.bulk',
+                risk: 'high-risk-write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Filter-based bulk metadata organization result with applied filters and per-note status',
+                    fields: ['field', 'operation', 'total', 'updatedCount', 'filters', 'results', 'stale'],
+                },
+                examples: [
+                    'dino note bulk --tags "Inbox" --tag-add "AI" --format json --dry-run',
+                    'dino note bulk "project" --boxes "Work/Inbox" --box-replace "Projects/Active" --expected-count 12 --confirm --format json',
+                ],
+            },
+            action: runNoteBulkAction,
+        },
         {
             name: 'delete',
             description: 'Soft-delete a note by setting is_del=1',

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

@@ -0,0 +1,21 @@
+import type { CommandExecutionContext } from '../descriptor/types.js';
+import { type NoteExportItem } from './repo.js';
+export type NoteExportFormat = 'markdown' | 'json';
+export type NoteExportFile = {
+    id: string;
+    path: string;
+    format: NoteExportFormat;
+};
+export type NoteExportResult = {
+    format: NoteExportFormat;
+    count: number;
+    notes: NoteExportItem[];
+    files: NoteExportFile[];
+};
+export declare function parseExportFormat(value: unknown): NoteExportFormat;
+export declare function buildExportFileName(note: NoteExportItem, format: NoteExportFormat): string;
+export declare function buildNoteExportStdout(args: {
+    notes: NoteExportItem[];
+    format: NoteExportFormat;
+}): string;
+export declare function runNoteExport({ command, options, args }: CommandExecutionContext): Promise<void>;

package/dist/commands/notes/export.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printHumanReadableBlock, printSuccess, toJson, } from '../../utils/output.js';
+import { commandStale, } from '../runtime.js';
+import { getNoteExportItems, } from './repo.js';
+import { parseTargetNoteIds, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
+export function parseExportFormat(value) {
+    if (value === undefined || value === null || value === '') {
+        return 'markdown';
+    }
+    if (typeof value !== 'string') {
+        throw new DinoxError('--type must be one of: markdown, json');
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'markdown' || normalized === 'md') {
+        return 'markdown';
+    }
+    if (normalized === 'json') {
+        return 'json';
+    }
+    throw new DinoxError('--type must be one of: markdown, json');
+}
+function normalizeFileNamePart(value) {
+    const normalized = value
+        .normalize('NFKD')
+        .replace(/[^\w\u4e00-\u9fff.-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+    return normalized || 'untitled';
+}
+export function buildExportFileName(note, format) {
+    const title = normalizeFileNamePart(note.title?.trim() ?? '');
+    const id = normalizeFileNamePart(note.id);
+    return `${title}-${id}.${format === 'markdown' ? 'md' : 'json'}`;
+}
+function serializeMarkdownExport(note) {
+    const frontmatter = stringifyYaml({
+        id: note.id,
+        title: note.title ?? '',
+        type: note.type ?? null,
+        created_at: note.created_at,
+        updated_at: note.updated_at,
+        source: note.source,
+        summary: note.summary,
+        tags: note.tags,
+        boxes: note.boxes,
+        box_ids: note.box_ids,
+        is_starred: note.is_starred,
+        is_del: note.is_del ?? 0,
+    }, {
+        lineWidth: 0,
+        indent: 2,
+    }).trimEnd();
+    return `---\n${frontmatter}\n---\n\n${note.content_md}`.trimEnd() + '\n';
+}
+function serializeJsonExport(notes) {
+    return toJson({
+        exported_at: new Date().toISOString(),
+        count: notes.length,
+        notes,
+    });
+}
+function assertNoMissingNotes(ids, notes) {
+    const found = new Set(notes.map((note) => note.id));
+    const missing = ids.filter((id) => !found.has(id));
+    if (missing.length > 0) {
+        throw new DinoxError(ids.length === 1 ? `Note not found: ${missing[0]}` : `Notes not found: ${missing.join(', ')}`);
+    }
+}
+function assertActiveNotes(notes, includeDeleted) {
+    if (includeDeleted) {
+        return;
+    }
+    const deleted = notes.filter((note) => typeof note.is_del === 'number' && note.is_del !== 0);
+    if (deleted.length > 0) {
+        throw new DinoxError(`Cannot export deleted notes without --include-deleted: ${deleted.map((note) => note.id).join(', ')}`);
+    }
+}
+async function pathExists(filePath) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function resolveOutputTargets(args) {
+    const outputPath = path.resolve(args.outputPath);
+    if (args.notes.length === 1) {
+        if (outputPath.endsWith(path.sep)) {
+            return [{
+                    id: args.notes[0].id,
+                    path: path.join(outputPath, buildExportFileName(args.notes[0], args.format)),
+                    format: args.format,
+                }];
+        }
+        const stat = await fs.stat(outputPath).catch((error) => {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        });
+        if (stat?.isDirectory()) {
+            return [{
+                    id: args.notes[0].id,
+                    path: path.join(outputPath, buildExportFileName(args.notes[0], args.format)),
+                    format: args.format,
+                }];
+        }
+        return [{ id: args.notes[0].id, path: outputPath, format: args.format }];
+    }
+    const stat = await fs.stat(outputPath).catch((error) => {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    });
+    if (stat && !stat.isDirectory()) {
+        throw new DinoxError('--output must be a directory when exporting multiple notes');
+    }
+    return args.notes.map((note) => ({
+        id: note.id,
+        path: path.join(outputPath, buildExportFileName(note, args.format)),
+        format: args.format,
+    }));
+}
+async function writeExportFiles(args) {
+    const targets = await resolveOutputTargets({
+        outputPath: args.outputPath,
+        notes: args.notes,
+        format: args.format,
+    });
+    for (const target of targets) {
+        if (!args.overwrite && await pathExists(target.path)) {
+            throw new DinoxError(`Refusing to overwrite existing file: ${target.path}`, {
+                suggestion: 'Use --overwrite to replace existing export files.',
+            });
+        }
+    }
+    if (args.notes.length > 1) {
+        await fs.mkdir(path.resolve(args.outputPath), { recursive: true, mode: 0o700 });
+    }
+    else {
+        await fs.mkdir(path.dirname(targets[0].path), { recursive: true, mode: 0o700 });
+    }
+    const noteById = new Map(args.notes.map((note) => [note.id, note]));
+    for (const target of targets) {
+        const note = noteById.get(target.id);
+        if (!note) {
+            continue;
+        }
+        const content = args.format === 'markdown'
+            ? serializeMarkdownExport(note)
+            : toJson(note);
+        await fs.writeFile(target.path, content, { encoding: 'utf8', flag: args.overwrite ? 'w' : 'wx' });
+    }
+    return targets;
+}
+export function buildNoteExportStdout(args) {
+    if (args.format === 'json') {
+        return serializeJsonExport(args.notes);
+    }
+    if (args.notes.length === 1) {
+        return serializeMarkdownExport(args.notes[0]);
+    }
+    return args.notes.map((note) => serializeMarkdownExport(note)).join('\n');
+}
+export async function runNoteExport({ command, options, args }) {
+    const exportOptions = options;
+    const format = parseExportFormat(exportOptions.type);
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withNoteDatabase(command, async (runtime) => {
+        const { db } = runtime;
+        await syncBeforeNoteCommand(runtime);
+        const ids = await parseTargetNoteIds(args.id, exportOptions.ids, 'detail');
+        const notes = await getNoteExportItems(db, ids);
+        assertNoMissingNotes(ids, notes);
+        assertActiveNotes(notes, Boolean(exportOptions.includeDeleted));
+        if (exportOptions.output) {
+            const files = await writeExportFiles({
+                notes,
+                format,
+                outputPath: exportOptions.output,
+                overwrite: Boolean(exportOptions.overwrite),
+            });
+            const payload = {
+                format,
+                count: notes.length,
+                notes: structuredOutput ? notes : [],
+                files,
+                stale: commandStale(runtime),
+            };
+            if (structuredOutput) {
+                printSuccess(payload);
+                return;
+            }
+            printHumanReadableLine(`Exported ${notes.length} note(s) to ${exportOptions.output}`);
+            for (const file of files) {
+                printHumanReadableLine(`- ${file.path}`);
+            }
+            return;
+        }
+        if (structuredOutput) {
+            printSuccess({
+                format,
+                count: notes.length,
+                notes,
+                stale: commandStale(runtime),
+            });
+            return;
+        }
+        if (format === 'json') {
+            printHumanReadableBlock(serializeJsonExport(notes));
+            return;
+        }
+        printHumanReadableBlock(buildNoteExportStdout({ notes, format }));
+    });
+}

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

@@ -0,0 +1,28 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+export type NoteMetadataListField = 'tags' | 'boxes';
+export type NoteMetadataOperation = 'add' | 'remove' | 'replace';
+export type NoteMetadataMutationInput = {
+    ids: string[];
+    field: NoteMetadataListField;
+    operation: NoteMetadataOperation;
+    values: string[];
+    displayValues?: string[];
+};
+export type NoteMetadataMutationItem = {
+    id: string;
+    title: string;
+    before: string[];
+    after: string[];
+    changed: boolean;
+};
+export type NoteMetadataMutationPlan = {
+    field: NoteMetadataListField;
+    operation: NoteMetadataOperation;
+    values: string[];
+    displayValues: string[];
+    total: number;
+    changedCount: number;
+    results: NoteMetadataMutationItem[];
+};
+export declare function planNoteMetadataMutation(db: AbstractPowerSyncDatabase, input: NoteMetadataMutationInput): Promise<NoteMetadataMutationPlan>;
+export declare function applyNoteMetadataMutation(db: AbstractPowerSyncDatabase, plan: NoteMetadataMutationPlan): Promise<NoteMetadataMutationPlan>;