agentworkshop 0.7.33 → 0.7.37

package/scripts/test-cli-exit.mjs

@@ -14,7 +14,7 @@
  * 父侧事件循环保持干净,信号转发语义才可被确定性地观测。
  */
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
@@ -22,6 +22,20 @@ const here = dirname(fileURLToPath(import.meta.url))
 const root = resolve(here, '..')
 const AW = join(root, 'cli', 'aw.mjs')
 const LIFECYCLE = join(root, 'cli', 'core', 'child-lifecycle.mjs')
+/** Windows 无 POSIX 信号语义(child.kill 走 TerminateProcess,子进程无法捕获) */
+const IS_WINDOWS = process.platform === 'win32'
+
+/**
+ * 去掉行/块注释后再做"源码里不应出现某写法"的静态断言。
+ * 直接 includes() 会被**注释里对旧写法的引用**误伤:例如 aw.mjs 的说明注释
+ * 明确写着"必须用 process.exit(code) 而非 process.exitCode = await main()",
+ * 于是断言把解释文字当成了违规代码 —— 假阳性。
+ */
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1')
+}
 
 let failures = 0
 let checks = 0
@@ -41,14 +55,23 @@ function runAw(args, { timeoutMs = 30000 } = {}) {
     })
     let stdout = ''
     let stderr = ''
-    child.stdout.on('data', d => { stdout += d })
-    child.stderr.on('data', d => { stderr += d })
-    const timer = setTimeout(() => { try { child.kill('SIGKILL') } catch { /* ignore */ } }, timeoutMs)
+    child.stdout.on('data', (d) => {
+      stdout += d
+    })
+    child.stderr.on('data', (d) => {
+      stderr += d
+    })
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      }
+      catch { /* ignore */ }
+    }, timeoutMs)
     child.on('close', (code, signal) => {
       clearTimeout(timer)
       resolveRun({ code, signal, stdout, stderr })
     })
