@dinoxx/dinox-cli 2.14.0 → 2.16.0

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[];
+};

package/dist/utils/select.js

@@ -0,0 +1,92 @@
+import { DinoxError } from './errors.js';
+const FIELD_PATH = /^[A-Za-z0-9_$-]+(\.[A-Za-z0-9_$-]+)*$/;
+/**
+ * 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 function parseFieldSelection(value) {
+    const raw = Array.isArray(value) ? value.join(',') : String(value ?? '');
+    const paths = raw.split(',').map((path) => path.trim()).filter(Boolean);
+    if (paths.length === 0) {
+        throw new DinoxError('--select needs at least one field path, e.g. --select notes.id,notes.title', {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+        });
+    }
+    const selection = {};
+    for (const path of paths) {
+        if (!FIELD_PATH.test(path)) {
+            throw new DinoxError(`Invalid --select field path: ${path}`, {
+                code: 'INVALID_ARGUMENT',
+                recoverable: true,
+                suggestion: 'Use dot-separated output field names from `dino schema <command> --format json`.',
+            });
+        }
+        let node = selection;
+        const segments = path.split('.');
+        segments.forEach((segment, index) => {
+            if (node[segment] === true)
+                return;
+            if (index === segments.length - 1) {
+                node[segment] = true;
+                return;
+            }
+            node[segment] ??= {};
+            node = node[segment];
+        });
+    }
+    return selection;
+}
+/**
+ * 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 function projectFields(value, selection) {
+    const matched = new Set();
+    // Paths below an empty list or a null value cannot be checked; never report them.
+    const assumeMatched = (node, prefix) => {
+        for (const [key, child] of Object.entries(node)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            matched.add(path);
+            if (child !== true)
+                assumeMatched(child, path);
+        }
+    };
+    const project = (current, node, prefix) => {
+        if (Array.isArray(current)) {
+            if (current.length === 0)
+                assumeMatched(node, prefix);
+            return current.map((item) => project(item, node, prefix));
+        }
+        if (!current || typeof current !== 'object') {
+            assumeMatched(node, prefix);
+            return current;
+        }
+        const record = current;
+        const result = {};
+        for (const [key, child] of Object.entries(node)) {
+            if (!Object.prototype.hasOwnProperty.call(record, key))
+                continue;
+            const path = prefix ? `${prefix}.${key}` : key;
+            matched.add(path);
+            result[key] = child === true ? record[key] : project(record[key], child, path);
+        }
+        return result;
+    };
+    const projected = project(value, selection, '');
+    const missing = [];
+    const collect = (node, prefix) => {
+        for (const [key, child] of Object.entries(node)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (!matched.has(path))
+                missing.push(path);
+            else if (child !== true)
+                collect(child, path);
+        }
+    };
+    collect(selection, '');
+    return { value: projected, missing };
+}

package/dist/utils/usageError.d.ts

@@ -0,0 +1,37 @@
+import type { Command } from 'commander';
+import type { SuggestedAction } from './errors.js';
+export type UsageErrorKind = 'unknown_option' | 'unknown_command' | 'missing_argument' | 'missing_option_value' | 'missing_required_option' | 'invalid_option_value' | 'too_many_arguments' | 'usage';
+/** Machine-readable form of a Commander usage error, carried in the error's `details`. */
+export type UsageErrorDetails = {
+    kind: UsageErrorKind;
+    /** The offending option, command, or argument name, when Commander names one. */
+    token: string | null;
+    /** Commander's spelling suggestions, closest first. */
+    did_you_mean: string[];
+    /** Dot path of the deepest command that was recognized, e.g. `note.search`. */
+    command: string | null;
+};
+export type ParsedUsageError = {
+    message: string;
+    details: UsageErrorDetails;
+    suggestion?: string;
+    suggestedAction?: SuggestedAction;
+};
+type ResolvedCommand = {
+    /** Names of the recognized commands, outermost first. */
+    path: string[];
+    command: Command;
+    /** The first word that did not name a subcommand of `command`. */
+    unmatched: string | null;
+};
+/** Walks argv through the command tree as far as it names commands. */
+export declare function resolveCommand(program: Command, argv: string[]): ResolvedCommand;
+/** Closest candidates, using the same thresholds as Commander's own suggestions. */
+export declare function suggestSimilar(word: string, candidates: string[]): string[];
+/**
+ * Turns Commander's error text ("error: unknown option '--limt'\n(Did you mean
+ * --limit?)") into a message, structured details and, when there is exactly
+ * one suggestion, the corrected command line an agent can run.
+ */
+export declare function parseCommanderUsageError(text: string, argv: string[], program: Command): ParsedUsageError;
+export {};

package/dist/utils/usageError.js

