@dinoxx/dinox-cli 1.0.18 → 1.0.20

package/dist/commands/prompt/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 { addPrompt, listPrompts } from './repo.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { buildPromptAddDryRunPreview } 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 { addPrompt, inspectAddPrompt, listPrompts } from './repo.js';
+const PROMPT_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 async function syncBeforePromptCommand(db, offline, timeoutMs) {
     if (offline) {
         return;
@@ -14,82 +19,127 @@ async function syncBeforePromptCommand(db, offline, timeoutMs) {
     await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
     await syncNoteTokenIndex(db);
 }
-async function runPromptListCommand(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 withPromptDb(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 syncBeforePromptCommand(db, offline, timeoutMs);
-        const prompts = await listPrompts(db);
-        printYaml(prompts);
+        await run({ db, config, rawConfig, offline, timeoutMs, stale });
     }
     finally {
         await db.close().catch(() => undefined);
     }
 }
-export function registerPromptCommands(program) {
-    const prompt = program.command('prompt').description('Manage prompts');
-    prompt
-        .command('list')
-        .description('List prompts from c_cmd (name and cmd)')
-        .option('--offline', 'skip connect/sync and only use local cache')
-        .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
-        .action(runPromptListCommand);
-    prompt
-        .command('add')
-        .description('Create a new prompt in c_cmd')
-        .option('--name <string>', 'prompt name')
-        .option('--cmd <string>', 'prompt command/prompt text')
-        .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 (options, command) => {
-        const globals = command.optsWithGlobals?.() ?? {};
-        const offline = Boolean(options.offline ?? globals.offline);
-        const jsonOutput = Boolean(options.json ?? globals.json);
-        const name = typeof options.name === 'string' ? options.name.trim() : '';
-        const cmd = typeof options.cmd === 'string' ? options.cmd.trim() : '';
-        if (!name) {
-            throw new DinoxError('Prompt name is required. Use `dino prompt add --name <name> --cmd <cmd>`.');
+async function runPromptList(context) {
+    await withPromptDb(context, async ({ db, offline, timeoutMs }) => {
+        await syncBeforePromptCommand(db, offline, timeoutMs);
+        printSuccess((await listPrompts(db)).map((prompt) => ({
+            name: prompt.name,
+            prompt: prompt.cmd,
+        })));
+    });
+}
+async function runPromptAdd(context) {
+    const name = typeof context.options.name === 'string' ? context.options.name.trim() : '';
+    const cmd = typeof context.options.prompt === 'string' ? context.options.prompt.trim() : '';
+    if (!name) {
+        throw new DinoxError('Prompt name is required. Use `dino prompt add --name <name> --prompt <text>`.');
+    }
+    if (!cmd) {
+        throw new DinoxError('Prompt text is required. Use `dino prompt add --name <name> --prompt <text>`.');
+    }
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    await withPromptDb(context, async ({ db, config, rawConfig, offline, timeoutMs, stale }) => {
+        const identity = await resolveAuthIdentity(rawConfig, config);
+        await syncBeforePromptCommand(db, offline, timeoutMs);
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildPromptAddDryRunPreview({
+                config,
+                offline,
+                ...(await inspectAddPrompt(db, {
+                    name,
+                    cmd,
+                    userId: identity.userId,
+                })),
+            }));
+            return;
         }
-        if (!cmd) {
-            throw new DinoxError('Prompt cmd is required. Use `dino prompt add --name <name> --cmd <cmd>`.');
+        const result = await addPrompt(db, {
+            name,
+            cmd,
+            userId: identity.userId,
+        });
+        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 syncBeforePromptCommand(db, offline, timeoutMs);
-            const result = await addPrompt(db, {
-                name,
-                cmd,
-                userId: identity.userId,
-            });
-            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,
+            id: result.id,
+            name: result.name,
+            prompt: result.cmd,
+            restored: result.restored,
+        };
+        if (structuredOutput) {
+            printSuccess(payload);
+            return;
+        }
+        printHumanReadableLine(result.id);
+        if (stale && !offline) {
+            printHumanReadableLine('warning: sync timed out; results may be stale');
         }
     });
-    prompt.action((_options, command) => {
-        command.outputHelp();
-    });
+}
+export const promptCommandGroup = {
+    name: 'prompt',
+    description: 'Manage prompts',
+    commands: [
+        {
+            name: 'list',
+            description: 'List reusable prompts from c_cmd',
+            schema: {
+                path: 'prompt.list',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: PROMPT_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Prompt list payload',
+                    fields: ['name', 'prompt'],
+                },
+                examples: ['dino prompt list --format json'],
+            },
+            action: runPromptList,
+        },
+        {
+            name: 'add',
+            description: 'Create a prompt template, restoring a deleted prompt when possible',
+            options: [
+                { flags: '--name <string>', description: 'Prompt name', required: true, type: 'string' },
+                { flags: '--prompt <string>', description: 'Prompt text', required: true, type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+            ],
+            schema: {
+                path: 'prompt.add',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROMPT_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Prompt creation acknowledgement',
+                    fields: ['id', 'name', 'prompt', 'restored', 'stale'],
+                },
+                examples: ['dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报" --format json --dry-run'],
+            },
+            action: runPromptAdd,
+        },
+    ],
+};
+export function registerPromptCommands(program) {
+    registerCommandGroup(program, promptCommandGroup);
 }

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

@@ -14,5 +14,12 @@ export type AddPromptResult = {
     cmd: string;
     restored: boolean;
 };
+export type InspectAddPromptResult = {
+    name: string;
+    cmd: string;
+    restored: boolean;
+    existingId?: string;
+};
 export declare function listPrompts(db: AbstractPowerSyncDatabase): Promise<PromptListItem[]>;
 export declare function addPrompt(db: AbstractPowerSyncDatabase, input: AddPromptInput): Promise<AddPromptResult>;
+export declare function inspectAddPrompt(db: AbstractPowerSyncDatabase, input: AddPromptInput): Promise<InspectAddPromptResult>;

package/dist/commands/prompt/repo.js

@@ -162,3 +162,49 @@ export async function addPrompt(db, input) {
         restored: false,
     };
 }
+export async function inspectAddPrompt(db, input) {
+    const name = normalizeText(input.name);
+    if (!name) {
+        throw new DinoxError('Prompt name is required');
+    }
+    const cmd = normalizeText(input.cmd);
+    if (!cmd) {
+        throw new DinoxError('Prompt cmd is required');
+    }
+    const userId = normalizeText(input.userId);
+    const nameLookup = normalizeLookup(name);
+    const cmdLookup = normalizeLookup(cmd);
+    const columnNames = await getPromptColumns(db);
+    const requiredColumns = ['id', 'name', 'cmd'];
+    const missingRequired = requiredColumns.filter((column) => !columnNames.has(column));
+    if (missingRequired.length > 0) {
+        throw new DinoxError(`c_cmd table is missing required columns: ${missingRequired.join(', ')}`);
+    }
+    if (columnNames.has('user_id') && !userId) {
+        throw new DinoxError('c_cmd insert requires user_id. Missing persisted userId. Run `dino auth login` first.');
+    }
+    const rows = await listPromptRowsForWrite(db, columnNames);
+    const samePromptRows = rows.filter((row) => {
+        return normalizeLookup(row.name ?? '') === nameLookup && normalizeLookup(row.cmd ?? '') === cmdLookup;
+    });
+    const activeRows = samePromptRows.filter((row) => row.is_del !== 1);
+    if (activeRows.length > 0) {
+        const ids = activeRows.map((row) => row.id?.trim() ?? '').filter(Boolean);
+        throw new DinoxError(`Prompt already exists: ${name}`, {
+            details: {
+                type: 'prompt_exists',
+                name,
+                cmd,
+                ids,
+                question: 'This prompt already exists. Do you want to keep using the existing prompt?',
+            },
+        });
+    }
+    const deletedRow = samePromptRows.find((row) => (row.id?.trim() ?? '').length > 0);
+    return {
+        name,
+        cmd,
+        restored: Boolean(deletedRow?.id),
+        ...(deletedRow?.id ? { existingId: deletedRow.id } : {}),
+    };
+}

package/dist/commands/schema/commandMetadata.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDescriptor } from '../descriptor/types.js';
+export declare const schemaCommandMetadata: Omit<CommandDescriptor, 'action'>;

package/dist/commands/schema/commandMetadata.js

@@ -0,0 +1,18 @@
+import { FORMAT_OPTIONS } from './globalOptions.js';
+export const schemaCommandMetadata = {
+    name: 'schema',
+    description: 'Inspect Dinox CLI command schemas for agent-friendly usage',
+    arguments: [{ syntax: '[path]', description: 'Command schema path, e.g. note.search or todo.update' }],
+    schema: {
+        path: 'schema',
+        risk: 'read',
+        auth: 'none',
+        globalOptions: FORMAT_OPTIONS,
+        output: {
+            type: 'structured',
+            summary: 'Schema listing or one schema detail payload',
+            fields: ['version', 'commands', 'command'],
+        },
+        examples: ['dino schema', 'dino schema note.search --format json'],
+    },
+};

package/dist/commands/schema/globalOptions.d.ts

@@ -0,0 +1,3 @@
+export declare const FORMAT_OPTIONS: string[];
+export declare const OFFLINE_OPTIONS: string[];
+export declare const SYNC_TIMEOUT_OPTIONS: string[];

package/dist/commands/schema/globalOptions.js

@@ -0,0 +1,3 @@
+export const FORMAT_OPTIONS = ['--format <yaml|json>', '--json'];
+export const OFFLINE_OPTIONS = ['--offline'];
+export const SYNC_TIMEOUT_OPTIONS = ['--sync-timeout <ms>'];

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

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

