@dinoxx/dinox-cli 2.14.0 → 2.15.0

package/dist/gateway/mcpCommandTools.js

@@ -3,6 +3,7 @@ import { promisify } from 'node:util';
 import { z } from 'zod';
 import { listCommandSchemas } from '../commands/schema/spec.js';
 import { tryForwardToDaemon } from '../daemon/forward.js';
+import { MCP_COMMAND_GROUPS } from './mcpGroups.js';
 import { requestContext } from '../utils/requestContext.js';
 /**
  * One MCP tool per command group, generated from the command schemas. Each runs
@@ -10,14 +11,19 @@ import { requestContext } from '../utils/requestContext.js';
  * validation, dry-run and confirmation guards. Approval belongs to the agent's
  * permission flow, guided by the tool annotations.
  */
-/** Command groups exposed as MCP tools. */
-export const MCP_COMMAND_GROUPS = [
-    'note', 'tag', 'box', 'todo', 'view', 'prop', 'template', 'prompt', 'graph', 'storage', 'meta.stats',
-];
+export { MCP_COMMAND_GROUPS };
 /** Commands deliberately excluded from the MCP surface. */
 export const MCP_COMMAND_EXCLUSIONS = [
     'auth.*', 'config.*', 'daemon.*', 'gateway.*', 'doctor', 'skills.*', 'update', 'sync', 'info', 'schema', 'meta.schema',
+    // MCP clients issue several tool calls themselves; batch is the shell's equivalent.
+    'batch',
+    // The MCP server itself.
+    'mcp',
 ];
+/** The tool name a command group is published under. */
+export function commandToolName(group) {
+    return group === 'meta.stats' ? 'dinox_stats' : `dinox_${group}`;
+}
 const execute = promisify(execFile);
 /** Runs the current CLI entry point without a shell. */
 export function createCliCommandRunner(overrides = {}) {
@@ -169,28 +175,33 @@ export function commandArgv(schema, input) {
     return [...schema.path.split('.'), ...flags, '--format', 'json', '--', ...positionals];
 }
 /** Builds grouped MCP tool definitions from the command schemas. */
-export function commandToolDefinitions() {
-    return MCP_COMMAND_GROUPS.map((group) => {
-        const commands = listCommandSchemas().filter((schema) => group === 'meta.stats' ? schema.path === group : schema.path.startsWith(`${group}.`));
+export function commandToolDefinitions(options = {}) {
+    const { readOnly = false, groups = MCP_COMMAND_GROUPS, knowledgeTools = true } = options;
+    return MCP_COMMAND_GROUPS.filter((group) => groups.includes(group)).flatMap((group) => {
+        const commands = listCommandSchemas().filter((schema) => (group === 'meta.stats' ? schema.path === group : schema.path.startsWith(`${group}.`))
+            && (!readOnly || schema.risk === 'read'));
+        if (commands.length === 0)
+            return [];
         const actions = commands.map(actionName);
-        const description = 'Dinox CLI commands. search_notes/read_note/search_todos/related_notes are the fast daemon-backed path for plain search/read. ' +
+        const description = 'Dinox CLI commands. ' +
+            (knowledgeTools ? 'search_notes/read_note/search_todos/related_notes are the fast daemon-backed path for plain search/read. ' : '') +
             'High-risk writes need dryRun: true first, then the CLI confirmation options listed below (e.g. confirm/expectedCount); ' +
             'CLI guards enforce them. Input keys are camelCase.\n' +
             commands.map(describeAction).join('\n');
-        return {
-            name: group === 'meta.stats' ? 'dinox_stats' : `dinox_${group}`,
-            commands,
-            config: {
-                description,
-                annotations: { ...toolAnnotations(commands), openWorldHint: group === 'storage' },
-                inputSchema: { action: z.enum(actions), input: z.record(z.string(), z.unknown()).optional() },
-            },
-        };
+        return [{
+                name: commandToolName(group),
+                commands,
+                config: {
+                    description,
+                    annotations: { ...toolAnnotations(commands), openWorldHint: group === 'storage' },
+                    inputSchema: { action: z.enum(actions), input: z.record(z.string(), z.unknown()).optional() },
+                },
+            }];
     });
 }
 /** Registers command tools using the real CLI or an injected runner. */
-export function registerCommandTools(server, runner = runCliCommand) {
-    for (const tool of commandToolDefinitions()) {
+export function registerCommandTools(server, runner = runCliCommand, options = {}) {
+    for (const tool of commandToolDefinitions(options)) {
         server.registerTool(tool.name, tool.config, async ({ action, input }) => {
             try {
                 const schema = tool.commands.find((command) => actionName(command) === action);

package/dist/gateway/mcpEnv.d.ts

@@ -5,3 +5,5 @@ export declare const GATEWAY_SESSION_TOKEN_ENV = "DINOX_GATEWAY_SESSION_TOKEN";
 export declare const GATEWAY_KNOWLEDGE_TOOLS_ENV = "DINOX_GATEWAY_KNOWLEDGE_TOOLS";
 /** Must not collide with MCP servers the user already registered with the agent. */
 export declare const DINOX_MCP_SERVER_NAME = "dinox-gateway";
+/** `dino mcp`, the server users register with their own MCP clients. */
+export declare const DINOX_STANDALONE_MCP_SERVER_NAME = "dinox";

package/dist/gateway/mcpEnv.js

@@ -5,3 +5,5 @@ export const GATEWAY_SESSION_TOKEN_ENV = 'DINOX_GATEWAY_SESSION_TOKEN';
 export const GATEWAY_KNOWLEDGE_TOOLS_ENV = 'DINOX_GATEWAY_KNOWLEDGE_TOOLS';
 /** Must not collide with MCP servers the user already registered with the agent. */
 export const DINOX_MCP_SERVER_NAME = 'dinox-gateway';
+/** `dino mcp`, the server users register with their own MCP clients. */
+export const DINOX_STANDALONE_MCP_SERVER_NAME = 'dinox';

package/dist/gateway/mcpGroups.d.ts

@@ -0,0 +1,3 @@
+/** Command groups exposed as MCP tools. Kept free of imports: command descriptors read it at load time. */
+export declare const MCP_COMMAND_GROUPS: readonly ["note", "tag", "box", "todo", "view", "prop", "template", "prompt", "graph", "storage", "meta.stats"];
+export type McpCommandGroup = (typeof MCP_COMMAND_GROUPS)[number];

package/dist/gateway/mcpGroups.js

@@ -0,0 +1,4 @@
+/** Command groups exposed as MCP tools. Kept free of imports: command descriptors read it at load time. */
+export const MCP_COMMAND_GROUPS = [
+    'note', 'tag', 'box', 'todo', 'view', 'prop', 'template', 'prompt', 'graph', 'storage', 'meta.stats',
+];

package/dist/gateway/mcpServer.d.ts

@@ -1,4 +1,4 @@
-import { type CommandRunner } from './mcpCommandTools.js';
+import { type CommandRunner, type CommandToolOptions } from './mcpCommandTools.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export type DaemonCall = (method: string, params?: unknown, options?: {
     timeoutMs?: number;
@@ -13,4 +13,13 @@ export type DinoxMcpOptions = {
     cwd?: string;
 };
 export declare function createDinoxMcpServer(call?: DaemonCall, options?: DinoxMcpOptions): McpServer;
+/**
+ * The Dinox MCP server for any MCP client (`dino mcp`). Only the generated
+ * command tools: they reach the daemon when it is available and otherwise run
+ * the CLI in a child process, so no daemon is required.
+ */
+export declare function createStandaloneMcpServer(options?: Omit<CommandToolOptions, 'knowledgeTools'> & {
+    commandRunner?: CommandRunner;
+}): McpServer;
 export declare function serveDinoxMcpOverStdio(): Promise<void>;
+export declare function serveStandaloneMcpOverStdio(options: Omit<CommandToolOptions, 'knowledgeTools'>): Promise<void>;

package/dist/gateway/mcpServer.js

@@ -4,7 +4,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { sendDaemonRequest } from '../daemon/client.js';
-import { DINOX_MCP_SERVER_NAME, GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from './mcpEnv.js';
+import { DINOX_MCP_SERVER_NAME, DINOX_STANDALONE_MCP_SERVER_NAME, GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from './mcpEnv.js';
 import { READ_CONVERSATION_MAX_LIMIT } from './conversationContext.js';
 import { getPackageVersion } from '../utils/version.js';
 /**
@@ -183,11 +183,31 @@ function registerKnowledgeTools(server, call) {
         }
     });
 }
+const STANDALONE_INSTRUCTIONS = "Tools for the user's Dinox knowledge base (notes, todos, tags, card boxes, views, properties, templates, prompts, " +
+    'the link graph and storage). Each dinox_* tool groups the CLI commands of one area: pick an `action` and pass its ' +
+    'camelCase `input`. Prefer note search for keywords and note semantic/context for meaning-based questions. Results ' +
+    'carry `_notice` (stale cache, pending upload) worth relaying. High-risk writes need dryRun: true first, then the ' +
+    'confirmation options the action lists.';
+/**
+ * The Dinox MCP server for any MCP client (`dino mcp`). Only the generated
+ * command tools: they reach the daemon when it is available and otherwise run
+ * the CLI in a child process, so no daemon is required.
+ */
+export function createStandaloneMcpServer(options = {}) {
+    const server = new McpServer({ name: DINOX_STANDALONE_MCP_SERVER_NAME, version: getPackageVersion() }, { instructions: STANDALONE_INSTRUCTIONS + (options.readOnly ? ' This server is read-only.' : '') });
+    registerCommandTools(server, options.commandRunner, { ...options, knowledgeTools: false });
+    return server;
+}
+async function serveOverStdio(server) {
+    await server.connect(new StdioServerTransport());
+    await new Promise((resolve) => process.stdin.once('close', resolve));
+}
 export async function serveDinoxMcpOverStdio() {
-    const server = createDinoxMcpServer(undefined, {
+    await serveOverStdio(createDinoxMcpServer(undefined, {
         knowledgeTools: process.env[GATEWAY_KNOWLEDGE_TOOLS_ENV] !== '0',
         sessionToken: process.env[GATEWAY_SESSION_TOKEN_ENV]?.trim() || undefined,
-    });
-    await server.connect(new StdioServerTransport());
-    await new Promise((resolve) => process.stdin.once('close', resolve));
+    }));
+}
+export async function serveStandaloneMcpOverStdio(options) {
+    await serveOverStdio(createStandaloneMcpServer(options));
 }

package/dist/powersync/syncPass.js

@@ -1,14 +1,26 @@
 import { createTimeoutSignal } from '../utils/abort.js';
+import { reportProgress } from '../utils/progress.js';
 import { getStatusSnapshot, waitForDownloadIdle } from './runtime.js';
 import { syncNoteTokenIndex } from './tokenIndex.js';
 export async function runSingleSyncPass(db, timeoutMs) {
     const deadline = Date.now() + Math.max(1, timeoutMs);
     const remainingMs = () => Math.max(0, deadline - Date.now());
-    const downloadIdle = await waitForDownloadIdle(db, Math.max(1, Math.min(remainingMs(), 60_000)));
+    // PowerSync reports operation counts while a checkpoint downloads.
+    const stopDownloadProgress = db.registerListener({
+        statusChanged: (status) => {
+            const progress = status.downloadProgress;
+            if (progress)
+                reportProgress({ phase: 'download', current: progress.downloadedOperations, total: progress.totalOperations });
+        },
+    });
+    reportProgress({ phase: 'download' });
+    const downloadIdle = await waitForDownloadIdle(db, Math.max(1, Math.min(remainingMs(), 60_000)))
+        .finally(stopDownloadProgress);
     const indexTimeoutMs = remainingMs();
     const timeout = indexTimeoutMs > 0 ? createTimeoutSignal(indexTimeoutMs) : null;
     const tokenIndex = await syncNoteTokenIndex(db, {
         signal: timeout?.signal ?? AbortSignal.abort(),
+        onBatch: (progress) => reportProgress({ phase: 'index', current: progress.scanned }),
     }).finally(() => timeout?.cancel());
     const status = getStatusSnapshot(db);
     const uploadIdle = !status.dataFlowStatus.uploading;

package/dist/powersync/tokenIndex.d.ts

@@ -25,6 +25,8 @@ export declare function syncNoteTokenIndex(db: AbstractPowerSyncDatabase, option
     nowIso?: () => string;
     tokenize?: (text: string, limit?: number) => string[];
     signal?: AbortSignal;
+    /** Called after each batch with the running counters. */
+    onBatch?: (result: NoteTokenIndexResult) => void;
 }): Promise<NoteTokenIndexResult>;
 export declare function inspectNoteTokenIndex(db: AbstractPowerSyncDatabase): Promise<NoteTokenIndexInspection>;
 export declare function rebuildNoteTokenIndex(db: AbstractPowerSyncDatabase, options?: Parameters<typeof syncNoteTokenIndex>[1]): Promise<NoteTokenIndexResult>;

package/dist/powersync/tokenIndex.js

@@ -67,6 +67,7 @@ export async function syncNoteTokenIndex(db, options) {
         }
         await updateIndexCursor(db, cursorUpdatedAt, cursorId, nowIso);
         result.cursor = { updatedAt: cursorUpdatedAt, id: cursorId };
+        options?.onBatch?.(result);
     }
     result.complete = await reconcileSkippedRows(db, result, batchSize, nowIso, tokenize, signal);
     result.cursor = {

package/dist/requests/execute.d.ts

@@ -0,0 +1,11 @@
+import type { CommandExecuteResult } from '../daemon/types.js';
+/**
+ * Runs a command line in this process with its stdout/stderr captured instead
+ * of written, the same way the daemon runs a forwarded command.
+ */
+export declare function runCapturedInProcess(argv: string[], onFatalError?: (error: unknown) => void): Promise<CommandExecuteResult>;
+/**
+ * Runs one data command and returns its captured output: inside the daemon
+ * when it is available, otherwise in this process (honoring `--request-id`).
+ */
+export declare function executeCommandLine(argv: string[]): Promise<CommandExecuteResult>;

package/dist/requests/execute.js

@@ -0,0 +1,26 @@
+import { tryForwardToDaemon } from '../daemon/forward.js';
+import { localCommandExecution, requestContext } from '../utils/requestContext.js';
+import { requestIdFromArgv, runWithRequestId } from './store.js';
+/**
+ * Runs a command line in this process with its stdout/stderr captured instead
+ * of written, the same way the daemon runs a forwarded command.
+ */
+export async function runCapturedInProcess(argv, onFatalError) {
+    const { runCli } = await import('../runCli.js');
+    const context = {
+        stdout: [], stderr: [], format: null, noticeProvider: null, cwd: process.cwd(),
+    };
+    const exitCode = await requestContext.run(context, () => localCommandExecution.run(true, () => runCli(argv, onFatalError)));
+    return { stdout: context.stdout.join(''), stderr: context.stderr.join(''), exitCode };
+}
+/**
+ * Runs one data command and returns its captured output: inside the daemon
+ * when it is available, otherwise in this process (honoring `--request-id`).
+ */
+export async function executeCommandLine(argv) {
+    const forwarded = await tryForwardToDaemon(argv);
+    if (forwarded)
+        return forwarded;
+    const key = requestIdFromArgv(argv);
+    return key ? runWithRequestId(key, argv, () => runCapturedInProcess(argv)) : runCapturedInProcess(argv);
+}

package/dist/skills/commandRefs.js

@@ -1,17 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { GLOBAL_OPTION_NAMES } from '../commands/schema/globalOptions.js';
 import { listCommandSchemas } from '../commands/schema/spec.js';
 // Global flags accepted by every command (see src/cli.ts) plus Commander builtins.
-const GLOBAL_FLAGS = new Set([
-    '--json',
-    '--format',
-    '--offline',
-    '--require-sync',
-    '--sync-timeout',
-    '--verbose',
-    '--help',
-    '--version',
-]);
+const GLOBAL_FLAGS = new Set([...GLOBAL_OPTION_NAMES, '--help', '--version']);
 const SHELL_BOUNDARY = /\s(?:\||&&|\|\||;|>|2>|#)\s/;
 function buildCommandIndex() {
     const byCommand = new Map();

package/dist/utils/cursor.d.ts

@@ -0,0 +1,9 @@
+export declare function encodeCursor(command: string, offset: number, query: unknown): string;
+/** Returns the offset a cursor points at; throws when it is malformed or belongs to another query. */
+export declare function decodeCursor(token: string, command: string, query: unknown): number;
+/**
+ * Resolves the start offset from `--cursor` or `--offset`; the two are
+ * mutually exclusive (an offset of 0, the default, does not count).
+ */
+export declare function resolveCursorOffset(cursor: unknown, offset: number, command: string, query: unknown): number;
+export declare function nextCursor(command: string, query: unknown, nextOffset: number, hasMore: boolean): string | null;

package/dist/utils/cursor.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+import { DinoxError } from './errors.js';
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+function queryHash(command, query) {
+    return createHash('sha256').update(`${command}\n${stableJson(query)}`).digest('base64url').slice(0, 16);
+}
+export function encodeCursor(command, offset, query) {
+    const payload = { v: 1, c: command, o: offset, q: queryHash(command, query) };
+    return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+function invalidCursor(message) {
+    return new DinoxError(message, {
+        code: 'INVALID_ARGUMENT',
+        recoverable: true,
+        suggestion: 'Pass the nextCursor from the previous page of the same command and query, or drop --cursor to start over.',
+    });
+}
+/** Returns the offset a cursor points at; throws when it is malformed or belongs to another query. */
+export function decodeCursor(token, command, query) {
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(token.trim(), 'base64url').toString('utf8'));
+    }
+    catch {
+        throw invalidCursor('--cursor is not a valid pagination cursor');
+    }
+    if (!payload || payload.v !== 1 || typeof payload.o !== 'number' || !Number.isInteger(payload.o) || payload.o < 0) {
+        throw invalidCursor('--cursor is not a valid pagination cursor');
+    }
+    if (payload.c !== command || payload.q !== queryHash(command, query)) {
+        throw invalidCursor(`--cursor belongs to a different ${payload.c === command ? 'query' : 'command'}`);
+    }
+    return payload.o;
+}
+/**
+ * Resolves the start offset from `--cursor` or `--offset`; the two are
+ * mutually exclusive (an offset of 0, the default, does not count).
+ */
+export function resolveCursorOffset(cursor, offset, command, query) {
+    if (cursor === undefined || cursor === null || cursor === '')
+        return offset;
+    if (typeof cursor !== 'string')
+        throw invalidCursor('--cursor must be a string');
+    if (offset > 0) {
+        throw new DinoxError('--cursor and --offset cannot be used together', { code: 'INVALID_ARGUMENT', recoverable: true });
+    }
+    return decodeCursor(cursor, command, query);
+}
+export function nextCursor(command, query, nextOffset, hasMore) {
+    return hasMore ? encodeCursor(command, nextOffset, query) : null;
+}

package/dist/utils/defaultFormat.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_FORMAT_ENV = "DINOX_FORMAT";
+/**
+ * Applies DINOX_FORMAT (json, yaml, or auto: json when stdout is not a
+ * terminal) by adding `--format` when the command line has none. Agents set
+ * it once instead of passing `--format json` on every call. Help, version and
+ * protocol commands are left alone.
+ */
+export declare function applyDefaultFormat(argv: string[], env?: NodeJS.ProcessEnv, stdoutIsTTY?: boolean): string[];

package/dist/utils/defaultFormat.js

@@ -0,0 +1,38 @@
+import { DinoxError } from './errors.js';
+export const DEFAULT_FORMAT_ENV = 'DINOX_FORMAT';
+/** Commands whose stdout is a protocol, never a command result. */
+const PROTOCOL_COMMANDS = [['gateway', 'mcp'], ['mcp'], ['daemon', 'supervise']];
+function commandWords(argv) {
+    return argv.filter((arg) => !arg.startsWith('-')).slice(0, 2);
+}
+/**
+ * Applies DINOX_FORMAT (json, yaml, or auto: json when stdout is not a
+ * terminal) by adding `--format` when the command line has none. Agents set
+ * it once instead of passing `--format json` on every call. Help, version and
+ * protocol commands are left alone.
+ */
+export function applyDefaultFormat(argv, env = process.env, stdoutIsTTY = Boolean(process.stdout.isTTY)) {
+    const raw = env[DEFAULT_FORMAT_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return argv;
+    if (raw !== 'json' && raw !== 'yaml' && raw !== 'auto') {
+        throw new DinoxError(`${DEFAULT_FORMAT_ENV} must be one of: json, yaml, auto`, {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+        });
+    }
+    const format = raw === 'auto' ? (stdoutIsTTY ? null : 'json') : raw;
+    if (!format || argv.length === 0)
+        return argv;
+    const terminator = argv.indexOf('--');
+    const options = terminator === -1 ? argv : argv.slice(0, terminator);
+    const explicit = options.some((arg) => arg === '--format' || arg.startsWith('--format=') || arg === '--json');
+    const informational = options.some((arg) => ['--help', '-h', '--version', '-V'].includes(arg)) || options[0] === 'help';
+    const words = commandWords(options);
+    const protocol = PROTOCOL_COMMANDS.some((command) => command.every((word, index) => words[index] === word));
+    if (explicit || informational || protocol)
+        return argv;
+    return terminator === -1
+        ? [...argv, '--format', format]
+        : [...argv.slice(0, terminator), '--format', format, ...argv.slice(terminator)];
+}

package/dist/utils/errorCodes.d.ts

@@ -471,6 +471,10 @@ export declare const ERROR_CODES: {
         readonly exitCode: 5;
         readonly description: "No command schema exists for the requested path.";
     };
+    readonly SEMANTIC_SEARCH_UNAVAILABLE: {
+        readonly exitCode: 1;
+        readonly description: "The semantic search service could not be reached or failed; keyword search (note search) still works.";
+    };
     readonly SKILLS_LOCK_INVALID: {
         readonly exitCode: 1;
         readonly description: "The skills installer lock file is malformed.";

package/dist/utils/errorCodes.js

@@ -123,6 +123,7 @@ export const ERROR_CODES = {
     SAVED_VIEW_UNSUPPORTED_LAYOUT: { exitCode: 1, description: 'The saved view layout is unsupported.' },
     SAVED_VIEW_VALUE_TYPE_MISMATCH: { exitCode: 1, description: 'A filter value does not match the field type.' },
     SCHEMA_PATH_NOT_FOUND: { exitCode: 5, description: 'No command schema exists for the requested path.' },
+    SEMANTIC_SEARCH_UNAVAILABLE: { exitCode: 1, description: 'The semantic search service could not be reached or failed; keyword search (note search) still works.' },
     SKILLS_LOCK_INVALID: { exitCode: 1, description: 'The skills installer lock file is malformed.' },
     SKILLS_LOCK_READ_FAILED: { exitCode: 1, description: 'The skills installer lock file could not be read.' },
     SKILLS_MIGRATION_FAILED: { exitCode: 1, description: 'The skills installer failed during migration.' },

package/dist/utils/output.d.ts

@@ -1,3 +1,4 @@
+import { type FieldSelection } from './select.js';
 export type StructuredOutputFormat = 'yaml' | 'json';
 export type StructuredNoticeMap = Record<string, unknown>;
 export declare function toYaml(value: unknown): string;
@@ -16,6 +17,7 @@ export declare function parseStructuredOutputFormatFromArgv(argv: string[]): Str
 export declare function setRequestedStructuredOutputFormat(format: StructuredOutputFormat | null): void;
 export declare function clearRequestedStructuredOutputFormat(): void;
 export declare function getRequestedStructuredOutputFormat(): StructuredOutputFormat | null;
+export declare function setRequestedFieldSelection(selection: FieldSelection | null): void;
 export declare function setPendingStructuredNoticeProvider(provider: (() => StructuredNoticeMap | null) | null): void;
 export declare function clearPendingStructuredNoticeProvider(): void;
 export declare function printStructuredData(value: unknown, format?: StructuredOutputFormat | null): void;

package/dist/utils/output.js

@@ -2,8 +2,10 @@ import { stringify as stringifyYaml } from 'yaml';
 import { DinoxError } from './errors.js';
 import { sanitizeForTerminal } from './terminalSanitization.js';
 import { requestContext } from './requestContext.js';
+import { projectFields } from './select.js';
 let requestedStructuredOutputFormat = null;
 let pendingStructuredNoticeProvider = null;
+let requestedFieldSelection = null;
 export function toYaml(value) {
     return stringifyYaml(value, {
         lineWidth: 0,
@@ -117,6 +119,36 @@ export function getRequestedStructuredOutputFormat() {
     const context = requestContext.getStore();
     return context ? context.format : requestedStructuredOutputFormat;
 }
+export function setRequestedFieldSelection(selection) {
+    const context = requestContext.getStore();
+    if (context) {
+        context.select = selection;
+        return;
+    }
+    requestedFieldSelection = selection;
+}
+function getRequestedFieldSelection() {
+    const context = requestContext.getStore();
+    return context ? context.select ?? null : requestedFieldSelection;
+}
+/** Applies `--select` to a command result; unmatched paths become a notice. */
+function selectRequestedFields(value) {
+    const selection = getRequestedFieldSelection();
+    if (!selection)
+        return { value, notice: null };
+    const { value: projected, missing } = projectFields(value, selection);
+    if (missing.length === 0)
+        return { value: projected, notice: null };
+    return {
+        value: projected,
+        notice: {
+            select_missing: {
+                message: 'These --select fields are not in the result; check `dino schema <command>` output fields.',
+                fields: missing,
+            },
+        },
+    };
+}
 export function setPendingStructuredNoticeProvider(provider) {
     const context = requestContext.getStore();
     if (context) {
@@ -190,15 +222,21 @@ function summarizeStructuredError(value) {
 export function printSuccess(value, format = getRequestedStructuredOutputFormat()) {
     if (format === 'json') {
         const data = normalizeSuccessEnvelopeData(value);
-        const notice = mergeStructuredNotices(getPendingStructuredNotice(), deriveStructuredNotice(data));
+        const selected = selectRequestedFields(data);
+        const notice = mergeStructuredNotices(mergeStructuredNotices(getPendingStructuredNotice(), deriveStructuredNotice(data)) ?? null, selected.notice);
         printStructuredData({
             ok: true,
-            data,
+            data: selected.value,
             ...(notice ? { _notice: notice } : {}),
         }, 'json');
         return;
     }
-    printStructuredData(value, format);
+    const selected = selectRequestedFields(value);
+    if (selected.notice) {
+        const fields = selected.notice.select_missing.fields;
+        printHumanReadableWarning(`warning: --select fields not in the result: ${fields.join(', ')}`);
+    }
+    printStructuredData(selected.value, format);
 }
 export function printError(value, format = getRequestedStructuredOutputFormat()) {
     if (format === 'json') {

package/dist/utils/progress.d.ts

@@ -0,0 +1,25 @@
+/** One step of a long-running command, reported on stderr under `--progress`. */
+export type ProgressEvent = {
+    /** What the command is doing: `download`, `index`, `write`, ... */
+    phase: string;
+    current?: number;
+    total?: number;
+    message?: string;
+};
+export type ProgressReporting = {
+    /** Command path (`sync`, `note.export`), carried by every event. */
+    command: string;
+    startedAtMs: number;
+    lastPhase?: string;
+    lastAtMs?: number;
+};
+/** Enables (`command`) or disables (`null`) progress events for the running command. */
+export declare function setProgressReporting(command: string | null, now?: number): void;
+/**
+ * Structured output gets one JSON object per line (`"type":"progress"`), so
+ * stdout stays a single result while stderr streams events; human output gets
+ * a short line.
+ */
+export declare function renderProgressEvent(reporting: ProgressReporting, event: ProgressEvent, structured: boolean, now: number): string;
+/** Reports a progress event when `--progress` is on; otherwise does nothing. */
+export declare function reportProgress(event: ProgressEvent, now?: number): void;

package/dist/utils/progress.js

@@ -0,0 +1,59 @@
+import { getRequestedStructuredOutputFormat, writeToStderr } from './output.js';
+import { requestContext } from './requestContext.js';
+/** Repeated events of one phase closer together than this are dropped, except the last of a known total. */
+const MIN_INTERVAL_MS = 200;
+let localReporting = null;
+/** Enables (`command`) or disables (`null`) progress events for the running command. */
+export function setProgressReporting(command, now = Date.now()) {
+    const reporting = command ? { command, startedAtMs: now } : null;
+    const context = requestContext.getStore();
+    if (context) {
+        context.progress = reporting;
+        return;
+    }
+    localReporting = reporting;
+}
+/**
+ * Structured output gets one JSON object per line (`"type":"progress"`), so
+ * stdout stays a single result while stderr streams events; human output gets
+ * a short line.
+ */
+export function renderProgressEvent(reporting, event, structured, now) {
+    if (structured) {
+        return `${JSON.stringify({
+            type: 'progress',
+            command: reporting.command,
+            phase: event.phase,
+            ...(event.current !== undefined ? { current: event.current } : {}),
+            ...(event.total !== undefined ? { total: event.total } : {}),
+            ...(event.message !== undefined ? { message: event.message } : {}),
+            elapsed_ms: Math.max(0, now - reporting.startedAtMs),
+        })}\n`;
+    }
+    const count = event.current === undefined
+        ? ''
+        : event.total === undefined
+            ? ` ${event.current}`
+            : ` ${event.current}/${event.total}${event.total > 0 ? ` (${Math.floor((event.current / event.total) * 100)}%)` : ''}`;
+    return `[${reporting.command}] ${event.phase}${count}${event.message ? ` ${event.message}` : ''}\n`;
+}
+/** Reports a progress event when `--progress` is on; otherwise does nothing. */
+export function reportProgress(event, now = Date.now()) {
+    const context = requestContext.getStore();
+    const reporting = context ? context.progress ?? null : localReporting;
+    if (!reporting)
+        return;
+    const finished = event.total !== undefined && event.current === event.total;
+    if (reporting.lastPhase === event.phase
+        && reporting.lastAtMs !== undefined
+        && now - reporting.lastAtMs < MIN_INTERVAL_MS
+        && !finished)
+        return;
+    reporting.lastPhase = event.phase;
+    reporting.lastAtMs = now;
+    const text = renderProgressEvent(reporting, event, getRequestedStructuredOutputFormat() !== null, now);
+    if (context?.onProgress)
+        context.onProgress(text);
+    else
+        writeToStderr(text);
+}

package/dist/utils/requestContext.d.ts

@@ -2,12 +2,20 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
 import type { ResolvedDinoxConfig } from '../config/types.js';
 import type { StructuredNoticeMap, StructuredOutputFormat } from './output.js';
+import type { FieldSelection } from './select.js';
+import type { ProgressReporting } from './progress.js';
 export type RequestContext = {
     stdout: string[];
     stderr: string[];
     format: StructuredOutputFormat | null;
+    /** `--select` of the running command; absent means the whole result. */
+    select?: FieldSelection | null;
     noticeProvider: (() => StructuredNoticeMap | null) | null;
     cwd: string;
+    /** `--progress` of the running command; absent means off. */
+    progress?: ProgressReporting | null;
+    /** Delivers rendered progress events live (the daemon streams them to the client); default stderr. */
+    onProgress?: (text: string) => void;
     daemon?: {
         db: AbstractPowerSyncDatabase;
         config: ResolvedDinoxConfig;

package/dist/utils/select.d.ts

@@ -0,0 +1,20 @@
+/** A parsed `--select` list: each key keeps the whole value (true) or a nested selection. */
+export type FieldSelection = {
+    [key: string]: FieldSelection | true;
+};
+/**
+ * Parses `--select notes.id,notes.title,count` into a selection tree. A path
+ * that names a parent also keeps everything below it (`notes,notes.id` keeps
+ * whole notes).
+ */
+export declare function parseFieldSelection(value: unknown): FieldSelection;
+/**
+ * Keeps only the selected fields. Arrays are projected item by item, so
+ * `notes.id` selects the id of every note. Returns the projected value and the
+ * paths that matched nothing anywhere, so a typo is reported instead of
+ * silently producing empty output.
+ */
+export declare function projectFields(value: unknown, selection: FieldSelection): {
+    value: unknown;
+    missing: string[];
+};