feat(ssw-loop): P7 — generate command reference from commander tree (kill drift)

Per DESIGN §6 / user catch: ssw-loop subagent templates hand-code dacli command
syntax and drift (typ. missing --category). Command tree is now the single source.
- src/program.ts: extract buildProgram() (assembles commander tree, no parse/side-effect)
- src/cli.ts: slimmed to import buildProgram() + parse + top-level error handling
- scripts/gen-command-reference.ts: walk tree → .claude/.../command-reference.generated.md
  (190 commands w/ all options + defaults, incl --category/--column-naming)

Verified: tsc 0; cli entry smoke (form list) intact after refactor; generator emits
190 commands. (.claude side: generated ref + drift-check committed separately.)

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-24 11:45:30 +08:00
1 parent 7988ead926
commit d4cc3d09db
3 files changed
+163 -91

No files matched your search

+80
View File
@@ -0,0 +1,80 @@
/**
* gen-command-reference.ts — 从 commander 命令树生成 ssw-loop 参考 (P7, 2026-07-24)
*
* 跑: npx tsx scripts/gen-command-reference.ts
* 产出: .claude/skills/ssw-loop/references/command-reference.generated.md
*
* 目的 (DESIGN §6): ssw-loop 子代理模板手写 dacli 命令语法会漂移 (典型: 缺 --category)。
* 命令树是唯一真相源 — 参考文件自动生成, CLI 一改重跑即同步, 永不漂移。
*/
import { writeFileSync } from 'node:fs'
import { join } from 'node:path'
import type { Command } from 'commander'
import { buildProgram, VERSION } from '../src/program.ts'
import { getCcWorkDir } from '../src/core/paths.ts'
interface CmdDoc {
path: string
desc: string
args: Array<{ name: string; desc: string }>
opts: Array<{ flags: string; desc: string; def?: unknown }>
}
function walk(cmd: Command, prefix: string, out: CmdDoc[]): void {
const subs = cmd.commands as Command[]
for (const c of subs) {
const path = `${prefix} ${c.name()}`.trim()
const args = ((c as any).registeredArguments ?? []).map((a: any) => ({
name: a.name?.() ?? a._name ?? '',
desc: a.description ?? '',
}))
const opts = (c.options ?? []).map((o: any) => ({
flags: o.flags as string,
desc: (o.description as string) ?? '',
def: o.defaultValue,
}))
// 只收叶子命令 (有 action / 无子命令) 和有内容的父命令
if (c.commands.length === 0 || args.length || opts.length) {
out.push({ path, desc: c.description() ?? '', args, opts })
}
if (c.commands.length > 0) walk(c, path, out)
}
}
const program = buildProgram()
const docs: CmdDoc[] = []
walk(program, 'dacli', docs)
const lines: string[] = []
lines.push('<!-- 自动生成, 请勿手改。改命令后跑: npx tsx scripts/gen-command-reference.ts -->')
lines.push(`# dacli 命令参考 (generated, dacli v${VERSION})`)
lines.push('')
lines.push('> ssw-loop 子代理引用本文件而非内联命令语法 (永不漂移)。')
lines.push(`> 共 ${docs.length} 条命令。`)
lines.push('')
let group = ''
for (const d of docs) {
const top = d.path.split(' ')[1] ?? ''
if (top !== group) {
group = top
lines.push(`\n## ${top}\n`)
}
lines.push(`### \`${d.path}\``)
if (d.desc) lines.push(d.desc)
if (d.args.length) {
lines.push('- 参数: ' + d.args.map(a => `\`${a.name}\`${a.desc ? ' — ' + a.desc : ''}`).join('; '))
}
if (d.opts.length) {
lines.push('- 选项:')
for (const o of d.opts) {
const def = (o.def !== undefined && o.def !== false) ? ` (默认 ${JSON.stringify(o.def)})` : ''
lines.push(` - \`${o.flags}\`${o.desc ? ' — ' + o.desc : ''}${def}`)
}
}
lines.push('')
}
const outPath = join(getCcWorkDir(), '.claude/skills/ssw-loop/references/command-reference.generated.md')
writeFileSync(outPath, lines.join('\n'), 'utf-8')
console.log(`✓ 生成 ${docs.length} 条命令 → ${outPath}`)
+4 -91
View File
@@ -4,102 +4,15 @@
*
* 调用: `npx tsx src/cli.ts <command>` 或 `node --import tsx src/cli.ts <command>`
*
* 设计: 嵌套子命令 (form/menu/dm/dict/workflow/doc/apis 父命令 + 子命令)
* AI 友好: 每个命令支持 --ai-help / --example / --source
* 设计: 命令树在 src/program.ts 组装 (buildProgram, 无副作用),
* 本文件只负责 parse + 顶层错误处理。
*/
import { Command } from 'commander'
import { buildFormCommand } from './commands/form/index.ts'
import { buildDmCommand } from './commands/dm/index.ts'
import { buildDictCommand } from './commands/dict/index.ts'
import { buildMenuCommand } from './commands/menu/index.ts'
import { buildDiCommand } from './commands/di/index.ts'
import { buildWorkflowCommand } from './commands/workflow/index.ts'
import { buildDocCommand } from './commands/doc/index.ts'
import { buildApisCommand } from './commands/apis/index.ts'
import { buildDatasourceCommand } from './commands/datasource/index.ts'
import { buildReportCommand } from './commands/report/index.ts'
import { buildPortalCommand } from './commands/portal/index.ts'
import { buildBigscreenCommand } from './commands/bigscreen/index.ts'
import { buildAppCommand } from './commands/app/index.ts'
import { buildPrintCommand } from './commands/print/index.ts'
import { buildRoleCommand } from './commands/role/index.ts'
import { buildUserCommand } from './commands/user/index.ts'
import { buildOrgCommand } from './commands/org/index.ts'
import { buildMsgCommand } from './commands/msg/index.ts'
import { buildScheduleCommand } from './commands/schedule/index.ts'
import { buildMonitorCommand } from './commands/monitor/index.ts'
import { buildLogCommand } from './commands/log/index.ts'
import { buildIntegrationCommand } from './commands/integration/index.ts'
import { buildStorageCommand } from './commands/storage/index.ts'
import { buildTestCommand } from './commands/test/index.ts'
import { buildSelfCheckCommand } from './commands/_selfcheck.ts'
import { buildDriftCheckCommand } from './commands/_drift_check.ts'
import { buildCoverageCommand } from './commands/_coverage.ts'
import { buildKbCommand } from './commands/kb/index.ts'
import { buildProgram } from './program.ts'
import { log } from './core/log.ts'
import { DacliError } from './core/types.ts'
const VERSION = '0.1.0'
const program = new Command()
.name('dacli')
.description('dacli (TS 版) — AI 驱动的 JNPF CLI. ')
.version(VERSION)
.showHelpAfterError(true)
// ----- 嵌套父命令 -----
// v0.9 命名规范化: 顶层命令全部归入 app 命名空间
// dacli login → dacli app login
// dacli status → dacli app status
// dacli switchapp → dacli app switch
// dacli initapp → dacli app init
program.addCommand(buildFormCommand())
program.addCommand(buildDmCommand())
program.addCommand(buildDictCommand())
program.addCommand(buildMenuCommand())
program.addCommand(buildDiCommand())
program.addCommand(buildWorkflowCommand())
program.addCommand(buildDocCommand())
program.addCommand(buildApisCommand())
// v0.8 W7-D3 新增 4 父命令
program.addCommand(buildDatasourceCommand())
program.addCommand(buildReportCommand())
program.addCommand(buildPortalCommand())
program.addCommand(buildBigscreenCommand())
// v0.8 W9-D1 新增 1 父命令
program.addCommand(buildAppCommand())
// v0.8 W9-D3 新增 1 父命令
program.addCommand(buildPrintCommand())
// v0.8 W10-D1 新增 1 父命令
program.addCommand(buildRoleCommand())
// v0.8 W10-D2 新增 1 父命令
program.addCommand(buildUserCommand())
// v0.8 W10-D3 新增 1 父命令
program.addCommand(buildOrgCommand())
// v0.8 W11-D1 新增 1 父命令
program.addCommand(buildMsgCommand())
// v0.8 W11-D2 新增 1 父命令
program.addCommand(buildScheduleCommand())
// v0.8 W12 新增 3 P2 父命令
program.addCommand(buildMonitorCommand())
program.addCommand(buildLogCommand())
program.addCommand(buildIntegrationCommand())
program.addCommand(buildStorageCommand())
// v0.11+ NEW: test (API 模拟录入 → 沉淀, 替代 tests/test-*.ts 散落脚本)
program.addCommand(buildTestCommand())
// v0.11d+ Phase 4.1: selfcheck (v0.11d+ 强制纪律自检, AI 场景补充)
program.addCommand(buildSelfCheckCommand())
// v0.11e+ Phase D2: drift-check + coverage (验证强化)
program.addCommand(buildDriftCheckCommand())
program.addCommand(buildCoverageCommand())
// v0.16+ Phase KB: PostgreSQL-backed knowledge base (auto date/expiry/search filter)
program.addCommand(buildKbCommand())
// ----- main -----
program.parseAsync(process.argv).catch((err: unknown) => {
buildProgram().parseAsync(process.argv).catch((err: unknown) => {
if (err instanceof DacliError) {
log.error(`${err.message}`)
if (err.raw && process.env.DACLI_DEBUG === '1') log.dim(err.raw)
+79
View File
@@ -0,0 +1,79 @@
/**
* program.ts — 组装 commander 命令树 (与 CLI 入口解耦, P7 2026-07-24)
*
* cli.ts 从这里拿 buildProgram() 后 parseAsync;
* scripts/gen-command-reference.ts 也从这里拿, 遍历命令树生成 ssw-loop 模板参考
* (模板从 --help 生成, 永不漂移 — DESIGN §6)。
* 关键: 本文件只组装、不 parse, import 无副作用。
*/
import { Command } from 'commander'
import { buildFormCommand } from './commands/form/index.ts'
import { buildDmCommand } from './commands/dm/index.ts'
import { buildDictCommand } from './commands/dict/index.ts'
import { buildMenuCommand } from './commands/menu/index.ts'
import { buildDiCommand } from './commands/di/index.ts'
import { buildWorkflowCommand } from './commands/workflow/index.ts'
import { buildDocCommand } from './commands/doc/index.ts'
import { buildApisCommand } from './commands/apis/index.ts'
import { buildDatasourceCommand } from './commands/datasource/index.ts'
import { buildReportCommand } from './commands/report/index.ts'
import { buildPortalCommand } from './commands/portal/index.ts'
import { buildBigscreenCommand } from './commands/bigscreen/index.ts'
import { buildAppCommand } from './commands/app/index.ts'
import { buildPrintCommand } from './commands/print/index.ts'
import { buildRoleCommand } from './commands/role/index.ts'
import { buildUserCommand } from './commands/user/index.ts'
import { buildOrgCommand } from './commands/org/index.ts'
import { buildMsgCommand } from './commands/msg/index.ts'
import { buildScheduleCommand } from './commands/schedule/index.ts'
import { buildMonitorCommand } from './commands/monitor/index.ts'
import { buildLogCommand } from './commands/log/index.ts'
import { buildIntegrationCommand } from './commands/integration/index.ts'
import { buildStorageCommand } from './commands/storage/index.ts'
import { buildTestCommand } from './commands/test/index.ts'
import { buildSelfCheckCommand } from './commands/_selfcheck.ts'
import { buildDriftCheckCommand } from './commands/_drift_check.ts'
import { buildCoverageCommand } from './commands/_coverage.ts'
import { buildKbCommand } from './commands/kb/index.ts'
export const VERSION = '0.1.0'
/** 组装完整 commander 命令树 (不 parse) */
export function buildProgram(): Command {
const program = new Command()
.name('dacli')
.description('dacli (TS 版) — AI 驱动的 JNPF CLI. ')
.version(VERSION)
.showHelpAfterError(true)
program.addCommand(buildFormCommand())
program.addCommand(buildDmCommand())
program.addCommand(buildDictCommand())
program.addCommand(buildMenuCommand())
program.addCommand(buildDiCommand())
program.addCommand(buildWorkflowCommand())
program.addCommand(buildDocCommand())
program.addCommand(buildApisCommand())
program.addCommand(buildDatasourceCommand())
program.addCommand(buildReportCommand())
program.addCommand(buildPortalCommand())
program.addCommand(buildBigscreenCommand())
program.addCommand(buildAppCommand())
program.addCommand(buildPrintCommand())
program.addCommand(buildRoleCommand())
program.addCommand(buildUserCommand())
program.addCommand(buildOrgCommand())
program.addCommand(buildMsgCommand())
program.addCommand(buildScheduleCommand())
program.addCommand(buildMonitorCommand())
program.addCommand(buildLogCommand())
program.addCommand(buildIntegrationCommand())
program.addCommand(buildStorageCommand())
program.addCommand(buildTestCommand())
program.addCommand(buildSelfCheckCommand())
program.addCommand(buildDriftCheckCommand())
program.addCommand(buildCoverageCommand())
program.addCommand(buildKbCommand())
return program
}