steroids-cli 0.4.47

package/dist/cli/flags.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Global flags parser for Steroids CLI
+ *
+ * Parses global flags that apply to all commands:
+ * - Output format: --json, --quiet, --verbose
+ * - Display: --no-color, --help
+ * - Configuration: --config, --dry-run, --timeout, --no-hooks
+ * - Version: --version
+ */
+/**
+ * Parsed global options available to all commands
+ */
+export interface GlobalFlags {
+    /** Output as JSON (-j, --json) */
+    json: boolean;
+    /** Minimal output (-q, --quiet) */
+    quiet: boolean;
+    /** Detailed output (-v, --verbose) */
+    verbose: boolean;
+    /** Show help (-h, --help) */
+    help: boolean;
+    /** Show version (--version) */
+    version: boolean;
+    /** Disable colors (--no-color) */
+    noColor: boolean;
+    /** Custom config path (--config) */
+    configPath?: string;
+    /** Preview without executing (--dry-run) */
+    dryRun: boolean;
+    /** Command timeout in milliseconds (--timeout) */
+    timeout?: number;
+    /** Skip hook execution (--no-hooks) */
+    noHooks: boolean;
+    /** Don't wait for locks to be released (--no-wait) */
+    noWait: boolean;
+}
+/**
+ * Result of parsing global flags
+ */
+export interface ParsedArgs {
+    /** Parsed global flags */
+    flags: GlobalFlags;
+    /** Remaining args after global flags are extracted */
+    remaining: string[];
+}
+/**
+ * Default values for global flags
+ */
+export declare function getDefaultFlags(): GlobalFlags;
+/**
+ * Parse duration string to milliseconds
+ * Supports: 30s, 5m, 1h, or plain number (ms)
+ */
+export declare function parseDuration(value: string): number;
+/**
+ * Load flags from environment variables
+ * Environment variables provide defaults that can be overridden by CLI flags
+ */
+export declare function loadEnvFlags(): Partial<GlobalFlags>;
+/**
+ * Parse global flags from command line arguments
+ *
+ * Global flags can appear anywhere in the args and are extracted,
+ * leaving the remaining args for command-specific parsing.
+ *
+ * @param args - Command line arguments to parse
+ * @returns Parsed flags and remaining arguments
+ */
+export declare function parseGlobalFlags(args: string[]): ParsedArgs;
+/**
+ * Apply global flags to affect runtime behavior
+ * Call this after parsing to set up the environment
+ */
+export declare function applyGlobalFlags(flags: GlobalFlags): void;
+//# sourceMappingURL=flags.d.ts.map

package/dist/cli/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/cli/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,sDAAsD;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,WAAW,CAc7C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBnD;AAUD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,CAiCnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA2H3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAKzD"}

