diff --git a/src/core/help.ts b/src/core/help.ts index 5f78b5a..f0ba9a1 100644 --- a/src/core/help.ts +++ b/src/core/help.ts @@ -1,9 +1,15 @@ /** - * help.ts — AI 友好帮助体系 + * dacli --help system: 知识落地到 CLI 自己 (Phase 1 改造). * - * 用法: 给 Commander.js 命令对象挂元数据 (cmd as any)._aiMeta = meta - * 由 cli.ts 顶层在 parse 之前扫 argv 拦截 --ai-help / --example / --source - * 打印后 process.exit, 避免命令真正执行 / 校验 requiredOption + * 架构 (v0.22+): + * - DacliHelp interface (Task 1.1): 含 4 新字段 pitfalls/bestPractices/decisionTree/relatedRefs + * - renderDacliHelp() (Task 1.2): 把 DacliHelp 序列化为 addHelpText 文本 + * - installHelpHook() (Task 1.3): 双路径注入 — .description(purpose) + .addHelpText('after', ...) + * + * Legacy compat (Task 1.6 将清理): + * - installAiHelpHook = installHelpHook (alias for source-compat during migration) + * - _aiMeta 副作用保留到 Task 1.6 删 --ai-help flag 时 + * - AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp 是遗留代码 */ import type { Command } from 'commander' @@ -128,8 +134,17 @@ const AI_FLAGS = new Set(['--ai-help', '--example', '--source']) * (Commander `helpInformation()` 不内置, 仅 `outputHelp()` / `--help` 实际输出可见) */ export function installHelpHook(command: Command, help: DacliHelp): void { + // Primary path: dual-path Commander integration (purpose + addHelpText) command.description(help.purpose) - command.addHelpText('after', renderDacliHelp(help)) + + const rendered = renderDacliHelp(help) + if (rendered.trim().length > 0) { + command.addHelpText('after', `\n${rendered}`) + } + + // Legacy compat: preserve _aiMeta side effect for --ai-help/--example/--source + // flag interception. Task 1.6 will delete this and the interceptor. + ;(command as unknown as { _aiMeta?: DacliHelp })._aiMeta = help } /** Backward-compat alias during migration */ diff --git a/tests/core/help.spec.ts b/tests/core/help.spec.ts index a86eaef..152a071 100644 --- a/tests/core/help.spec.ts +++ b/tests/core/help.spec.ts @@ -100,4 +100,25 @@ describe('installHelpHook', () => { const helpOutput = cmd.helpInformation() expect(helpOutput).toContain('test purpose') }) + + it('should inject sections via addHelpText into actual --help output', () => { + const cmd = new Command('test') + installHelpHook(cmd, { + purpose: 'test purpose', + example: 'dacli foo --bar', + bestPractices: ['use --autoRelease'], + }) + + // Capture the full output via configureOutput + let captured = '' + cmd.configureOutput({ writeOut: (s) => { captured += s } }) + cmd.outputHelp() + + // Sections must appear in actual --help output (NOT helpInformation) + expect(captured).toContain('test purpose') // from .description() + expect(captured).toContain('Examples:') + expect(captured).toContain('dacli foo --bar') + expect(captured).toContain('Best Practices:') + expect(captured).toContain('use --autoRelease') + }) })