帮助

func/help 提供基于当前命令图的 --help 动作。它读取 Command、Handler 和字段选项已经声明的元数据自动进行组装，引入后无需进行其他配置。

启用 --help

把 HelpOption 注册到根模块的 options：

src/app.module.ts

Copy

import { Module } from 'func'
import { HelpOption } from 'func/help'
import { commands } from './commands'

@Module({
  commands,
  options: [HelpOption],
})
export class AppModule {}

根模块的 option action 对所有命令节点可见，因此 ship --help、ship deploy --help 等调用会展示对应节点的帮助。帮助动作被选中时不会要求当前业务命令的必填字段通过校验。

完善命令元数据

默认输出由已有声明生成：

如果帮助中缺少说明，优先补全对应声明的 description，让帮助、补全和运行时元数据共用同一个信息来源。

调整帮助内容

继承 HelpOption 并覆盖 transform(meta, context)，可以在格式化之前修改结构化的 HelpMeta：

src/app.module.ts

Copy

import { Module } from 'func'
import { HelpOption } from 'func/help'
import type { HelpMeta } from 'func/help'

class AppHelp extends HelpOption {
  override transform(meta: HelpMeta): HelpMeta {
    return {
      ...meta,
      title: meta.title ? `ship ${meta.title}` : 'ship',
    }
  }
}

@Module({ options: [AppHelp] })
export class AppModule {}

transform 可以同步返回，也可以返回 Promise。meta 及其中的集合都是只读值；返回新对象可以调整标题、排序、说明、命令或选项。context 提供当前 Args、运行时 Context 和剩余位置输入。

HelpFormatter 会根据可见字符宽度对齐输出，因此标题和选项名称中可以保留 ANSI 颜色。

为单个命令覆盖帮助

根模块注册的 HelpOption 默认对所有命令生效。如果某个 Command 需要另一套帮助内容，可以在该 Command 中声明同名的 @Flag()，并由默认 Handler 输出自定义帮助：

src/commands/deploy.command.ts

Copy

import { Command, Flag, Handler, Override, Stdout } from 'func'
import type { Writable } from 'node:stream'

@Command('deploy')
class DeployCommand {
  @Override()
  @Flag({ alias: 'h', description: 'show deploy help' })
  help = false

  @Handler()
  run(@Stdout() stdout: Writable) {
    if (this.help) {
      stdout.write('🚀 ship deploy\n\nUsage: ship deploy [--help]\n')
      return
    }

    stdout.write('Deploying...\n')
  }
}

@Override() 让 DeployCommand.help 显式替换从根模块继承的全局帮助信息。因此 ship deploy --help 进入 DeployCommand 的默认 Handler 并输出定制内容，ship status --help 等其他命令仍使用根模块注册的 HelpOption。

这里通过 @Stdout() 注入本次调用的 stdout，并直接写入用户定义的字符串，没有引入 func/help 的上下文或格式化实现。help 是普通字段 flag，不是独立动作；默认 Handler 应先判断它并立即返回，当前 Command 的其他字段绑定与校验仍会照常发生。如果没有注册根级 HelpOption，则不会产生 token 冲突，也不需要添加 @Override()。

这种方式只覆盖当前 Command，不需要声明新的 @OptionCommand()。

API 速查