@dinoxx/dinox-cli 1.0.17 → 1.0.19

package/dist/commands/notes/actions.js

@@ -0,0 +1,403 @@
+import { resolveAuthIdentity } from '../../auth/userInfo.js';
+import { canonicalizeBidlinksInMarkdown } from '../../utils/bidlinkCanonicalization.js';
+import { printDryRunPreview } from '../../utils/dryRun.js';
+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 { 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 { parseNoteSearchFields, projectNoteSearchFields } from './searchOutput.js';
+import { parseCreatedAtRange } from './searchTime.js';
+import { buildNoteSearchResponse, normalizeDaysForMeta } from './searchResponse.js';
+import { parseNoteType, parsePreviewLineCount, parseSearchLimit, parseSearchListInput, parseSearchOffset, parseStarredOption, parseStringInput, parseStringListInput, parseTargetNoteIds, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
+function toPublicNoteContext(note) {
+    if (!note) {
+        return null;
+    }
+    const { zettel_boxes, ...rest } = note;
+    return {
+        ...rest,
+        boxes: zettel_boxes,
+    };
+}
+function toPublicNoteDetail(note) {
+    const { zettel_boxes, ...rest } = note;
+    return {
+        ...rest,
+        boxes: zettel_boxes,
+    };
+}
+function toPublicNote(note) {
+    if (!note) {
+        return null;
+    }
+    const { zettel_boxes, ...rest } = note;
+    return {
+        ...rest,
+        ...(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);
+        const ids = await parseTargetNoteIds(args.id, args.idsOption, 'update');
+        const hasTags = typeof args.tagsOption === 'string';
+        const hasBoxes = typeof args.boxOption === 'string';
+        const hasStarred = typeof args.starred === 'boolean';
+        if (!hasTags && !hasBoxes && !hasStarred) {
+            throw new DinoxError('At least one option is required: --tags, --boxes, or --starred');
+        }
+        const tags = hasTags
+            ? await validateTagsForUpdate(db, await parseStringListInput(args.tagsOption, '--tags'))
+            : undefined;
+        const zettelBoxIds = hasBoxes
+            ? await resolveZettelBoxIdsForUpdate(db, await parseStringListInput(args.boxOption, '--boxes'))
+            : undefined;
+        await assertNotesUpdatable(db, ids);
+        if (args.dryRun) {
+            const preview = await buildNoteUpdateDryRunPreview({
+                db,
+                config,
+                offline,
+                ids,
+                tagsInput: tags,
+                zettelBoxNames: hasBoxes ? await parseStringListInput(args.boxOption, '--boxes') : undefined,
+                starred: hasStarred ? args.starred : undefined,
+                commandName: args.commandName ?? 'dino note update',
+                action: args.actionName ?? 'update_note',
+            });
+            printDryRunPreview(preview);
+            return;
+        }
+        const results = [];
+        for (const targetId of ids) {
+            results.push(await updateNote(db, {
+                id: targetId,
+                tags,
+                zettelBoxIds,
+                starred: hasStarred ? args.starred : undefined,
+            }));
+        }
+        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);
+        }
+        const payload = {
+            ok: true,
+            total: results.length,
+            updatedCount,
+            results: results.map((item) => ({
+                id: item.id,
+                updated: item.updated,
+                tags: item.tags,
+                boxes: item.zettelBoxIds,
+                is_starred: item.is_starred,
+            })),
+            stale: offline ? true : stale,
+        };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        if (results.length === 1) {
+            if (!args.actionLabel) {
+                printHumanReadableLine(results[0].updated ? 'OK' : 'No changes');
+            }
+            else if (results[0].updated) {
+                printHumanReadableLine(args.actionLabel);
+            }
+            else {
+                printHumanReadableLine(`Already ${args.staleVerb ?? args.actionLabel.toLowerCase()}`);
+            }
+        }
+        else if (args.actionLabel) {
+            printHumanReadableLine(`${args.actionLabel} ${updatedCount}/${results.length} notes`);
+        }
+        else {
+            printHumanReadableLine(`Updated ${updatedCount}/${results.length} notes`);
+        }
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; local cache may be stale');
+        }
+    });
+}
+export async function runNoteSearch({ command, options, args }) {
+    const searchOptions = options;
+    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
+        await syncBeforeNoteCommand(db, offline, timeoutMs);
+        const keyword = args.query?.trim() ?? '';
+        const tagsExpression = typeof searchOptions.tags === 'string' ? searchOptions.tags.trim() : '';
+        const { createdAtFrom, createdAtTo } = parseCreatedAtRange({
+            from: searchOptions.from,
+            to: searchOptions.to,
+            days: searchOptions.days,
+        });
+        const starred = typeof searchOptions.starred === 'string'
+            ? parseStarredOption(searchOptions.starred, '--starred')
+            : undefined;
+        const boxInput = typeof searchOptions.boxes === 'string' ? searchOptions.boxes : '';
+        const parsedBoxInput = boxInput
+            ? await parseSearchListInput(boxInput, '--boxes')
+            : { values: [], isExplicitEmptyArray: false };
+        const zettelBoxIds = await resolveZettelBoxIdsForSearch(db, parsedBoxInput.values);
+        const sqlExpression = typeof searchOptions.sql === 'string' ? searchOptions.sql.trim() : '';
+        const limit = parseSearchLimit(searchOptions.limit);
+        const offset = parseSearchOffset(searchOptions.offset);
+        const fields = parseNoteSearchFields(searchOptions.fields, '--fields');
+        const rows = await searchNotes(db, keyword, {
+            includeDeleted: Boolean(searchOptions.includeDeleted),
+            tagsExpression: tagsExpression || undefined,
+            createdAtFrom,
+            createdAtTo,
+            starred,
+            zettelBoxIds,
+            matchEmptyZettelBoxes: parsedBoxInput.isExplicitEmptyArray,
+            sqlExpression: sqlExpression || undefined,
+        });
+        printSuccess(buildNoteSearchResponse({
+            query: keyword,
+            notes: projectNoteSearchFields(rows.slice(offset, offset + limit), fields),
+            totalCount: rows.length,
+            stale: offline ? true : stale,
+            includeDeleted: Boolean(searchOptions.includeDeleted),
+            limit,
+            offset,
+            fields,
+            tagsExpression: tagsExpression || undefined,
+            createdAtFrom,
+            createdAtTo,
+            days: normalizeDaysForMeta(searchOptions.days),
+            starred,
+            boxNames: parsedBoxInput.values,
+            boxIds: zettelBoxIds,
+            matchEmptyBoxes: parsedBoxInput.isExplicitEmptyArray,
+            sqlExpression: sqlExpression || undefined,
+        }));
+    });
+}
+export async function runNoteGet({ command, options, args }) {
+    const getOptions = options;
+    const id = args.id;
+    if (!id) {
+        throw new DinoxError('Note id is required');
+    }
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
+        await syncBeforeNoteCommand(db, offline, timeoutMs);
+        if (getOptions.contextOnly) {
+            const context = await getNoteContext(db, id);
+            if (!context) {
+                throw new DinoxError(`Note not found: ${id}`, {
+                    code: 'NOTE_NOT_FOUND',
+                    suggestion: "Run 'dino note search <keyword>' to locate the note id.",
+                    recoverable: true,
+                });
+            }
+            printSuccess({ stale: offline ? true : stale, note: toPublicNoteContext(context) });
+            return;
+        }
+        const note = await getNote(db, id);
+        if (!note) {
+            throw new DinoxError(`Note not found: ${id}`, {
+                code: 'NOTE_NOT_FOUND',
+                suggestion: "Run 'dino note search <keyword>' to locate the note id.",
+                recoverable: true,
+            });
+        }
+        if (structuredOutput) {
+            printSuccess({ stale, note: toPublicNote(note) });
+            return;
+        }
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; result may be stale');
+        }
+        printHumanReadableLine(`${note.id}`);
+        printHumanReadableLine(`title: ${note.title ?? ''}`);
+        if (note.updated_at) {
+            printHumanReadableLine(`updated_at: ${note.updated_at}`);
+        }
+        if (note.is_starred) {
+            printHumanReadableLine('is_starred: 1');
+        }
+        if (note.is_del) {
+            printHumanReadableLine('is_del: 1');
+        }
+    });
+}
+export async function runNotePreview({ command, options, args }) {
+    const previewOptions = options;
+    const id = args.id;
+    if (!id) {
+        throw new DinoxError('Note id is required');
+    }
+    await withNoteDatabase(command, async ({ db, offline, timeoutMs, stale }) => {
+        await syncBeforeNoteCommand(db, offline, timeoutMs);
+        const preview = await getNotePreview(db, id, parsePreviewLineCount(previewOptions.lines));
+        if (!preview) {
+            throw new DinoxError(`Note not found: ${id}`, {
+                code: 'NOTE_NOT_FOUND',
+                suggestion: "Run 'dino note search <keyword>' to locate the note id.",
+                recoverable: true,
+            });
+        }
+        printSuccess({ stale: offline ? true : stale, note: preview });
+    });
+}
+export async function runNoteDetail({ command, options, args }) {
+    const detailOptions = options;
+    await withNoteDatabase(command, async ({ db, offline, timeoutMs }) => {
+        await syncBeforeNoteCommand(db, offline, timeoutMs);
+        const ids = await parseTargetNoteIds(args.id, detailOptions.ids, 'detail');
+        const notes = await getNoteDetails(db, ids);
+        const foundIds = new Set(notes.map((note) => note.id));
+        const missing = ids.filter((noteId) => !foundIds.has(noteId));
+        if (missing.length > 0) {
+            throw new DinoxError(ids.length === 1 ? `Note not found: ${missing[0]}` : `Notes not found: ${missing.join(', ')}`);
+        }
+        const publicNotes = notes.map((note) => toPublicNoteDetail(note));
+        printSuccess(publicNotes.length === 1 ? publicNotes[0] : publicNotes);
+    });
+}
+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);
+        const contentMd = await parseStringInput(String(createOptions.content));
+        const canonicalContentMd = await canonicalizeBidlinksInMarkdown(db, contentMd, identity.userId);
+        const { contentJson, contentText } = convertMarkdownToNoteContent(canonicalContentMd);
+        const tagsInput = typeof createOptions.tags === 'string'
+            ? await parseStringListInput(createOptions.tags, '--tags')
+            : [];
+        const boxNames = typeof createOptions.boxes === 'string'
+            ? await parseStringListInput(createOptions.boxes, '--boxes')
+            : [];
+        const noteType = parseNoteType(createOptions.type);
+        if (Boolean(createOptions.dryRun)) {
+            printDryRunPreview(await buildNoteCreateDryRunPreview({
+                db,
+                config,
+                offline,
+                userId: identity.userId,
+                title: String(createOptions.title),
+                noteType,
+                contentMd,
+                tagsInput,
+                zettelBoxNames: boxNames,
+            }));
+            return;
+        }
+        const id = generateId();
+        await createNote(db, {
+            id,
+            title: String(createOptions.title),
+            noteType,
+            contentMd: canonicalContentMd,
+            contentJson,
+            contentText,
+            tags: await validateTagsForCreate(db, tagsInput),
+            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 };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine(id);
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; local cache may be stale');
+        }
+    });
+}
+export async function runNoteDelete({ command, options, args }) {
+    const deleteOptions = options;
+    const id = args.id;
+    if (!id) {
+        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);
+        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 };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine('OK');
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; local cache may be stale');
+        }
+    });
+}
+export async function runNoteUpdate({ command, options, args }) {
+    const updateOptions = options;
+    await executeNoteUpdateOperation({
+        boxOption: updateOptions.boxes,
+        command,
+        dryRun: Boolean(updateOptions.dryRun),
+        id: args.id,
+        idsOption: updateOptions.ids,
+        starred: typeof updateOptions.starred === 'string'
+            ? parseStarredOption(updateOptions.starred, '--starred')
+            : undefined,
+        tagsOption: updateOptions.tags,
+        commandName: 'dino note update',
+        actionName: 'update_note',
+    });
+}
+export async function runNoteStar({ command, options, args }) {
+    const starOptions = options;
+    await executeNoteUpdateOperation({
+        actionLabel: 'Starred',
+        command,
+        dryRun: Boolean(starOptions.dryRun),
+        id: args.id,
+        idsOption: starOptions.ids,
+        starred: true,
+        staleVerb: 'starred',
+        commandName: 'dino note star',
+        actionName: 'star_note',
+    });
+}
+export async function runNoteUnstar({ command, options, args }) {
+    const unstarOptions = options;
+    await executeNoteUpdateOperation({
+        actionLabel: 'Unstarred',
+        command,
+        dryRun: Boolean(unstarOptions.dryRun),
+        id: args.id,
+        idsOption: unstarOptions.ids,
+        starred: false,
+        staleVerb: 'unstarred',
+        commandName: 'dino note unstar',
+        actionName: 'unstar_note',
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { CommandGroupDescriptor } from '../descriptor/types.js';
+export declare const noteCommandGroup: CommandGroupDescriptor;
+export declare function registerNoteCommands(program: Command): void;

package/dist/commands/notes/descriptors.js

@@ -0,0 +1,250 @@
+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];
+export const noteCommandGroup = {
+    name: 'note',
+    description: 'Manage notes',
+    commands: [
+        {
+            name: 'search',
+            description: 'Search notes by keyword, tags, date range, boxes, or SQL-like filter',
+            arguments: [{ syntax: '[query]', description: 'Search keyword; may be omitted for filter-only search' }],
+            options: [
+                { flags: '--tags <expr>', description: 'Tag expression with AND/OR/NOT, or [] for empty tags', type: 'string' },
+                { flags: '--from <date>', description: 'created_at start (YYYY-MM-DD or ISO datetime)', type: 'string' },
+                { 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: '--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 },
+                { flags: '--fields <list>', description: 'Comma-separated fields: id,title,summary,tags,created_at,boxes,is_starred', type: 'string[]' },
+                { flags: '--include-deleted', description: 'Include soft-deleted notes', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.search',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'AI-friendly note search payload',
+                    entity: 'note_search_result',
+                    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',
+                ],
+            },
+            action: runNoteSearch,
+        },
+        {
+            name: 'get',
+            description: 'Get one note by id, optionally in lightweight context mode',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [{ flags: '--context-only', description: 'Return lightweight note context (title/tags/summary/links)', type: 'boolean' }],
+            schema: {
+                path: 'note.get',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Single note or note context payload',
+                    entity: 'note_context',
+                    fields: ['id', 'title', 'summary', 'tags', 'created_at', 'updated_at', 'is_del', 'boxes', 'links'],
+                },
+                examples: ['dino note get <id> --context-only --format json', 'dino note get <id> --format json'],
+            },
+            action: runNoteGet,
+        },
+        {
+            name: 'preview',
+            description: 'Preview the first N lines of note markdown',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [{ flags: '--lines <n>', description: 'Number of lines to return', type: 'number', defaultValue: 10 }],
+            schema: {
+                path: 'note.preview',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Markdown preview payload',
+                    fields: ['note.id', 'note.title', 'note.preview', 'note.lines', 'note.truncated', 'stale'],
+                },
+                examples: ['dino note preview <id> --lines 30 --format json'],
+            },
+            action: runNotePreview,
+        },
+        {
+            name: 'detail',
+            description: 'Get full note details for one or more ids',
+            arguments: [{ syntax: '[id]', description: 'Optional note id when reading a single note' }],
+            options: [{ flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' }],
+            schema: {
+                path: 'note.detail',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    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: 'create',
+            description: 'Create a new note from markdown content',
+            options: [
+                { flags: '--title <string>', description: 'Note title', required: true, type: 'string' },
+                { 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: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.create',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    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' }],
+            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: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.update',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Mutation result with per-note update 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'],
+            },
+            action: runNoteUpdate,
+        },
+        {
+            name: 'delete',
+            description: 'Soft-delete a note by setting is_del=1',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [{ flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' }],
+            schema: {
+                path: 'note.delete',
+                risk: 'high-risk-write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Deletion acknowledgement',
+                    fields: ['id', 'stale'],
+                },
+                examples: ['dino note delete <id> --format json'],
+            },
+            action: runNoteDelete,
+        },
+        {
+            name: 'star',
+            description: 'Mark one or more notes as starred',
+            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note update' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.star',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Mutation result with per-note starred status',
+                    fields: ['total', 'updatedCount', 'results', 'stale'],
+                },
+                examples: ['dino note star <id> --format json --dry-run'],
+            },
+            action: runNoteStar,
+        },
+        {
+            name: 'unstar',
+            description: 'Mark one or more notes as not starred',
+            arguments: [{ syntax: '[id]', description: 'Optional note id for single-note update' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.unstar',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: NOTE_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Mutation result with per-note starred status',
+                    fields: ['total', 'updatedCount', 'results', 'stale'],
+                },
+                examples: ['dino note unstar <id> --format json --dry-run'],
+            },
+            action: runNoteUnstar,
+        },
+    ],
+};
+export function registerNoteCommands(program) {
+    registerCommandGroup(program, noteCommandGroup);
+}