@dinoxx/dinox-cli 1.0.19 → 1.0.21

package/dist/auth/userInfo.d.ts

@@ -5,6 +5,8 @@ export type AuthIdentity = {
     email: string | null;
     syncedAt: string;
 };
+export declare function buildPendingAuthConfig(rawConfig: DinoxConfig, authorization: string): DinoxConfig;
+export declare function mergeAuthIdentityIntoConfig(rawConfig: DinoxConfig, authorization: string, identity: AuthIdentity): DinoxConfig;
 export declare function fetchUserInfoWithAuthorization(input: {
     authorization: string;
     config: ResolvedDinoxConfig;
@@ -12,4 +14,11 @@ export declare function fetchUserInfoWithAuthorization(input: {
     signal?: AbortSignal;
 }): Promise<AuthIdentity>;
 export declare function refreshAndPersistAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;
-export declare function resolveAuthIdentity(rawConfig: DinoxConfig, resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;
+export declare function hydrateResolvedAuthIdentity(resolvedConfig: ResolvedDinoxConfig, options?: {
+    timeoutMs?: number;
+}): Promise<{
+    config: ResolvedDinoxConfig;
+    identity: AuthIdentity | null;
+    hydrated: boolean;
+}>;
+export declare function resolveAuthIdentity(resolvedConfig: ResolvedDinoxConfig): Promise<AuthIdentity>;

package/dist/auth/userInfo.js

@@ -3,6 +3,33 @@ import { DinoxError } from '../utils/errors.js';
 import { createTimeoutSignal, mergeAbortSignals } from '../utils/abort.js';
 import { toAuthorizationHeaderValue } from '../utils/authToken.js';
 const AUTH_CODE_OK = '000000';
+export function buildPendingAuthConfig(rawConfig, authorization) {
+    return {
+        ...rawConfig,
+        auth: {
+            ...(rawConfig.auth ?? {}),
+            authorization,
+            userId: undefined,
+            username: undefined,
+            email: undefined,
+            userInfoSyncedAt: undefined,
+        },
+    };
+}
+export function mergeAuthIdentityIntoConfig(rawConfig, authorization, identity) {
+    const pendingConfig = buildPendingAuthConfig(rawConfig, authorization);
+    return {
+        ...pendingConfig,
+        auth: {
+            ...(pendingConfig.auth ?? {}),
+            authorization,
+            userId: identity.userId,
+            username: identity.username,
+            email: identity.email,
+            userInfoSyncedAt: identity.syncedAt,
+        },
+    };
+}
 function normalizeOptionalString(value) {
     if (typeof value !== 'string') {
         return undefined;
@@ -105,30 +132,52 @@ export async function refreshAndPersistAuthIdentity(rawConfig, resolvedConfig) {
         authorization,
         config: resolvedConfig,
     });
-    const nextConfig = {
-        ...rawConfig,
-        auth: {
-            ...(rawConfig.auth ?? {}),
-            authorization: rawConfig.auth?.authorization ?? authorization,
-            userId: identity.userId,
-            username: identity.username,
-            email: identity.email,
-            userInfoSyncedAt: identity.syncedAt,
-        },
-    };
+    const nextConfig = mergeAuthIdentityIntoConfig(rawConfig, authorization, identity);
     await saveConfig(nextConfig);
     return identity;
 }
-export async function resolveAuthIdentity(rawConfig, resolvedConfig) {
-    const savedUserId = normalizeOptionalString(rawConfig.auth?.userId ?? resolvedConfig.auth.userId);
-    const syncedAt = normalizeOptionalString(rawConfig.auth?.userInfoSyncedAt ?? resolvedConfig.auth.userInfoSyncedAt);
+function authIdentityFromResolvedConfig(resolvedConfig) {
+    const savedUserId = normalizeOptionalString(resolvedConfig.auth.userId);
+    const syncedAt = normalizeOptionalString(resolvedConfig.auth.userInfoSyncedAt);
     if (savedUserId) {
         return {
             userId: savedUserId,
-            username: normalizeOptionalNullableString(rawConfig.auth?.username ?? resolvedConfig.auth.username),
-            email: normalizeOptionalNullableString(rawConfig.auth?.email ?? resolvedConfig.auth.email),
+            username: normalizeOptionalNullableString(resolvedConfig.auth.username),
+            email: normalizeOptionalNullableString(resolvedConfig.auth.email),
             syncedAt: syncedAt ?? new Date().toISOString(),
         };
     }
-    throw new DinoxError('Missing persisted userId. Run `dino auth login` first.');
+    return null;
+}
+export async function hydrateResolvedAuthIdentity(resolvedConfig, options = {}) {
+    const existing = authIdentityFromResolvedConfig(resolvedConfig);
+    if (existing || !resolvedConfig.auth.authorization) {
+        return { config: resolvedConfig, identity: existing, hydrated: false };
+    }
+    const identity = await fetchUserInfoWithAuthorization({
+        authorization: resolvedConfig.auth.authorization,
+        config: resolvedConfig,
+        timeoutMs: options.timeoutMs,
+    });
+    return {
+        config: {
+            ...resolvedConfig,
+            auth: {
+                ...resolvedConfig.auth,
+                userId: identity.userId,
+                username: identity.username,
+                email: identity.email,
+                userInfoSyncedAt: identity.syncedAt,
+            },
+        },
+        identity,
+        hydrated: true,
+    };
+}
+export async function resolveAuthIdentity(resolvedConfig) {
+    const identity = authIdentityFromResolvedConfig(resolvedConfig);
+    if (identity) {
+        return identity;
+    }
+    throw new DinoxError('Missing resolved userId for the current authorization. Run `dino auth login` first, or set DINOX_TOKEN and run an online command so the CLI can resolve the token identity.');
 }

package/dist/cli.js

@@ -5,7 +5,6 @@ import { registerConfigCommands } from './commands/config/index.js';
 import { registerDaemonCommands } from './daemon/index.js';
 import { registerGraphCommands } from './commands/graph/index.js';
 import { registerInfoCommand } from './commands/info/index.js';
-import { registerMCPCommands } from './commands/mcp/index.js';
 import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
@@ -44,7 +43,6 @@ export function createCli() {
     registerDaemonCommands(program);
     registerGraphCommands(program);
     registerInfoCommand(program);
-    registerMCPCommands(program);
     registerMetaCommands(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);

package/dist/commands/auth/index.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
-import { refreshAndPersistAuthIdentity } from '../../auth/userInfo.js';
-import { getPowerSyncDbPath } from '../../config/paths.js';
+import { buildPendingAuthConfig, fetchUserInfoWithAuthorization, hydrateResolvedAuthIdentity, mergeAuthIdentityIntoConfig, } from '../../auth/userInfo.js';
+import { getLegacyPowerSyncDbPath, getPowerSyncDbPath } from '../../config/paths.js';
 import { loadConfig, saveConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
 import { fetchCredentialsWithAuthorization } from '../../powersync/connector.js';
@@ -8,7 +8,7 @@ import { connectPowerSync, getStatusSnapshot } from '../../powersync/runtime.js'
 import { runSingleSyncPass } from '../../powersync/syncPass.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
-import { normalizeAuthToken } from '../../utils/authToken.js';
+import { normalizeAuthToken, readEnvAuthToken } from '../../utils/authToken.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
 import { redactAuthorization } from '../../utils/redact.js';
@@ -26,10 +26,13 @@ async function runAuthLogin(context) {
     if (!rawToken) {
         throw new DinoxError('Token is required');
     }
-    const config = await loadConfig();
-    config.auth = { ...(config.auth ?? {}), authorization: rawToken };
-    await saveConfig(config);
-    const resolved = resolveConfig(config);
+    const envToken = readEnvAuthToken();
+    if (envToken && envToken !== rawToken) {
+        throw new DinoxError('DINOX_TOKEN is set and differs from the login token. Unset DINOX_TOKEN before running `dino auth login`, or use the same token.');
+    }
+    const previousConfig = await loadConfig();
+    const pendingConfig = buildPendingAuthConfig(previousConfig, rawToken);
+    const resolved = resolveConfig(pendingConfig);
     const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? resolved.sync.timeoutMs;
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     await fetchCredentialsWithAuthorization({
@@ -38,19 +41,26 @@ async function runAuthLogin(context) {
         credentialsUrl: resolved.powersync.tokenEndpoint,
         timeoutMs,
     });
-    const identity = await refreshAndPersistAuthIdentity(config, resolved);
-    const { db, dbPath, stale } = await connectPowerSync({
+    const identity = await fetchUserInfoWithAuthorization({
+        authorization: rawToken,
         config: resolved,
+        timeoutMs,
+    });
+    const verifiedConfig = mergeAuthIdentityIntoConfig(previousConfig, rawToken, identity);
+    const verifiedResolved = resolveConfig(verifiedConfig);
+    const { db, dbPath, stale } = await connectPowerSync({
+        config: verifiedResolved,
         offline: false,
         timeoutMs,
     });
     try {
         await runSingleSyncPass(db, timeoutMs);
+        await saveConfig(verifiedConfig);
         const status = getStatusSnapshot(db);
         const result = {
             ok: true,
             verified: true,
-            endpoint: resolved.powersync.endpoint,
+            endpoint: verifiedResolved.powersync.endpoint,
             dbPath,
             stale,
             lastSyncedAt: status.lastSyncedAt,
@@ -78,6 +88,7 @@ async function runAuthLogin(context) {
 async function runAuthLogout(context) {
     const options = context.options;
     const config = await loadConfig();
+    const currentUserId = config.auth?.userId;
     if (config.auth) {
         config.auth.authorization = undefined;
         config.auth.userId = undefined;
@@ -87,7 +98,8 @@ async function runAuthLogout(context) {
     }
     await saveConfig(config);
     if (options.clearLocalDb) {
-        await removeSqliteArtifacts(getPowerSyncDbPath());
+        await removeSqliteArtifacts(getPowerSyncDbPath(currentUserId));
+        await removeSqliteArtifacts(getLegacyPowerSyncDbPath());
     }
     if (getRequestedStructuredOutputFormat()) {
         printSuccess({
@@ -99,11 +111,14 @@ async function runAuthLogout(context) {
 }
 async function runAuthStatus(context) {
     const config = await loadConfig();
-    const resolved = resolveConfig(config);
+    const baseResolved = resolveConfig(config);
     const offline = Boolean(context.globals.offline);
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? resolved.sync.timeoutMs;
-    const dbPath = getPowerSyncDbPath();
+    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? baseResolved.sync.timeoutMs;
+    const { config: resolved } = offline
+        ? { config: baseResolved }
+        : await hydrateResolvedAuthIdentity(baseResolved, { timeoutMs });
+    const dbPath = getPowerSyncDbPath(resolved.auth.userId);
     const base = {
         loggedIn: Boolean(resolved.auth.authorization),
         authorization: redactAuthorization(resolved.auth.authorization),

package/dist/commands/boxes/index.js

@@ -1,41 +1,39 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
-import { loadConfig } from '../../config/store.js';
-import { resolveConfig } from '../../config/resolve.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
-import { syncNoteTokenIndex } from '../../powersync/tokenIndex.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
-import { buildBoxAddDryRunPreview } from '../writeDryRun.js';
+import { buildBoxAddDryRunPreview, buildBoxMutationDryRunPreview } from '../writeDryRun.js';
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
+import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
 import { addBox, inspectAddBox, listBoxes } from './repo.js';
+import { getBoxStats, getBoxTree, inspectBoxCleanup, mergeBox, moveBox, renameBox, } from './operations.js';
 const BOX_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
-async function syncBeforeBoxCommand(db, offline, timeoutMs) {
-    if (offline) {
-        return;
-    }
-    await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
-    await syncNoteTokenIndex(db);
+async function runBoxList(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess(await listBoxes(runtime.db, { userId: identity.userId }));
+    });
 }
-async function withBoxDb(context, run) {
-    const rawConfig = await loadConfig();
-    const config = resolveConfig(rawConfig);
-    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? config.sync.timeoutMs;
-    const offline = Boolean(context.globals.offline);
-    const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-    try {
-        await run({ db, config, rawConfig, offline, timeoutMs, stale });
-    }
-    finally {
-        await db.close().catch(() => undefined);
-    }
+async function runBoxTree(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess({
+            stale: commandStale(runtime),
+            tree: await getBoxTree(runtime.db, { userId: identity.userId }),
+        });
+    });
 }
-async function runBoxList(context) {
-    await withBoxDb(context, async ({ db, offline, timeoutMs }) => {
-        await syncBeforeBoxCommand(db, offline, timeoutMs);
-        printSuccess(await listBoxes(db));
+async function runBoxStats(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess({
+            stale: commandStale(runtime),
+            ...(await getBoxStats(runtime.db, { userId: identity.userId })),
+        });
     });
 }
 async function runBoxAdd(context) {
@@ -43,22 +41,22 @@ async function runBoxAdd(context) {
     const optionName = typeof context.options.name === 'string' ? context.options.name : undefined;
     const name = (nameArg ?? optionName ?? '').trim();
     if (!name) {
-        throw new DinoxError('Box name is required. Use `dino box add <name>` or `dino box add --name <name>`.');
+        throw new DinoxError('Box path is required. Use `dino box add <path>` or `dino box add --name <path>`.');
     }
     if (nameArg && optionName && nameArg.trim() !== optionName.trim()) {
-        throw new DinoxError('Conflicting box name values from positional argument and --name option.');
+        throw new DinoxError('Conflicting box path values from positional argument and --name option.');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withBoxDb(context, async ({ db, config, rawConfig, offline, timeoutMs, stale }) => {
-        const identity = await resolveAuthIdentity(rawConfig, config);
-        await syncBeforeBoxCommand(db, offline, timeoutMs);
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
         const description = typeof context.options.description === 'string' ? context.options.description : undefined;
         const color = typeof context.options.color === 'string' ? context.options.color : undefined;
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildBoxAddDryRunPreview({
-                config,
-                offline,
-                ...(await inspectAddBox(db, {
+                config: runtime.config,
+                offline: runtime.offline,
+                ...(await inspectAddBox(runtime.db, {
                     name,
                     userId: identity.userId,
                     description,
@@ -67,27 +65,131 @@ async function runBoxAdd(context) {
             }));
             return;
         }
-        const result = await addBox(db, {
+        const result = await addBox(runtime.db, {
             name,
             userId: identity.userId,
             description,
             color,
         });
-        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));
-        }
-        const payload = { ok: true, stale: offline ? true : stale, ...result };
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = { ok: true, stale: commandStale(runtime), ...result };
         if (structuredOutput) {
             printSuccess(payload);
             return;
         }
         printHumanReadableLine(result.id);
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; results may be stale');
+        printStaleCacheWarning(runtime, 'warning: sync timed out; results may be stale');
+    });
+}
+async function withBoxWriteRuntime(context, run) {
+    return withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        return run({ runtime, userId: identity.userId });
+    });
+}
+function requireArg(value, message) {
+    const trimmed = value?.trim() ?? '';
+    if (!trimmed) {
+        throw new DinoxError(message);
+    }
+    return trimmed;
+}
+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 }) => {
+        const result = await renameBox(runtime.db, { path, newName, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildBoxMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino box rename',
+                action: 'rename_box',
+                risk: 'write',
+                summary: `Rename zettel box "${result.fromPath}" to "${result.toPath}".`,
+                inputs: { path, new_name: newName },
+                changes: { updated_boxes: result.updatedBoxes },
+            }));
+            return;
+        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runBoxMove(context) {
+    const path = requireArg(context.args.path, 'Box path is required');
+    const to = typeof context.options.to === 'string' ? context.options.to.trim() : '';
+    if (!to) {
+        throw new DinoxError('--to is required');
+    }
+    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+        const result = await moveBox(runtime.db, { path, to, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildBoxMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino box move',
+                action: 'move_box',
+                risk: 'write',
+                summary: `Move zettel box "${result.fromPath}" to "${result.toPath}".`,
+                inputs: { path, to },
+                changes: { updated_boxes: result.updatedBoxes },
+            }));
+            return;
+        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runBoxMerge(context) {
+    const from = requireArg(context.args.from, 'Source box path is required');
+    const to = requireArg(context.args.to, 'Target box path is required');
+    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+        const result = await mergeBox(runtime.db, { from, to, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildBoxMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino box merge',
+                action: 'merge_box',
+                risk: 'high-risk-write',
+                summary: `Merge zettel box subtree "${result.fromPath}" into "${result.toPath}".`,
+                inputs: { from, to },
+                changes: {
+                    soft_deleted_box_ids: result.softDeletedBoxIds,
+                    updated_notes: result.updatedNotes,
+                },
+            }));
+            return;
         }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runBoxCleanup(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        const result = await inspectBoxCleanup(runtime.db, { userId: identity.userId });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildBoxMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino box cleanup',
+                action: 'cleanup_boxes',
+                risk: 'write',
+                summary: `Inspect zettel box cleanup candidates (${result.issues.length} issues).`,
+                inputs: {},
+                targets: result.issues,
+            }));
+            return;
+        }
+        printSuccess({ stale: commandStale(runtime), ...result });
     });
 }
 export const boxCommandGroup = {
@@ -105,7 +207,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Box list payload',
-                    fields: ['id', 'name', 'description'],
+                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color'],
                 },
                 examples: ['dino box list --format json'],
             },
@@ -113,10 +215,10 @@ export const boxCommandGroup = {
         },
         {
             name: 'add',
-            description: 'Create a zettel box, restoring a deleted row when possible',
-            arguments: [{ syntax: '[name]', description: 'Box name' }],
+            description: 'Create a zettel box path, restoring deleted path nodes when possible',
+            arguments: [{ syntax: '[path]', description: 'Box path, for example Work/Inbox' }],
             options: [
-                { flags: '--name <string>', description: 'Box name (alternative to positional name)' },
+                { 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' },
@@ -129,12 +231,130 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Box creation acknowledgement',
-                    fields: ['id', 'name', 'description', 'color', 'restored', 'stale'],
+                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color', 'restored', 'createdNodes', 'restoredNodes', 'stale'],
                 },
-                examples: ['dino box add "Inbox" --description "用于存放待整理的想法和资料" --format json --dry-run'],
+                examples: ['dino box add "Work/Inbox" --description "用于存放待整理的想法和资料" --format json --dry-run'],
             },
             action: runBoxAdd,
         },
+        {
+            name: 'tree',
+            description: 'Show zettel boxes as a hierarchy tree',
+            schema: {
+                path: 'box.tree',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Nested zettel box tree payload',
+                    fields: ['tree.id', 'tree.name', 'tree.path', 'tree.parentId', 'tree.children', 'stale'],
+                },
+                examples: ['dino box tree --format json'],
+            },
+            action: runBoxTree,
+        },
+        {
+            name: 'stats',
+            description: 'Show zettel box note counts and empty-box status',
+            schema: {
+                path: 'box.stats',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Zettel box statistics payload',
+                    fields: ['totalBoxes', 'emptyBoxes', 'boxes.id', 'boxes.path', 'boxes.directNoteCount', 'boxes.descendantNoteCount', 'boxes.latestNoteUpdatedAt', 'boxes.isEmpty', 'stale'],
+                },
+                examples: ['dino box stats --format json'],
+            },
+            action: runBoxStats,
+        },
+        {
+            name: 'rename',
+            description: 'Rename a zettel box and cascade descendant paths',
+            arguments: [
+                { syntax: '<path>', description: 'Existing box path' },
+                { syntax: '<new-name>', description: 'New leaf name' },
+            ],
+            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            schema: {
+                path: 'box.rename',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Zettel box rename result',
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                },
+                examples: ['dino box rename "Work/Inbox" "Ideas" --format json --dry-run'],
+            },
+            action: runBoxRename,
+        },
+        {
+            name: 'move',
+            description: 'Move a zettel box under another parent and cascade descendant paths',
+            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' },
+            ],
+            schema: {
+                path: 'box.move',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Zettel box move result',
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                },
+                examples: ['dino box move "Inbox" --to "Work" --format json --dry-run'],
+            },
+            action: runBoxMove,
+        },
+        {
+            name: 'merge',
+            description: 'Merge a zettel box subtree into another box and soft-delete the source subtree',
+            arguments: [
+                { syntax: '<from>', description: 'Source box path' },
+                { syntax: '<to>', description: 'Target box path' },
+            ],
+            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            schema: {
+                path: 'box.merge',
+                risk: 'high-risk-write',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Zettel box merge result',
+                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedBoxIds', 'updatedNotes', 'stale'],
+                },
+                examples: ['dino box merge "Work/Inbox" "Work/Archive" --format json --dry-run'],
+            },
+            action: runBoxMerge,
+        },
+        {
+            name: 'cleanup',
+            description: 'Inspect zettel box cleanup candidates',
+            options: [{ flags: '--dry-run', description: 'Preview cleanup candidates without writing' }],
+            schema: {
+                path: 'box.cleanup',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Zettel box cleanup inspection payload',
+                    fields: ['issues', 'emptyBoxes', 'duplicatePaths', 'orphanParents', 'deletedWithActiveChildren', 'stale'],
+                },
+                examples: ['dino box cleanup --format json --dry-run'],
+            },
+            action: runBoxCleanup,
+        },
     ],
 };
 export function registerBoxesCommand(program) {