@dinoxx/dinox-cli 1.0.17 → 1.0.19

package/dist/commands/boxes/repo.js

@@ -152,3 +152,44 @@ export async function addBox(db, input) {
         restored: false,
     };
 }
+export async function inspectAddBox(db, input) {
+    const userId = input.userId.trim();
+    const name = normalizeName(input.name);
+    if (!name) {
+        throw new DinoxError('Box name is required');
+    }
+    const description = normalizeName(input.description ?? '');
+    const color = normalizeName(input.color ?? '');
+    const lookup = normalizeLookup(name);
+    const columnNames = await getBoxColumns(db);
+    const requiredColumns = ['id', 'name', 'user_no'];
+    const missingRequired = requiredColumns.filter((column) => !columnNames.has(column));
+    if (missingRequired.length > 0) {
+        throw new DinoxError(`c_zettel_box table is missing required columns: ${missingRequired.join(', ')}`);
+    }
+    if (!userId) {
+        throw new DinoxError('c_zettel_box insert requires user_no. Missing persisted userId. Run `dino auth login` first.');
+    }
+    const rows = await listBoxRowsForWrite(db);
+    const sameNameRows = rows.filter((row) => normalizeLookup(row.name ?? '') === lookup);
+    const activeRows = sameNameRows.filter((row) => row.is_del !== 1);
+    if (activeRows.length > 0) {
+        const ids = activeRows.map((row) => row.id?.trim() ?? '').filter(Boolean);
+        throw new DinoxError(`Zettel box already exists: ${name}`, {
+            details: {
+                type: 'box_exists',
+                name,
+                ids,
+                question: 'This box already exists. Do you want to keep using the existing box?',
+            },
+        });
+    }
+    const deletedRow = sameNameRows.find((row) => (row.id?.trim() ?? '').length > 0);
+    return {
+        name,
+        description,
+        color,
+        restored: Boolean(deletedRow?.id),
+        ...(deletedRow?.id ? { existingId: deletedRow.id } : {}),
+    };
+}

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

@@ -1,3 +1,5 @@
 import { Command } from 'commander';
+import type { CommandGroupDescriptor } from '../descriptor/types.js';
 export declare function sanitizeConfigForDisplay(config: unknown): unknown;
+export declare const configCommandGroup: CommandGroupDescriptor;
 export declare function registerConfigCommands(program: Command): void;

package/dist/commands/config/index.js

@@ -1,8 +1,10 @@
 import { isConfigKey, isFixedConfigKey, isReadableConfigKey } from '../../config/keys.js';
 import { getConfigValue, setConfigValue } from '../../config/store.js';
-import { redactAuthorization } from '../../utils/redact.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS } from '../schema/globalOptions.js';
 import { DinoxError } from '../../utils/errors.js';
-import { printYaml } from '../../utils/output.js';
+import { getRequestedStructuredOutputFormat, printSuccess } from '../../utils/output.js';
+import { redactAuthorization } from '../../utils/redact.js';
 export function sanitizeConfigForDisplay(config) {
     if (!config || typeof config !== 'object' || Array.isArray(config)) {
         return config;
@@ -15,40 +17,87 @@ export function sanitizeConfigForDisplay(config) {
     delete clone.powersync;
     return clone;
 }
-export function registerConfigCommands(program) {
-    const configCmd = program.command('config').description('Read and write Dinox configuration');
-    configCmd
-        .command('get')
-        .description('Get configuration value')
-        .argument('[key]', 'config key (dot path)')
-        .action(async (key) => {
-        if (key && !isReadableConfigKey(key)) {
-            throw new DinoxError(`Unknown config key: ${key}`);
-        }
-        const value = await getConfigValue(key);
-        const redacted = key ? value : sanitizeConfigForDisplay(value);
-        printYaml(redacted);
-    });
-    configCmd
-        .command('set')
-        .description('Set configuration value')
-        .argument('<key>', 'config key (dot path)')
-        .argument('<value>', 'value')
-        .action(async (key, value) => {
-        if (isFixedConfigKey(key)) {
-            throw new DinoxError(`${key} is fixed and cannot be changed`);
-        }
-        if (!isConfigKey(key)) {
-            throw new DinoxError(`Unknown config key: ${key}`);
+async function runConfigGet(context) {
+    const key = context.args.key;
+    if (key && !isReadableConfigKey(key)) {
+        throw new DinoxError(`Unknown config key: ${key}`);
+    }
+    const value = await getConfigValue(key);
+    printSuccess(key ? value : sanitizeConfigForDisplay(value));
+}
+async function runConfigSet(context) {
+    const key = context.args.key;
+    const value = context.args.value;
+    if (!key || value === undefined) {
+        throw new DinoxError('Config key and value are required');
+    }
+    if (isFixedConfigKey(key)) {
+        throw new DinoxError(`${key} is fixed and cannot be changed`);
+    }
+    if (!isConfigKey(key)) {
+        throw new DinoxError(`Unknown config key: ${key}`);
+    }
+    if (key === 'sync.timeoutMs') {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new DinoxError('sync.timeoutMs must be a positive integer');
         }
-        if (key === 'sync.timeoutMs') {
-            const parsed = Number(value);
-            if (!Number.isFinite(parsed) || parsed <= 0) {
-                throw new DinoxError('sync.timeoutMs must be a positive integer');
-            }
-            await setConfigValue(key, Math.trunc(parsed));
-            return;
+        await setConfigValue(key, Math.trunc(parsed));
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, key, value: Math.trunc(parsed) });
         }
-        await setConfigValue(key, value);
-    });
+        return;
+    }
+    await setConfigValue(key, value);
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ ok: true, key, value });
+    }
+}
+export const configCommandGroup = {
+    name: 'config',
+    description: 'Read and write Dinox configuration',
+    commands: [
+        {
+            name: 'get',
+            description: 'Read sanitized Dinox CLI configuration values',
+            arguments: [{ syntax: '[key]', description: 'Optional config key (dot path)' }],
+            schema: {
+                path: 'config.get',
+                risk: 'read',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Requested config value or sanitized config object',
+                    fields: ['sync.timeoutMs', 'auth'],
+                },
+                examples: ['dino config get --format json', 'dino config get sync.timeoutMs --format json'],
+            },
+            action: runConfigGet,
+        },
+        {
+            name: 'set',
+            description: 'Write configurable Dinox CLI settings',
+            arguments: [
+                { syntax: '<key>', description: 'Config key (dot path)' },
+                { syntax: '<value>', description: 'Config value' },
+            ],
+            schema: {
+                path: 'config.set',
+                risk: 'write',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Config write acknowledgement',
+                    fields: ['key', 'value'],
+                },
+                examples: ['dino config set sync.timeoutMs 20000 --format json'],
+            },
+            action: runConfigSet,
+        },
+    ],
+};
+export function registerConfigCommands(program) {
+    registerCommandGroup(program, configCommandGroup);
 }

package/dist/commands/descriptor/register.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+import type { CommandSchema } from '../schema/types.js';
+import type { CommandDescriptor, CommandGroupDescriptor } from './types.js';
+export declare function registerCommandGroup(program: Command, group: CommandGroupDescriptor): Command;
+export declare function registerStandaloneCommand(program: Command, descriptor: CommandDescriptor): Command;
+export declare function commandSchemaFromDescriptor(groupName: string, descriptor: CommandDescriptor): CommandSchema;
+export declare function commandSchemasFromGroupDescriptor(group: CommandGroupDescriptor): CommandSchema[];
+export declare function standaloneCommandSchemaFromDescriptor(descriptor: CommandDescriptor): CommandSchema;

package/dist/commands/descriptor/register.js

@@ -0,0 +1,113 @@
+import { toSchemaArgument, toSchemaOption } from './types.js';
+function deriveArgumentKey(syntax) {
+    const normalized = syntax.trim().replace(/^[<[.]+|[>\].]+$/g, '');
+    return normalized.replace(/[-_]+([a-zA-Z0-9])/g, (_match, segment) => segment.toUpperCase());
+}
+function addArgument(command, argument) {
+    command.argument(argument.syntax, argument.description);
+}
+function addOption(command, option) {
+    if (option.required) {
+        if (option.parser && option.defaultValue !== undefined) {
+            command.requiredOption(option.flags, option.description, option.parser, option.defaultValue);
+            return;
+        }
+        if (option.parser) {
+            command.requiredOption(option.flags, option.description, option.parser);
+            return;
+        }
+        if (option.defaultValue !== undefined) {
+            command.requiredOption(option.flags, option.description, option.defaultValue);
+            return;
+        }
+        command.requiredOption(option.flags, option.description);
+        return;
+    }
+    if (option.parser && option.defaultValue !== undefined) {
+        command.option(option.flags, option.description, option.parser, option.defaultValue);
+        return;
+    }
+    if (option.parser) {
+        command.option(option.flags, option.description, option.parser);
+        return;
+    }
+    if (option.defaultValue !== undefined) {
+        command.option(option.flags, option.description, option.defaultValue);
+        return;
+    }
+    command.option(option.flags, option.description);
+}
+function buildExecutionContext(command, descriptors, values) {
+    const namedArgs = Object.fromEntries(descriptors.map((descriptor, index) => [deriveArgumentKey(descriptor.syntax), values[index]]));
+    return {
+        command,
+        globals: (command.optsWithGlobals?.() ?? {}),
+        options: (command.opts() ?? {}),
+        args: namedArgs,
+    };
+}
+export function registerCommandGroup(program, group) {
+    const parent = program.command(group.name).description(group.description);
+    for (const descriptor of group.commands) {
+        const subcommand = parent.command(descriptor.name).description(descriptor.description);
+        const argumentsList = descriptor.arguments ?? [];
+        for (const argument of argumentsList) {
+            addArgument(subcommand, argument);
+        }
+        for (const option of descriptor.options ?? []) {
+            addOption(subcommand, option);
+        }
+        subcommand.action(async (...actionArgs) => {
+            const command = actionArgs[actionArgs.length - 1];
+            const positionalValues = actionArgs.slice(0, argumentsList.length);
+            await descriptor.action(buildExecutionContext(command, argumentsList, positionalValues));
+        });
+    }
+    parent.action((_options, command) => {
+        command.outputHelp();
+    });
+    return parent;
+}
+function buildCommandInvocation(groupName, descriptor) {
+    return `dino ${groupName} ${descriptor.name}`.trimEnd();
+}
+function registerCommandDescriptor(command, descriptor) {
+    const argumentsList = descriptor.arguments ?? [];
+    for (const argument of argumentsList) {
+        addArgument(command, argument);
+    }
+    for (const option of descriptor.options ?? []) {
+        addOption(command, option);
+    }
+    command.action(async (...actionArgs) => {
+        const currentCommand = actionArgs[actionArgs.length - 1];
+        const positionalValues = actionArgs.slice(0, argumentsList.length);
+        await descriptor.action(buildExecutionContext(currentCommand, argumentsList, positionalValues));
+    });
+    return command;
+}
+export function registerStandaloneCommand(program, descriptor) {
+    const command = program.command(descriptor.name).description(descriptor.description);
+    return registerCommandDescriptor(command, descriptor);
+}
+export function commandSchemaFromDescriptor(groupName, descriptor) {
+    return {
+        ...descriptor.schema,
+        command: buildCommandInvocation(groupName, descriptor),
+        summary: descriptor.description,
+        ...(descriptor.arguments?.length ? { arguments: descriptor.arguments.map(toSchemaArgument) } : {}),
+        ...(descriptor.options?.length ? { options: descriptor.options.map(toSchemaOption) } : {}),
+    };
+}
+export function commandSchemasFromGroupDescriptor(group) {
+    return group.commands.map((descriptor) => commandSchemaFromDescriptor(group.name, descriptor));
+}
+export function standaloneCommandSchemaFromDescriptor(descriptor) {
+    return {
+        ...descriptor.schema,
+        command: `dino ${descriptor.name}`,
+        summary: descriptor.description,
+        ...(descriptor.arguments?.length ? { arguments: descriptor.arguments.map(toSchemaArgument) } : {}),
+        ...(descriptor.options?.length ? { options: descriptor.options.map(toSchemaOption) } : {}),
+    };
+}

package/dist/commands/descriptor/types.d.ts

@@ -0,0 +1,37 @@
+import type { Command } from 'commander';
+import type { CommandSchema, CommandSchemaArgument, CommandSchemaOption } from '../schema/types.js';
+export type CommandOptionDescriptor = {
+    flags: string;
+    description: string;
+    type?: 'string' | 'number' | 'boolean' | 'string[]';
+    required?: boolean;
+    parser?: (value: string, previous: unknown) => unknown;
+    defaultValue?: unknown;
+    enum?: string[];
+};
+export type CommandArgumentDescriptor = {
+    syntax: string;
+    description: string;
+};
+export type CommandExecutionContext = {
+    command: Command;
+    globals: Record<string, unknown>;
+    options: Record<string, unknown>;
+    args: Record<string, string | undefined>;
+};
+export type CommandDescriptorSchema = Omit<CommandSchema, 'command' | 'summary' | 'arguments' | 'options'>;
+export type CommandDescriptor = {
+    name: string;
+    description: string;
+    arguments?: CommandArgumentDescriptor[];
+    options?: CommandOptionDescriptor[];
+    schema: CommandDescriptorSchema;
+    action: (context: CommandExecutionContext) => Promise<void> | void;
+};
+export type CommandGroupDescriptor = {
+    name: string;
+    description: string;
+    commands: CommandDescriptor[];
+};
+export declare function toSchemaArgument(argument: CommandArgumentDescriptor): CommandSchemaArgument;
+export declare function toSchemaOption(option: CommandOptionDescriptor): CommandSchemaOption;

package/dist/commands/descriptor/types.js

@@ -0,0 +1,17 @@
+export function toSchemaArgument(argument) {
+    return {
+        name: argument.syntax,
+        required: argument.syntax.trim().startsWith('<'),
+        description: argument.description,
+    };
+}
+export function toSchemaOption(option) {
+    return {
+        name: option.flags,
+        description: option.description,
+        ...(option.type ? { type: option.type } : {}),
+        ...(option.required ? { required: true } : {}),
+        ...(option.defaultValue !== undefined ? { defaultValue: option.defaultValue } : {}),
+        ...(option.enum ? { enum: option.enum } : {}),
+    };
+}

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

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

package/dist/commands/graph/index.js

@@ -1,12 +1,15 @@
-import { printYaml } from '../../utils/output.js';
-import { sendDaemonRequest } from '../../daemon/client.js';
-import { ensureDaemonRunning } from '../../daemon/ensure.js';
-import { DinoxError } from '../../utils/errors.js';
 import { loadConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
 import { connectPowerSync } from '../../powersync/runtime.js';
+import { sendDaemonRequest } from '../../daemon/client.js';
+import { ensureDaemonRunning } from '../../daemon/ensure.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { DinoxError } from '../../utils/errors.js';
+import { printSuccess } from '../../utils/output.js';
 import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
 import { getBacklinks, getGraphStats, getOutlinks, getRelatedNotes } from './repo.js';
+const GRAPH_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 function parseDepth(value) {
     if (value === undefined || value === null || value === '') {
         return 2;
@@ -26,8 +29,7 @@ function parseDepth(value) {
 }
 async function withOfflineDb(command, fn) {
     const globals = command.optsWithGlobals?.() ?? {};
-    const offline = Boolean(globals.offline);
-    if (!offline) {
+    if (!Boolean(globals.offline)) {
         throw new DinoxError('withOfflineDb called without --offline');
     }
     const config = resolveConfig(await loadConfig());
@@ -40,74 +42,142 @@ async function withOfflineDb(command, fn) {
         await db.close().catch(() => undefined);
     }
 }
-export function registerGraphCommands(program) {
-    const graph = program.command('graph').description('Query knowledge graph');
-    graph
-        .command('backlinks')
-        .description('Get notes that link to this note')
-        .argument('<id>', 'note id')
-        .action(async (id, _options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        if (offline) {
-            const result = await withOfflineDb(command, (db) => getBacklinks(db, id));
-            printYaml(result);
-            return;
-        }
-        await ensureDaemonRunning();
-        const result = await sendDaemonRequest('graph.backlinks', { id });
-        printYaml(result);
-    });
-    graph
-        .command('outlinks')
-        .description('Get notes that this note links to')
-        .argument('<id>', 'note id')
-        .action(async (id, _options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        if (offline) {
-            const result = await withOfflineDb(command, (db) => getOutlinks(db, id));
-            printYaml(result);
-            return;
+async function runGraphCommand(context, onlineAction, offlineAction) {
+    const globals = context.globals;
+    if (Boolean(globals.offline)) {
+        printSuccess(await withOfflineDb(context.command, offlineAction));
+        return;
+    }
+    await ensureDaemonRunning();
+    printSuccess(await onlineAction());
+}
+const graphBacklinksCommand = {
+    name: 'backlinks',
+    description: 'Get notes that link to a target note',
+    arguments: [{ syntax: '<id>', description: 'Note id' }],
+    schema: {
+        path: 'graph.backlinks',
+        risk: 'read',
+        auth: 'required',
+        globalOptions: GRAPH_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Backlink graph payload',
+            fields: ['note_id', 'backlinks'],
+        },
+        mcp: {
+            toolName: 'dinox_graph_backlinks',
+            description: 'Get notes that link to this note',
+            properties: [{ name: 'id', type: 'string', description: 'Note ID', required: true }],
+        },
+        examples: ['dino graph backlinks <id> --format json'],
+    },
+    action: async (context) => {
+        const id = context.args.id;
+        if (!id) {
+            throw new DinoxError('Note id is required');
         }
-        await ensureDaemonRunning();
-        const result = await sendDaemonRequest('graph.outlinks', { id });
-        printYaml(result);
-    });
-    graph
-        .command('stats')
-        .description('Get graph statistics')
-        .action(async (_options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        if (offline) {
-            const result = await withOfflineDb(command, (db) => getGraphStats(db));
-            printYaml(result);
-            return;
+        await runGraphCommand(context, () => sendDaemonRequest('graph.backlinks', { id }), (db) => getBacklinks(db, id));
+    },
+};
+const graphOutlinksCommand = {
+    name: 'outlinks',
+    description: 'Get notes that this note links to',
+    arguments: [{ syntax: '<id>', description: 'Note id' }],
+    schema: {
+        path: 'graph.outlinks',
+        risk: 'read',
+        auth: 'required',
+        globalOptions: GRAPH_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Outlink graph payload',
+            fields: ['note_id', 'outlinks'],
+        },
+        mcp: {
+            toolName: 'dinox_graph_outlinks',
+            description: 'Get notes that this note links to',
+            properties: [{ name: 'id', type: 'string', description: 'Note ID', required: true }],
+        },
+        examples: ['dino graph outlinks <id> --format json'],
+    },
+    action: async (context) => {
+        const id = context.args.id;
+        if (!id) {
+            throw new DinoxError('Note id is required');
         }
-        await ensureDaemonRunning();
-        const result = await sendDaemonRequest('graph.stats');
-        printYaml(result);
-    });
-    graph
-        .command('related')
-        .description('Get related notes within N degrees of separation')
-        .argument('<id>', 'note id')
-        .option('--depth <n>', 'degrees of separation (1-5, default: 2)')
-        .action(async (id, options, command) => {
-        const depth = parseDepth(options.depth);
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(globals.offline);
-        if (offline) {
-            const result = await withOfflineDb(command, (db) => getRelatedNotes(db, id, depth));
-            printYaml(result);
-            return;
+        await runGraphCommand(context, () => sendDaemonRequest('graph.outlinks', { id }), (db) => getOutlinks(db, id));
+    },
+};
+const graphRelatedCommand = {
+    name: 'related',
+    description: 'Get notes related within N degrees of separation',
+    arguments: [{ syntax: '<id>', description: 'Note id' }],
+    options: [{ flags: '--depth <n>', description: 'Degrees of separation (1-5)', defaultValue: '2' }],
+    schema: {
+        path: 'graph.related',
+        risk: 'read',
+        auth: 'required',
+        globalOptions: GRAPH_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Related-notes graph payload',
+            fields: ['note_id', 'depth', 'related_notes'],
+        },
+        mcp: {
+            toolName: 'dinox_graph_related',
+            description: 'Get related notes within N degrees',
+            properties: [
+                { name: 'id', type: 'string', description: 'Note ID', required: true },
+                { name: 'depth', type: 'number', description: 'Degrees (1-5, default: 2)' },
+            ],
+        },
+        examples: ['dino graph related <id> --depth 2 --format json'],
+    },
+    action: async (context) => {
+        const id = context.args.id;
+        if (!id) {
+            throw new DinoxError('Note id is required');
         }
-        await ensureDaemonRunning();
-        const result = await sendDaemonRequest('graph.related', { id, depth });
-        printYaml(result);
-    });
-    graph.action((_options, command) => {
-        command.outputHelp();
-    });
+        const depth = parseDepth(context.options.depth);
+        await runGraphCommand(context, () => sendDaemonRequest('graph.related', { id, depth }), (db) => getRelatedNotes(db, id, depth));
+    },
+};
+const graphStatsCommand = {
+    name: 'stats',
+    description: 'Get graph statistics for notes and links',
+    schema: {
+        path: 'graph.stats',
+        risk: 'read',
+        auth: 'required',
+        globalOptions: GRAPH_GLOBAL_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Graph statistics payload',
+            entity: 'graph_stats',
+            fields: ['notes_count', 'links_count', 'connected_notes_count', 'isolated_notes_count'],
+        },
+        mcp: {
+            toolName: 'dinox_graph_stats',
+            description: 'Get graph statistics for notes and links',
+            properties: [],
+        },
+        examples: ['dino graph stats --format json'],
+    },
+    action: async (context) => {
+        await runGraphCommand(context, () => sendDaemonRequest('graph.stats'), (db) => getGraphStats(db));
+    },
+};
+export const graphCommandGroup = {
+    name: 'graph',
+    description: 'Query knowledge graph',
+    commands: [
+        graphBacklinksCommand,
+        graphOutlinksCommand,
+        graphRelatedCommand,
+        graphStatsCommand,
+    ],
+};
+export function registerGraphCommands(program) {
+    registerCommandGroup(program, graphCommandGroup);
 }

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

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