/**
 * Custom help configuration for the AILF CLI.
 *
 * Uses Commander v14's native help customization APIs:
 * - `helpGroup()` on Command for grouped subcommand listings
 * - `configureHelp()` with a custom Help subclass for styling
 * - `addHelpText('after', ...)` for contextual examples
 *
 * This avoids ad-hoc console.log formatting and keeps help output
 * consistent, testable, and automatically aligned with the command tree.
 */
import { Help } from "commander";
// ---------------------------------------------------------------------------
// Command group headings
// ---------------------------------------------------------------------------
/**
 * Semantic group headings displayed in `ailf --help`.
 *
 * Groups appear in the order their first member is registered with the
 * program. Keep the registration order in cli.ts intentional.
 */
export const CommandGroup = {
    CoreWorkflow: "Core Workflow:",
    AnalysisReports: "Analysis & Reports:",
    GraderReliability: "Grader Reliability:",
    SetupConfig: "Setup & Configuration:",
    PipelineInternals: "Pipeline Internals:",
    DeveloperTools: "Developer Tools:",
};
// ---------------------------------------------------------------------------
// Custom Help formatter
// ---------------------------------------------------------------------------
/**
 * Extended Help class that adds subtle ANSI styling to section headings.
 *
 * Commander v14 calls these style methods during `formatHelp()`.
 * Terminal emulators that don't support ANSI codes degrade gracefully
 * (the escape sequences are invisible in raw-mode pipes like `| cat`).
 */
class AilfHelp extends Help {
    /** Bold section titles (Options:, Commands:, group headings). */
    styleTitle(str) {
        if (!hasColorSupport())
            return str;
        return `\x1b[1m${str}\x1b[0m`;
    }
    /** Dim the description text slightly for visual hierarchy. */
    styleDescriptionText(str) {
        if (!hasColorSupport())
            return str;
        return `\x1b[2m${str}\x1b[0m`;
    }
}
// ---------------------------------------------------------------------------
// Color support detection
// ---------------------------------------------------------------------------
/** Conservative check — disable color when piped or when NO_COLOR is set. */
function hasColorSupport() {
    if (process.env.NO_COLOR !== undefined)
        return false;
    if (process.env.FORCE_COLOR !== undefined)
        return true;
    return Boolean(process.stdout.isTTY);
}
// ---------------------------------------------------------------------------
// After-help text (Quick Start + links)
// ---------------------------------------------------------------------------
const afterHelpText = `
Quick Start:
  $ ailf run --debug               Run a quick evaluation (first 2 tests)
  $ ailf run --area groq           Evaluate a specific feature area
  $ ailf run --explain             Preview the execution plan
  $ ailf init                      Set up AILF in a new project

Documentation:
  Repository   https://github.com/sanity-io/ai-literacy-framework
  CLI Guide    https://github.com/sanity-io/ai-literacy-framework/blob/main/docs/guides/cli-guide.md
  Getting Started  https://github.com/sanity-io/ai-literacy-framework/blob/main/docs/getting-started.md

Run ailf <command> --help for detailed usage of any command.`;
// ---------------------------------------------------------------------------
// Program configuration
// ---------------------------------------------------------------------------
/**
 * Apply help configuration to the root program.
 *
 * Call this once in cli.ts after creating the program but before
 * registering commands. It:
 * 1. Sets the custom Help formatter via `configureHelp()`
 * 2. Appends Quick Start examples via `addHelpText('after', ...)`
 * 3. Customizes the built-in help command description
 */
export function configureProgram(program) {
    program
        .configureHelp(new AilfHelp())
        .addHelpText("after", afterHelpText)
        .addHelpCommand("help [command]", "Show help for a command");
}
