@dinoxx/dinox-cli 2.14.0 → 2.15.0

package/dist/ai/ragxClient.d.ts

@@ -0,0 +1,15 @@
+export type RagxRequest = {
+    baseUrl: string;
+    authorization: string | undefined;
+    path: '/api/ragx/search' | '/api/ragx/similar' | '/api/ragx/context';
+    body: unknown;
+    timeoutMs: number;
+    fetch?: typeof fetch;
+};
+/**
+ * Calls a dinox-tool RAG endpoint and returns its `data`. Business codes map
+ * onto CLI codes: 000001 is a rejected token or request, 000006 a missing
+ * target, anything else (and every transport failure) is the service being
+ * unavailable.
+ */
+export declare function postRagx<T>(request: RagxRequest): Promise<T>;

package/dist/ai/ragxClient.js

@@ -0,0 +1,71 @@
+import { toAuthorizationHeaderValue } from '../utils/authToken.js';
+import { DinoxError } from '../utils/errors.js';
+const RAGX_OK = '000000';
+const RAGX_INVALID = '000001';
+const RAGX_NOT_FOUND = '000006';
+function unavailable(message, cause) {
+    return new DinoxError(message, {
+        code: 'SEMANTIC_SEARCH_UNAVAILABLE',
+        cause,
+        recoverable: true,
+        suggestion: 'Retry shortly, or fall back to keyword search with `dino note search <query> --format json`.',
+    });
+}
+/**
+ * Calls a dinox-tool RAG endpoint and returns its `data`. Business codes map
+ * onto CLI codes: 000001 is a rejected token or request, 000006 a missing
+ * target, anything else (and every transport failure) is the service being
+ * unavailable.
+ */
+export async function postRagx(request) {
+    if (!request.authorization) {
+        throw new DinoxError('Semantic search needs a logged-in account.', { code: 'AUTH_REQUIRED', recoverable: true });
+    }
+    let response;
+    try {
+        response = await (request.fetch ?? fetch)(`${request.baseUrl}${request.path}`, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                Authorization: toAuthorizationHeaderValue(request.authorization),
+            },
+            body: JSON.stringify(request.body),
+            signal: AbortSignal.timeout(request.timeoutMs),
+        });
+    }
+    catch (error) {
+        const timedOut = error instanceof Error && error.name === 'TimeoutError';
+        throw unavailable(timedOut
+            ? `Semantic search did not answer within ${request.timeoutMs} ms`
+            : `Semantic search service unreachable: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(await response.text());
+    }
+    catch {
+        payload = null;
+    }
+    const code = typeof payload?.code === 'string' ? payload.code : null;
+    const message = typeof payload?.msg === 'string' ? payload.msg.trim() : '';
+    if (code === RAGX_OK && response.ok)
+        return (payload?.data ?? null);
+    if (response.status === 401 || response.status === 403 || (code === RAGX_INVALID && /authorization|userNo|token/i.test(message))) {
+        throw new DinoxError('The semantic search service rejected the login token.', {
+            code: 'AUTH_INVALID',
+            recoverable: true,
+            suggestion: 'Run `dino auth status --format json`; if the token expired, log in again with `dino auth login`.',
+        });
+    }
+    if (code === RAGX_INVALID) {
+        throw new DinoxError(`Semantic search rejected the request: ${message || 'invalid request'}`, {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+        });
+    }
+    if (code === RAGX_NOT_FOUND) {
+        throw new DinoxError(message || 'The semantic search target was not found.', { code: 'NOT_FOUND', recoverable: true });
+    }
+    throw unavailable(`Semantic search failed (HTTP ${response.status}${code ? `, code ${code}` : ''})${message ? `: ${message}` : ''}`);
+}

package/dist/cli.js

@@ -1,5 +1,8 @@
 import { Command } from 'commander';
 import { registerAuthCommands } from './commands/auth/index.js';
+import { parseCommanderUsageError } from './utils/usageError.js';
+import { registerBatchCommand } from './commands/batch.js';
+import { registerMcpCommand } from './commands/mcp.js';
 import { registerBoxesCommand } from './commands/boxes/index.js';
 import { registerConfigCommands } from './commands/config/index.js';
 import { registerDaemonCommands } from './daemon/index.js';
@@ -22,8 +25,17 @@ import { registerTemplateCommands } from './commands/templates/index.js';
 import { registerTodoCommands } from './commands/todo/index.js';
 import { getPackageVersion } from './utils/version.js';
 import { validateRequestId } from './requests/store.js';
+import { parseFieldSelection } from './utils/select.js';
+import { setProgressReporting } from './utils/progress.js';
 import { buildStructuredErrorPayload, DinoxError } from './utils/errors.js';
-import { writeToStdout, writeToStderr, clearRequestedStructuredOutputFormat, parseStructuredOutputFormatFromArgv, printError, resolveStructuredOutputFormat, setRequestedStructuredOutputFormat, } from './utils/output.js';
+import { writeToStdout, writeToStderr, clearRequestedStructuredOutputFormat, parseStructuredOutputFormatFromArgv, printError, resolveStructuredOutputFormat, setRequestedFieldSelection, setRequestedStructuredOutputFormat, } from './utils/output.js';
+/** `note.export` for `dino note export`. */
+function commandPath(command) {
+    const names = [];
+    for (let current = command; current?.parent; current = current.parent)
+        names.unshift(current.name());
+    return names.join('.');
+}
 export function createCli() {
     clearRequestedStructuredOutputFormat();
     const program = new Command();
@@ -55,10 +67,14 @@ export function createCli() {
                 return;
             }
             structuredCommanderErrorWritten = true;
-            const message = text.trim().replace(/^error:\s*/i, '');
-            const error = new DinoxError(message, {
+            const args = program.rawArgs?.slice(2) ?? [];
+            const usage = parseCommanderUsageError(text, args, program);
+            const error = new DinoxError(usage.message, {
                 code: 'USAGE_ERROR',
                 recoverable: true,
+                details: usage.details,
+                suggestion: usage.suggestion,
+                suggestedAction: usage.suggestedAction,
             });
             printError(buildStructuredErrorPayload(error, false), format);
         },
@@ -71,15 +87,22 @@ export function createCli() {
         .option('--require-sync', 'fail if the local PowerSync cache cannot be confirmed fresh before reading')
         .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
         .option('--request-id <id>', 'idempotency key: replays the stored result instead of running the command again (24h)', validateRequestId)
+        .option('--select <fields>', 'keep only these comma-separated output fields (dot paths, e.g. notes.id,notes.title)')
+        .option('--progress', 'report progress of long-running commands (sync, note export) on stderr')
         .option('--verbose', 'enable verbose logging');
     program.hook('preAction', (_thisCommand, actionCommand) => {
         const options = actionCommand.optsWithGlobals?.() ?? {};
         setRequestedStructuredOutputFormat(resolveStructuredOutputFormat(options));
+        setRequestedFieldSelection(options.select === undefined ? null : parseFieldSelection(options.select));
+        setProgressReporting(options.progress === true ? commandPath(actionCommand) : null);
     });
     program.hook('postAction', () => {
         clearRequestedStructuredOutputFormat();
+        setRequestedFieldSelection(null);
+        setProgressReporting(null);
     });
     registerAuthCommands(program);
+    registerBatchCommand(program);
     registerBoxesCommand(program);
     registerConfigCommands(program);
     registerDaemonCommands(program);
@@ -87,6 +110,7 @@ export function createCli() {
     registerDoctorCommand(program);
     registerGraphCommands(program);
     registerInfoCommand(program);
+    registerMcpCommand(program);
     registerMetaCommands(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);

package/dist/commands/batch.d.ts

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import type { CommandExecuteResult } from '../daemon/types.js';
+import { executeCommandLine } from '../requests/execute.js';
+import type { CommandDescriptor, CommandExecutionContext } from './descriptor/types.js';
+export declare const MAX_BATCH_ITEMS = 100;
+export type BatchItem = {
+    index: number;
+    id: string | null;
+    args: string[];
+};
+export type BatchItemResult = {
+    index: number;
+    id: string | null;
+    args: string[];
+    ok: boolean;
+    exit_code: number;
+    data?: unknown;
+    notice?: unknown;
+    error?: unknown;
+};
+/** Validates the batch document: argv arrays, or `{ id?, args, request_id? }` objects. */
+export declare function parseBatchItems(text: string): BatchItem[];
+/** Adds the batch's own sync options to an item that does not set them itself. */
+export declare function itemArgv(args: string[], globals: Record<string, unknown>): string[];
+export declare function toBatchItemResult(item: BatchItem, result: CommandExecuteResult): BatchItemResult;
+declare function readStdin(): Promise<string>;
+declare const batchDependencies: {
+    readStdin: typeof readStdin;
+    readFile: (file: string) => Promise<string>;
+    execute: typeof executeCommandLine;
+};
+export declare function runBatch(context: CommandExecutionContext, overrides?: Partial<typeof batchDependencies>): Promise<void>;
+export declare const batchCommandDescriptor: CommandDescriptor;
+export declare function registerBatchCommand(program: Command): void;
+export {};

package/dist/commands/batch.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs/promises';
+import { commandExecutionTarget } from '../daemon/forward.js';
+import { executeCommandLine } from '../requests/execute.js';
+import { validateRequestId } from '../requests/store.js';
+import { DinoxError } from '../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../utils/output.js';
+import { assertStdinAvailable, resolveUserPath } from '../utils/requestContext.js';
+import { registerStandaloneCommand } from './descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from './schema/globalOptions.js';
+export const MAX_BATCH_ITEMS = 100;
+/** Options each item may not set: the batch owns output format and help. */
+const RESERVED_ITEM_OPTIONS = ['--format', '--json', '--help', '-h', '--version', '-V'];
+function invalidInput(message, details) {
+    return new DinoxError(message, {
+        code: 'INVALID_ARGUMENT',
+        recoverable: true,
+        details,
+        suggestion: 'Pass a JSON array whose items are argument arrays, e.g. [["note","search","AI"],{"id":"t1","args":["todo","search"]}].',
+    });
+}
+/** Validates the batch document: argv arrays, or `{ id?, args, request_id? }` objects. */
+export function parseBatchItems(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw invalidInput(`Batch input is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0)
+        throw invalidInput('Batch input must be a non-empty JSON array');
+    if (parsed.length > MAX_BATCH_ITEMS)
+        throw invalidInput(`Batch input has ${parsed.length} items; the limit is ${MAX_BATCH_ITEMS}`);
+    return parsed.map((entry, index) => {
+        const record = Array.isArray(entry) ? { args: entry } : entry;
+        const args = record && typeof record === 'object' ? record.args : undefined;
+        if (!Array.isArray(args) || args.length === 0 || !args.every((arg) => typeof arg === 'string')) {
+            throw invalidInput(`Batch item ${index} must be a non-empty array of strings or an object with "args"`, { index });
+        }
+        const id = record.id;
+        if (id !== undefined && typeof id !== 'string')
+            throw invalidInput(`Batch item ${index} has a non-string "id"`, { index });
+        const reserved = args.find((arg) => RESERVED_ITEM_OPTIONS.includes(arg) || arg.startsWith('--format='));
+        if (reserved)
+            throw invalidInput(`Batch item ${index} may not set ${reserved}; the batch returns JSON for every item`, { index });
+        if (commandExecutionTarget(args) !== 'daemon') {
+            throw invalidInput(`Batch item ${index} (${args.join(' ')}) is not a data command; only note, todo, tag, box, view, prop, template, prompt, graph, storage and meta commands can be batched`, { index });
+        }
+        const requestId = record.request_id;
+        if (requestId !== undefined) {
+            if (typeof requestId !== 'string')
+                throw invalidInput(`Batch item ${index} has a non-string "request_id"`, { index });
+            validateRequestId(requestId);
+            if (args.includes('--request-id'))
+                throw invalidInput(`Batch item ${index} sets both "request_id" and --request-id`, { index });
+        }
+        return {
+            index,
+            id: typeof id === 'string' ? id : null,
+            args: requestId === undefined ? [...args] : [...args, '--request-id', requestId],
+        };
+    });
+}
+/** Adds the batch's own sync options to an item that does not set them itself. */
+export function itemArgv(args, globals) {
+    const argv = [...args];
+    if (globals.offline && !argv.includes('--offline'))
+        argv.push('--offline');
+    if (globals.requireSync && !argv.includes('--require-sync'))
+        argv.push('--require-sync');
+    if (typeof globals.syncTimeout === 'string' && !argv.some((arg) => arg === '--sync-timeout' || arg.startsWith('--sync-timeout='))) {
+        argv.push('--sync-timeout', globals.syncTimeout);
+    }
+    return [...argv, '--format', 'json'];
+}
+/** Reads the JSON document a command printed, skipping any plain-text lines before it. */
+function parseJsonOutput(text) {
+    const start = text.search(/^[{[]/m);
+    if (start === -1)
+        return null;
+    try {
+        const value = JSON.parse(text.slice(start));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function toBatchItemResult(item, result) {
+    const base = { index: item.index, id: item.id, args: item.args, exit_code: result.exitCode };
+    if (result.exitCode === 0) {
+        const envelope = parseJsonOutput(result.stdout);
+        return {
+            ...base,
+            ok: true,
+            data: envelope && 'data' in envelope ? envelope.data : (envelope ?? result.stdout),
+            ...(envelope?._notice ? { notice: envelope._notice } : {}),
+        };
+    }
+    const payload = parseJsonOutput(result.stderr);
+    return {
+        ...base,
+        ok: false,
+        error: payload?.error ?? payload ?? { code: 'COMMAND_FAILED', message: result.stderr.trim() || `exit code ${result.exitCode}` },
+    };
+}
+function errorResult(item, error) {
+    const dinox = error instanceof DinoxError ? error : null;
+    return {
+        index: item.index,
+        id: item.id,
+        args: item.args,
+        ok: false,
+        exit_code: dinox?.exitCode ?? 1,
+        error: {
+            code: dinox?.code ?? 'INTERNAL_ERROR',
+            message: error instanceof Error ? error.message : String(error),
+            ...(dinox?.suggestion ? { suggestion: dinox.suggestion } : {}),
+            ...(dinox?.details !== undefined ? { details: dinox.details } : {}),
+        },
+    };
+}
+async function readStdin() {
+    assertStdinAvailable();
+    if (process.stdin.isTTY) {
+        throw invalidInput('dino batch reads a JSON array from stdin; pipe it in or pass --input <file>');
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+const batchDependencies = {
+    readStdin,
+    readFile: (file) => fs.readFile(resolveUserPath(file), 'utf8'),
+    execute: executeCommandLine,
+};
+export async function runBatch(context, overrides = {}) {
+    const deps = { ...batchDependencies, ...overrides };
+    const input = typeof context.options.input === 'string' && context.options.input !== '-'
+        ? await deps.readFile(context.options.input)
+        : await deps.readStdin();
+    const items = parseBatchItems(input);
+    const stopOnError = Boolean(context.options.stopOnError);
+    const results = [];
+    for (const item of items) {
+        let result;
+        try {
+            result = toBatchItemResult(item, await deps.execute(itemArgv(item.args, context.globals)));
+        }
+        catch (error) {
+            result = errorResult(item, error);
+        }
+        results.push(result);
+        if (!result.ok && stopOnError)
+            break;
+    }
+    const failed = results.filter((result) => !result.ok).length;
+    const summary = {
+        total: items.length,
+        succeeded: results.length - failed,
+        failed,
+        skipped: items.length - results.length,
+    };
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ ok: failed === 0, summary, results });
+        return;
+    }
+    for (const result of results) {
+        const label = result.id ? `${result.id} ` : '';
+        const error = result.error;
+        printHumanReadableLine(`#${result.index} ${label}${result.ok ? 'ok' : `failed (${error?.code ?? 'ERROR'}: ${error?.message ?? ''})`}\t${result.args.join(' ')}`);
+    }
+    printHumanReadableLine(`${summary.succeeded} succeeded, ${summary.failed} failed, ${summary.skipped} skipped of ${summary.total}.`);
+}
+export const batchCommandDescriptor = {
+    name: 'batch',
+    description: 'Run several data commands from one JSON array on stdin or a file and return every result',
+    options: [
+        { flags: '--input <file>', description: 'Read the JSON array from this file instead of stdin (- for stdin)' },
+        { flags: '--stop-on-error', description: 'Stop at the first failed item; later items are reported as skipped', type: 'boolean' },
+    ],
+    schema: {
+        path: 'batch',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS],
+        output: {
+            type: 'structured',
+            summary: 'Per-item results in input order with a success summary; each item carries the command\'s own data or structured error',
+            fields: ['ok', 'summary', 'results'],
+        },
+        examples: [
+            'echo \'[["note","search","AI","--limit","5"],["todo","search","--status","uncompleted"]]\' | dino batch --format json',
+            'dino batch --input ops.json --stop-on-error --format json',
+        ],
+    },
+    action: (context) => runBatch(context),
+};
+export function registerBatchCommand(program) {
+    registerStandaloneCommand(program, batchCommandDescriptor);
+}

package/dist/commands/boxes/index.js

@@ -1,3 +1,5 @@
+import { WRITE_DURABILITY_OPTION } from '../writeDurability.js';
+import { completeWrite, WRITE_RECEIPT_FIELDS } from '../writeReceipt.js';
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
@@ -5,7 +7,7 @@ import { buildBoxAddDryRunPreview, buildBoxMutationDryRunPreview } from '../writ
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { commandStale, printStaleCacheWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
+import { commandStale, printStaleCacheWarning, syncBeforeCommand, resolveWriteDurabilityForRuntime, withCommandRuntime, } from '../runtime.js';
 import { assertWriteConfirmationProvided, parseExpectedCount } from '../writeConfirmation.js';
 import { addBox, inspectAddBox, listBoxes } from './repo.js';
 import { getBoxStats, getBoxTree, inspectBoxCleanup, mergeBox, moveBox, renameBox, } from './operations.js';
@@ -54,6 +56,7 @@ async function runBoxAdd(context) {
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     await withCommandRuntime(context, async (runtime) => {
+        const durability = resolveWriteDurabilityForRuntime(runtime, context.options.durability);
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime, { syncTokenIndex: true });
         const description = typeof context.options.description === 'string' ? context.options.description : undefined;
@@ -77,8 +80,7 @@ async function runBoxAdd(context) {
             description,
             color,
         });
-        await waitForMutationUpload(runtime);
-        const payload = { ok: true, stale: commandStale(runtime), ...result };
+        const payload = { ok: true, ...(await completeWrite(runtime, durability)), ...result };
         if (structuredOutput) {
             printSuccess(payload);
             return;
@@ -89,9 +91,10 @@ async function runBoxAdd(context) {
 }
 async function withBoxWriteRuntime(context, run) {
     return withCommandRuntime(context, async (runtime) => {
+        const durability = resolveWriteDurabilityForRuntime(runtime, context.options.durability);
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime, { syncTokenIndex: true });
-        return run({ runtime, userId: identity.userId });
+        return run({ runtime, userId: identity.userId, durability });
     });
 }
 function requireArg(value, message) {
@@ -104,7 +107,7 @@ function requireArg(value, message) {
 async function runBoxRename(context) {
     const path = requireArg(context.args.path, 'Box path is required');
     const newName = requireArg(context.args.newName, 'New box name is required');
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await renameBox(runtime.db, { path, newName, userId }, { dryRun: Boolean(context.options.dryRun) });
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -119,8 +122,7 @@ async function runBoxRename(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxMove(context) {
@@ -129,7 +131,7 @@ async function runBoxMove(context) {
     if (!to) {
         throw new DinoxError('--to is required');
     }
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await moveBox(runtime.db, { path, to, userId }, { dryRun: Boolean(context.options.dryRun) });
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -144,8 +146,7 @@ async function runBoxMove(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxMerge(context) {
@@ -159,7 +160,7 @@ async function runBoxMerge(context) {
         expectedCount,
     };
     assertWriteConfirmationProvided('Box merge', writeOptions);
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await mergeBox(runtime.db, { from, to, userId }, writeOptions);
         if (dryRun) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -180,8 +181,7 @@ async function runBoxMerge(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxCleanup(context) {
@@ -234,7 +234,7 @@ export const boxCommandGroup = {
                 { flags: '--name <string>', description: 'Box path (alternative to positional path)' },
                 { flags: '--description <string>', description: 'Box purpose/usage description' },
                 { flags: '--color <string>', description: 'Box color' },
-                { flags: '--dry-run', description: 'Preview the write without executing it' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' },
             ],
             schema: {
                 path: 'box.add',
@@ -244,7 +244,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Box creation acknowledgement',
-                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color', 'restored', 'createdNodes', 'restoredNodes', 'stale'],
+                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color', 'restored', 'createdNodes', 'restoredNodes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box add "Work/Inbox" --description "用于存放待整理的想法和资料" --format json --dry-run'],
             },
@@ -291,7 +291,7 @@ export const boxCommandGroup = {
                 { syntax: '<path>', description: 'Existing box path' },
                 { syntax: '<new-name>', description: 'New leaf name' },
             ],
-            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            options: [WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' }],
             schema: {
                 path: 'box.rename',
                 risk: 'write',
@@ -300,7 +300,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box rename result',
-                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box rename "Work/Inbox" "Ideas" --format json --dry-run'],
             },
@@ -312,7 +312,7 @@ export const boxCommandGroup = {
             arguments: [{ syntax: '<path>', description: 'Existing box path' }],
             options: [
                 { flags: '--to <parent-path>', description: 'Target parent box path', required: true, type: 'string' },
-                { flags: '--dry-run', description: 'Preview the write without executing it' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' },
             ],
             schema: {
                 path: 'box.move',
@@ -322,7 +322,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box move result',
-                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box move "Inbox" --to "Work" --format json --dry-run'],
             },
@@ -338,7 +338,7 @@ export const boxCommandGroup = {
             options: [
                 { flags: '--expected-count <n>', description: 'Required for real writes; must equal source boxes plus notes affected', type: 'number' },
                 { flags: '--confirm', description: 'Required for real writes after reviewing a dry run', type: 'boolean' },
-                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
             ],
             schema: {
                 path: 'box.merge',
@@ -348,7 +348,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box merge result',
-                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedBoxIds', 'updatedNotes', 'affectedCount', 'stale'],
+                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedBoxIds', 'updatedNotes', 'affectedCount', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: [
                     'dino box merge "Work/Inbox" "Work/Archive" --format json --dry-run',

package/dist/commands/mcp.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { type McpCommandGroup } from '../gateway/mcpGroups.js';
+import type { CommandDescriptor } from './descriptor/types.js';
+export declare function parseMcpGroups(raw: unknown): McpCommandGroup[] | undefined;
+export declare const mcpCommandDescriptor: CommandDescriptor;
+export declare function registerMcpCommand(program: Command): void;

package/dist/commands/mcp.js

@@ -0,0 +1,47 @@
+import { MCP_COMMAND_GROUPS } from '../gateway/mcpGroups.js';
+import { DinoxError } from '../utils/errors.js';
+import { registerStandaloneCommand } from './descriptor/register.js';
+/** `--groups` names: the command group, with `stats` for meta.stats. */
+const GROUP_NAMES = new Map(MCP_COMMAND_GROUPS.map((group) => [group === 'meta.stats' ? 'stats' : group, group]));
+export function parseMcpGroups(raw) {
+    if (raw === undefined)
+        return undefined;
+    const names = String(raw).split(',').map((name) => name.trim().toLowerCase()).filter(Boolean);
+    const unknown = names.filter((name) => !GROUP_NAMES.has(name));
+    if (names.length === 0 || unknown.length > 0) {
+        throw new DinoxError(`--groups must list some of: ${[...GROUP_NAMES.keys()].join(', ')}`, {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+            details: { invalid: unknown, allowed: [...GROUP_NAMES.keys()] },
+        });
+    }
+    return [...new Set(names.map((name) => GROUP_NAMES.get(name)))];
+}
+async function runMcp(context) {
+    const groups = parseMcpGroups(context.options.groups);
+    const { serveStandaloneMcpOverStdio } = await import('../gateway/mcpServer.js');
+    await serveStandaloneMcpOverStdio({ readOnly: context.options.readOnly === true, groups });
+}
+export const mcpCommandDescriptor = {
+    name: 'mcp',
+    description: 'Serve Dinox commands as MCP tools over stdio for MCP clients (Claude Desktop, Cursor, ...)',
+    options: [
+        { flags: '--read-only', description: 'Expose only read actions', type: 'boolean' },
+        {
+            flags: '--groups <names>',
+            description: `Comma-separated tool groups to expose (${[...GROUP_NAMES.keys()].join(', ')}); default all`,
+        },
+    ],
+    schema: {
+        path: 'mcp',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: [],
+        output: { type: 'structured', summary: 'MCP JSON-RPC over stdio until stdin closes', fields: [] },
+        examples: ['dino mcp', 'dino mcp --read-only --groups note,todo,graph'],
+    },
+    action: (context) => runMcp(context),
+};
+export function registerMcpCommand(program) {
+    registerStandaloneCommand(program, mcpCommandDescriptor);
+}