@@ -0,0 +1,127 @@
+import { GLOBAL_VALUE_OPTIONS } from '../commands/schema/globalOptions.js';
+const PATTERNS = [
+    ['unknown_option', /^unknown option '([^']+)'/],
+    ['unknown_command', /^unknown command '([^']+)'/],
+    ['missing_argument', /^missing required argument '([^']+)'/],
+    ['missing_option_value', /^option '([^']+)' argument missing/],
+    ['missing_required_option', /^required option '([^']+)' not specified/],
+    ['invalid_option_value', /^option '([^']+)' argument '.*' is invalid/s],
+    ['too_many_arguments', /^too many arguments/],
+];
+/** Walks argv through the command tree as far as it names commands. */
+export function resolveCommand(program, argv) {
+    const path = [];
+    let current = program;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--')
+            break;
+        if (GLOBAL_VALUE_OPTIONS.includes(arg)) {
+            i++;
+            continue;
+        }
+        if (arg.startsWith('-'))
+            continue;
+        const next = current.commands.find((command) => command.name() === arg || command.aliases().includes(arg));
+        if (!next)
+            return { path, command: current, unmatched: arg };
+        path.push(next.name());
+        current = next;
+    }
+    return { path, command: current, unmatched: null };
+}
+/** Optimal string alignment distance (Damerau-Levenshtein with adjacent transpositions). */
+function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return d[a.length][b.length];
+}
+/** Closest candidates, using the same thresholds as Commander's own suggestions. */
+export function suggestSimilar(word, candidates) {
+    let best = 3;
+    let similar = [];
+    for (const candidate of new Set(candidates)) {
+        if (candidate.length <= 1)
+            continue;
+        const distance = editDistance(word, candidate);
+        const length = Math.max(word.length, candidate.length);
+        if ((length - distance) / length <= 0.4)
+            continue;
+        if (distance < best) {
+            best = distance;
+            similar = [candidate];
+        }
+        else if (distance === best) {
+            similar.push(candidate);
+        }
+    }
+    return similar.sort((a, b) => a.localeCompare(b));
+}
+function shellQuote(arg) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Turns Commander's error text ("error: unknown option '--limt'\n(Did you mean
+ * --limit?)") into a message, structured details and, when there is exactly
+ * one suggestion, the corrected command line an agent can run.
+ */
+export function parseCommanderUsageError(text, argv, program) {
+    const body = text.trim().replace(/^error:\s*/i, '');
+    const suggestionMatch = /\n?\(Did you mean (?:one of )?(.+)\?\)\s*$/.exec(body);
+    let message = (suggestionMatch ? body.slice(0, suggestionMatch.index) : body).trim();
+    let didYouMean = suggestionMatch ? suggestionMatch[1].split(',').map((item) => item.trim()).filter(Boolean) : [];
+    const resolved = resolveCommand(program, argv);
+    let kind = 'usage';
+    let token = null;
+    for (const [candidate, pattern] of PATTERNS) {
+        const match = pattern.exec(message);
+        if (match) {
+            kind = candidate;
+            token = match[1] ?? null;
+            break;
+        }
+    }
+    // A command group with its own action reports a mistyped subcommand as an
+    // extra argument; report it as the unknown command it is.
+    if (resolved.command.commands.length > 0 && resolved.unmatched && (kind === 'too_many_arguments' || kind === 'unknown_command')) {
+        kind = 'unknown_command';
+        token = resolved.unmatched;
+        message = `unknown command '${token}'${resolved.path.length > 0 ? ` for 'dino ${resolved.path.join(' ')}'` : ''}`;
+    }
+    if (kind === 'unknown_command' && token) {
+        didYouMean = suggestSimilar(token, resolved.command.commands.flatMap((command) => [command.name(), ...command.aliases()]));
+    }
+    const command = resolved.path.length > 0 ? resolved.path.join('.') : null;
+    const details = { kind, token, did_you_mean: didYouMean, command };
+    // Only leaf commands have a schema of their own; the bare form lists them all.
+    const schemaHint = command && resolved.command.commands.length === 0
+        ? `dino schema ${command} --format json`
+        : 'dino schema --format json';
+    const parsed = {
+        message,
+        details,
+        suggestion: didYouMean.length > 0
+            ? `Did you mean ${didYouMean.join(' or ')}? Run \`${schemaHint}\` to list valid ${kind === 'unknown_command' ? 'commands' : 'options'}.`
+            : `Run \`${schemaHint}\` for the valid arguments and options.`,
+    };
+    const index = token ? argv.indexOf(token) : -1;
+    if (didYouMean.length === 1 && index !== -1 && (kind === 'unknown_option' || kind === 'unknown_command')) {
+        const corrected = [...argv];
+        corrected[index] = didYouMean[0];
+        parsed.suggestedAction = {
+            command: `dino ${corrected.map(shellQuote).join(' ')}`,
+            reason: `${token} is not a valid ${kind === 'unknown_option' ? 'option' : 'command'}; ${didYouMean[0]} is the closest match.`,
+        };
+    }
+    return parsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {