@deepwhale/coding-agent 1.0.12 → 1.0.13

package/dist/verify/verify-runner.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @deepwhale/coding-agent — Verify runner
+ *
+ * Sprint 1c-revive-2-D-11 (2026-06-04): `deepwhale --verify` 跟 REPL `/verify`
+ * 内部统一走 `runVerify()` — 跑 4 步真验证 (build / lint / typecheck / test),
+ * 不走 LLM, 不走 tool loop, 生成 `VerificationReport`.
+ *
+ * 设计拍板:
+ *   - 4 步默认: corepack pnpm build / lint / typecheck / test
+ *   - 用户可覆盖 checks (单测用) / cwd (单测 tmpdir) / signal (取消)
+ *   - 每步 spawn child_process 同步等 exit, **不**用 stream (避免长 stdout 卡 session)
+ *   - stdout/stderr 截断: 默认 4 KB 尾, 防止 session JSONL 撑爆
+ *   - timeout 默认 5 min/步, 总 timeout 默认 30 min (build+lint+typecheck+test 全跑)
+ *   - 任何一步 fail → 整体 fail, **不**继续后续步 (用户拍的 D-11 review: fail-fast
+ *     比继续跑节省时间, 而且后续步基于 build 产物, fail-fast 防止假绿)
+ *   - 不读 .env, 不动 LLM, 不调 tool loop — 真·本地 CLI
+ *
+ * 不变量 (跟 D-10c 集成测语义 hotfix 一脉相承):
+ *   - 不打印 / 不写 key 值
+ *   - 不做 ASCII-only sanitize
+ *   - 不读 .env 文件 (D-7 loadProjectEnv 是 caller 职责)
+ *   - 不依赖 LLM client (跑 verify 不需要 key)
+ *
+ * @module @deepwhale/coding-agent/verify-runner
+ */
+/**
+ * Verify context. 拍板 (D-21.0, 2026-06-06): verify 模式现在支持 2 种环境:
+ *   - 'monorepo': 在 deepwhale 源码仓库根跑 (有 pnpm-workspace.yaml, 或根 package.json 含 workspaces 字段),
+ *     跑 4 步真验证 (build/lint/typecheck/test), 跟 D-11 拍板保持一致
+ *   - 'installed': 在 `npm install -g @deepwhale/coding-agent` 后的环境跑 (单包 node_modules,
+ *     没 pnpm / vitest / eslint), 跑 4 步 sanity check (node --check / import / bin / exports),
+ *     验证"装出来能跑" + "主入口能 import" + "bin 能装" + "至少 export 1 个 symbol"
+ *
+ * 判 monorepo: `cwd` 存在 `pnpm-workspace.yaml` **或** 根 `package.json` 含 `workspaces` 字段.
+ * 拍板: 这两个 marker 在生态里都表示 monorepo. deepwhale 自己用的是 pnpm-workspace.yaml
+ * 形式 (根 package.json 没有 workspaces 字段), npm/yarn workspaces 用 package.json#workspaces
+ * 形式. 任一存在即 monorepo — 兼容两家. 都不存在 → installed.
+ *
+ * 不变量: detectContext 是 **同步纯函数** (不调外部命令, 不读 .env), 给定 cwd 返固定 context.
+ */
+export type VerifyContext = 'monorepo' | 'installed';
+export declare function detectContext(cwd?: string): VerifyContext;
+/** 单步验证配置. */
+export interface VerifyCheck {
+    /** 人类可读步骤名 (报告里显示). */
+    name: string;
+    /** 完整命令 (报告里显示). 例: "corepack pnpm build". */
+    command: string;
+    /** 实际 spawn 的 argv (不含 corepack, corepack 处理自动). */
+    args: ReadonlyArray<string>;
+    /** spawn cwd. 不传走 options.cwd / process.cwd(). */
+    cwd?: string;
+    /** 该步 timeout (ms). 不传走 options.defaultTimeoutMs / 300_000. */
+    timeoutMs?: number;
+}
+/** 单步结果. */
+export type VerifyCheckStatus = 'passed' | 'failed' | 'timed-out' | 'spawn-error' | 'aborted';
+export interface VerifyCheckResult {
+    name: string;
+    command: string;
+    status: VerifyCheckStatus;
+    /** spawn 退出码. spawn 失败或 timeout 时为 null. */
+    exitCode: number | null;
+    /** 该步 startedAt (epoch ms). */
+    startedAt: number;
+    /** 该步 endedAt (epoch ms). */
+    endedAt: number;
+    /** 该步 durationMs. */
+    durationMs: number;
+    /** stdout 末尾截断 (默认 4 KB). 永远不写原始大文件. */
+    stdoutTail: string;
+    /** stderr 末尾截断 (默认 4 KB). */
+    stderrTail: string;
+    /** spawn / abort 错时的 error.message. 否则 undefined. */
+    errorMessage?: string;
+}
+/** 整体报告. */
+export type VerificationOverallStatus = 'passed' | 'failed';
+export interface VerificationReport {
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    overallStatus: VerificationOverallStatus;
+    checks: ReadonlyArray<VerifyCheckResult>;
+    /** 一句话人类可读总结. */
+    summary: string;
+    /** 建议下一步. */
+    nextSuggestedAction: string;
+}
+export interface RunVerifyOptions {
+    /** 自定义 checks. 不传走默认 4 步. */
+    checks?: ReadonlyArray<VerifyCheck>;
+    /** 工作目录. 不传走 process.cwd(). */
+    cwd?: string;
+    /** 外部 AbortSignal (单测 / REPL / CLI 取消). */
+    signal?: AbortSignal;
+    /** 默认每步 timeout (ms). 默认 300_000 (5 min). */
+    defaultTimeoutMs?: number;
+    /** stdout/stderr 截断字节数. 默认 4096. */
+    stdoutCapBytes?: number;
+    /** 失败时是否继续. 默认 false (fail-fast). 单测可改. */
+    continueOnError?: boolean;
+}
+/**
+ * 给定"装出来的 coding-agent 包的根路径" 渲染 INSTALLED_CHECKS_TEMPLATE: 替换
+ * args 里的占位符, 同时生成可读的 command 字符串. 模板 → 实例 是纯映射.
+ *
+ * 拍板: 包根 = "包含 dist/ + bin/ + package.json 的目录". 1.0.1 实测路径:
+ *   global install: `<prefix>/lib/node_modules/@deepwhale/coding-agent`
+ *   local install: `<proj>/node_modules/@deepwhale/coding-agent`
+ *
+ * 拍板 (D-21.0, 2026-06-06, bugfix 3): import-check / exports-check 必须把
+ * cwd 设到 `dirname(packageRoot)` (即 node_modules 的**父目录**), 不然 Node
+ * 在用户 cwd (/tmp 或别的项目) 跑 `import('@deepwhale/coding-agent')` 时报
+ * "Cannot find package" — Node 解析包名从 cwd 向上找 node_modules, cwd 错
+ * 就找不到. 把 cwd 设到包根**之上**, Node 解析时能找到 node_modules/@deepwhale/...
+ *
+ * 调用方 (pickChecksForContext) 用 resolveInstalledPackageRoot() 拿这个路径.
+ * 包名 (PKG) 硬编码 '@deepwhale/coding-agent' — 这是 verify 验证的唯一目标包.
+ */
+/**
+ * D-25 A3 (F3, 2026-06-06): 内部 helper export 出, 仅供测试断言 args 形态.
+ * 业务 0 改, 仅 +1 个 export, 0 影响现有调用方 (pickChecksForContext 内部仍调).
+ * 测试用 `renderInstalledChecks('/fake/pkg/root')` 拿 4 check 验 args[0]==='node' / args[1] 不是 POSIX 标志.
+ */
+export declare function renderInstalledChecks(packageRoot: string): ReadonlyArray<VerifyCheck>;
+/**
+ * 解析"装出来的 @deepwhale/coding-agent 包的根目录" (绝对路径).
+ *
+ * 拍板 (D-21.0, 2026-06-06): verify 验证的目标是这个**包本身**, 不是用户
+ * cwd. 跟用户跑 `deepwhale --verify` 在哪个目录无关. resolveInstalledPackageRoot
+ * 必须**独立于 cwd** — 否则用户在 /tmp 跑, verify 就跑去 /tmp 检查, 完全错.
+ *
+ * 实现策略: ESM 里用 `import.meta.url` 不行 (verify-runner 不是 entry). 用
+ * `require.resolve('@deepwhale/coding-agent/package.json')` 找自身包的 package.json,
+ * 再 dirname 拿根. CommonJS require 在 ESM module 里走 createRequire. 兼容 tsc
+ * 输出 CommonJS 跟 ESM 两种 module 格式.
+ */
+export declare function resolveInstalledPackageRoot(): string;
+/**
+ * 给定 cwd 选对应 context 的 check 集. 拍板 (D-21.0): 单点决策, 后续要加
+ * 'ci' (GitHub Actions) 或 'docker' (容器内) 上下文, 改这里.
+ *
+ * 重要: cwd 参数**只用于 detectContext** (判 monorepo). installed 模式的
+ * check 始终以 coding-agent 包自身根为基准, 不受 cwd 影响.
+ */
+export declare function pickChecksForContext(cwd?: string): ReadonlyArray<VerifyCheck>;
+/**
+ * Sprint 1c-revive-2-D-11-4 review P1 修复: Windows 上 `corepack` 在 PATH 解析不到
+ * (Node `spawn('corepack', ...)` 在 Win32 默认走 CreateProcessW, 不接 .cmd shim).
+ * 实际 `where corepack` 只返 `corepack.cmd`. 修复: Win32 上把 'corepack' → 'corepack.cmd'.
+ *
+ * 设计: 接受 platform 参数, 默认用 process.platform, 单测可注入 'win32' 验证.
+ * 仅在 args0 严格 === 'corepack' 时转换; 其它可执行 (node / bash / .exe) 透传,
+ * 跟单测里 mock 各种 runner 的行为兼容.
+ */
+export declare function resolveRunner(args0: string, platform?: NodeJS.Platform): string;
+/**
+ * 判定 child close 时的 stderr / stdout 是不是 "启错" 文本 (Win32 shell:true
+ * 路径下, "命令不存在" / "No such file" 走 cmd.exe exit 1, 不会 sync spawn
+ * 抛). 跨 Win32 shell 启错模式: cmd.exe "X is not recognized" + PowerShell
+ * "term not recognized" + POSIX shell 偶发 (e.g. via /bin/sh -c) "No such
+ * file". 命中返 true, caller 报 'spawn-error' 跟 POSIX 语义对齐.
+ *
+ * 设计: 故意**不**用 ENOENT (Node child 不暴露), 也不查 PATH. 简单字符串匹配
+ * 几个高置信度关键词, 误伤率低. 留 D-20.8 用 stderr 双检 + Node fs.access
+ * 再强化.
+ *
+ * 拍板 (D-20.7.7, 2026-06-06): 保守匹配, 不命中普通命令 exit 1 (e.g. 编译失败,
+ * 测试 fail) 误报.
+ */
+export declare function looksLikeSpawnError(stdout: string, stderr: string, exitCode: number | null): boolean;
+/**
+ * 跑 4 步验证 (默认), 返回 `VerificationReport`.
+ *
+ * 拍板 (D-11, 2026-06-04):
+ *   - 任一 step 失败 → 整体 fail, **不**继续后续 step (fail-fast).
+ *     后续 step 基于 build 产物, 跑也是浪费; 而且 build fail 时 typecheck/test 必挂,
+ *     显式 fail-fast 比假绿更诚实.
+ *   - 步骤间**不**共享 stdout/stderr buffer: 每步清零 Buffer 防止污染.
+ *   - 返回的报告 `overallStatus` = 'failed' iff 任一 step status ∈ {failed, timed-out, spawn-error}.
+ *   - summary / nextSuggestedAction 由调用方 (REPL/CLI/format-report) 写.
+ *     runner 不写自然语言, 保持纯函数语义 (便于单测 / roundtrip).
+ */
+export declare function runVerify(options?: RunVerifyOptions): Promise<VerificationReport>;
+//# sourceMappingURL=verify-runner.d.ts.map

package/dist/verify/verify-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-runner.d.ts","sourceRoot":"","sources":["../../src/verify/verify-runner.ts"],"names":[],"mappings":"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"}