package/dist/cli/flags.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Global flags parser for Steroids CLI
+ *
+ * Parses global flags that apply to all commands:
+ * - Output format: --json, --quiet, --verbose
+ * - Display: --no-color, --help
+ * - Configuration: --config, --dry-run, --timeout, --no-hooks
+ * - Version: --version
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultFlags = getDefaultFlags;
+exports.parseDuration = parseDuration;
+exports.loadEnvFlags = loadEnvFlags;
+exports.parseGlobalFlags = parseGlobalFlags;
+exports.applyGlobalFlags = applyGlobalFlags;
+/**
+ * Default values for global flags
+ */
+function getDefaultFlags() {
+    return {
+        json: false,
+        quiet: false,
+        verbose: false,
+        help: false,
+        version: false,
+        noColor: false,
+        configPath: undefined,
+        dryRun: false,
+        timeout: undefined,
+        noHooks: false,
+        noWait: false,
+    };
+}
+/**
+ * Parse duration string to milliseconds
+ * Supports: 30s, 5m, 1h, or plain number (ms)
+ */
+function parseDuration(value) {
+    const match = value.match(/^(\d+)(ms|s|m|h)?$/);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${value}. Use format: 30s, 5m, 1h, or milliseconds`);
+    }
+    const num = parseInt(match[1], 10);
+    const unit = match[2] || 'ms';
+    switch (unit) {
+        case 'ms':
+            return num;
+        case 's':
+            return num * 1000;
+        case 'm':
+            return num * 60 * 1000;
+        case 'h':
+            return num * 60 * 60 * 1000;
+        default:
+            return num;
+    }
+}
+/**
+ * Check if a value is truthy for boolean env vars
+ */
+function isTruthy(value) {
+    if (!value)
+        return false;
+    return value === '1' || value.toLowerCase() === 'true';
+}
+/**
+ * Load flags from environment variables
+ * Environment variables provide defaults that can be overridden by CLI flags
+ */
+function loadEnvFlags() {
+    const env = {};
+    if (isTruthy(process.env.STEROIDS_JSON)) {
+        env.json = true;
+    }
+    if (isTruthy(process.env.STEROIDS_QUIET)) {
+        env.quiet = true;
+    }
+    if (isTruthy(process.env.STEROIDS_VERBOSE)) {
+        env.verbose = true;
+    }
+    if (isTruthy(process.env.STEROIDS_NO_HOOKS)) {
+        env.noHooks = true;
+    }
+    if (isTruthy(process.env.STEROIDS_NO_WAIT)) {
+        env.noWait = true;
+    }
+    if (isTruthy(process.env.STEROIDS_NO_COLOR) || process.env.NO_COLOR !== undefined) {
+        env.noColor = true;
+    }
+    if (process.env.STEROIDS_CONFIG) {
+        env.configPath = process.env.STEROIDS_CONFIG;
+    }
+    if (process.env.STEROIDS_TIMEOUT) {
+        try {
+            env.timeout = parseDuration(process.env.STEROIDS_TIMEOUT);
+        }
+        catch {
+            // Ignore invalid timeout from env
+        }
+    }
+    return env;
+}
+/**
+ * Parse global flags from command line arguments
+ *
+ * Global flags can appear anywhere in the args and are extracted,
+ * leaving the remaining args for command-specific parsing.
+ *
+ * @param args - Command line arguments to parse
+ * @returns Parsed flags and remaining arguments
+ */
+function parseGlobalFlags(args) {
+    // Start with defaults, then apply env vars
+    const flags = {
+        ...getDefaultFlags(),
+        ...loadEnvFlags(),
+    };
+    const remaining = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        // Handle combined short flags like -jqv
+        if (arg.match(/^-[jqvh]+$/) && arg.length > 2) {
+            for (const char of arg.slice(1)) {
+                switch (char) {
+                    case 'j':
+                        flags.json = true;
+                        break;
+                    case 'q':
+                        flags.quiet = true;
+                        break;
+                    case 'v':
+                        flags.verbose = true;
+                        break;
+                    case 'h':
+                        flags.help = true;
+                        break;
+                }
+            }
+            i++;
+            continue;
+        }
+        switch (arg) {
+            case '-j':
+            case '--json':
+                flags.json = true;
+                i++;
+                break;
+            case '-q':
+            case '--quiet':
+                flags.quiet = true;
+                i++;
+                break;
+            case '-v':
+            case '--verbose':
+                flags.verbose = true;
+                i++;
+                break;
+            case '-h':
+            case '--help':
+                flags.help = true;
+                i++;
+                break;
+            case '--version':
+                flags.version = true;
+                i++;
+                break;
+            case '--no-color':
+                flags.noColor = true;
+                i++;
+                break;
+            case '--dry-run':
+                flags.dryRun = true;
+                i++;
+                break;
+            case '--no-hooks':
+                flags.noHooks = true;
+                i++;
+                break;
+            case '--no-wait':
+                flags.noWait = true;
+                i++;
+                break;
+            case '--config':
+                if (i + 1 >= args.length) {
+                    throw new Error('--config requires a path argument');
+                }
+                flags.configPath = args[i + 1];
+                i += 2;
+                break;
+            case '--timeout':
+                if (i + 1 >= args.length) {
+                    throw new Error('--timeout requires a duration argument');
+                }
+                flags.timeout = parseDuration(args[i + 1]);
+                i += 2;
+                break;
+            default:
+                // Handle --config=value and --timeout=value syntax
+                if (arg.startsWith('--config=')) {
+                    flags.configPath = arg.slice('--config='.length);
+                    i++;
+                }
+                else if (arg.startsWith('--timeout=')) {
+                    flags.timeout = parseDuration(arg.slice('--timeout='.length));
+                    i++;
+                }
+                else {
+                    // Not a global flag, pass through to remaining
+                    remaining.push(arg);
+                    i++;
+                }
+        }
+    }
+    // Validate conflicting flags
+    if (flags.quiet && flags.verbose) {
+        throw new Error('Cannot use --quiet and --verbose together');
+    }
+    return { flags, remaining };
+}
+/**
+ * Apply global flags to affect runtime behavior
+ * Call this after parsing to set up the environment
+ */
+function applyGlobalFlags(flags) {
+    // Disable colors if requested
+    if (flags.noColor) {
+        process.env.NO_COLOR = '1';
+    }
+}
+//# sourceMappingURL=flags.js.map

package/dist/cli/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/cli/flags.ts"],"names":[],"mappings":"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"}

package/dist/cli/help.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Help system for Steroids CLI
+ *
+ * Provides templates and utilities for creating consistent,
+ * comprehensive help text across all commands.
+ */
+/**
+ * Help section structure
+ */
+export interface HelpSection {
+    title: string;
+    content: string;
+}
+/**
+ * Command example
+ */
+export interface CommandExample {
+    command: string;
+    description: string;
+}
+/**
+ * Option definition for help text
+ */
+export interface OptionDef {
+    short?: string;
+    long: string;
+    description: string;
+    values?: string;
+    default?: string;
+}
+/**
+ * Subcommand definition
+ */
+export interface SubcommandDef {
+    name: string;
+    description: string;
+    args?: string;
+}
+/**
+ * Related command reference
+ */
+export interface RelatedCommand {
+    command: string;
+    description: string;
+}
+/**
+ * Help template configuration
+ */
+export interface HelpTemplate {
+    /** Command name (e.g., 'tasks', 'sections') */
+    command: string;
+    /** Short one-line description */
+    description: string;
+    /** Detailed description (optional) */
+    details?: string;
+    /** Usage examples */
+    usage?: string[];
+    /** Subcommands */
+    subcommands?: SubcommandDef[];
+    /** Command-specific options */
+    options?: OptionDef[];
+    /** Examples with descriptions */
+    examples?: CommandExample[];
+    /** Related commands */
+    related?: RelatedCommand[];
+    /** Custom sections */
+    sections?: HelpSection[];
+    /** Whether to show global options (default: true) */
+    showGlobalOptions?: boolean;
+    /** Whether to show exit codes (default: true) */
+    showExitCodes?: boolean;
+    /** Whether to show environment variables (default: true) */
+    showEnvVars?: boolean;
+}
+/**
+ * Generate help text from template
+ */
+export declare function generateHelp(template: HelpTemplate): string;
+/**
+ * Quick help for simple commands
+ *
+ * Generates basic help text with just usage and options
+ */
+export declare function quickHelp(command: string, description: string, options?: OptionDef[], examples?: CommandExample[]): string;
+/**
+ * Display error codes table
+ */
+export declare function showErrorCodes(): void;
+/**
+ * Format a compact help hint for error messages
+ */
+export declare function helpHint(command?: string): string;
+/**
+ * Format a "Did you mean?" suggestion
+ */
+export declare function didYouMean(provided: string, options: string[]): string | null;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kBAAkB;IAClB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,uBAAuB;IACvB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAsFD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAoG3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,SAAS,EAAO,EACzB,QAAQ,GAAE,cAAc,EAAO,GAC9B,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CA0BrC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAe7E"}

package/dist/cli/help.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * Help system for Steroids CLI
+ *
+ * Provides templates and utilities for creating consistent,
+ * comprehensive help text across all commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateHelp = generateHelp;
+exports.quickHelp = quickHelp;
+exports.showErrorCodes = showErrorCodes;
+exports.helpHint = helpHint;
+exports.didYouMean = didYouMean;
+/**
+ * Format an option for display
+ */
+function formatOption(opt) {
+    const flags = opt.short ? `-${opt.short}, --${opt.long}` : `    --${opt.long}`;
+    const paddedFlags = flags.padEnd(24);
+    let desc = opt.description;
+    if (opt.values) {
+        desc += `\n${' '.repeat(24)}Values: ${opt.values}`;
+    }
+    if (opt.default) {
+        desc += `\n${' '.repeat(24)}Default: ${opt.default}`;
+    }
+    return `  ${paddedFlags}${desc}`;
+}
+/**
+ * Format a subcommand for display
+ */
+function formatSubcommand(sub) {
+    const name = sub.args ? `${sub.name} ${sub.args}` : sub.name;
+    const paddedName = name.padEnd(20);
+    return `  ${paddedName}${sub.description}`;
+}
+/**
+ * Format an example for display
+ */
+function formatExample(ex) {
+    return `  ${ex.command.padEnd(50)} # ${ex.description}`;
+}
+/**
+ * Global options that apply to all commands
+ */
+const GLOBAL_OPTIONS = [
+    { short: 'h', long: 'help', description: 'Show help' },
+    { long: 'version', description: 'Show version' },
+    { short: 'j', long: 'json', description: 'Output as JSON' },
+    { short: 'q', long: 'quiet', description: 'Minimal output' },
+    { short: 'v', long: 'verbose', description: 'Detailed output' },
+    { long: 'no-color', description: 'Disable colored output' },
+    { long: 'config', description: 'Custom config file path', values: '<path>' },
+    { long: 'dry-run', description: 'Preview without executing' },
+    { long: 'timeout', description: 'Command timeout', values: '<duration> (e.g., 30s, 5m, 1h)' },
+    { long: 'no-hooks', description: 'Skip hook execution' },
+    { long: 'no-wait', description: 'Don\'t wait for locks' },
+];
+/**
+ * Environment variables section
+ */
+const ENV_VARS_SECTION = `
+ENVIRONMENT VARIABLES:
+  STEROIDS_CONFIG        Custom config path (--config)
+  STEROIDS_JSON          Output as JSON (--json)
+  STEROIDS_QUIET         Minimal output (--quiet)
+  STEROIDS_VERBOSE       Detailed output (--verbose)
+  STEROIDS_NO_HOOKS      Skip hooks (--no-hooks)
+  STEROIDS_NO_COLOR      Disable colors (--no-color)
+  STEROIDS_NO_WAIT       Don't wait for locks (--no-wait)
+  STEROIDS_AUTO_MIGRATE  Auto-migrate database (1, true)
+  STEROIDS_TIMEOUT       Command timeout (duration)
+  NO_COLOR               Standard no-color variable
+  CI                     CI environment detected
+`;
+/**
+ * Exit codes section
+ */
+const EXIT_CODES_SECTION = `
+EXIT CODES:
+  0  Success
+  1  General error
+  2  Invalid arguments
+  3  Configuration error or not initialized
+  4  Resource not found
+  5  Permission denied
+  6  Resource locked
+  7  Health check failed
+`;
+/**
+ * Generate help text from template
+ */
+function generateHelp(template) {
+    const lines = [];
+    // Header
+    lines.push(`steroids ${template.command} - ${template.description}`);
+    lines.push('');
+    // Usage
+    if (template.usage && template.usage.length > 0) {
+        lines.push('USAGE:');
+        for (const usage of template.usage) {
+            lines.push(`  ${usage}`);
+        }
+        lines.push('');
+    }
+    else {
+        lines.push('USAGE:');
+        lines.push(`  steroids ${template.command} [options]`);
+        lines.push('');
+    }
+    // Detailed description
+    if (template.details) {
+        lines.push('DESCRIPTION:');
+        const detailLines = template.details.trim().split('\n');
+        for (const line of detailLines) {
+            lines.push(line ? `  ${line}` : '');
+        }
+        lines.push('');
+    }
+    // Subcommands
+    if (template.subcommands && template.subcommands.length > 0) {
+        lines.push('SUBCOMMANDS:');
+        for (const sub of template.subcommands) {
+            lines.push(formatSubcommand(sub));
+        }
+        lines.push('');
+    }
+    // Command-specific options
+    if (template.options && template.options.length > 0) {
+        lines.push('OPTIONS:');
+        for (const opt of template.options) {
+            lines.push(formatOption(opt));
+        }
+        lines.push('');
+    }
+    // Global options
+    if (template.showGlobalOptions !== false) {
+        lines.push('GLOBAL OPTIONS:');
+        for (const opt of GLOBAL_OPTIONS) {
+            lines.push(formatOption(opt));
+        }
+        lines.push('');
+    }
+    // Examples
+    if (template.examples && template.examples.length > 0) {
+        lines.push('EXAMPLES:');
+        for (const ex of template.examples) {
+            lines.push(formatExample(ex));
+        }
+        lines.push('');
+    }
+    // Related commands
+    if (template.related && template.related.length > 0) {
+        lines.push('RELATED COMMANDS:');
+        for (const rel of template.related) {
+            lines.push(`  ${rel.command.padEnd(30)}${rel.description}`);
+        }
+        lines.push('');
+    }
+    // Custom sections
+    if (template.sections && template.sections.length > 0) {
+        for (const section of template.sections) {
+            lines.push(`${section.title}:`);
+            const sectionLines = section.content.trim().split('\n');
+            for (const line of sectionLines) {
+                lines.push(line ? `  ${line}` : '');
+            }
+            lines.push('');
+        }
+    }
+    // Environment variables
+    if (template.showEnvVars !== false) {
+        lines.push(ENV_VARS_SECTION.trim());
+        lines.push('');
+    }
+    // Exit codes
+    if (template.showExitCodes !== false) {
+        lines.push(EXIT_CODES_SECTION.trim());
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Quick help for simple commands
+ *
+ * Generates basic help text with just usage and options
+ */
+function quickHelp(command, description, options = [], examples = []) {
+    return generateHelp({
+        command,
+        description,
+        options,
+        examples,
+    });
+}
+/**
+ * Display error codes table
+ */
+function showErrorCodes() {
+    console.log('ERROR CODES AND EXIT CODES:\n');
+    console.log('  Code                  Exit  Description');
+    console.log('  ' + '─'.repeat(70));
+    const codes = [
+        ['SUCCESS', '0', 'Operation completed successfully'],
+        ['GENERAL_ERROR', '1', 'Unspecified error'],
+        ['INVALID_ARGUMENTS', '2', 'Bad command arguments'],
+        ['CONFIG_ERROR', '3', 'Configuration problem'],
+        ['NOT_FOUND', '4', 'Resource not found'],
+        ['PERMISSION_DENIED', '5', 'Access denied'],
+        ['RESOURCE_LOCKED', '6', 'Lock held by another'],
+        ['HEALTH_FAILED', '7', 'Health check failed'],
+        ['TASK_NOT_FOUND', '4', 'Task doesn\'t exist'],
+        ['SECTION_NOT_FOUND', '4', 'Section doesn\'t exist'],
+        ['TASK_LOCKED', '6', 'Task locked by runner'],
+        ['NOT_INITIALIZED', '3', 'Steroids not initialized'],
+        ['MIGRATION_REQUIRED', '3', 'Database needs migration'],
+        ['HOOK_FAILED', '1', 'Hook execution failed'],
+    ];
+    for (const [code, exit, desc] of codes) {
+        console.log(`  ${code.padEnd(20)} ${exit.padEnd(5)} ${desc}`);
+    }
+    console.log();
+}
+/**
+ * Format a compact help hint for error messages
+ */
+function helpHint(command) {
+    if (command) {
+        return `Run 'steroids ${command} --help' for usage information.`;
+    }
+    return `Run 'steroids --help' for usage information.`;
+}
+/**
+ * Format a "Did you mean?" suggestion
+ */
+function didYouMean(provided, options) {
+    // Simple Levenshtein distance for suggestions
+    const distances = options.map(opt => ({
+        option: opt,
+        distance: levenshtein(provided.toLowerCase(), opt.toLowerCase()),
+    }));
+    distances.sort((a, b) => a.distance - b.distance);
+    // Only suggest if distance is small enough (less than half the length)
+    if (distances[0] && distances[0].distance <= provided.length / 2) {
+        return `Did you mean '${distances[0].option}'?`;
+    }
+    return null;
+}
+/**
+ * Simple Levenshtein distance for suggestions
+ */
+function levenshtein(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+//# sourceMappingURL=help.js.map