@orchagent/cli 0.3.118 → 0.3.120

package/dist/lib/command-introspection.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenizeCommandQuery = tokenizeCommandQuery;
+exports.buildCliCommandMetadata = buildCliCommandMetadata;
+exports.findCommandMetadata = findCommandMetadata;
+exports.collectFlagNames = collectFlagNames;
+const MUTATING_TOKENS = new Set([
+    'add',
+    'clear',
+    'connect',
+    'create',
+    'delete',
+    'deploy',
+    'disconnect',
+    'fork',
+    'install',
+    'invite',
+    'login',
+    'logout',
+    'publish',
+    'remove',
+    'revoke',
+    'rotate',
+    'set',
+    'trigger',
+    'transfer',
+    'unlink',
+    'unset',
+    'update',
+    'use',
+]);
+function normalizeToken(value) {
+    return value.trim().toLowerCase();
+}
+function parseAliasTarget(description) {
+    const match = description.match(/^\s*alias for\s+(--[a-z0-9][a-z0-9-]*)(?:\.)?\s*$/i);
+    if (!match)
+        return null;
+    return match[1].toLowerCase();
+}
+function extractOptionAliases(options) {
+    const aliasOptions = new Set();
+    const aliasesByPrimary = new Map();
+    for (const option of options) {
+        if (!option.long)
+            continue;
+        const primary = parseAliasTarget(option.description || '');
+        if (!primary)
+            continue;
+        const aliasName = option.long.toLowerCase();
+        if (aliasName === primary)
+            continue;
+        aliasOptions.add(aliasName);
+        const existing = aliasesByPrimary.get(primary) || [];
+        existing.push(option.long);
+        aliasesByPrimary.set(primary, existing);
+    }
+    return { aliasOptions, aliasesByPrimary };
+}
+function getFlagType(option) {
+    if (option.isBoolean())
+        return 'boolean';
+    if (option.variadic)
+        return 'string[]';
+    return 'string';
+}
+function inferArgumentFormat(pathSegments, argument) {
+    const name = argument.name().toLowerCase();
+    const path = pathSegments.join(' ').toLowerCase();
+    if (name === 'agent' || name.endsWith('agent')) {
+        return 'org/name[@version]';
+    }
+    if (name === 'command') {
+        return 'command [subcommand...]';
+    }
+    if (name === 'shell') {
+        return 'bash | zsh | fish';
+    }
+    if (name === 'json' || name === 'data' || name === 'input' || name.includes('json')) {
+        return 'inline-json | @file | @-';
+    }
+    if (name.includes('file') || name.includes('path') || name.includes('dir')) {
+        return 'path';
+    }
+    if (path === 'run' && name === 'agent') {
+        return 'org/name[@version]';
+    }
+    return argument.variadic ? `${argument.name()}...` : argument.name();
+}
+function extractArguments(pathSegments, args) {
+    return args.map((arg) => ({
+        name: arg.name(),
+        required: arg.required,
+        variadic: arg.variadic,
+        description: arg.description || '',
+        format: inferArgumentFormat(pathSegments, arg),
+    }));
+}
+function extractFlags(options) {
+    const { aliasOptions, aliasesByPrimary } = extractOptionAliases(options);
+    const flags = [];
+    for (const option of options) {
+        if (option.hidden)
+            continue;
+        if (!option.long && !option.short)
+            continue;
+        if (option.long && aliasOptions.has(option.long.toLowerCase()))
+            continue;
+        if (option.long === '--help')
+            continue;
+        const aliases = option.long
+            ? aliasesByPrimary.get(option.long.toLowerCase()) || []
+            : [];
+        flags.push({
+            name: option.long || option.short,
+            short: option.short || null,
+            type: getFlagType(option),
+            required: option.mandatory,
+            valueRequired: option.required,
+            description: option.description || '',
+            ...(option.defaultValue !== undefined ? { defaultValue: option.defaultValue } : {}),
+            ...(option.argChoices ? { choices: option.argChoices } : {}),
+            ...(aliases.length > 0 ? { alias: aliases[0] } : {}),
+        });
+    }
+    return flags;
+}
+function renderHelpText(command) {
+    const internal = command;
+    const original = internal._outputConfiguration;
+    let output = '';
+    internal._outputConfiguration = {
+        ...original,
+        writeOut: (str) => {
+            output += str;
+        },
+        writeErr: (str) => {
+            output += str;
+        },
+    };
+    try {
+        command.outputHelp();
+    }
+    finally {
+        internal._outputConfiguration = original;
+    }
+    return output;
+}
+function extractExamples(command) {
+    const helpText = renderHelpText(command);
+    const examples = helpText
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => /^(orch|orchagent)\s+\S+/.test(line));
+    return [...new Set(examples)];
+}
+function isMutatingSelf(pathSegments, description, flags) {
+    if (flags.some((flag) => flag.name === '--dry-run')) {
+        return true;
+    }
+    const tokens = pathSegments
+        .map((segment) => normalizeToken(segment))
+        .flatMap((segment) => segment.split(/[^a-z0-9]+/g))
+        .filter(Boolean);
+    if (tokens.some((token) => MUTATING_TOKENS.has(token))) {
+        return true;
+    }
+    const desc = description.toLowerCase();
+    return /\b(add|create|delete|deploy|fork|install|invite|login|logout|publish|remove|revoke|set|transfer|trigger|unset|update|use)\b/.test(desc);
+}
+function buildUsage(pathSegments, command) {
+    const base = pathSegments.join(' ');
+    const usage = command.usage();
+    if (!usage)
+        return base;
+    return `${base} ${usage}`.trim();
+}
+function buildCommandMetadata(command, parentPath) {
+    const pathSegments = [...parentPath, command.name()];
+    const subcommands = command.commands
+        .filter((subcommand) => subcommand.name() !== 'help')
+        .map((subcommand) => buildCommandMetadata(subcommand, pathSegments));
+    const flags = extractFlags(command.options);
+    const selfMutating = isMutatingSelf(pathSegments, command.description(), flags);
+    const childMutating = subcommands.some((subcommand) => subcommand.mutations);
+    const hasDryRun = flags.some((flag) => flag.name === '--dry-run') || subcommands.some((subcommand) => subcommand.dryRun);
+    return {
+        name: command.name(),
+        path: pathSegments.join(' '),
+        description: command.description() || '',
+        usage: buildUsage(pathSegments, command),
+        aliases: command.aliases(),
+        arguments: extractArguments(pathSegments, command.registeredArguments),
+        flags,
+        subcommands,
+        mutations: selfMutating || childMutating,
+        dryRun: hasDryRun,
+        examples: extractExamples(command),
+    };
+}
+function isCommandMatch(command, token) {
+    const lower = normalizeToken(token);
+    if (command.name.toLowerCase() === lower)
+        return true;
+    return command.aliases.some((alias) => alias.toLowerCase() === lower);
+}
+function tokenizeCommandQuery(parts) {
+    return parts
+        .flatMap((part) => part.split(/[/:.]/g))
+        .map((part) => normalizeToken(part))
+        .filter(Boolean);
+}
+function buildCliCommandMetadata(program, options) {
+    const excluded = new Set((options?.excludeTopLevelCommands || []).map((name) => name.toLowerCase()));
+    return program.commands
+        .filter((command) => command.name() !== 'help')
+        .filter((command) => !excluded.has(command.name().toLowerCase()))
+        .map((command) => buildCommandMetadata(command, []));
+}
+function findCommandMetadata(commands, queryParts) {
+    const tokens = tokenizeCommandQuery(queryParts);
+    if (tokens.length === 0)
+        return null;
+    let currentCommands = commands;
+    let matched = null;
+    for (const token of tokens) {
+        matched = currentCommands.find((command) => isCommandMatch(command, token)) || null;
+        if (!matched) {
+            return null;
+        }
+        currentCommands = matched.subcommands;
+    }
+    return matched;
+}
+function collectFlagNames(command) {
+    const names = new Set();
+    const visit = (node) => {
+        for (const flag of node.flags) {
+            names.add(flag.name);
+            if (flag.alias) {
+                names.add(flag.alias);
+            }
+        }
+        for (const child of node.subcommands) {
+            visit(child);
+        }
+    };
+    visit(command);
+    return [...names].sort();
+}

