incur 0.3.5 → 0.3.7

package/dist/Cli.js

@@ -1,12 +1,16 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { estimateTokenCount, sliceByTokens } from 'tokenx';
 import * as Completions from './Completions.js';
-import { IncurError, ValidationError } from './Errors.js';
+import { IncurError, ParseError, ValidationError } from './Errors.js';
 import * as Fetch from './Fetch.js';
 import * as Filter from './Filter.js';
 import * as Formatter from './Formatter.js';
 import * as Help from './Help.js';
 import { builtinCommands, shells } from './internal/command.js';
 import * as Command from './internal/command.js';
+import { isRecord, suggest } from './internal/helpers.js';
 import { detectRunner } from './internal/pm.js';
 import * as Mcp from './Mcp.js';
 import * as Openapi from './Openapi.js';
@@ -93,6 +97,7 @@ export function create(nameOrDefinition, definition) {
             return serveImpl(name, commands, argv, {
                 ...serveOptions,
                 aliases: def.aliases,
+                config: def.config,
                 description: def.description,
                 envSchema: def.env,
                 format: def.format,
@@ -113,6 +118,10 @@ export function create(nameOrDefinition, definition) {
     };
     if (rootDef)
         toRootDefinition.set(cli, rootDef);
+    if (def.options)
+        toRootOptions.set(cli, def.options);
+    if (def.config !== undefined)
+        toConfigEnabled.set(cli, true);
     if (def.outputPolicy)
         toOutputPolicy.set(cli, def.outputPolicy);
     toMiddlewares.set(cli, middlewares);
@@ -124,7 +133,26 @@ export function create(nameOrDefinition, definition) {
 async function serveImpl(name, commands, argv, options = {}) {
     const stdout = options.stdout ?? ((s) => process.stdout.write(s));
     const exit = options.exit ?? ((code) => process.exit(code));
-    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, rest: filtered, } = extractBuiltinFlags(argv);
+    const human = process.stdout.isTTY === true;
+    const configEnabled = options.config !== undefined;
+    const configFlag = options.config?.flag;
+    function writeln(s) {
+        stdout(s.endsWith('\n') ? s : `${s}\n`);
+    }
+    let builtinFlags;
+    try {
+        builtinFlags = extractBuiltinFlags(argv, { configFlag });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (human)
+            writeln(formatHumanError({ code: 'UNKNOWN', message }));
+        else
+            writeln(Formatter.format({ code: 'UNKNOWN', message }, 'toon'));
+        exit(1);
+        return;
+    }
+    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = builtinFlags;
     // --mcp: start as MCP stdio server
     if (mcpFlag) {
         await Mcp.serve(name, options.version ?? '0.0.0', commands, {
@@ -176,12 +204,8 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         return;
     }
-    // Human mode: stdout is a TTY.
-    const human = process.stdout.isTTY === true;
-    function writeln(s) {
-        stdout(s.endsWith('\n') ? s : `${s}\n`);
-    }
     // Skills staleness check (skip for built-in commands)
+    let skillsCta;
     if (!llms && !llmsFull && !schema && !help && !version) {
         const isSkillsAdd = filtered[0] === 'skills' || (filtered[0] === name && filtered[1] === 'skills');
         const isMcpAdd = filtered[0] === 'mcp' || (filtered[0] === name && filtered[1] === 'mcp');
@@ -193,7 +217,10 @@ async function serveImpl(name, commands, argv, options = {}) {
                 if (Skill.hash(entries) !== stored) {
                     const runner = detectRunner();
                     const spec = SyncMcp.detectPackageSpecifier(name);
-                    process.stderr.write(`⚠ Skills are out of date. Run '${runner} ${spec} skills add' to update.\n\n`);
+                    skillsCta = {
+                        description: 'Skills are out of date:',
+                        commands: [{ command: `${runner} ${spec} skills add`, description: 'sync outdated skills' }],
+                    };
                 }
             }
         }
@@ -278,7 +305,28 @@ async function serveImpl(name, commands, argv, options = {}) {
     // skills add: generate skill files and install via `<pm>x skills add` (only when sync is configured)
     const skillsIdx = filtered[0] === 'skills' ? 0 : filtered[0] === name && filtered[1] === 'skills' ? 1 : -1;
     if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills') {
-        if (filtered[skillsIdx + 1] !== 'add') {
+        const skillsSub = filtered[skillsIdx + 1];
+        if (skillsSub && skillsSub !== 'add') {
+            const suggestion = suggest(skillsSub, ['add']);
+            const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
+            const message = `'${skillsSub}' is not a command for '${name} skills'.${didYouMean}`;
+            const ctaCommands = [];
+            if (suggestion) {
+                const corrected = argv.map((t) => (t === skillsSub ? suggestion : t));
+                ctaCommands.push({ command: `${name} ${corrected.join(' ')}` });
+            }
+            ctaCommands.push({ command: `${name} skills --help`, description: 'see all available commands' });
+            const cta = { description: 'Next steps:', commands: ctaCommands };
+            if (human) {
+                writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }));
+                writeln(formatHumanCta(cta));
+            }
+            else
+                writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'));
+            exit(1);
+            return;
+        }
+        if (!skillsSub) {
             const b = builtinCommands.find((c) => c.name === 'skills');
             writeln(formatBuiltinHelp(name, b));
             return;
@@ -345,7 +393,28 @@ async function serveImpl(name, commands, argv, options = {}) {
     // mcp add: register CLI as MCP server via `npx add-mcp`
     const mcpIdx = filtered[0] === 'mcp' ? 0 : filtered[0] === name && filtered[1] === 'mcp' ? 1 : -1;
     if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp') {
-        if (filtered[mcpIdx + 1] !== 'add') {
+        const mcpSub = filtered[mcpIdx + 1];
+        if (mcpSub && mcpSub !== 'add') {
+            const suggestion = suggest(mcpSub, ['add']);
+            const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
+            const message = `'${mcpSub}' is not a command for '${name} mcp'.${didYouMean}`;
+            const ctaCommands = [];
+            if (suggestion) {
+                const corrected = argv.map((t) => (t === mcpSub ? suggestion : t));
+                ctaCommands.push({ command: `${name} ${corrected.join(' ')}` });
+            }
+            ctaCommands.push({ command: `${name} mcp --help`, description: 'see all available commands' });
+            const cta = { description: 'Next steps:', commands: ctaCommands };
+            if (human) {
+                writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }));
+                writeln(formatHumanCta(cta));
+            }
+            else
+                writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'));
+            exit(1);
+            return;
+        }
+        if (!mcpSub) {
             const b = builtinCommands.find((c) => c.name === 'mcp');
             writeln(formatBuiltinHelp(name, b));
             return;
@@ -412,6 +481,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatCommand(name, {
                 alias: cmd.alias,
                 aliases: options.aliases,
+                configFlag,
                 description: cmd.description ?? options.description,
                 version: options.version,
                 args: cmd.args,
@@ -432,6 +502,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         else {
             writeln(Help.formatRoot(name, {
                 aliases: options.aliases,
+                configFlag,
                 description: options.description,
                 version: options.version,
                 commands: collectHelpCommands(commands),
@@ -474,6 +545,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 writeln(Help.formatCommand(name, {
                     alias: cmd.alias,
                     aliases: options.aliases,
+                    configFlag,
                     description: cmd.description ?? options.description,
                     version: options.version,
                     args: cmd.args,
@@ -490,6 +562,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             else {
                 writeln(Help.formatRoot(helpName, {
                     aliases: isRoot ? options.aliases : undefined,
+                    configFlag,
                     description: helpDesc,
                     version: isRoot ? options.version : undefined,
                     commands: collectHelpCommands(helpCmds),
@@ -507,6 +580,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatCommand(commandName, {
                 alias: cmd.alias,
                 aliases: isRootCmd ? options.aliases : undefined,
+                configFlag,
                 description: cmd.description,
                 version: isRootCmd ? options.version : undefined,
                 args: cmd.args,
@@ -526,6 +600,7 @@ async function serveImpl(name, commands, argv, options = {}) {
     if (schema) {
         if ('help' in resolved) {
             writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+                configFlag,
                 description: resolved.description,
                 commands: collectHelpCommands(resolved.commands),
             }));
@@ -533,7 +608,9 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         if ('error' in resolved) {
             const parent = resolved.path ? `${name} ${resolved.path}` : name;
-            writeln(`Error: '${resolved.error}' is not a command for '${parent}'.`);
+            const suggestion = suggest(resolved.error, resolved.commands.keys());
+            const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
+            writeln(`Error: '${resolved.error}' is not a command for '${parent}'.${didYouMean}`);
             exit(1);
             return;
         }
@@ -558,6 +635,7 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     if ('help' in resolved) {
         writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+            configFlag,
             description: resolved.description,
             commands: collectHelpCommands(resolved.commands),
         }));
@@ -606,6 +684,21 @@ async function serveImpl(name, commands, argv, options = {}) {
     function write(output) {
         if (filterPaths && output.ok && output.data != null)
             output = { ...output, data: Filter.apply(output.data, filterPaths) };
+        if (skillsCta) {
+            const existing = output.meta.cta;
+            output = {
+                ...output,
+                meta: {
+                    ...output.meta,
+                    cta: existing
+                        ? {
+                            description: existing.description,
+                            commands: [...existing.commands, ...skillsCta.commands],
+                        }
+                        : skillsCta,
+                },
+            };
+        }
         if (tokenCount) {
             const base = output.ok ? output.data : output.error;
             const formatted = base != null ? Formatter.format(base, format) : '';
@@ -658,14 +751,26 @@ async function serveImpl(name, commands, argv, options = {}) {
     if ('error' in effective) {
         const helpCmd = effective.path ? `${name} ${effective.path} --help` : `${name} --help`;
         const parent = effective.path ? `${name} ${effective.path}` : name;
-        const message = `'${effective.error}' is not a command for '${parent}'.`;
-        const cta = {
-            description: 'See available commands:',
-            commands: [{ command: helpCmd }],
-        };
+        const candidates = 'commands' in effective ? [...effective.commands.keys()] : [];
+        if (!effective.path)
+            for (const b of builtinCommands)
+                candidates.push(b.name);
+        const suggestion = suggest(effective.error, candidates);
+        const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
+        const message = `'${effective.error}' is not a command for '${parent}'.${didYouMean}`;
+        const ctaCommands = [];
+        if (suggestion) {
+            const corrected = argv.map((t) => (t === effective.error ? suggestion : t));
+            ctaCommands.push({ command: `${name} ${corrected.join(' ')}` });
+        }
+        ctaCommands.push({ command: helpCmd, description: 'see all available commands' });
+        const cta = { description: 'Next steps:', commands: ctaCommands };
         if (human && !verbose) {
             writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }));
-            writeln(formatHumanCta(cta));
+            const mergedCta = skillsCta
+                ? { ...cta, commands: [...cta.commands, ...skillsCta.commands] }
+                : cta;
+            writeln(formatHumanCta(mergedCta));
             exit(1);
             return;
         }
@@ -817,9 +922,33 @@ async function serveImpl(name, commands, argv, options = {}) {
     ];
     if (human)
         emitDeprecationWarnings(rest, command.options, command.alias);
+    let defaults;
+    if (configEnabled) {
+        try {
+            defaults = await loadCommandOptionDefaults(name, path, {
+                configDisabled,
+                configPath,
+                files: options.config?.files,
+                loader: options.config?.loader,
+            });
+        }
+        catch (error) {
+            write({
+                ok: false,
+                error: {
+                    code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+                meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
+            });
+            exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
+            return;
+        }
+    }
     const result = await Command.execute(command, {
         agent: !human,
         argv: rest,
+        defaults,
         env: options.envSchema,
         envSource: options.env,
         format,
@@ -868,7 +997,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(formatHumanValidationError(name, path, command, new ValidationError({
                 message: result.error.message,
                 fieldErrors: result.error.fieldErrors,
-            }), options.env));
+            }), options.env, configFlag));
             exit(1);
             return;
         }
@@ -1008,15 +1137,19 @@ async function fetchImpl(name, commands, req, options = {}) {
         }, 404);
     }
     const resolved = resolveCommand(commands, segments);
-    if ('error' in resolved)
+    if ('error' in resolved) {
+        const parent = resolved.path ? `${name} ${resolved.path}` : name;
+        const suggestion = suggest(resolved.error, resolved.commands.keys());
+        const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
         return jsonResponse({
             ok: false,
             error: {
                 code: 'COMMAND_NOT_FOUND',
-                message: `'${resolved.error}' is not a command for '${resolved.path ? `${name} ${resolved.path}` : name}'.`,
+                message: `'${resolved.error}' is not a command for '${parent}'.${didYouMean}`,
             },
             meta: { command: resolved.error, duration: `${Math.round(performance.now() - start)}ms` },
         }, 404);
+    }
     if ('help' in resolved)
         return jsonResponse({
             ok: false,
@@ -1126,7 +1259,7 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
     }, 200);
 }
 /** @internal Formats a validation error for TTY with usage hint. */
-function formatHumanValidationError(cli, path, command, error, envSource) {
+function formatHumanValidationError(cli, path, command, error, envSource, configFlag) {
     const lines = [];
     for (const fe of error.fieldErrors)
         lines.push(`Error: missing required argument <${fe.path}>`);
@@ -1134,6 +1267,7 @@ function formatHumanValidationError(cli, path, command, error, envSource) {
     lines.push('');
     lines.push(Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
         alias: command.alias,
+        configFlag,
         description: command.description,
         args: command.args,
         env: command.env,
@@ -1149,7 +1283,7 @@ function formatHumanValidationError(cli, path, command, error, envSource) {
 function resolveCommand(commands, tokens) {
     const [first, ...rest] = tokens;
     if (!first || !commands.has(first))
-        return { error: first ?? '(none)', path: '' };
+        return { error: first ?? '(none)', path: '', commands, rest };
     let entry = commands.get(first);
     const path = [first];
     let remaining = rest;
@@ -1181,7 +1315,7 @@ function resolveCommand(commands, tokens) {
             };
         const child = entry.commands.get(next);
         if (!child) {
-            return { error: next, path: path.join(' ') };
+            return { error: next, path: path.join(' '), commands: entry.commands, rest: remaining.slice(1) };
         }
         path.push(next);
         remaining = remaining.slice(1);
@@ -1207,7 +1341,7 @@ function resolveCommand(commands, tokens) {
     };
 }
 /** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
-function extractBuiltinFlags(argv) {
+function extractBuiltinFlags(argv, options = {}) {
     let verbose = false;
     let llms = false;
     let llmsFull = false;
@@ -1217,11 +1351,16 @@ function extractBuiltinFlags(argv) {
     let schema = false;
     let format = 'toon';
     let formatExplicit = false;
+    let configPath;
+    let configDisabled = false;
     let filterOutput;
     let tokenLimit;
     let tokenOffset;
     let tokenCount = false;
     const rest = [];
+    const cfgFlag = options.configFlag ? `--${options.configFlag}` : undefined;
+    const cfgFlagEq = options.configFlag ? `--${options.configFlag}=` : undefined;
+    const noCfgFlag = options.configFlag ? `--no-${options.configFlag}` : undefined;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
         if (token === '--verbose')
@@ -1247,6 +1386,25 @@ function extractBuiltinFlags(argv) {
             formatExplicit = true;
             i++;
         }
+        else if (cfgFlag && token === cfgFlag) {
+            const value = argv[i + 1];
+            if (value === undefined)
+                throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` });
+            configPath = value;
+            configDisabled = false;
+            i++;
+        }
+        else if (cfgFlagEq && token.startsWith(cfgFlagEq)) {
+            const value = token.slice(cfgFlagEq.length);
+            if (value.length === 0)
+                throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` });
+            configPath = value;
+            configDisabled = false;
+        }
+        else if (noCfgFlag && token === noCfgFlag) {
+            configPath = undefined;
+            configDisabled = true;
+        }
         else if (token === '--filter-output' && argv[i + 1]) {
             filterOutput = argv[i + 1];
             i++;
@@ -1268,6 +1426,8 @@ function extractBuiltinFlags(argv) {
         verbose,
         format,
         formatExplicit,
+        configPath,
+        configDisabled,
         filterOutput,
         tokenLimit,
         tokenOffset,
@@ -1281,6 +1441,117 @@ function extractBuiltinFlags(argv) {
         rest,
     };
 }
+/** @internal Loads config-backed option defaults for the active command. */
+async function loadCommandOptionDefaults(cli, path, options = {}) {
+    if (options.configDisabled)
+        return undefined;
+    const { loader } = options;
+    // Resolve the target file path
+    let targetPath;
+    if (options.configPath) {
+        targetPath = resolveConfigPath(options.configPath);
+    }
+    else {
+        const searchPaths = options.files ?? [`${cli}.json`];
+        targetPath = await findFirstExisting(searchPaths);
+    }
+    // Load and parse the config
+    let parsed;
+    if (loader) {
+        const result = await loader(targetPath);
+        if (result === undefined)
+            return undefined;
+        if (!isRecord(result))
+            throw new ParseError({ message: 'Config loader must return a plain object or undefined' });
+        parsed = result;
+    }
+    else {
+        if (!targetPath)
+            return undefined;
+        const result = await readJsonConfig(targetPath, !!options.configPath);
+        if (!result)
+            return undefined;
+        parsed = result;
+    }
+    // Extract the command section from the config tree
+    return extractCommandSection(parsed, cli, path);
+}
+/** @internal Resolves a config file path, expanding `~` to home dir. */
+function resolveConfigPath(filePath) {
+    if (filePath.startsWith('~/') || filePath === '~') {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return path.resolve(process.cwd(), filePath);
+}
+/** @internal Returns the first readable file from a list of paths, or `undefined`. */
+async function findFirstExisting(paths) {
+    for (const p of paths) {
+        const resolved = resolveConfigPath(p);
+        try {
+            await fs.access(resolved, fs.constants.R_OK);
+            return resolved;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** @internal Reads and parses a JSON config file. */
+async function readJsonConfig(targetPath, explicit) {
+    let raw;
+    try {
+        raw = await fs.readFile(targetPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            if (explicit)
+                throw new ParseError({ message: `Config file not found: ${targetPath}` });
+            return undefined;
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ParseError({
+            message: `Invalid JSON config file: ${targetPath}`,
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (!isRecord(parsed))
+        throw new ParseError({
+            message: `Invalid config file: expected a top-level object in ${targetPath}`,
+        });
+    return parsed;
+}
+/** @internal Walks the nested config tree to extract option defaults for a command path. */
+function extractCommandSection(parsed, cli, path) {
+    const segments = path === cli ? [] : path.split(' ');
+    let node = parsed;
+    for (const seg of segments) {
+        if (!isRecord(node))
+            return undefined;
+        const commands = node.commands;
+        if (!isRecord(commands))
+            return undefined;
+        node = commands[seg];
+        if (node === undefined)
+            return undefined;
+    }
+    if (!isRecord(node))
+        throw new ParseError({
+            message: `Invalid config section for '${path}': expected an object`,
+        });
+    const options = node.options;
+    if (options === undefined)
+        return undefined;
+    if (!isRecord(options))
+        throw new ParseError({
+            message: `Invalid config 'options' for '${path}': expected an object`,
+        });
+    return Object.keys(options).length > 0 ? options : undefined;
+}
 /** @internal Collects immediate child commands/groups for help output. */
 function collectHelpCommands(commands) {
     const result = [];
@@ -1339,7 +1610,11 @@ export const toCommands = new WeakMap();
 /** @internal Maps CLI instances to their middleware arrays. */
 const toMiddlewares = new WeakMap();
 /** @internal Maps root CLI instances to their command definitions. */
-const toRootDefinition = new WeakMap();
+export const toRootDefinition = new WeakMap();
+/** @internal Maps CLI instances to their root options schema. */
+export const toRootOptions = new WeakMap();
+/** @internal Maps CLI instances to whether config file loading is enabled. */
+export const toConfigEnabled = new WeakMap();
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap();
 /** @internal Sentinel symbol for `ok()` and `error()` return values. */