package/dist/commands/schema/index.js

@@ -0,0 +1,109 @@
+import { registerStandaloneCommand } from '../descriptor/register.js';
+import { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableBlock, printSuccess } from '../../utils/output.js';
+import { findCommandSchema, listCommandSchemas } from './spec.js';
+import { schemaCommandMetadata } from './commandMetadata.js';
+function renderSchemaList(schemas) {
+    const lines = ['Available command schemas:', ''];
+    for (const schema of schemas) {
+        lines.push(`  ${schema.path.padEnd(16)} ${schema.summary}`);
+    }
+    lines.push('');
+    lines.push('Usage: dino schema <path>');
+    return lines.join('\n');
+}
+function renderDetailSection(title, rows) {
+    if (rows.length === 0) {
+        return [];
+    }
+    return [title, ...rows.map((row) => `  ${row}`), ''];
+}
+function formatOptionMetadata(option) {
+    if (!option) {
+        return '';
+    }
+    const metadata = [];
+    if (option.type) {
+        metadata.push(`type=${option.type}`);
+    }
+    if (option.defaultValue !== undefined) {
+        metadata.push(`default=${Array.isArray(option.defaultValue) ? JSON.stringify(option.defaultValue) : String(option.defaultValue)}`);
+    }
+    if (option.enum && option.enum.length > 0) {
+        metadata.push(`enum=${option.enum.join('|')}`);
+    }
+    return metadata.length > 0 ? `  [${metadata.join(', ')}]` : '';
+}
+function renderSchemaDetail(schema) {
+    const lines = [
+        `${schema.path}`,
+        '',
+        `Command: ${schema.command}`,
+        `Summary: ${schema.summary}`,
+        `Risk: ${schema.risk}`,
+        `Auth: ${schema.auth}`,
+        '',
+    ];
+    lines.push(...renderDetailSection('Global Options:', schema.globalOptions));
+    lines.push(...renderDetailSection('Arguments:', (schema.arguments ?? []).map((entry) => `${entry.name}  ${entry.required ? 'required' : 'optional'}  ${entry.description}`)));
+    lines.push(...renderDetailSection('Options:', (schema.options ?? []).map((entry) => `${entry.name}${entry.required ? '  required' : ''}  ${entry.description}${formatOptionMetadata(entry)}`)));
+    const outputRows = [`summary  ${schema.output.summary}`];
+    if (schema.output.entity) {
+        outputRows.push(`entity   ${schema.output.entity}`);
+    }
+    for (const field of schema.output.fields ?? []) {
+        outputRows.push(`field    ${field}`);
+    }
+    for (const field of schema.output.metaFields ?? []) {
+        outputRows.push(`meta     ${field}`);
+    }
+    lines.push(...renderDetailSection('Output:', outputRows));
+    lines.push(...renderDetailSection('Examples:', schema.examples));
+    return lines.join('\n').trimEnd();
+}
+async function runSchemaCommand(context) {
+    const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    const path = context.args.path;
+    if (!path) {
+        const schemas = listCommandSchemas();
+        if (structuredOutput) {
+            printSuccess({
+                version: 1,
+                commands: schemas.map((schema) => ({
+                    path: schema.path,
+                    command: schema.command,
+                    summary: schema.summary,
+                    risk: schema.risk,
+                    auth: schema.auth,
+                })),
+            });
+            return;
+        }
+        printHumanReadableBlock(`${renderSchemaList(schemas)}\n`);
+        return;
+    }
+    const normalizedPath = path.trim();
+    const schema = findCommandSchema(normalizedPath);
+    if (!schema) {
+        throw new DinoxError(`Unknown schema path: ${normalizedPath}`, {
+            code: 'SCHEMA_PATH_NOT_FOUND',
+            suggestion: 'Run `dino schema` to list available schema paths.',
+            recoverable: true,
+        });
+    }
+    if (structuredOutput) {
+        printSuccess({
+            version: 1,
+            command: schema,
+        });
+        return;
+    }
+    printHumanReadableBlock(`${renderSchemaDetail(schema)}\n`);
+}
+export const schemaCommandDescriptor = {
+    ...schemaCommandMetadata,
+    action: runSchemaCommand,
+};
+export function registerSchemaCommands(program) {
+    registerStandaloneCommand(program, schemaCommandDescriptor);
+}

package/dist/commands/schema/renderSkills.d.ts

@@ -0,0 +1,6 @@
+export declare function renderBundledSkillReference(): string;
+export declare function renderGeneratedCommandSection(sectionKey: string): string;
+export declare function replaceGeneratedSection(source: string, markerName: string, content: string): string;
+export declare function syncBundledSkillReference(skillFilePath: string): void;
+export declare function syncGeneratedCommandSection(skillFilePath: string, sectionKey: string): void;
+export declare function resolveBundledSkillPath(repoRoot: string): string;

package/dist/commands/schema/renderSkills.js

@@ -0,0 +1,216 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listCommandSchemas } from './spec.js';
+const SECTION_ORDER = [
+    { title: 'Auth', paths: ['auth.login', 'auth.logout', 'auth.status'] },
+    { title: 'Sync', paths: ['sync'] },
+    { title: 'Schema', paths: ['schema'] },
+    { title: 'Update CLI', paths: ['update'] },
+    { title: 'Notes', paths: ['note.search', 'note.get', 'note.preview', 'note.detail', 'note.create', 'note.update', 'note.star', 'note.unstar', 'note.delete'] },
+    { title: 'Todo', paths: ['todo.search', 'todo.append', 'todo.create', 'todo.update'] },
+    { title: 'Tags', paths: ['tag.list', 'tag.add'] },
+    { title: 'Card Boxes (Zettel Boxes)', paths: ['box.list', 'box.add'] },
+    { title: 'Prompts', paths: ['prompt.list', 'prompt.add'] },
+    { title: 'Storage', paths: ['storage.list', 'storage.test', 'storage.upload', 'storage.stats'] },
+    { title: 'Config', paths: ['config.get', 'config.set'] },
+    { title: 'Info', paths: ['info'] },
+    { title: 'Graph', paths: ['graph.backlinks', 'graph.outlinks', 'graph.related', 'graph.stats'] },
+];
+const GLOBAL_OPTIONS = [
+    ['`--format <yaml|json>`', 'Structured output format. Prefer `json` for agent and script integrations.'],
+    ['`--json`', 'Legacy alias for machine-readable YAML output. Keep only for backward compatibility.'],
+    ['`--offline`', 'Skip sync, use local cache only'],
+    ['`--sync-timeout <ms>`', 'Override default 300000 ms (5 min) sync/connect timeout'],
+    ['`--verbose`', 'Enable verbose logging'],
+];
+function buildCommandSignature(schema) {
+    const args = schema.arguments?.map((entry) => entry.name).join(' ') ?? '';
+    return args ? `${schema.command} ${args}` : schema.command;
+}
+function padRight(value, width) {
+    if (value.length >= width) {
+        return value;
+    }
+    return `${value}${' '.repeat(width - value.length)}`;
+}
+function renderCommand(schema) {
+    const lines = [`${padRight(buildCommandSignature(schema), 34)} # ${schema.summary}`];
+    for (const option of schema.options ?? []) {
+        lines.push(`  ${padRight(option.name, 30)} # ${option.description}`);
+    }
+    return lines;
+}
+const GENERATED_COMMAND_SECTIONS = {
+    'skill:dino-manage-prompts': {
+        title: 'Command Reference',
+        paths: ['prompt.list', 'prompt.add'],
+        intro: 'Use these commands as the canonical Dinox CLI interface for prompt management.',
+        notes: [
+            'Prefer `--format json` for both browse and create flows.',
+            'For writes, run the same command with `--dry-run` first.',
+        ],
+    },
+    'skill:dino-manage-tags': {
+        title: 'Command Reference',
+        paths: ['tag.list', 'tag.add'],
+        intro: 'Use these commands as the canonical Dinox CLI interface for tag management.',
+        notes: [
+            'For writes, run the same command with `--dry-run` first.',
+        ],
+    },
+    'skill:dino-manage-boxes': {
+        title: 'Command Reference',
+        paths: ['box.list', 'box.add'],
+        intro: 'Use these commands as the canonical Dinox CLI interface for box management.',
+        notes: [
+            'For writes, run the same command with `--dry-run` first.',
+        ],
+    },
+    'skill:dino-storage': {
+        title: 'Command Reference',
+        paths: ['storage.list', 'storage.test', 'storage.upload', 'storage.stats'],
+        intro: 'Use these commands as the canonical Dinox CLI interface for custom storage inspection, connectivity testing, uploads, and usage stats.',
+        notes: [
+            'Prefer `--storage-id` when you want to bypass the current active custom storage selection.',
+            'For test and upload writes, run the same command with `--dry-run` first.',
+        ],
+    },
+    'ref:dino-note:search-and-read': {
+        title: 'Command Surface',
+        paths: ['note.search', 'note.get', 'note.preview', 'note.detail'],
+        intro: 'Use these generated commands as the canonical interfaces for note search and read workflows.',
+        notes: [
+            'Use `--boxes` for public box filters.',
+            'Prefer `--fields id,title,summary,tags,created_at,boxes,is_starred` when the user only needs search metadata.',
+            '`--sql` remains storage-oriented and still uses the field name `zettel_boxes`.',
+        ],
+    },
+    'ref:dino-note:create': {
+        title: 'Command Surface',
+        paths: ['note.create'],
+        intro: 'Use this generated command surface as the canonical interface for note creation.',
+        notes: [
+            'Use `--boxes` for public box input.',
+            'Prefer `--type note` unless the user explicitly wants a `crawl` note.',
+            'Run the same command with `--dry-run --format json` first.',
+        ],
+    },
+    'ref:dino-note:update-and-delete': {
+        title: 'Command Surface',
+        paths: ['note.update', 'note.star', 'note.unstar', 'note.delete'],
+        intro: 'Use these generated commands as the canonical interfaces for note mutation workflows.',
+        notes: [
+            '`--tags` and `--boxes` are full-replacement inputs.',
+            'Prefer `note star` / `note unstar` for pure starring changes, and `note update` when multiple fields change together.',
+            'Run the same command with `--dry-run --format json` first.',
+        ],
+    },
+    'ref:dino-manage-todo:todo-search': {
+        title: 'Command Surface',
+        paths: ['todo.search'],
+        intro: 'Use this generated command surface as the canonical interface for todo search.',
+        notes: [
+            'Prefer `--format json` for machine-readable search output.',
+        ],
+    },
+    'ref:dino-manage-todo:todo-mutations': {
+        title: 'Command Surface',
+        paths: ['todo.append', 'todo.create', 'todo.update'],
+        intro: 'Use these generated commands as the canonical mutation interfaces for todo workflows.',
+        notes: [
+            'Run the same command with `--dry-run` first.',
+            'For append, prefer explicit `--note-id` unless the user confirms the default target behavior.',
+        ],
+    },
+};
+export function renderBundledSkillReference() {
+    const schemas = new Map(listCommandSchemas().map((schema) => [schema.path, schema]));
+    const lines = [];
+    lines.push('## Global Options');
+    lines.push('');
+    lines.push('| Flag | Description |');
+    lines.push('|------|-------------|');
+    for (const [flag, description] of GLOBAL_OPTIONS) {
+        lines.push(`| ${flag} | ${description} |`);
+    }
+    lines.push('');
+    lines.push('## Commands Quick Reference');
+    lines.push('');
+    for (const section of SECTION_ORDER) {
+        lines.push(`### ${section.title}`);
+        lines.push('```text');
+        for (const pathKey of section.paths) {
+            const schema = schemas.get(pathKey);
+            if (!schema) {
+                continue;
+            }
+            lines.push(...renderCommand(schema));
+            lines.push('');
+        }
+        if (lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        lines.push('```');
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+export function renderGeneratedCommandSection(sectionKey) {
+    const section = GENERATED_COMMAND_SECTIONS[sectionKey];
+    if (!section) {
+        throw new Error(`No generated command section configuration for ${sectionKey}`);
+    }
+    const schemas = new Map(listCommandSchemas().map((schema) => [schema.path, schema]));
+    const lines = [];
+    lines.push(`## ${section.title}`);
+    lines.push('');
+    if (section.intro) {
+        lines.push(section.intro);
+        lines.push('');
+    }
+    lines.push('```text');
+    for (const pathKey of section.paths) {
+        const schema = schemas.get(pathKey);
+        if (!schema) {
+            throw new Error(`Unknown schema path for generated command section: ${pathKey}`);
+        }
+        lines.push(...renderCommand(schema));
+        lines.push('');
+    }
+    if (lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    lines.push('```');
+    if (section.notes && section.notes.length > 0) {
+        lines.push('');
+        for (const note of section.notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    return lines.join('\n').trimEnd();
+}
+export function replaceGeneratedSection(source, markerName, content) {
+    const startMarker = `<!-- BEGIN ${markerName} -->`;
+    const endMarker = `<!-- END ${markerName} -->`;
+    const start = source.indexOf(startMarker);
+    const end = source.indexOf(endMarker);
+    if (start === -1 || end === -1 || end < start) {
+        throw new Error(`Missing markers for ${markerName}`);
+    }
+    const prefix = source.slice(0, start + startMarker.length);
+    const suffix = source.slice(end);
+    return `${prefix}\n${content}\n${suffix}`;
+}
+export function syncBundledSkillReference(skillFilePath) {
+    const source = fs.readFileSync(skillFilePath, 'utf8');
+    const next = replaceGeneratedSection(source, 'GENERATED_REFERENCE', renderBundledSkillReference());
+    fs.writeFileSync(skillFilePath, next);
+}
+export function syncGeneratedCommandSection(skillFilePath, sectionKey) {
+    const source = fs.readFileSync(skillFilePath, 'utf8');
+    const next = replaceGeneratedSection(source, 'GENERATED_COMMANDS', renderGeneratedCommandSection(sectionKey));
+    fs.writeFileSync(skillFilePath, next);
+}
+export function resolveBundledSkillPath(repoRoot) {
+    return path.join(repoRoot, 'skills', 'dino-dinox', 'SKILL.md');
+}

package/dist/commands/schema/spec.d.ts

@@ -0,0 +1,6 @@
+import type { CommandSchema } from './types.js';
+export type { CommandSchema, CommandSchemaAuth, CommandSchemaMcp, CommandSchemaMcpProperty, CommandSchemaOutput, CommandSchemaRisk, } from './types.js';
+export declare const COMMAND_SCHEMAS: CommandSchema[];
+export declare function listCommandSchemas(): CommandSchema[];
+export declare function findCommandSchema(path: string): CommandSchema | null;
+export declare function listMcpCommandSchemas(): CommandSchema[];