package/dist/lib/errors.js

@@ -33,16 +33,32 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NetworkError = exports.ExitCodes = exports.CliError = void 0;
+exports.NetworkError = exports.ExitCodes = exports.CliError = exports.ErrorCodes = void 0;
 exports.formatError = formatError;
+exports.formatJsonError = formatJsonError;
 exports.exitWithError = exitWithError;
 exports.mapHttpStatusToExitCode = mapHttpStatusToExitCode;
 exports.jsonInputError = jsonInputError;
 const Sentry = __importStar(require("@sentry/node"));
 const analytics_1 = require("./analytics");
 const api_1 = require("./api");
+const output_1 = require("./output");
+exports.ErrorCodes = {
+    GENERAL_ERROR: 'GENERAL_ERROR',
+    AUTH_REQUIRED: 'AUTH_REQUIRED',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    NOT_FOUND: 'NOT_FOUND',
+    INVALID_INPUT: 'INVALID_INPUT',
+    RATE_LIMITED: 'RATE_LIMITED',
+    TIMEOUT: 'TIMEOUT',
+    SERVER_ERROR: 'SERVER_ERROR',
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    MISSING_SECRETS: 'MISSING_SECRETS',
+};
 class CliError extends Error {
     exitCode;
+    code;
+    hint;
     cause;
     responseBody;
     /** When true, exitWithError skips printing — the message was already shown (e.g. via spinner.fail). */
@@ -96,28 +112,119 @@ function formatError(err) {
     }
     return String(err);
 }
