{"version":3,"file":"help.mjs","names":[],"sources":["../../src/extension/help.ts"],"sourcesContent":["import { resolveAllCommands, resolveCommand } from '../core/commands.ts';\nimport { RoutingError, ValidationError } from '../core/errors.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport { formatIssueMessages } from '../core/validate.ts';\nimport type { HelpDetail, HelpFormat } from '../output/formatter.ts';\nimport { generateHelp } from '../output/help.ts';\nimport type { AnyPadroneBuilder, AnyPadroneCommand, CommandTypesBase, PadroneCommand } from '../types/index.ts';\nimport type { PadroneSchema } from '../types/schema.ts';\nimport type { WithCommand } from '../util/type-utils.ts';\nimport { getRootCommand } from '../util/utils.ts';\nimport { findCommandInTree, passthroughSchema } from './utils.ts';\n\n// ── Types ────────────────────────────────────────────────────────────────\n\ntype HelpArgs = { command?: string[]; detail?: HelpDetail; format?: HelpFormat; all?: boolean };\n\nexport type HelpCommand = PadroneCommand<'help', '', PadroneSchema<HelpArgs>, string, [], ['h', ''], false>;\n\nexport type WithHelp<T> = WithCommand<T, 'help', HelpCommand>;\n\n// ── Interceptor ─────────────────────────────────────────────────────────\n\nconst helpInterceptor = defineInterceptor({ id: 'padrone:help', name: 'padrone:help', order: -1000 }, () => {\n  let helpText: string | undefined;\n  let showDefaultHelp = false;\n\n  return {\n    parse(ctx, next) {\n      return thenMaybe(next(), (res) => {\n        const hasHelpFlag = res.rawArgs.help || res.rawArgs.h;\n        const reverseHelp = !hasHelpFlag && res.positionalArgs?.length > 0 && res.positionalArgs[res.positionalArgs.length - 1] === 'help';\n\n        if (hasHelpFlag || reverseHelp) {\n          delete res.rawArgs.help;\n          delete res.rawArgs.h;\n\n          const detail = res.rawArgs.detail as HelpDetail | undefined;\n          const format = res.rawArgs.format as HelpFormat | undefined;\n          const all = res.rawArgs.all as boolean | undefined;\n          delete res.rawArgs.detail;\n          delete res.rawArgs.format;\n          delete res.rawArgs.all;\n          delete res.rawArgs.d;\n          delete res.rawArgs.f;\n\n          const rootCommand = getRootCommand(res.command);\n          resolveAllCommands(rootCommand);\n\n          helpText = generateHelp(rootCommand, res.command, {\n            detail,\n            format: format ?? ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            all,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          });\n          return res;\n        }\n\n        // Track whether the parsed command has no action (for default help in execute phase)\n        if (helpText === undefined) {\n          const { command } = res;\n          const hasSubcommands = command.commands && command.commands.length > 0;\n          const hasSchema = command.argsSchema != null;\n          const hasUnmatchedTerms = res.positionalArgs?.length > 0 && !command.meta?.positional?.length;\n          if (!command.action && (hasSubcommands || !hasSchema) && !hasUnmatchedTerms) {\n            showDefaultHelp = true;\n          }\n        }\n\n        return res;\n      });\n    },\n    validate(_ctx, next) {\n      if (helpText !== undefined) return { args: undefined as any, argsResult: { value: undefined } as any };\n      return next();\n    },\n    execute(ctx, next) {\n      if (helpText !== undefined) return { result: helpText };\n      if (showDefaultHelp) {\n        const rootCommand = getRootCommand(ctx.command);\n        resolveAllCommands(rootCommand);\n        return {\n          result: generateHelp(rootCommand, ctx.command, {\n            format: ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          }),\n        };\n      }\n      return next();\n    },\n    error(ctx, next) {\n      return thenMaybe(next(), (er) => {\n        if (ctx.caller !== 'cli' || !er.error) return er;\n\n        const rootCommand = getRootCommand(ctx.command);\n\n        if (er.error instanceof RoutingError) {\n          const targetPath = er.error.command;\n          const targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : undefined;\n          const sourceCmd = targetCommand ?? rootCommand;\n\n          ctx.runtime.error(er.error.message);\n\n          if (er.error.suggestions.length > 0) {\n            const visibleCommands = (sourceCmd.commands ?? []).filter((c: AnyPadroneCommand) => !c.hidden && c.name);\n            if (visibleCommands.length > 0) {\n              for (const cmd of visibleCommands) resolveCommand(cmd);\n              const cmdList = visibleCommands.map((c: AnyPadroneCommand) => c.name).join(', ');\n              ctx.runtime.output(`\\nAvailable commands: ${cmdList}`);\n            }\n          } else {\n            resolveAllCommands(rootCommand);\n            const helpText = generateHelp(rootCommand, sourceCmd, {\n              format: ctx.runtime.format,\n              theme: ctx.runtime.theme,\n              terminal: ctx.runtime.terminal,\n              env: ctx.runtime.env(),\n            });\n            ctx.runtime.error(helpText);\n          }\n\n          return er;\n        }\n\n        if (er.error instanceof ValidationError) {\n          const targetPath = er.error.command;\n          const targetCommand = targetPath ? findCommandInTree(targetPath, rootCommand) : undefined;\n          const issueMessages = formatIssueMessages(er.error.issues);\n\n          resolveAllCommands(rootCommand);\n          const helpText = generateHelp(rootCommand, targetCommand ?? rootCommand, {\n            format: ctx.runtime.format,\n            theme: ctx.runtime.theme,\n            terminal: ctx.runtime.terminal,\n            env: ctx.runtime.env(),\n          });\n          ctx.runtime.error(`Validation error:\\n${issueMessages}`);\n          ctx.runtime.error(helpText);\n\n          return er;\n        }\n\n        return er;\n      });\n    },\n  };\n});\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that adds help support:\n * - `help` command with aliases `h` and `` (empty = executes on root when no subcommand matches)\n * - `--help` / `-h` flags\n * - `<cmd> help` reverse syntax\n * - Default help display when a command has no action\n *\n * Usage:\n * ```ts\n * createPadrone('my-cli').extend(padroneHelp())\n * ```\n */\nexport function padroneHelp(): <T extends CommandTypesBase>(builder: T) => WithHelp<T> {\n  return ((builder: AnyPadroneBuilder) =>\n    builder\n      .command(['help', 'h'], (c) =>\n        c\n          .configure({ description: 'Display help for a command', hidden: true })\n          .arguments(passthroughSchema({ command: 'string[]', detail: 'string', format: 'string', all: 'boolean' }), {\n            positional: ['...command'],\n          })\n          .action((args, ctx) => {\n            const rootCommand = getRootCommand(ctx.command);\n            resolveAllCommands(rootCommand);\n            const commandName = args.command?.join(' ');\n            const targetCommand = commandName ? findCommandInTree(commandName, rootCommand) : rootCommand;\n            return generateHelp(rootCommand, targetCommand ?? rootCommand, {\n              detail: args.detail as HelpDetail,\n              format: (args.format as HelpFormat) ?? ctx.runtime.format,\n              theme: ctx.runtime.theme,\n              all: args.all,\n              terminal: ctx.runtime.terminal,\n              env: ctx.runtime.env(),\n            });\n          }),\n      )\n      .intercept(helpInterceptor)) as any;\n}\n"],"mappings":"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"}