@dinoxx/dinox-cli 1.0.17 → 1.0.19

package/dist/commands/todo/index.js

@@ -1,11 +1,15 @@
+import { resolveAuthIdentity } from '../../auth/userInfo.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { loadConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
-import { DinoxError } from '../../utils/errors.js';
+import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
 import { readStringOrFile } from '../../utils/argValue.js';
-import { printYaml } from '../../utils/output.js';
+import { printDryRunPreview } from '../../utils/dryRun.js';
+import { DinoxError } from '../../utils/errors.js';
+import { printHumanReadableLine, printSuccess } from '../../utils/output.js';
 import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
-import { resolveAuthIdentity } from '../../auth/userInfo.js';
+import { buildTodoAppendDryRunPreview, buildTodoCreateDryRunPreview, buildTodoUpdateDryRunPreview, } from './dryRun.js';
 import { appendTodoTasks, createTodoNote, normalizeTaskTexts, searchTodoTasks, updateTodoTaskStatus, } from './repo.js';
 const DATE_ONLY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -13,6 +17,7 @@ const DEFAULT_TASK_LIMIT = 50;
 const DEFAULT_NOTE_SCAN_LIMIT = 200;
 const MAX_TASK_LIMIT = 500;
 const MAX_NOTE_SCAN_LIMIT = 5000;