-    child.on('error', err => {
+    child.on('error', (err) => {
       clearTimeout(timer)
       resolveRun({ code: null, signal: null, stdout, stderr, error: err })
     })
@@ -61,7 +84,9 @@ const TMP = {
   stubborn: join(root, 'scripts', '_tmp-stubborn-child.mjs'),
   marker: join(root, 'scripts', '_tmp-signal-marker.json'),
 }
-const cleanup = () => { for (const p of [TMP.sig, TMP.stubborn, TMP.marker]) rmSync(p, { force: true }) }
+const cleanup = () => {
+  for (const p of [TMP.sig, TMP.stubborn, TMP.marker]) rmSync(p, { force: true })
+}
 process.on('exit', cleanup)
 
 console.log('[1] aw 入口退出码（缺陷 C:stdio 未 flush 导致 TLA 以 13 收场）')
@@ -113,9 +138,22 @@ console.log('[2] 全局标志剥离不吞掉值位同名 token（缺陷 B）')
   const u5 = stripGlobals(['--', '--json'], GLOBALS)
   check('-- 之后不剥离', JSON.stringify(u5) === JSON.stringify(['--', '--json']), `got=${JSON.stringify(u5)}`)
 
-  const u6 = stripGlobals(['--root', 'R', '--json'], GLOBALS)
-  check('带值全局项连同取值一起移除', JSON.stringify(u6) === JSON.stringify(['--json']),
-    `got=${JSON.stringify(u6)}`)
+  // 布尔全局项**不得吞掉**紧随其后的位置参数。
+  // 旧实现对每个被剔除项一律套用"下一 token 非选项就当它的取值吃掉",
+  // 于是 `aw build --json x` 里的 x 会静默消失(位置参数丢失)。
+  const u8 = stripGlobals(['--json', 'x'], GLOBALS)
+  check('布尔全局项不吞位置参数', JSON.stringify(u8) === JSON.stringify(['x']), `got=${JSON.stringify(u8)}`)
+
+  // 带值全局项:经 opts.valueNames 显式声明后,才连同取值一起移除
+  // (注:要被移除的项必须出现在 names 里;valueNames 只是"其中哪些带取值"的声明)
+  const u6 = stripGlobals(['--root', 'R', '--json'], ['--json', '--debug', '--root'], { valueNames: ['--root'] })
+  check('带值全局项连同取值一起移除', JSON.stringify(u6) === JSON.stringify([]), `got=${JSON.stringify(u6)}`)
+  // 未声明带值时按布尔处理:只移除选项本身,取值 token 原样保留
+  const u6b = stripGlobals(['--root', 'R', '--json'], GLOBALS)
+  check('未声明带值 ⇒ 仅移除选项本身', JSON.stringify(u6b) === JSON.stringify(['--root', 'R']), `got=${JSON.stringify(u6b)}`)
+  // --root 的取值恰好长得像另一个全局项时,它是"值"而不是选项 → 随 --root 一起移除
+  const u6c = stripGlobals(['--root', '--json'], ['--json', '--root'], { valueNames: ['--root'] })
+  check('--json 作为 --root 的取值时随它一起移除', JSON.stringify(u6c) === JSON.stringify([]), `got=${JSON.stringify(u6c)}`)
 
   const u7 = stripGlobals(['--debug=1'], GLOBALS)
   check('内联取值形式 --debug=1 整体移除', JSON.stringify(u7) === JSON.stringify([]), `got=${JSON.stringify(u7)}`)
@@ -131,6 +169,25 @@ console.log('[2] 全局标志剥离不吞掉值位同名 token（缺陷 B）')
   const fixedFlags = parseArgs(['--name', '--json']).flags
   check('按位置解析后 --json 不再是全局标志', fixedFlags.json === true && fixedFlags.name === true,
     JSON.stringify(fixedFlags))
+
+  // 指令名提取必须跳过全局选项的**取值位**:
+  // 旧实现只跳过 '-' 开头的 token,于是 `aw --root /p version` 把 '/p' 当指令名
+  // → "未知指令: /p",用户被迫只能写 --root=/p 等号形式。
+  const { extractCommandName } = await import(pathToFileURL(join(root, 'cli', 'core', 'args.mjs')).href)
+  check('extractCommandName: --root <值> 后取到指令名',
+    extractCommandName(['--root', '/p', 'version']) === 'version',
+    `got=${extractCommandName(['--root', '/p', 'version'])}`)
+  check('extractCommandName: --root=<值> 等号形式',
+    extractCommandName(['--root=/p', 'version']) === 'version',
+    `got=${extractCommandName(['--root=/p', 'version'])}`)
+  check('extractCommandName: 布尔全局项不吃指令名',
+    extractCommandName(['--json', 'build']) === 'build',
+    `got=${extractCommandName(['--json', 'build'])}`)
+  check('extractCommandName: -- 之后一律位置参数',
+    extractCommandName(['--', '--weird']) === '--weird',
+    `got=${extractCommandName(['--', '--weird'])}`)
+  check('extractCommandName: 单个 - 视为位置参数',
+    extractCommandName(['-']) === '-', `got=${extractCommandName(['-'])}`)
 }
 
 console.log('[3] 子进程生命周期:信号 → 退出码传播（缺陷 A）')
@@ -165,8 +222,8 @@ console.log('[3] 子进程生命周期:信号 → 退出码传播（缺陷 A）'
   // 强杀兜底:子进程忽略 SIGTERM → 宽限期后 SIGKILL,父仍非 0 且能返回
   writeFileSync(TMP.stubborn, [
     '// 忽略可捕获信号,只有 SIGKILL 能终止',
-    "process.on('SIGTERM', () => {})",
-    "process.on('SIGINT', () => {})",
+    'process.on(\'SIGTERM\', () => {})',
+    'process.on(\'SIGINT\', () => {})',
     'setTimeout(() => {}, 60000)',
     '',
   ].join('\n'))
@@ -183,23 +240,43 @@ console.log('[3] 子进程生命周期:信号 → 退出码传播（缺陷 A）'
   // 信号转发确实到达子进程（缺陷 A/2:子进程不再变孤儿）:
   // 子进程收到 SIGTERM 后写标记文件,父进程排在后面的监听器据此断言。
   writeFileSync(TMP.sig, [
-    "import { writeFileSync } from 'node:fs'",
+    'import { writeFileSync } from \'node:fs\'',
     `process.on('SIGTERM', () => { writeFileSync(${JSON.stringify(TMP.marker)}, JSON.stringify({ sig: 'SIGTERM' })); process.exit(0) })`,
-    "process.on('SIGINT', () => {})",
+    'process.on(\'SIGINT\', () => {})',
     'setTimeout(() => {}, 60000)',
     '',
   ].join('\n'))
   {
     let forwarded = null
-    const observe = () => { forwarded = readFileSync(TMP.marker, 'utf8') }
+    // observe 在信号到达时立即执行,而子进程可能还没写完标记文件 ——
+    // 必须容忍"文件尚不存在",否则 readFileSync 抛 ENOENT 会把整个测试进程带走
+    // (旧写法在文件缺失时直接崩,断言根本没机会执行)。
+    const observe = () => {
+      try {
+        forwarded = readFileSync(TMP.marker, 'utf8')
+      }
+      catch {
+        forwarded = null
+      }
+    }
     process.on('SIGTERM', observe) // 注册在 runChild 之后 → 在 runChild 转发之后执行
     try {
       const p = runChild(process.execPath, [TMP.sig], { stdio: 'inherit', graceMs: 3000 })
       setTimeout(() => process.emit('SIGTERM'), 300)
       const code = await p
       const sawSignal = forwarded !== null && String(forwarded).includes('SIGTERM')
-      check('SIGTERM 被转发至子进程（孤儿化已修复）', sawSignal, `marker=${forwarded}`)
-      check('子进程正常退出(0)后父透传 0', code === 0, `got=${code}`)
+      if (IS_WINDOWS) {
+        // Windows 没有真正的 POSIX 信号:child.kill('SIGTERM') 底层走 TerminateProcess,
+        // 子进程**无法捕获**它,因此"子进程收到信号后写标记文件"在该平台不可观测。
+        // 能且只能在 Windows 断言的是:转发路径确实把子进程终止了(不是放任它变孤儿)。
+        check('SIGTERM 转发确实终止了子进程(Windows 无法观测捕获)',
+          code !== 0 || sawSignal, `code=${code} marker=${forwarded}`)
+        console.log('    · Windows:跳过"子进程捕获 SIGTERM"断言(平台无 POSIX 信号语义)')
+      }
+      else {
+        check('SIGTERM 被转发至子进程（孤儿化已修复）', sawSignal, `marker=${forwarded}`)
+        check('子进程正常退出(0)后父透传 0', code === 0, `got=${code}`)
+      }
     }
     finally {
       process.removeListener('SIGTERM', observe)
@@ -215,17 +292,48 @@ console.log('[3] 子进程生命周期:信号 → 退出码传播（缺陷 A）'
 
 console.log('[4] start / dev / build 已接入统一生命周期（静态断言）')
 {
+  // 静态断言一律在**去注释后的代码**上做:注释里对旧写法的引用不是违规代码
   for (const f of ['start.mjs', 'dev.mjs', 'build.mjs']) {
-    const src = readFileSync(join(root, 'cli', 'commands', f), 'utf8')
-    check(`${f} 复用 runChild`, src.includes("from '../core/child-lifecycle.mjs'") && src.includes('runChild('))
+    const raw = readFileSync(join(root, 'cli', 'commands', f), 'utf8')
+    const src = stripComments(raw)
+    check(`${f} 复用 runChild`, src.includes('from \'../core/child-lifecycle.mjs\'') && src.includes('runChild('))
     check(`${f} 不再有 'code ?? 0' 误报`, !src.includes('code ?? 0'))
-    check(`${f} 不再自建 SIGINT handler（统一收敛）`, !src.includes("process.on('SIGINT'"))
+    check(`${f} 不再自建 SIGINT handler（统一收敛）`, !src.includes('process.on(\'SIGINT\''))
   }
-  const buildSrc = readFileSync(join(root, 'cli', 'commands', 'build.mjs'), 'utf8')
+  const buildSrc = stripComments(readFileSync(join(root, 'cli', 'commands', 'build.mjs'), 'utf8'))
   check('build.mjs 已转发信号（Ctrl+C 不再产生孤儿 nuxt）', buildSrc.includes('runChild(process.execPath'))
-  const awSrc = readFileSync(AW, 'utf8')
+  const awSrc = stripComments(readFileSync(AW, 'utf8'))
   check('aw.mjs 入口改用 process.exit(code)', awSrc.includes('process.exit(await main())'))
   check('aw.mjs 不再用 exitCode = await main()', !awSrc.includes('process.exitCode = await main()'))
+  // 入口不得反向被命令模块引入:cli/commands/* → ../aw.mjs 会形成循环依赖,
+  // 在 cli/aw.mjs 自任入口时死锁(顶层 await main() 永远等不到 scanDirs 完成),
+  // 现象是 `aw --help` 退出码 13 且无输出。
+  const cmdDir = join(root, 'cli', 'commands')
+  const cyclic = readdirSync(cmdDir)
+    .filter(n => /\.(mjs|js)$/.test(n))
+    .filter((n) => {
+      const s = stripComments(readFileSync(join(cmdDir, n), 'utf8'))
+      return /from '\.\.\/aw\.mjs'/.test(s) || /import\('\.\.\/aw\.mjs'\)/.test(s)
+    })
+  check('命令模块不反向 import 入口（无循环依赖）', cyclic.length === 0, `违规=${cyclic.join(',') || '无'}`)
+
+  // 每个内建指令都必须能真正 import 且导出 { meta.name, run }。
+  // 动机:registry.scanDirs → registerFile 会把 import 失败**吞进 failures**,
+  // 结果是一条指令静默消失(`aw plugin` 报"未知指令"),而静态文本检查完全看不出来
+  // —— 实际踩坑:插件指令的模板字符串里漏转义一个反引号,整个模块就废了。
+  for (const n of readdirSync(cmdDir).filter(x => /\.(mjs|js)$/.test(x) && !x.startsWith('_'))) {
+    const name = `cli/commands/${n}`
+    try {
+      const mod = await import(pathToFileURL(join(cmdDir, n)).href)
+      const m = mod.meta
+      check(`${name} 可 import 且导出 meta.name + run()`,
+        Boolean(m?.name) && typeof mod.run === 'function',
+        `meta.name=${m?.name ?? '(缺失)'} run=${typeof mod.run}`)
+    }
+    catch (err) {
+      check(`${name} 可 import 且导出 meta.name + run()`, false, `import 抛错: ${err?.message ?? err}`)
+    }
+  }
 }
 
 console.log(`\n${failures === 0 ? '✔ 全部通过' : '✖ 存在失败'} : ${checks - failures}/${checks}`)