+/** Map an exit code to a default error code string. */
+function exitCodeToErrorCode(exitCode) {
+    switch (exitCode) {
+        case exports.ExitCodes.AUTH_ERROR: return exports.ErrorCodes.AUTH_REQUIRED;
+        case exports.ExitCodes.PERMISSION_DENIED: return exports.ErrorCodes.PERMISSION_DENIED;
+        case exports.ExitCodes.NOT_FOUND: return exports.ErrorCodes.NOT_FOUND;
+        case exports.ExitCodes.INVALID_INPUT: return exports.ErrorCodes.INVALID_INPUT;
+        case exports.ExitCodes.RATE_LIMITED: return exports.ErrorCodes.RATE_LIMITED;
+        case exports.ExitCodes.TIMEOUT: return exports.ErrorCodes.TIMEOUT;
+        case exports.ExitCodes.SERVER_ERROR: return exports.ErrorCodes.SERVER_ERROR;
+        case exports.ExitCodes.NETWORK_ERROR: return exports.ErrorCodes.NETWORK_ERROR;
+        default: return exports.ErrorCodes.GENERAL_ERROR;
+    }
+}
+/** Map an HTTP status code to an error code string. */
+function httpStatusToErrorCode(status) {
+    if (status === 401)
+        return exports.ErrorCodes.AUTH_REQUIRED;
+    if (status === 402 || status === 403)
+        return exports.ErrorCodes.PERMISSION_DENIED;
+    if (status === 404)
+        return exports.ErrorCodes.NOT_FOUND;
+    if (status === 422)
+        return exports.ErrorCodes.INVALID_INPUT;
+    if (status === 429)
+        return exports.ErrorCodes.RATE_LIMITED;
+    if (status >= 500 && status <= 599)
+        return exports.ErrorCodes.SERVER_ERROR;
+    return exports.ErrorCodes.GENERAL_ERROR;
+}
+/**
+ * Build a structured JSON error object from any error.
+ * Output format: { error: true, code: string, message: string, hint?: string, exit_code: number }
+ */
+function formatJsonError(err) {
+    if (err instanceof CliError) {
+        const code = err.code || exitCodeToErrorCode(err.exitCode);
+        return {
+            error: true,
+            code,
+            message: err.message,
+            ...(err.hint ? { hint: err.hint } : {}),
+            exit_code: err.exitCode,
+        };
+    }
+    if (err instanceof api_1.ApiError) {
+        const p = err.payload;
+        const gatewayCode = p?.error?.code;
+        const detail = p?.error?.detail || p?.detail;
+        const code = gatewayCode || httpStatusToErrorCode(err.status);
+        const exitCode = mapHttpStatusToExitCode(err.status);
+        return {
+            error: true,
+            code,
+            message: err.message,
+            ...(typeof detail === 'string' && detail !== err.message ? { hint: detail } : {}),
+            exit_code: exitCode,
+        };
+    }
+    if (err instanceof Error) {
+        const anyErr = err;
+        if (anyErr.status) {
+            const exitCode = mapHttpStatusToExitCode(anyErr.status);
+            return {
+                error: true,
+                code: httpStatusToErrorCode(anyErr.status),
+                message: anyErr.message,
+                exit_code: exitCode,
+            };
+        }
+        return {
+            error: true,
+            code: exports.ErrorCodes.GENERAL_ERROR,
+            message: anyErr.message,
+            exit_code: 1,
+        };
+    }
+    return {
+        error: true,
+        code: exports.ErrorCodes.GENERAL_ERROR,
+        message: String(err),
+        exit_code: 1,
+    };
+}
 async function exitWithError(err) {
-    const message = formatError(err);
     // Report to Sentry if it's a real error (not a CliError which is expected)
     if (!(err instanceof CliError) && process.env.SENTRY_DSN) {
         Sentry.captureException(err);
     }
     // Flush PostHog before exiting
     await (0, analytics_1.shutdownPostHog)();
+    // Determine exit code
+    let exitCode = 1;
+    if (err instanceof CliError) {
+        exitCode = err.exitCode;
+    }
+    else if (err instanceof api_1.ApiError) {
+        exitCode = mapHttpStatusToExitCode(err.status);
+    }
     // Skip printing if the error was already shown (e.g. by spinner.fail)
     const alreadyDisplayed = (err instanceof CliError && err.displayed) ||
         (err instanceof Error && err._displayed);
     if (!alreadyDisplayed) {
-        process.stderr.write(`${message}\n`);
-    }
-    if (err instanceof CliError) {
-        process.exit(err.exitCode);
-    }
-    // Handle API errors with proper exit codes
-    if (err instanceof api_1.ApiError) {
-        process.exit(mapHttpStatusToExitCode(err.status));
+        if ((0, output_1.isJsonMode)()) {
+            const jsonErr = formatJsonError(err);
+            process.stdout.write(`${JSON.stringify(jsonErr, null, 2)}\n`);
+        }
+        else {
+            const message = formatError(err);
+            process.stderr.write(`${message}\n`);
+        }
     }
-    process.exit(1);
+    process.exit(exitCode);
 }
 exports.ExitCodes = {
     SUCCESS: 0,
@@ -152,18 +259,15 @@ function mapHttpStatusToExitCode(status) {
 class NetworkError extends CliError {
     constructor(url, cause) {
         const host = new URL(url).host;
-        super(`Unable to connect to ${host}\n\n` +
-            'Possible causes:\n' +
-            '  - Network connectivity issues\n' +
-            '  - Service temporarily unavailable\n' +
-            '  - Firewall or proxy blocking the request\n\n' +
-            'Check status at: https://status.orchagent.io', exports.ExitCodes.NETWORK_ERROR);
+        super(`Unable to connect to ${host}`, exports.ExitCodes.NETWORK_ERROR);
+        this.code = exports.ErrorCodes.NETWORK_ERROR;
+        this.hint = 'Check network connectivity or status at https://status.orchagent.io';
         this.cause = cause;
     }
 }
 exports.NetworkError = NetworkError;
 function jsonInputError(flag) {
-    return new CliError(`Invalid JSON in --${flag} option.\n\n` +
+    const err = new CliError(`Invalid JSON in --${flag} option.\n\n` +
         'Common causes:\n' +
         '  - Shell special characters (!, $, `) need escaping\n' +
         '  - Missing or mismatched quotes\n\n' +
@@ -174,4 +278,7 @@ function jsonInputError(flag) {
         'Alternatives:\n' +
         `  - Use a file:  --${flag} @input.json\n` +
         `  - Use stdin:   echo '{"key":"value"}' | orch run agent --${flag} @-`, exports.ExitCodes.INVALID_INPUT);
+    err.code = exports.ErrorCodes.INVALID_INPUT;
+    err.hint = `Use a file: --${flag} @input.json`;
+    return err;
 }

package/dist/lib/list-options.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Shared utilities for --fields, --limit, and --offset on list commands.
+ *
+ * --fields: client-side JSON key filtering (implies --json output)
+ * --limit / --offset: pagination (passed to API where supported, applied client-side as fallback)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFields = parseFields;
+exports.filterFields = filterFields;
+exports.applyLimitOffset = applyLimitOffset;
+exports.parseIntOption = parseIntOption;
+/**
+ * Parse a comma-separated fields string into an array of field names.
+ * Trims whitespace and removes empty entries.
+ */
+function parseFields(fieldsStr) {
+    return fieldsStr.split(',').map(f => f.trim()).filter(Boolean);
+}
+/**
+ * Filter an object or array of objects to include only specified fields.
+ *
+ * - Array of objects: filter each object's keys
+ * - Single object: filter top-level keys
+ * - Primitives: return as-is
+ */
+function filterFields(data, fields) {
+    if (Array.isArray(data)) {
+        return data.map(item => item !== null && typeof item === 'object'
+            ? pickKeys(item, fields)
+            : item);
+    }
+    if (data !== null && typeof data === 'object') {
+        return pickKeys(data, fields);
+    }
+    return data;
+}
+function pickKeys(obj, fields) {
+    const result = {};
+    for (const field of fields) {
+        if (field in obj) {
+            result[field] = obj[field];
+        }
+    }
+    return result;
+}
+/**
+ * Apply client-side limit and offset to an array.
+ * Returns a new array (never mutates the input).
+ */
+function applyLimitOffset(items, limit, offset) {
+    const start = offset ?? 0;
+    if (limit != null) {
+        return items.slice(start, start + limit);
+    }
+    if (start > 0) {
+        return items.slice(start);
+    }
+    return items;
+}
+/**
+ * Parse a string number option, returning undefined if invalid or absent.
+ */
+function parseIntOption(value) {
+    if (value == null)
+        return undefined;
+    const n = parseInt(value, 10);
+    return isNaN(n) ? undefined : n;
+}

package/dist/lib/llm.js

@@ -15,6 +15,7 @@ exports.buildPrompt = buildPrompt;
 exports.callLlm = callLlm;
 exports.callLlmWithFallback = callLlmWithFallback;
 exports.validateProvider = validateProvider;
+exports.validateModelIds = validateModelIds;
 exports.detectProviderFromModel = detectProviderFromModel;
 exports.warnProviderModelMismatch = warnProviderModelMismatch;
 const errors_1 = require("./errors");
@@ -267,6 +268,40 @@ function validateProvider(provider) {
         throw new errors_1.CliError(`Invalid provider: ${provider}. Valid: ${validProviders.join(', ')}`);
     }
 }
+/**
+ * Validate model IDs in default_models against known provider patterns.
+ * Returns warnings for unrecognized model IDs (does not error — could be new models).
+ */
+function validateModelIds(defaultModels) {
+    const validProviders = ['openai', 'anthropic', 'gemini', 'ollama'];
+    const warnings = [];
+    for (const [provider, model] of Object.entries(defaultModels)) {
+        if (!validProviders.includes(provider)) {
+            warnings.push({
+                provider,
+                model,
+                message: `Unknown provider "${provider}" in default_models. Valid providers: ${validProviders.join(', ')}`,
+            });
+            continue;
+        }
+        const detectedProvider = detectProviderFromModel(model);
+        if (!detectedProvider) {
+            warnings.push({
+                provider,
+                model,
+                message: `Unrecognized model ID "${model}" for provider "${provider}". This may cause a 404 at runtime.`,
+            });
+        }
+        else if (detectedProvider !== provider) {
+            warnings.push({
+                provider,
+                model,
+                message: `Model "${model}" looks like a ${detectedProvider} model but is set under "${provider}".`,
+            });
+        }
+    }
+    return warnings;
+}
 /**
  * Model-name patterns for auto-detecting the LLM provider.
  * Tested against the lowercased model string.

package/dist/lib/output.js

@@ -1,6 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printJson = printJson;
+exports.setJsonMode = setJsonMode;
+exports.isJsonMode = isJsonMode;
+exports.shouldAutoJson = shouldAutoJson;
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+/** Global JSON-mode flag — set by the preAction hook when --json is active. */
+let _jsonMode = false;
+function setJsonMode(enabled) {
+    _jsonMode = enabled;
+}
+function isJsonMode() {
+    return _jsonMode;
+}
+/**
+ * Determine if the CLI should auto-switch to JSON output.
+ *
+ * Priority (highest wins):
+ * 1. Explicit --json flag on the command → true (handled by Commander, not here)
+ * 2. ORCHAGENT_OUTPUT=json env var → true
+ * 3. ORCHAGENT_OUTPUT=text env var → false (override non-TTY auto-detection)
+ * 4. stdout is not a TTY (piped, redirected, or run by an agent) → true
+ * 5. stdout is a TTY (human terminal) → false
+ */
+function shouldAutoJson() {
+    const outputEnv = process.env.ORCHAGENT_OUTPUT?.toLowerCase();
+    if (outputEnv === 'json')
+        return true;
+    if (outputEnv === 'text')
+        return false;
+    return !process.stdout.isTTY;
+}