@dinoxx/dinox-cli 1.0.18 → 1.0.19

package/dist/commands/sync.d.ts

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

package/dist/commands/sync.js

@@ -1,18 +1,30 @@
 import { loadConfig } from '../config/store.js';
 import { resolveConfig } from '../config/resolve.js';
-import { printYaml } from '../utils/output.js';
+import { registerStandaloneCommand } from './descriptor/register.js';
+import { FORMAT_OPTIONS, SYNC_TIMEOUT_OPTIONS } from './schema/globalOptions.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../utils/output.js';
 import { parseSyncTimeoutMs } from '../utils/syncTimeout.js';
 import { connectPowerSync, getStatusSnapshot } from '../powersync/runtime.js';
 import { runSingleSyncPass } from '../powersync/syncPass.js';
-export function registerSyncCommand(program) {
-    program
-        .command('sync')
-        .description('Connect and synchronize local PowerSync database')
-        .action(async (_options, command) => {
+export const syncCommandDescriptor = {
+    name: 'sync',
+    description: 'Connect and synchronize the local PowerSync database',
+    schema: {
+        path: 'sync',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: [...FORMAT_OPTIONS, ...SYNC_TIMEOUT_OPTIONS],
+        output: {
+            type: 'structured',
+            summary: 'Sync result with connection status and token index counters',
+            fields: ['dbPath', 'stale', 'idle', 'uploadEnabled', 'tokenIndex', 'status'],
+        },
+        examples: ['dino sync --format json', 'dino sync --sync-timeout 600000 --format json'],
+    },
+    action: async (context) => {
         const config = resolveConfig(await loadConfig());
-        const globals = command.optsWithGlobals?.() ?? {};
-        const jsonOutput = Boolean(globals.json);
-        const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
+        const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+        const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? config.sync.timeoutMs;
         const { db, dbPath, stale } = await connectPowerSync({
             config,
             offline: false,
@@ -30,28 +42,30 @@ export function registerSyncCommand(program) {
                 tokenIndex: syncPass.tokenIndex,
                 status,
             };
-            if (jsonOutput) {
-                printYaml(payload);
+            if (structuredOutput) {
+                printSuccess(payload);
+                return;
+            }
+            printHumanReadableLine(`db: ${payload.dbPath}`);
+            if (!payload.uploadEnabled) {
+                printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset)');
+            }
+            if (payload.status.lastSyncedAt) {
+                printHumanReadableLine(`lastSyncedAt: ${payload.status.lastSyncedAt}`);
             }
-            else {
-                console.log(`db: ${payload.dbPath}`);
-                if (!payload.uploadEnabled) {
-                    console.log('warning: upload disabled (powersync.uploadBaseUrl is unset)');
-                }
-                if (payload.status.lastSyncedAt) {
-                    console.log(`lastSyncedAt: ${payload.status.lastSyncedAt}`);
-                }
-                if (payload.stale) {
-                    console.log('warning: sync timed out; local cache may be stale');
-                }
-                if (!payload.idle) {
-                    console.log('warning: data flow did not become idle before timeout');
-                }
-                console.log(`tokenIndex: scanned=${payload.tokenIndex.scanned} reindexed=${payload.tokenIndex.reindexed} skipped=${payload.tokenIndex.skipped} removed=${payload.tokenIndex.removed} ftsRowsUpserted=${payload.tokenIndex.ftsRowsUpserted}`);
+            if (payload.stale) {
+                printHumanReadableLine('warning: sync timed out; local cache may be stale');
             }
+            if (!payload.idle) {
+                printHumanReadableLine('warning: data flow did not become idle before timeout');
+            }
+            printHumanReadableLine(`tokenIndex: scanned=${payload.tokenIndex.scanned} reindexed=${payload.tokenIndex.reindexed} skipped=${payload.tokenIndex.skipped} removed=${payload.tokenIndex.removed} ftsRowsUpserted=${payload.tokenIndex.ftsRowsUpserted}`);
         }
         finally {
             await db.close().catch(() => undefined);
         }
-    });
+    },
+};
+export function registerSyncCommand(program) {
+    registerStandaloneCommand(program, syncCommandDescriptor);
 }

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

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

package/dist/commands/tags/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 { addTag, listTags } from './repo.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { buildTagAddDryRunPreview } 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 { addTag, inspectAddTag, listTags } from './repo.js';
+const TAG_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function syncBeforeTagCommand(db, offline, timeoutMs) {
     if (offline) {
         return;
@@ -14,98 +19,135 @@ async function syncBeforeTagCommand(db, offline, timeoutMs) {
     await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
     await syncNoteTokenIndex(db);
 }
-async function runTagListCommand(options, command) {
-    const globals = command.optsWithGlobals?.() ?? {};
-    const offline = Boolean(options.offline ?? globals.offline);
-    const jsonOutput = Boolean(options.json ?? globals.json);
-    const config = resolveConfig(await loadConfig());
-    const timeoutMs = parseSyncTimeoutMs(options.syncTimeout ?? globals.syncTimeout) ?? config.sync.timeoutMs;
+async function withTagDb(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 runTagList(context) {
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withTagDb(context, async ({ db, offline, timeoutMs, stale }) => {
         await syncBeforeTagCommand(db, offline, timeoutMs);
         const tags = await listTags(db);
-        if (jsonOutput) {
-            printYaml({ stale, count: tags.length, tags });
+        if (structuredOutput) {
+            printSuccess({ stale, count: tags.length, tags });
             return;
         }
         if (stale && !offline) {
-            console.log('warning: sync timed out; results may be stale');
+            printHumanReadableLine('warning: sync timed out; results may be stale');
         }
         if (tags.length === 0) {
-            console.log('No tags.');
+            printHumanReadableLine('No tags.');
             return;
         }
         for (const tag of tags) {
-            console.log(tag);
+            printHumanReadableLine(tag);
         }
+    });
+}
+async function runTagAdd(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('Tag name is required. Use `dino tag add <name>` or `dino tag add --name <name>`.');
     }
-    finally {
-        await db.close().catch(() => undefined);
+    if (nameArg && optionName && nameArg.trim() !== optionName.trim()) {
+        throw new DinoxError('Conflicting tag name values from positional argument and --name option.');
     }
-}
-export function registerTagsCommand(program) {
-    const tag = program.command('tag').description('Manage tags');
-    tag
-        .command('list')
-        .description('List tags from c_tag_node')
-        .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(runTagListCommand);
-    tag
-        .command('add')
-        .description('Create a new tag in c_tag_node')
-        .argument('[name]', 'tag name/path (supports slash hierarchy)')
-        .option('--name <string>', 'tag name/path (alternative to positional name)')
-        .option('--emoji <string>', 'tag emoji')
-        .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('Tag name is required. Use `dino tag add <name>` or `dino tag add --name <name>`.');
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withTagDb(context, async ({ db, config, rawConfig, offline, timeoutMs, stale }) => {
+        const identity = await resolveAuthIdentity(rawConfig, config);
+        await syncBeforeTagCommand(db, offline, timeoutMs);
+        const emoji = typeof context.options.emoji === 'string' ? context.options.emoji : undefined;
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildTagAddDryRunPreview({
+                config,
+                offline,
+                ...(await inspectAddTag(db, {
+                    name,
+                    userId: identity.userId,
+                    emoji,
+                })),
+            }));
+            return;
         }
-        if (nameArg && optionName && nameArg.trim() !== optionName.trim()) {
-            throw new DinoxError('Conflicting tag name values from positional argument and --name option.');
+        const result = await addTag(db, {
+            name,
+            userId: identity.userId,
+            emoji,
+        });
+        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 syncBeforeTagCommand(db, offline, timeoutMs);
-            const result = await addTag(db, {
-                name,
-                userId: identity.userId,
-                emoji: typeof options.emoji === 'string' ? options.emoji : 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');
         }
     });
-    tag.action((_options, command) => {
-        command.outputHelp();
-    });
+}
+export const tagCommandGroup = {
+    name: 'tag',
+    description: 'Manage tags',
+    commands: [
+        {
+            name: 'list',
+            description: 'List all tags from c_tag_node',
+            schema: {
+                path: 'tag.list',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag list payload',
+                    fields: ['count', 'tags', 'stale'],
+                },
+                examples: ['dino tag list --format json'],
+            },
+            action: runTagList,
+        },
+        {
+            name: 'add',
+            description: 'Create a tag path, restoring deleted nodes when possible',
+            arguments: [{ syntax: '[name]', description: 'Tag name/path (supports slash hierarchy)' }],
+            options: [
+                { flags: '--name <string>', description: 'Tag name/path (alternative to positional name)' },
+                { flags: '--emoji <string>', description: 'Tag emoji' },
+                { flags: '--dry-run', description: 'Preview the write without executing it' },
+            ],
+            schema: {
+                path: 'tag.add',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag creation acknowledgement',
+                    fields: ['id', 'tag', 'createdNodes', 'restoredNodes', 'stale'],
+                },
+                examples: ['dino tag add "work/projects" --format json --dry-run', 'dino tag add "work/projects" --emoji "🏷️" --format json'],
+            },
+            action: runTagAdd,
+        },
+    ],
+};
+export function registerTagsCommand(program) {
+    registerCommandGroup(program, tagCommandGroup);
 }

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

@@ -10,5 +10,12 @@ export type AddTagResult = {
     createdNodes: number;
     restoredNodes: number;
 };
+export type InspectAddTagResult = {
+    tag: string;
+    createdPaths: string[];
+    restoredPaths: string[];
+    emoji: string;
+};
 export declare function listTags(db: AbstractPowerSyncDatabase): Promise<string[]>;
 export declare function addTag(db: AbstractPowerSyncDatabase, input: AddTagInput): Promise<AddTagResult>;
+export declare function inspectAddTag(db: AbstractPowerSyncDatabase, input: AddTagInput): Promise<InspectAddTagResult>;

package/dist/commands/tags/repo.js

@@ -245,3 +245,55 @@ export async function addTag(db, input) {
         restoredNodes,
     };
 }
+export async function inspectAddTag(db, input) {
+    const userId = input.userId.trim();
+    const emoji = typeof input.emoji === 'string' ? input.emoji.trim() : '';
+    const tag = canonicalizeTagPath(input.name);
+    if (!tag) {
+        throw new DinoxError('Tag name is required');
+    }
+    const columnNames = await getTagNodeColumns(db);
+    if (!columnNames.has('id')) {
+        throw new DinoxError('c_tag_node table is missing required column: id');
+    }
+    if (!columnNames.has('full_path') && !columnNames.has('path_key')) {
+        throw new DinoxError('c_tag_node table is missing required column: full_path or path_key');
+    }
+    const requiredUserColumns = ['user_id'].filter((column) => columnNames.has(column));
+    if (requiredUserColumns.length > 0 && !userId) {
+        throw new DinoxError(`c_tag_node insert requires ${requiredUserColumns.join(', ')}. Missing persisted userId. Run \`dino auth login\` first.`);
+    }
+    const nodesByPath = await loadTagNodes(db, columnNames);
+    const existingLeaf = nodesByPath.get(tag);
+    if (existingLeaf && existingLeaf.isDel !== 1 && existingLeaf.isActual === 1) {
+        throw new DinoxError(`Tag already exists: ${tag}`, {
+            details: {
+                type: 'tag_exists',
+                tag,
+                id: existingLeaf.id,
+                question: 'This tag already exists. Do you want to keep using the existing tag?',
+            },
+        });
+    }
+    const segments = tag.split('/');
+    const createdPaths = [];
+    const restoredPaths = [];
+    for (let i = 0; i < segments.length; i += 1) {
+        const path = segments.slice(0, i + 1).join('/');
+        const isLeaf = i === segments.length - 1;
+        const existing = nodesByPath.get(path);
+        if (!existing) {
+            createdPaths.push(path);
+            continue;
+        }
+        if (existing.isDel === 1 || (isLeaf && existing.isActual !== 1)) {
+            restoredPaths.push(path);
+        }
+    }
+    return {
+        tag,
+        createdPaths,
+        restoredPaths,
+        emoji,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { ResolvedDinoxConfig } from '../../config/types.js';
+import type { DryRunPreview } from '../../utils/dryRun.js';
+export declare function buildTodoAppendDryRunPreview(args: {
+    db: AbstractPowerSyncDatabase;
+    config: ResolvedDinoxConfig;
+    offline: boolean;
+    noteId?: string;
+    taskTexts: string[];
+}): Promise<DryRunPreview>;
+export declare function buildTodoCreateDryRunPreview(args: {
+    config: ResolvedDinoxConfig;
+    offline: boolean;
+    title?: string;
+    taskTexts: string[];
+}): Promise<DryRunPreview>;
+export declare function buildTodoUpdateDryRunPreview(args: {
+    db: AbstractPowerSyncDatabase;
+    config: ResolvedDinoxConfig;
+    offline: boolean;
+    taskId: string;
+    checked: boolean;
+}): Promise<DryRunPreview>;

package/dist/commands/todo/dryRun.js

@@ -0,0 +1,133 @@
+import { DinoxError } from '../../utils/errors.js';
+import { applyTaskCheckedStatus, buildSummaryTitle, normalizeTaskTexts, parseTiptapDocFromDb, } from './contentModel.js';
+import { getLatestTodoAppendTarget, getTodoAppendTargetById, loadTodoTaskCandidatesByTaskId, } from './repo.js';
+function buildExecutionWarnings(config, offline) {
+    const warnings = [];
+    if (offline) {
+        warnings.push('Execution would run in offline mode and only use the local cache.');
+    }
+    if (!offline && !config.powersync.uploadBaseUrl) {
+        warnings.push('Execution would be local-only because powersync.uploadBaseUrl is unset.');
+    }
+    return warnings;
+}
+export async function buildTodoAppendDryRunPreview(args) {
+    const normalizedTaskTexts = normalizeTaskTexts(args.taskTexts);
+    const explicitNoteId = typeof args.noteId === 'string' ? args.noteId.trim() : '';
+    const source = explicitNoteId ? 'explicit' : 'latest_non_empty_image_detail';
+    const target = explicitNoteId
+        ? await getTodoAppendTargetById(args.db, explicitNoteId)
+        : await getLatestTodoAppendTarget(args.db);
+    if (!target) {
+        if (explicitNoteId) {
+            throw new DinoxError(`Note not found: ${explicitNoteId}`);
+        }
+        throw new DinoxError('No eligible note found for append. Try `dino todo create ...` first.');
+    }
+    return {
+        dry_run: true,
+        command: 'dino todo append',
+        action: 'append_todo_tasks',
+        risk: 'write',
+        summary: `Append ${normalizedTaskTexts.length} task(s) to note "${(target.title ?? '').trim()}".`,
+        warnings: buildExecutionWarnings(args.config, args.offline),
+        inputs: {
+            note_id: explicitNoteId || null,
+            source,
+            task_count: normalizedTaskTexts.length,
+            task_texts: normalizedTaskTexts,
+        },
+        targets: [
+            {
+                id: target.id,
+                title: (target.title ?? '').trim(),
+                source,
+            },
+        ],
+        changes: {
+            appended_count: normalizedTaskTexts.length,
+            task_texts: normalizedTaskTexts,
+        },
+    };
+}
+export async function buildTodoCreateDryRunPreview(args) {
+    const normalizedTaskTexts = normalizeTaskTexts(args.taskTexts);
+    const resolvedTitle = args.title?.trim() || buildSummaryTitle(normalizedTaskTexts);
+    return {
+        dry_run: true,
+        command: 'dino todo create',
+        action: 'create_todo_note',
+        risk: 'write',
+        summary: `Create a new todo note titled "${resolvedTitle}" with ${normalizedTaskTexts.length} task(s).`,
+        warnings: buildExecutionWarnings(args.config, args.offline),
+        inputs: {
+            title: resolvedTitle,
+            task_count: normalizedTaskTexts.length,
+            task_texts: normalizedTaskTexts,
+        },
+        changes: {
+            title: resolvedTitle,
+            created_count: normalizedTaskTexts.length,
+            task_texts: normalizedTaskTexts,
+        },
+    };
+}
+export async function buildTodoUpdateDryRunPreview(args) {
+    const taskId = args.taskId.trim();
+    if (!taskId) {
+        throw new DinoxError('taskId is required');
+    }
+    const candidates = await loadTodoTaskCandidatesByTaskId(args.db, taskId);
+    const matches = [];
+    for (const candidate of candidates) {
+        try {
+            const doc = parseTiptapDocFromDb(candidate.content_json);
+            const applied = applyTaskCheckedStatus(doc, taskId, args.checked);
+            if (applied.matchedIndices.length === 0) {
+                continue;
+            }
+            const noteId = (candidate.id ?? '').trim();
+            if (!noteId) {
+                continue;
+            }
+            matches.push({
+                noteId,
+                title: (candidate.title ?? '').trim(),
+                checked: applied.changedCount > 0 ? !args.checked : args.checked,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    if (matches.length === 0) {
+        throw new DinoxError(`Task not found: ${taskId}`);
+    }
+    if (matches.length > 1) {
+        throw new DinoxError(`Task id is not unique; found in multiple notes: ${matches.map((item) => item.noteId).join(', ')}`);
+    }
+    const match = matches[0];
+    return {
+        dry_run: true,
+        command: 'dino todo update',
+        action: 'update_todo_status',
+        risk: 'write',
+        summary: `Mark task ${taskId} as ${args.checked ? 'completed' : 'uncompleted'} in note "${match.title}".`,
+        warnings: buildExecutionWarnings(args.config, args.offline),
+        inputs: {
+            task_id: taskId,
+            status_to: args.checked ? 'completed' : 'uncompleted',
+        },
+        targets: [
+            {
+                note_id: match.noteId,
+                title: match.title,
+            },
+        ],
+        changes: {
+            checked_from: match.checked,
+            checked_to: args.checked,
+            updated: match.checked !== args.checked,
+        },
+    };
+}

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

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