@dinoxx/dinox-cli 1.0.17 → 1.0.19

package/dist/commands/auth/index.js

@@ -1,183 +1,229 @@
 import fs from 'node:fs/promises';
+import { refreshAndPersistAuthIdentity } from '../../auth/userInfo.js';
+import { getPowerSyncDbPath } from '../../config/paths.js';
 import { loadConfig, saveConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
-import { getPowerSyncDbPath } from '../../config/paths.js';
-import { redactAuthorization } from '../../utils/redact.js';
-import { DinoxError } from '../../utils/errors.js';
-import { printYaml } from '../../utils/output.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
-import { normalizeAuthToken } from '../../utils/authToken.js';
-import { refreshAndPersistAuthIdentity } from '../../auth/userInfo.js';
-import { connectPowerSync, getStatusSnapshot } from '../../powersync/runtime.js';
 import { fetchCredentialsWithAuthorization } from '../../powersync/connector.js';
+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 { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
+import { redactAuthorization } from '../../utils/redact.js';
+import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
+const AUTH_LOGIN_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
+const AUTH_STATUS_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function removeSqliteArtifacts(dbPath) {
-    const artifacts = ['', '-wal', '-shm'];
-    for (const suffix of artifacts) {
+    for (const suffix of ['', '-wal', '-shm']) {
         await fs.rm(`${dbPath}${suffix}`, { force: true }).catch(() => undefined);
     }
 }
-export function registerAuthCommands(program) {
-    const auth = program
-        .command('auth')
-        .description('Authentication and PowerSync connectivity commands');
-    auth
-        .command('login')
-        .description('Save login token and verify PowerSync connectivity')
-        .argument('<token>', 'login token (pass the raw token string, without Bearer prefix)')
-        .action(async (token, _options, command) => {
-        const rawToken = normalizeAuthToken(token);
-        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 globals = command.optsWithGlobals?.() ?? {};
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? resolved.sync.timeoutMs;
-        const jsonOutput = Boolean(globals.json);
-        // 1) Token exchange sanity check.
-        await fetchCredentialsWithAuthorization({
-            authorization: rawToken,
-            endpoint: resolved.powersync.endpoint,
-            credentialsUrl: resolved.powersync.tokenEndpoint,
-            timeoutMs,
-        });
-        // 1.5) Fetch and persist user identity.
-        const identity = await refreshAndPersistAuthIdentity(config, resolved);
-        // 2) Connect + initial sync.
-        const { db, dbPath, stale } = await connectPowerSync({
-            config: resolved,
-            offline: false,
-            timeoutMs,
-        });
-        try {
-            await runSingleSyncPass(db, timeoutMs);
-            const status = getStatusSnapshot(db);
-            const result = {
-                ok: true,
-                verified: true,
-                endpoint: resolved.powersync.endpoint,
-                dbPath,
-                stale,
-                lastSyncedAt: status.lastSyncedAt,
-                userId: identity.userId,
-            };
-            if (jsonOutput) {
-                printYaml(result);
-            }
-            else {
-                console.log('Login verified.');
-                console.log(`- endpoint: ${result.endpoint}`);
-                console.log(`- db: ${result.dbPath}`);
-                console.log(`- userId: ${result.userId}`);
-                if (result.lastSyncedAt) {
-                    console.log(`- lastSyncedAt: ${result.lastSyncedAt}`);
-                }
-                if (stale) {
-                    console.log('- warning: initial sync timed out; local cache may be stale');
-                }
-            }
-        }
-        finally {
-            await db.close().catch(() => undefined);
-        }
+async function runAuthLogin(context) {
+    const token = context.args.token;
+    const rawToken = normalizeAuthToken(token);
+    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 timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? resolved.sync.timeoutMs;
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await fetchCredentialsWithAuthorization({
+        authorization: rawToken,
+        endpoint: resolved.powersync.endpoint,
+        credentialsUrl: resolved.powersync.tokenEndpoint,
+        timeoutMs,
     });
-    auth
-        .command('logout')
-        .description('Clear saved login token')
-        .option('--clear-local-db', 'delete the local PowerSync SQLite database')
-        .action(async (options) => {
-        const config = await loadConfig();
-        if (config.auth) {
-            config.auth.authorization = undefined;
-            config.auth.userId = undefined;
-            config.auth.username = undefined;
-            config.auth.email = undefined;
-            config.auth.userInfoSyncedAt = undefined;
-        }
-        await saveConfig(config);
-        if (options.clearLocalDb) {
-            const dbPath = getPowerSyncDbPath();
-            await removeSqliteArtifacts(dbPath);
-        }
+    const identity = await refreshAndPersistAuthIdentity(config, resolved);
+    const { db, dbPath, stale } = await connectPowerSync({
+        config: resolved,
+        offline: false,
+        timeoutMs,
     });
-    auth
-        .command('status')
-        .description('Show current login and sync status')
-        .action(async (_options, command) => {
-        const config = await loadConfig();
-        const resolved = resolveConfig(config);
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        const jsonOutput = Boolean(globals.json);
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? resolved.sync.timeoutMs;
-        const dbPath = getPowerSyncDbPath();
-        const base = {
-            loggedIn: Boolean(resolved.auth.authorization),
-            authorization: redactAuthorization(resolved.auth.authorization),
-            userId: resolved.auth.userId ?? null,
-            username: resolved.auth.username ?? null,
-            email: resolved.auth.email ?? null,
-            powersync: {
-                endpoint: resolved.powersync.endpoint ?? null,
-                tokenEndpoint: resolved.powersync.tokenEndpoint ?? null,
-                uploadBaseUrl: resolved.powersync.uploadBaseUrl ?? null,
-                uploadV4Path: resolved.powersync.uploadV4Path,
-                uploadV2Path: resolved.powersync.uploadV2Path,
-            },
+    try {
+        await runSingleSyncPass(db, timeoutMs);
+        const status = getStatusSnapshot(db);
+        const result = {
+            ok: true,
+            verified: true,
+            endpoint: resolved.powersync.endpoint,
             dbPath,
+            stale,
+            lastSyncedAt: status.lastSyncedAt,
+            userId: identity.userId,
         };
-        if (offline || !resolved.auth.authorization || !resolved.powersync.endpoint || !resolved.powersync.tokenEndpoint) {
-            const payload = { ...base, offline: true };
-            if (jsonOutput) {
-                printYaml(payload);
-            }
-            else {
-                console.log(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
-                if (payload.userId) {
-                    console.log(`userId: ${payload.userId}`);
-                }
-                console.log(`db: ${payload.dbPath}`);
-                console.log(`powersync.endpoint: ${payload.powersync.endpoint ?? '(unset)'}`);
-                console.log(`powersync.tokenEndpoint: ${payload.powersync.tokenEndpoint ?? '(unset)'}`);
-                console.log(`powersync.uploadBaseUrl: ${payload.powersync.uploadBaseUrl ?? '(unset)'}`);
-            }
+        if (structuredOutput) {
+            printSuccess(result);
             return;
         }
-        const { db, stale } = await connectPowerSync({
-            config: resolved,
-            offline: false,
-            timeoutMs,
+        printHumanReadableLine('Login verified.');
+        printHumanReadableLine(`- endpoint: ${result.endpoint}`);
+        printHumanReadableLine(`- db: ${result.dbPath}`);
+        printHumanReadableLine(`- userId: ${result.userId}`);
+        if (result.lastSyncedAt) {
+            printHumanReadableLine(`- lastSyncedAt: ${result.lastSyncedAt}`);
+        }
+        if (stale) {
+            printHumanReadableLine('- warning: initial sync timed out; local cache may be stale');
+        }
+    }
+    finally {
+        await db.close().catch(() => undefined);
+    }
+}
+async function runAuthLogout(context) {
+    const options = context.options;
+    const config = await loadConfig();
+    if (config.auth) {
+        config.auth.authorization = undefined;
+        config.auth.userId = undefined;
+        config.auth.username = undefined;
+        config.auth.email = undefined;
+        config.auth.userInfoSyncedAt = undefined;
+    }
+    await saveConfig(config);
+    if (options.clearLocalDb) {
+        await removeSqliteArtifacts(getPowerSyncDbPath());
+    }
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({
+            ok: true,
+            loggedOut: true,
+            clearedLocalDb: Boolean(options.clearLocalDb),
         });
-        try {
-            const status = getStatusSnapshot(db);
-            const payload = { ...base, offline: false, stale, status };
-            if (jsonOutput) {
-                printYaml(payload);
-            }
-            else {
-                console.log(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
-                if (payload.userId) {
-                    console.log(`userId: ${payload.userId}`);
-                }
-                console.log(`db: ${payload.dbPath}`);
-                console.log(`connected: ${payload.status.connected ? 'yes' : 'no'}`);
-                if (payload.status.lastSyncedAt) {
-                    console.log(`lastSyncedAt: ${payload.status.lastSyncedAt}`);
-                }
-                console.log(`dataFlow: downloading=${payload.status.dataFlowStatus.downloading} uploading=${payload.status.dataFlowStatus.uploading}`);
-                if (payload.stale) {
-                    console.log('warning: sync timed out; local cache may be stale');
-                }
-            }
+    }
+}
+async function runAuthStatus(context) {
+    const config = await loadConfig();
+    const resolved = 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 base = {
+        loggedIn: Boolean(resolved.auth.authorization),
+        authorization: redactAuthorization(resolved.auth.authorization),
+        userId: resolved.auth.userId ?? null,
+        username: resolved.auth.username ?? null,
+        email: resolved.auth.email ?? null,
+        powersync: {
+            endpoint: resolved.powersync.endpoint ?? null,
+            tokenEndpoint: resolved.powersync.tokenEndpoint ?? null,
+            uploadBaseUrl: resolved.powersync.uploadBaseUrl ?? null,
+            uploadV4Path: resolved.powersync.uploadV4Path,
+            uploadV2Path: resolved.powersync.uploadV2Path,
+        },
+        dbPath,
+    };
+    if (offline || !resolved.auth.authorization || !resolved.powersync.endpoint || !resolved.powersync.tokenEndpoint) {
+        const payload = { ...base, offline: true };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
         }
-        finally {
-            await db.close().catch(() => undefined);
+        printHumanReadableLine(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
+        if (payload.userId) {
+            printHumanReadableLine(`userId: ${payload.userId}`);
         }
+        printHumanReadableLine(`db: ${payload.dbPath}`);
+        printHumanReadableLine(`powersync.endpoint: ${payload.powersync.endpoint ?? '(unset)'}`);
+        printHumanReadableLine(`powersync.tokenEndpoint: ${payload.powersync.tokenEndpoint ?? '(unset)'}`);
+        printHumanReadableLine(`powersync.uploadBaseUrl: ${payload.powersync.uploadBaseUrl ?? '(unset)'}`);
+        return;
+    }
+    const { db, stale } = await connectPowerSync({
+        config: resolved,
+        offline: false,
+        timeoutMs,
     });
-    auth.action((_options, command) => {
-        command.outputHelp();
-    });
+    try {
+        const status = getStatusSnapshot(db);
+        const payload = { ...base, offline: false, stale, status };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine(`loggedIn: ${payload.loggedIn ? 'yes' : 'no'}`);
+        if (payload.userId) {
+            printHumanReadableLine(`userId: ${payload.userId}`);
+        }
+        printHumanReadableLine(`db: ${payload.dbPath}`);
+        printHumanReadableLine(`connected: ${payload.status.connected ? 'yes' : 'no'}`);
+        if (payload.status.lastSyncedAt) {
+            printHumanReadableLine(`lastSyncedAt: ${payload.status.lastSyncedAt}`);
+        }
+        printHumanReadableLine(`dataFlow: downloading=${payload.status.dataFlowStatus.downloading} uploading=${payload.status.dataFlowStatus.uploading}`);
+        if (payload.stale) {
+            printHumanReadableLine('warning: sync timed out; local cache may be stale');
+        }
+    }
+    finally {
+        await db.close().catch(() => undefined);
+    }
+}
+export const authCommandGroup = {
+    name: 'auth',
+    description: 'Authentication and PowerSync connectivity commands',
+    commands: [
+        {
+            name: 'login',
+            description: 'Save login token and verify PowerSync connectivity',
+            arguments: [{ syntax: '<token>', description: 'Login token (without Bearer prefix)' }],
+            schema: {
+                path: 'auth.login',
+                risk: 'write',
+                auth: 'optional',
+                globalOptions: AUTH_LOGIN_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Login verification result',
+                    fields: ['verified', 'endpoint', 'dbPath', 'stale', 'lastSyncedAt', 'userId'],
+                },
+                examples: ['dino auth login "<token>" --format json'],
+            },
+            action: runAuthLogin,
+        },
+        {
+            name: 'logout',
+            description: 'Clear saved login token and optionally remove the local cache',
+            options: [{ flags: '--clear-local-db', description: 'Delete the local PowerSync SQLite database' }],
+            schema: {
+                path: 'auth.logout',
+                risk: 'write',
+                auth: 'optional',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Logout acknowledgement',
+                    fields: ['loggedOut', 'clearedLocalDb'],
+                },
+                examples: ['dino auth logout --format json', 'dino auth logout --clear-local-db --format json'],
+            },
+            action: runAuthLogout,
+        },
+        {
+            name: 'status',
+            description: 'Show current login, local cache, and sync status',
+            schema: {
+                path: 'auth.status',
+                risk: 'read',
+                auth: 'optional',
+                globalOptions: AUTH_STATUS_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Auth and connectivity status envelope',
+                    fields: ['loggedIn', 'authorization', 'userId', 'username', 'email', 'powersync', 'dbPath', 'offline', 'stale', 'status'],
+                },
+                examples: ['dino auth status --format json', 'dino auth status --offline --format json'],
+            },
+            action: runAuthStatus,
+        },
+    ],
+};
+export function registerAuthCommands(program) {
+    registerCommandGroup(program, authCommandGroup);
 }

package/dist/commands/boxes/index.d.ts

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

package/dist/commands/boxes/index.js

@@ -1,12 +1,17 @@
+import { resolveAuthIdentity } from '../../auth/userInfo.js';
 import { loadConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
-import { DinoxError } from '../../utils/errors.js';
-import { printYaml } from '../../utils/output.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
 import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
 import { syncNoteTokenIndex } from '../../powersync/tokenIndex.js';
-import { resolveAuthIdentity } from '../../auth/userInfo.js';
-import { addBox, listBoxes } from './repo.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 { 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 { addBox, inspectAddBox, listBoxes } from './repo.js';
+const BOX_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function syncBeforeBoxCommand(db, offline, timeoutMs) {
     if (offline) {
         return;
@@ -14,85 +19,124 @@ async function syncBeforeBoxCommand(db, offline, timeoutMs) {
     await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
     await syncNoteTokenIndex(db);
 }
-async function runBoxListCommand(options, command) {
-    const globals = command.optsWithGlobals?.() ?? {};
-    const offline = Boolean(options.offline ?? globals.offline);
-    const config = resolveConfig(await loadConfig());
-    const timeoutMs = parseSyncTimeoutMs(options.syncTimeout ?? globals.syncTimeout) ?? config.sync.timeoutMs;
-    const { db } = await connectPowerSync({ config, offline, timeoutMs });
+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 syncBeforeBoxCommand(db, offline, timeoutMs);
-        const boxes = await listBoxes(db);
-        printYaml(boxes);
+        await run({ db, config, rawConfig, offline, timeoutMs, stale });
     }
     finally {
         await db.close().catch(() => undefined);
     }
 }
-export function registerBoxesCommand(program) {
-    const box = program.command('box').description('Manage zettel boxes');
-    box
-        .command('list')
-        .description('List zettel boxes (id and name) from c_zettel_box')
-        .option('--offline', 'skip connect/sync and only use local cache')
-        .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
-        .action(runBoxListCommand);
-    box
-        .command('add')
-        .description('Create a new zettel box in c_zettel_box')
-        .argument('[name]', 'box name')
-        .option('--name <string>', 'box name (alternative to positional name)')
-        .option('--description <string>', 'box purpose/usage description (helps AI route notes to this box)')
-        .option('--color <string>', 'box color')
-        .option('--json', 'output machine-readable YAML')
-        .option('--offline', 'skip connect/sync and only use local cache')
-        .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
-        .action(async (nameArg, options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(options.offline ?? globals.offline);
-        const jsonOutput = Boolean(options.json ?? globals.json);
-        const optionName = typeof options.name === 'string' ? 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>`.');
+async function runBoxList(context) {
+    await withBoxDb(context, async ({ db, offline, timeoutMs }) => {
+        await syncBeforeBoxCommand(db, offline, timeoutMs);
+        printSuccess(await listBoxes(db));
+    });
+}
+async function runBoxAdd(context) {
+    const nameArg = context.args.name;
+    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>`.');
+    }
+    if (nameArg && optionName && nameArg.trim() !== optionName.trim()) {
+        throw new DinoxError('Conflicting box name 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);
+        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, {
+                    name,
+                    userId: identity.userId,
+                    description,
+                    color,
+                })),
+            }));
+            return;
         }
-        if (nameArg && optionName && nameArg.trim() !== optionName.trim()) {
-            throw new DinoxError('Conflicting box name values from positional argument and --name option.');
+        const result = await addBox(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');
         }
-        const rawConfig = await loadConfig();
-        const config = resolveConfig(rawConfig);
-        const timeoutMs = parseSyncTimeoutMs(options.syncTimeout ?? globals.syncTimeout) ?? config.sync.timeoutMs;
-        const identity = await resolveAuthIdentity(rawConfig, config);
-        const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-        try {
-            await syncBeforeBoxCommand(db, offline, timeoutMs);
-            const result = await addBox(db, {
-                name,
-                userId: identity.userId,
-                description: typeof options.description === 'string' ? options.description : undefined,
-                color: typeof options.color === 'string' ? options.color : undefined,
-            });
-            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));
-            }
-            const payload = { ok: true, stale: offline ? true : stale, ...result };
-            if (jsonOutput) {
-                printYaml(payload);
-                return;
-            }
-            console.log(result.id);
-            if (stale && !offline) {
-                console.log('warning: sync timed out; results may be stale');
-            }
+        if (!offline) {
+            await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
         }
-        finally {
-            await db.close().catch(() => undefined);
+        const payload = { ok: true, stale: offline ? true : stale, ...result };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine(result.id);
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; results may be stale');
         }
     });
-    box.action((_options, command) => {
-        command.outputHelp();
-    });
+}
+export const boxCommandGroup = {
+    name: 'box',
+    description: 'Manage zettel boxes',
+    commands: [
+        {
+            name: 'list',
+            description: 'List all zettel boxes from c_zettel_box',
+            schema: {
+                path: 'box.list',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Box list payload',
+                    fields: ['id', 'name', 'description'],
+                },
+                examples: ['dino box list --format json'],
+            },
+            action: runBoxList,
+        },
+        {
+            name: 'add',
+            description: 'Create a zettel box, restoring a deleted row when possible',
+            arguments: [{ syntax: '[name]', description: 'Box name' }],
+            options: [
+                { flags: '--name <string>', description: 'Box name (alternative to positional name)' },
+                { flags: '--description <string>', description: 'Box purpose/usage description' },
+                { flags: '--color <string>', description: 'Box color' },
+                { flags: '--dry-run', description: 'Preview the write without executing it' },
+            ],
+            schema: {
+                path: 'box.add',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: BOX_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Box creation acknowledgement',
+                    fields: ['id', 'name', 'description', 'color', 'restored', 'stale'],
+                },
+                examples: ['dino box add "Inbox" --description "用于存放待整理的想法和资料" --format json --dry-run'],
+            },
+            action: runBoxAdd,
+        },
+    ],
+};
+export function registerBoxesCommand(program) {
+    registerCommandGroup(program, boxCommandGroup);
 }

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

@@ -17,5 +17,13 @@ export type AddBoxResult = {
     color: string;
     restored: boolean;
 };
+export type InspectAddBoxResult = {
+    name: string;
+    description: string;
+    color: string;
+    restored: boolean;
+    existingId?: string;
+};
 export declare function listBoxes(db: AbstractPowerSyncDatabase): Promise<BoxListItem[]>;
 export declare function addBox(db: AbstractPowerSyncDatabase, input: AddBoxInput): Promise<AddBoxResult>;
+export declare function inspectAddBox(db: AbstractPowerSyncDatabase, input: AddBoxInput): Promise<InspectAddBoxResult>;