@dinoxx/dinox-cli 2.14.0 → 2.15.0

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.15.0",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {