@dinoxx/dinox-cli 2.13.1 → 2.15.0

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/runtime.d.ts

@@ -7,6 +7,8 @@ export type ConnectResult = {
     dbPath: string;
     stale: boolean;
     releaseOwner: () => Promise<void>;
+    /** Drops the sync stream and connects again (online connections only). */
+    reconnect?: () => Promise<void>;
 };
 type ClosablePowerSyncDatabase = {
     close: () => Promise<void>;

package/dist/powersync/runtime.js

@@ -215,9 +215,11 @@ export async function connectPowerSync(args) {
             });
         }, uploader);
         await db.connect(connector);
+        // connect() disconnects an existing stream first.
+        const reconnect = () => db.connect(connector);
         if (args.waitForInitialSync === false) {
             const status = getStatusSnapshot(db);
-            return { db, dbPath, stale: !status.connected || !status.hasSynced, releaseOwner };
+            return { db, dbPath, stale: !status.connected || !status.hasSynced, releaseOwner, reconnect };
         }
         const { signal, cancel } = createTimeoutSignal(args.timeoutMs);
         try {

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/requests/store.d.ts

@@ -0,0 +1,10 @@
+import type { CommandExecuteResult } from '../daemon/types.js';
+export declare const AUTO_REQUEST_ID_PREFIX = "auto:";
+export declare function validateRequestId(key: string): string;
+/** Reads only options before the argument terminator. */
+export declare function requestIdFromArgv(argv: string[]): string | undefined;
+/** Claims once across processes and preserves the complete output for replay. */
+export declare function runWithRequestId(key: string, argv: string[], run: () => Promise<CommandExecuteResult>, opts?: {
+    waitTimeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<CommandExecuteResult>;

package/dist/requests/store.js

@@ -0,0 +1,190 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { getDataDir } from '../config/paths.js';
+import { DinoxError } from '../utils/errors.js';
+const RETENTION_MS = 24 * 60 * 60 * 1000;
+/** Ids the CLI generates only cover its own single retry; their output need not linger. */
+const AUTO_RETENTION_MS = 10 * 60 * 1000;
+export const AUTO_REQUEST_ID_PREFIX = 'auto:';
+const instanceId = randomUUID();
+const cleanedDirs = new Set();
+export function validateRequestId(key) {
+    if (typeof key !== 'string' || key.length < 1 || key.length > 128 || /[^A-Za-z0-9._:-]/.test(key)) {
+        throw new DinoxError('Request id must contain 1–128 characters from A-Z, a-z, 0-9, ., _, :, -.', { code: 'INVALID_ARGUMENT' });
+    }
+    return key;
+}
+/** Reads only options before the argument terminator. */
+export function requestIdFromArgv(argv) {
+    let key;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--')
+            break;
+        if (argv[i] === '--request-id')
+            key = validateRequestId(argv[++i] ?? '');
+        else if (argv[i].startsWith('--request-id='))
+            key = validateRequestId(argv[i].slice(13));
+    }
+    return key;
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function argvHash(argv) {
+    const filtered = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--') {
+            filtered.push(...argv.slice(i));
+            break;
+        }
+        if (argv[i] === '--request-id') {
+            i++;
+            continue;
+        }
+        if (argv[i].startsWith('--request-id='))
+            continue;
+        filtered.push(argv[i]);
+    }
+    return hash(JSON.stringify(filtered));
+}
+function ownerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function cleanup(dir) {
+    if (cleanedDirs.has(dir))
+        return;
+    cleanedDirs.add(dir);
+    const lockPath = path.join(dir, '.cleanup.lock');
+    let lock;
+    try {
+        lock = await fs.open(lockPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return;
+        throw error;
+    }
+    try {
+        for (const name of await fs.readdir(dir)) {
+            if (!/^[a-f0-9]{64}\.json$/.test(name))
+                continue;
+            const file = path.join(dir, name);
+            try {
+                const age = Date.now() - (await fs.stat(file)).mtimeMs;
+                if (age <= AUTO_RETENTION_MS)
+                    continue;
+                const record = JSON.parse(await fs.readFile(file, 'utf8'));
+                if (!record.auto && age <= RETENTION_MS)
+                    continue;
+                // Never expire a command that is still executing, even after 24 hours.
+                if (record.state === 'running' && ownerAlive(record.pid))
+                    continue;
+                await fs.unlink(file);
+            }
+            catch {
+                // Cleanup is best effort; another process may already have removed it.
+            }
+        }
+    }
+    finally {
+        await lock.close();
+        await fs.rm(lockPath, { force: true });
+    }
+}
+/** Claims once across processes and preserves the complete output for replay. */
+export async function runWithRequestId(key, argv, run, opts = {}) {
+    validateRequestId(key);
+    const dir = path.join(getDataDir(), 'requests');
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.chmod(dir, 0o700);
+    await cleanup(dir);
+    const file = path.join(dir, `${hash(key)}.json`);
+    const record = {
+        version: 1, argvHash: argvHash(argv), state: 'running', auto: key.startsWith(AUTO_REQUEST_ID_PREFIX), pid: process.pid,
+        instanceId, startedAt: Date.now(),
+    };
+    const deadline = Date.now() + (opts.waitTimeoutMs ?? 300_000);
+    try {
+        const handle = await fs.open(file, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(record));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        while (true) {
+            let previous;
+            try {
+                previous = JSON.parse(await fs.readFile(file, 'utf8'));
+            }
+            catch (error) {
+                // A claimant may still be writing, or may have rejected and removed its claim.
+                if (error.code === 'ENOENT') {
+                    return runWithRequestId(key, argv, run, { ...opts, waitTimeoutMs: Math.max(0, deadline - Date.now()) });
+                }
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                if (Date.now() >= deadline) {
+                    throw new DinoxError('Request claim is not readable yet.', { code: 'REQUEST_IN_PROGRESS', recoverable: true });
+                }
+                await delay(opts.pollIntervalMs ?? 100);
+                continue;
+            }
+            if (previous.argvHash !== record.argvHash) {
+                throw new DinoxError('Request id was used with different arguments.', { code: 'REQUEST_ID_CONFLICT' });
+            }
+            if (previous.state === 'done' && previous.result)
+                return previous.result;
+            if (!ownerAlive(previous.pid)) {
+                throw new DinoxError('The earlier request stopped; its outcome is unknown.', {
+                    code: 'REQUEST_INTERRUPTED',
+                    suggestion: 'Verify the result, then retry with a new request id.',
+                });
+            }
+            if (Date.now() >= deadline) {
+                throw new DinoxError('The earlier request is still running.', {
+                    code: 'REQUEST_IN_PROGRESS', recoverable: true,
+                    suggestion: 'Rerun the exact same command with the same request id.',
+                });
+            }
+            await delay(opts.pollIntervalMs ?? 100);
+        }
+    }
+    let result;
+    try {
+        result = await run();
+    }
+    catch (error) {
+        await fs.unlink(file);
+        throw error;
+    }
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await fs.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({ ...record, state: 'done', finishedAt: Date.now(), result }));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+    return result;
+}

package/dist/runCli.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(input: string[], onFatalError?: (error: unknown) => void): Promise<number>;
+export declare function printCliError(error: unknown, argv: string[]): number;

package/dist/runCli.js

@@ -0,0 +1,64 @@
+import { createCli } from './cli.js';
+import { buildStructuredErrorPayload, isDinoxError } from './utils/errors.js';
+import { clearRequestedStructuredOutputFormat, parseStructuredOutputFormatFromArgv, printError, printHumanReadableError, setRequestedStructuredOutputFormat, } from './utils/output.js';
+function normalizeArgv(argv) {
+    // pnpm/npm script forwarding can prepend a standalone "--".
+    if (argv[0] === '--') {
+        return argv.slice(1);
+    }
+    return argv;
+}
+function isVerbose(argv) {
+    return argv.includes('--verbose');
+}
+function isCommanderError(error) {
+    return Boolean(error)
+        && typeof error === 'object'
+        && typeof error.code === 'string'
+        && error.code.startsWith('commander.')
+        && typeof error.exitCode === 'number';
+}
+export async function runCli(input, onFatalError) {
+    const argv = normalizeArgv(input);
+    try {
+        await createCli().parseAsync(['node', process.argv[1] ?? 'dino', ...argv]);
+        return 0;
+    }
+    catch (error) {
+        onFatalError?.(error);
+        return printCliError(error, argv);
+    }
+}
+export function printCliError(error, argv) {
+    if (isCommanderError(error)) {
+        return error.exitCode === 0 ? 0 : 2;
+    }
+    let format = null;
+    try {
+        format = parseStructuredOutputFormatFromArgv(argv);
+    }
+    catch {
+        format = null;
+    }
+    const verbose = isVerbose(argv);
+    const payload = buildStructuredErrorPayload(error, verbose);
+    const exitCode = isDinoxError(error) ? error.exitCode : 1;
+    if (format) {
+        setRequestedStructuredOutputFormat(format);
+        printError(payload, format);
+        clearRequestedStructuredOutputFormat();
+        return exitCode;
+    }
+    printHumanReadableError(payload.message);
+    if (payload.suggested_action) {
+        printHumanReadableError(`suggested action: ${payload.suggested_action.command}`);
+        printHumanReadableError(`reason: ${payload.suggested_action.reason}`);
+    }
+    else if (payload.suggestion) {
+        printHumanReadableError(`suggestion: ${payload.suggestion}`);
+    }
+    if (verbose && payload.stack) {
+        printHumanReadableError(payload.stack);
+    }
+    return exitCode;
+}

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/argValue.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import { DinoxError } from './errors.js';
+import { resolveUserPath } from './requestContext.js';
 export async function readStringOrFile(value) {
     if (!value.startsWith('@')) {
         return value;
@@ -9,7 +10,7 @@ export async function readStringOrFile(value) {
         throw new DinoxError('Invalid @file syntax: expected @<path>');
     }
     try {
-        return await fs.readFile(filePath, 'utf8');
+        return await fs.readFile(resolveUserPath(filePath), 'utf8');
     }
     catch (error) {
         throw new DinoxError(`Failed to read file: ${filePath}`, { cause: error });

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

@@ -47,6 +47,10 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "Another process is writing the CLI config.";
     };
+    readonly DAEMON_COMMAND_NOT_FORWARDABLE: {
+        readonly exitCode: 2;
+        readonly description: "The command must run in the CLI process.";
+    };
     readonly DAEMON_ERROR: {
         readonly exitCode: 5;
         readonly description: "The background daemon reported an error.";
@@ -79,6 +83,10 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "The service manager (launchd / systemd) rejected a daemon service operation.";
     };
+    readonly DAEMON_SERVICE_FOREIGN: {
+        readonly exitCode: 1;
+        readonly description: "The daemon service runs another dino install; it was left unchanged.";
+    };
     readonly DAEMON_SERVICE_UNSUPPORTED: {
         readonly exitCode: 5;
         readonly description: "The daemon cannot run as a login service on this platform or with this auth setup.";
@@ -343,6 +351,18 @@ export declare const ERROR_CODES: {
         readonly exitCode: 1;
         readonly description: "A property value does not match its definition.";
     };
+    readonly REQUEST_ID_CONFLICT: {
+        readonly exitCode: 2;
+        readonly description: "The request id was already used for different arguments.";
+    };
+    readonly REQUEST_INTERRUPTED: {
+        readonly exitCode: 1;
+        readonly description: "The earlier request owner exited; its outcome is unknown.";
+    };
+    readonly REQUEST_IN_PROGRESS: {
+        readonly exitCode: 1;
+        readonly description: "The earlier request is still running; retry with the same id.";
+    };
     readonly SAVED_VIEW_FILTER_CORRUPT: {
         readonly exitCode: 1;
         readonly description: "A stored saved view filter is corrupt.";
@@ -451,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.";