diff --git a/src/core/help.ts b/src/core/help.ts index 504fff3..5f78b5a 100644 --- a/src/core/help.ts +++ b/src/core/help.ts @@ -117,11 +117,24 @@ export function renderDacliHelp(help: DacliHelp): string { const AI_FLAGS = new Set(['--ai-help', '--example', '--source']) -/** 把元数据挂到 command 上, cli.ts 顶层会读 */ -export function installAiHelpHook(cmd: Command, meta: DacliHelp): void { - ;(cmd as unknown as { _aiMeta?: DacliHelp })._aiMeta = meta +/** + * 把 DacliHelp 注入 Commander 命令的 --help 输出. + * 替换旧的 installAiHelpHook, 单 flag --help 包含所有信息. + * + * - `purpose` 走 Commander 的 `.description()`, 出现在 Usage 之后 Options 之前 + * (Commander `helpInformation()` 内置可见) + * - 其他字段 (example/source/pitfalls/bestPractices/decisionTree/relatedRefs/notes) + * 走 `addHelpText('after', ...)`, 出现在 Options 之后 + * (Commander `helpInformation()` 不内置, 仅 `outputHelp()` / `--help` 实际输出可见) + */ +export function installHelpHook(command: Command, help: DacliHelp): void { + command.description(help.purpose) + command.addHelpText('after', renderDacliHelp(help)) } +/** Backward-compat alias during migration */ +export const installAiHelpHook = installHelpHook + function getMeta(cmd: Command): DacliHelp | undefined { return (cmd as unknown as { _aiMeta?: DacliHelp })._aiMeta } diff --git a/tests/core/help.spec.ts b/tests/core/help.spec.ts index 90cfafd..a86eaef 100644 --- a/tests/core/help.spec.ts +++ b/tests/core/help.spec.ts @@ -1,6 +1,7 @@ import { describe, it, expect } from 'vitest' -import { renderDacliHelp } from '../../src/core/help' +import { renderDacliHelp, installHelpHook } from '../../src/core/help' import type { DacliHelp } from '../../src/core/help' +import { Command } from 'commander' describe('DacliHelp interface', () => { it('should accept the 4 new fields', () => { @@ -91,3 +92,12 @@ describe('renderDacliHelp pitfalls rationale', () => { expect(out).not.toContain('→') }) }) + +describe('installHelpHook', () => { + it('should register addHelpText on Commander command', () => { + const cmd = new Command('test') + installHelpHook(cmd, { purpose: 'test purpose' }) + const helpOutput = cmd.helpInformation() + expect(helpOutput).toContain('test purpose') + }) +})