+const TODO_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 function parseTaskStatus(value) {
     const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
     if (normalized === 'all' || normalized === 'completed' || normalized === 'uncompleted') {
@@ -170,8 +175,8 @@ async function parseTaskListInput(value) {
     const raw = await readStringOrFile(value);
     return parseListInput(raw, '--tasks');
 }
-function collectStringOptionValue(value, previous = []) {
-    return [...previous, value];
+function collectStringOptionValue(value, previous) {
+    return [...(Array.isArray(previous) ? previous : []), value];
 }
 async function parseTaskInput(args) {
     const merged = [];
@@ -193,148 +198,293 @@ async function syncBeforeTodoCommand(db, offline, timeoutMs) {
     }
     await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
 }
-export function registerTodoCommands(program) {
-    const todo = program.command('todo').description('Manage todo tasks');
-    todo
-        .command('search')
-        .description('Search tasks from note image_detail')
-        .argument('[query]', 'task text query')
-        .option('--status <status>', 'task status: all | completed | uncompleted', 'all')
-        .option('--tags <string|@file>', 'task tags (JSON array or comma/newline-separated)')
-        .option('--from <date>', 'task date range start (YYYY-MM-DD or ISO datetime)')
-        .option('--to <date>', 'task date range end (YYYY-MM-DD or ISO datetime)')
-        .option('--days <n>', 'recent N days for task date range (cannot be used with --from/--to)')
-        .option('--limit <n>', `maximum returned tasks (default: ${DEFAULT_TASK_LIMIT}, max: ${MAX_TASK_LIMIT})`)
-        .option('--scan-limit <n>', `maximum note rows scanned from c_note (default: ${DEFAULT_NOTE_SCAN_LIMIT}, max: ${MAX_NOTE_SCAN_LIMIT})`)
-        .option('--include-deleted', 'include soft-deleted notes')
-        .action(async (query, options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        const config = resolveConfig(await loadConfig());
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
-        const { db } = await connectPowerSync({ config, offline, timeoutMs });
-        try {
-            await syncBeforeTodoCommand(db, offline, timeoutMs);
-            const keyword = query?.trim() ?? '';
-            const taskStatus = parseTaskStatus(options.status);
-            const taskTagFilter = typeof options.tags === 'string'
-                ? await parseTagFilterInput(options.tags)
-                : [];
-            const taskDateRange = parseTaskDateRange({
-                from: options.from,
-                to: options.to,
-                days: options.days,
-            });
-            const limit = parsePositiveIntegerOption(options.limit, '--limit', DEFAULT_TASK_LIMIT, MAX_TASK_LIMIT);
-            const scanLimit = parsePositiveIntegerOption(options.scanLimit, '--scan-limit', DEFAULT_NOTE_SCAN_LIMIT, MAX_NOTE_SCAN_LIMIT);
-            const result = await searchTodoTasks(db, keyword, {
-                includeDeleted: Boolean(options.includeDeleted),
-                taskStatus,
-                taskTagFilter,
-                taskDateRange,
-                limit,
-                scanLimit,
-            });
-            printYaml(result);
-        }
-        finally {
-            await db.close().catch(() => undefined);
-        }
+async function withTodoDatabase(globals, run) {
+    const rawConfig = await loadConfig();
+    const config = resolveConfig(rawConfig);
+    const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
+    const offline = Boolean(globals.offline);
+    const { db } = await connectPowerSync({ config, offline, timeoutMs });
+    try {
+        await run({
+            db,
+            rawConfig,
+            config,
+            offline,
+            timeoutMs,
+        });
+    }
+    finally {
+        await db.close().catch(() => undefined);
+    }
+}
+async function runTodoSearch({ args, globals, options }) {
+    const searchOptions = options;
+    await withTodoDatabase(globals, async ({ db, offline, timeoutMs }) => {
+        await syncBeforeTodoCommand(db, offline, timeoutMs);
+        const keyword = args.query?.trim() ?? '';
+        const taskStatus = parseTaskStatus(searchOptions.status);
+        const taskTagFilter = typeof searchOptions.tags === 'string'
+            ? await parseTagFilterInput(searchOptions.tags)
+            : [];
+        const taskDateRange = parseTaskDateRange({
+            from: searchOptions.from,
+            to: searchOptions.to,
+            days: searchOptions.days,
+        });
+        const limit = parsePositiveIntegerOption(searchOptions.limit, '--limit', DEFAULT_TASK_LIMIT, MAX_TASK_LIMIT);
+        const scanLimit = parsePositiveIntegerOption(searchOptions.scanLimit, '--scan-limit', DEFAULT_NOTE_SCAN_LIMIT, MAX_NOTE_SCAN_LIMIT);
+        const result = await searchTodoTasks(db, keyword, {
+            includeDeleted: Boolean(searchOptions.includeDeleted),
+            taskStatus,
+            taskTagFilter,
+            taskDateRange,
+            limit,
+            scanLimit,
+        });
+        printSuccess(result);
     });
-    todo
-        .command('append')
-        .description('Append one or more todo items to a note')
-        .argument('[task]', 'single task text')
-        .option('--task <text>', 'task text (repeatable)', collectStringOptionValue, [])
-        .option('--tasks <string|@file>', 'task list (JSON array or comma/newline-separated)')
-        .option('--note-id <id>', 'target note id; defaults to latest note with non-empty image_detail')
-        .action(async (taskArg, options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        const config = resolveConfig(await loadConfig());
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
-        const { db } = await connectPowerSync({ config, offline, timeoutMs });
-        try {
-            await syncBeforeTodoCommand(db, offline, timeoutMs);
-            const taskTexts = await parseTaskInput({
-                positionalTask: taskArg,
-                tasksOption: typeof options.tasks === 'string' ? options.tasks : undefined,
-                taskOptionList: Array.isArray(options.task) ? options.task : [],
-            });
-            const result = await appendTodoTasks(db, {
-                noteId: typeof options.noteId === 'string' ? options.noteId : undefined,
+}
+async function runTodoAppend({ args, globals, options }) {
+    const appendOptions = options;
+    await withTodoDatabase(globals, async ({ db, config, offline, timeoutMs }) => {
+        await syncBeforeTodoCommand(db, offline, timeoutMs);
+        const taskTexts = await parseTaskInput({
+            positionalTask: args.task,
+            tasksOption: typeof appendOptions.tasks === 'string' ? appendOptions.tasks : undefined,
+            taskOptionList: Array.isArray(appendOptions.task) ? appendOptions.task : [],
+        });
+        if (Boolean(appendOptions.dryRun)) {
+            const preview = await buildTodoAppendDryRunPreview({
+                db,
+                config,
+                offline,
+                noteId: typeof appendOptions.noteId === 'string' ? appendOptions.noteId : undefined,
                 taskTexts,
             });
-            printYaml({ ok: true, ...result });
-        }
-        finally {
-            await db.close().catch(() => undefined);
+            printDryRunPreview(preview);
+            return;
         }
+        const result = await appendTodoTasks(db, {
+            noteId: typeof appendOptions.noteId === 'string' ? appendOptions.noteId : undefined,
+            taskTexts,
+        });
+        printSuccess({ ok: true, ...result });
     });
-    todo
-        .command('create')
-        .description('Create a new note containing one or more todo items')
-        .argument('[task]', 'single task text')
-        .option('--task <text>', 'task text (repeatable)', collectStringOptionValue, [])
-        .option('--tasks <string|@file>', 'task list (JSON array or comma/newline-separated)')
-        .option('--title <string>', 'optional note title; defaults to an auto-generated summary')
-        .action(async (taskArg, options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        const rawConfig = await loadConfig();
-        const config = resolveConfig(rawConfig);
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
-        const identity = await resolveAuthIdentity(rawConfig, config);
-        const { db } = await connectPowerSync({ config, offline, timeoutMs });
-        try {
-            await syncBeforeTodoCommand(db, offline, timeoutMs);
-            const taskTexts = await parseTaskInput({
-                positionalTask: taskArg,
-                tasksOption: typeof options.tasks === 'string' ? options.tasks : undefined,
-                taskOptionList: Array.isArray(options.task) ? options.task : [],
-            });
-            const result = await createTodoNote(db, {
+}
+async function runTodoCreate({ args, globals, options }) {
+    const createOptions = options;
+    await withTodoDatabase(globals, async ({ db, rawConfig, config, offline, timeoutMs }) => {
+        await syncBeforeTodoCommand(db, offline, timeoutMs);
+        const taskTexts = await parseTaskInput({
+            positionalTask: args.task,
+            tasksOption: typeof createOptions.tasks === 'string' ? createOptions.tasks : undefined,
+            taskOptionList: Array.isArray(createOptions.task) ? createOptions.task : [],
+        });
+        if (Boolean(createOptions.dryRun)) {
+            const preview = await buildTodoCreateDryRunPreview({
+                config,
+                offline,
+                title: typeof createOptions.title === 'string' ? createOptions.title : undefined,
                 taskTexts,
-                title: typeof options.title === 'string' ? options.title : undefined,
-                userId: identity.userId,
             });
-            if (!offline && !config.powersync.uploadBaseUrl) {
-                console.log('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
-            }
-            if (!offline) {
-                await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
-            }
-            printYaml({ ok: true, ...result });
+            printDryRunPreview(preview);
+            return;
         }
-        finally {
-            await db.close().catch(() => undefined);
+        const identity = await resolveAuthIdentity(rawConfig, config);
+        const result = await createTodoNote(db, {
+            taskTexts,
+            title: typeof createOptions.title === 'string' ? createOptions.title : undefined,
+            userId: identity.userId,
+        });
+        if (!offline && !config.powersync.uploadBaseUrl) {
+            printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
         }
+        if (!offline) {
+            await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
+        }
+        printSuccess({ ok: true, ...result });
     });
-    todo
-        .command('update')
-        .description('Update checked status for a todo task by taskId')
-        .argument('<taskId>', 'task id')
-        .requiredOption('--status <status>', 'target status: completed|uncompleted|done|undone|true|false|1|0')
-        .action(async (taskId, options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        const config = resolveConfig(await loadConfig());
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
-        const { db } = await connectPowerSync({ config, offline, timeoutMs });
-        try {
-            await syncBeforeTodoCommand(db, offline, timeoutMs);
-            const checked = parseTaskCheckedStatus(options.status);
-            const result = await updateTodoTaskStatus(db, {
+}
+async function runTodoUpdate({ args, globals, options }) {
+    const updateOptions = options;
+    await withTodoDatabase(globals, async ({ db, config, offline, timeoutMs }) => {
+        await syncBeforeTodoCommand(db, offline, timeoutMs);
+        const taskId = args.taskId;
+        if (!taskId) {
+            throw new DinoxError('taskId is required');
+        }
+        const checked = parseTaskCheckedStatus(updateOptions.status);
+        if (Boolean(updateOptions.dryRun)) {
+            const preview = await buildTodoUpdateDryRunPreview({
+                db,
+                config,
+                offline,
                 taskId,
                 checked,
             });
-            printYaml({ ok: true, ...result });
+            printDryRunPreview(preview);
+            return;
         }
-        finally {
-            await db.close().catch(() => undefined);
-        }
-    });
-    todo.action((_options, command) => {
-        command.outputHelp();
+        const result = await updateTodoTaskStatus(db, {
+            taskId,
+            checked,
+        });
+        printSuccess({ ok: true, ...result });
     });
 }
+const todoSearchCommand = {
+    name: 'search',
+    description: 'Search todo tasks extracted from note content',
+    arguments: [
+        {
+            syntax: '[query]',
+            description: 'Task text query; may be omitted for filter-only search',
+        },
+    ],
+    options: [
+        { flags: '--status <status>', description: 'Task status: all | completed | uncompleted', defaultValue: 'all' },
+        { flags: '--tags <string|@file>', description: 'Task tags (JSON array or comma/newline-separated)' },
+        { flags: '--from <date>', description: 'Task date range start (YYYY-MM-DD or ISO datetime)' },
+        { flags: '--to <date>', description: 'Task date range end (YYYY-MM-DD or ISO datetime)' },
+        { flags: '--days <n>', description: 'Recent N days; mutually exclusive with --from/--to' },
+        { flags: '--limit <n>', description: 'Maximum returned tasks' },
+        { flags: '--scan-limit <n>', description: 'Maximum scanned note rows' },
+        { flags: '--include-deleted', description: 'Include soft-deleted notes' },
+    ],
+    schema: {
+        path: 'todo.search',
+        risk: 'read',
+        auth: 'required',
+        globalOptions: TODO_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Todo search payload with metadata and task list',
+            fields: ['tasks.task_id', 'tasks.task_key', 'tasks.note_id', 'tasks.note_title', 'tasks.status', 'tasks.depth', 'tasks.parent_id', 'tasks.tags'],
+            metaFields: ['meta.query', 'meta.returned_count', 'meta.limit', 'meta.task_status', 'meta.task_tag_filter', 'meta.task_date_range', 'meta.scanned_note_count'],
+        },
+        mcp: {
+            toolName: 'dinox_search_todos',
+            description: 'Search todo tasks',
+            properties: [
+                { name: 'query', type: 'string', description: 'Task text query' },
+                { name: 'status', type: 'string', description: 'Task status', enum: ['all', 'completed', 'uncompleted'] },
+                { name: 'tags', type: 'string[]', description: 'Task tags' },
+                { name: 'limit', type: 'number', description: 'Max results (default: 50)' },
+            ],
+        },
+        examples: ['dino todo search "报销" --status uncompleted --format json', 'dino todo search --days 7 --format json'],
+    },
+    action: runTodoSearch,
+};
+const todoAppendCommand = {
+    name: 'append',
+    description: 'Append one or more tasks to an existing note',
+    arguments: [
+        {
+            syntax: '[task]',
+            description: 'Single task text',
+        },
+    ],
+    options: [
+        {
+            flags: '--task <text>',
+            description: 'Repeatable task text',
+            parser: collectStringOptionValue,
+            defaultValue: [],
+        },
+        { flags: '--tasks <string|@file>', description: 'Task list (JSON array or comma/newline-separated)' },
+        { flags: '--note-id <id>', description: 'Target note id; omitted means latest eligible note' },
+        { flags: '--dry-run', description: 'Preview the write without executing it' },
+    ],
+    schema: {
+        path: 'todo.append',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: TODO_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Append result with target note and appended task ids',
+            fields: ['noteId', 'appendedCount', 'taskIds'],
+        },
+        examples: ['dino todo append --note-id <id> --task "补交报销单" --format json'],
+    },
+    action: runTodoAppend,
+};
+const todoCreateCommand = {
+    name: 'create',
+    description: 'Create a new note containing one or more todo items',
+    arguments: [
+        {
+            syntax: '[task]',
+            description: 'Single task text',
+        },
+    ],
+    options: [
+        {
+            flags: '--task <text>',
+            description: 'Repeatable task text',
+            parser: collectStringOptionValue,
+            defaultValue: [],
+        },
+        { flags: '--tasks <string|@file>', description: 'Task list (JSON array or comma/newline-separated)' },
+        { flags: '--title <string>', description: 'Optional note title' },
+        { flags: '--dry-run', description: 'Preview the write without executing it' },
+    ],
+    schema: {
+        path: 'todo.create',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: TODO_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Creation result with new note id and task ids',
+            fields: ['noteId', 'taskIds', 'title'],
+        },
+        examples: ['dino todo create --task "补交报销单" --task "整理发票" --format json'],
+    },
+    action: runTodoCreate,
+};
+const todoUpdateCommand = {
+    name: 'update',
+    description: 'Update a todo task checked status by task id',
+    arguments: [
+        {
+            syntax: '<taskId>',
+            description: 'Task id',
+        },
+    ],
+    options: [
+        {
+            flags: '--status <status>',
+            description: 'Target status: completed|uncompleted|done|undone|true|false|1|0',
+            required: true,
+        },
+        { flags: '--dry-run', description: 'Preview the write without executing it' },
+    ],
+    schema: {
+        path: 'todo.update',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: TODO_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Mutation result with updated status and target note id',
+            fields: ['taskId', 'checked', 'updated', 'noteId'],
+        },
+        examples: ['dino todo update <taskId> --status completed --format json'],
+    },
+    action: runTodoUpdate,
+};
+export const todoCommandGroup = {
+    name: 'todo',
+    description: 'Manage todo tasks',
+    commands: [
+        todoSearchCommand,
+        todoAppendCommand,
+        todoCreateCommand,
+        todoUpdateCommand,
+    ],
+};
+export function registerTodoCommands(program) {
+    registerCommandGroup(program, todoCommandGroup);
+}

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

@@ -79,7 +79,18 @@ export type SearchedTodoResponse = {
 };
 export type { TaskDateRangeFilter, TaskStatusFilter } from './taskModel.js';
 export { normalizeTaskTexts } from './contentModel.js';
+type TodoMutableNoteRow = {
+    id: string | null;
+    title: string | null;
+    content_json: string | null;
+    content_md: string | null;
+    is_del: number | null;
+    created_at?: string | null;
+};
 export declare function searchTodoTasks(db: AbstractPowerSyncDatabase, query: string, options: SearchTodoOptions): Promise<SearchedTodoResponse>;
 export declare function appendTodoTasks(db: AbstractPowerSyncDatabase, options: AppendTodoTasksOptions): Promise<AppendTodoTasksResult>;
 export declare function createTodoNote(db: AbstractPowerSyncDatabase, options: CreateTodoNoteOptions): Promise<CreateTodoNoteResult>;
 export declare function updateTodoTaskStatus(db: AbstractPowerSyncDatabase, options: UpdateTodoTaskStatusOptions): Promise<UpdateTodoTaskStatusResult>;
+export declare function getTodoAppendTargetById(db: AbstractPowerSyncDatabase, noteId: string): Promise<TodoMutableNoteRow | null>;
+export declare function getLatestTodoAppendTarget(db: AbstractPowerSyncDatabase): Promise<TodoMutableNoteRow | null>;
+export declare function loadTodoTaskCandidatesByTaskId(db: AbstractPowerSyncDatabase, taskId: string): Promise<TodoMutableNoteRow[]>;

package/dist/commands/todo/repo.js

@@ -133,20 +133,48 @@ export async function updateTodoTaskStatus(db, options) {
         throw new DinoxError('taskId is required');
     }
     const candidates = await loadTodoTaskCandidatesByTaskId(db, taskId);
-    const matches = candidates.flatMap((candidate) => {
+    const matches = [];
+    const skippedCandidates = [];
+    for (const candidate of candidates) {
         try {
             const doc = parseTiptapDocFromDb(candidate.content_json);
             const applied = applyTaskCheckedStatus(doc, taskId, options.checked);
             if (applied.matchedIndices.length === 0) {
-                return [];
+                continue;
             }
-            return [{ candidate, applied }];
+            matches.push({ candidate, applied });
         }
-        catch {
-            return [];
+        catch (error) {
+            skippedCandidates.push({
+                noteId: candidate.id,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
         }
-    });
+    }
     if (matches.length === 0) {
+        if (skippedCandidates.length > 0) {
+            const failedNoteIds = Array.from(new Set(skippedCandidates
+                .map((entry) => (entry.noteId ?? '').trim())
+                .filter((value) => value.length > 0)));
+            const sampleFailedIds = failedNoteIds.slice(0, 3);
+            const suffix = sampleFailedIds.length > 0
+                ? ` Failed note ids: ${sampleFailedIds.join(', ')}${failedNoteIds.length > sampleFailedIds.length ? ', ...' : ''}.`
+                : '';
+            throw new DinoxError(`Task not found: ${taskId}. Skipped ${skippedCandidates.length} candidate note(s) with invalid content_json.${suffix}`, {
+                code: 'TODO_TASK_NOT_FOUND',
+                suggestion: sampleFailedIds.length > 0
+                    ? `Try 'dino note detail ${sampleFailedIds[0]}' to inspect/repair note content.`
+                    : undefined,
+                details: {
+                    taskId,
+                    candidatesCount: candidates.length,
+                    skippedCandidatesCount: skippedCandidates.length,
+                    failedNoteIds,
+                    skippedCandidates: skippedCandidates.slice(0, 5),
+                },
+                recoverable: true,
+            });
+        }
         throw new DinoxError(`Task not found: ${taskId}`);
     }
     if (matches.length > 1) {
@@ -222,7 +250,7 @@ async function loadTodoNoteRows(db, includeDeleted, scanLimit) {
     LIMIT ?
     `, [scanLimit]);
 }
-async function getTodoAppendTargetById(db, noteId) {
+export async function getTodoAppendTargetById(db, noteId) {
     return db.getOptional(`
     SELECT
       n.id,
@@ -234,7 +262,7 @@ async function getTodoAppendTargetById(db, noteId) {
     WHERE n.id = ?
     `, [noteId]);
 }
-async function getLatestTodoAppendTarget(db) {
+export async function getLatestTodoAppendTarget(db) {
     return db.getOptional(`
     SELECT
       n.id,
@@ -251,7 +279,7 @@ async function getLatestTodoAppendTarget(db) {
     LIMIT 1
     `, []);
 }
-async function loadTodoTaskCandidatesByTaskId(db, taskId) {
+export async function loadTodoTaskCandidatesByTaskId(db, taskId) {
     const escapedTaskId = escapeLikePattern(taskId);
     return db.getAll(`
     SELECT

package/dist/commands/update.d.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import type { CommandDescriptor } from './descriptor/types.js';
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
 type LogFn = (...parts: unknown[]) => void;
 type UpdateCommandDeps = {
@@ -7,5 +8,7 @@ type UpdateCommandDeps = {
     getVersion: () => string;
     log: LogFn;
 };
+export declare function createUpdateCommandDescriptor(overrides?: Partial<UpdateCommandDeps>): CommandDescriptor;
+export declare const updateCommandDescriptor: CommandDescriptor;
 export declare function registerUpdateCommand(program: Command, overrides?: Partial<UpdateCommandDeps>): void;
 export {};

package/dist/commands/update.js

@@ -1,7 +1,12 @@
 import { spawn } from 'node:child_process';
+import { registerStandaloneCommand } from './descriptor/register.js';
 import { SKILLS_REPO_URL } from '../constants/links.js';
+import { printHumanReadableLine } from '../utils/output.js';
 import { getPackageVersion } from '../utils/version.js';
 const PACKAGE_NAME = '@dinoxx/dinox-cli';
+function logHumanReadable(...parts) {
+    printHumanReadableLine(parts.map((part) => String(part)).join(' '));
+}
 function detectPackageManager() {
     const scriptPath = process.argv[1] ?? '';
     if (scriptPath.includes('/.bun/'))
@@ -38,7 +43,7 @@ function resolveDeps(overrides) {
         detectPackageManager,
         runUpdate,
         getVersion: getPackageVersion,
-        log: console.log,
+        log: logHumanReadable,
         ...overrides,
     };
 }
@@ -46,17 +51,34 @@ function printSkillsReminder(log) {
     log(`skills repo: ${SKILLS_REPO_URL}`);
     log('ai reminder: review and update local Dinox skills after CLI updates (especially dino-dinox and dino-update-cli).');
 }
-export function registerUpdateCommand(program, overrides = {}) {
+export function createUpdateCommandDescriptor(overrides = {}) {
     const deps = resolveDeps(overrides);
-    program
-        .command('update')
-        .description(`Update ${PACKAGE_NAME} to the latest version`)
-        .action(async () => {
-        const pm = deps.detectPackageManager();
-        deps.log(`current version: ${deps.getVersion()}`);
-        deps.log(`updating ${PACKAGE_NAME} via ${pm}...`);
-        await deps.runUpdate(pm);
-        deps.log('done');
-        printSkillsReminder(deps.log);
-    });
+    return {
+        name: 'update',
+        description: `Update ${PACKAGE_NAME} to the latest version`,
+        schema: {
+            path: 'update',
+            risk: 'write',
+            auth: 'none',
+            globalOptions: [],
+            output: {
+                type: 'structured',
+                summary: 'Human-readable updater progress and bundled skills reminder',
+                fields: ['current version log', 'package manager log', 'skills repo reminder'],
+            },
+            examples: ['dino update'],
+        },
+        action: async () => {
+            const pm = deps.detectPackageManager();
+            deps.log(`current version: ${deps.getVersion()}`);
+            deps.log(`updating ${PACKAGE_NAME} via ${pm}...`);
+            await deps.runUpdate(pm);
+            deps.log('done');
+            printSkillsReminder(deps.log);
+        },
+    };
+}
+export const updateCommandDescriptor = createUpdateCommandDescriptor();
+export function registerUpdateCommand(program, overrides = {}) {
+    registerStandaloneCommand(program, createUpdateCommandDescriptor(overrides));
 }