get-shit-done 的 gsd-tools --json-errors 如何输出稳定错误码供脚本断言【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done当你在测试或 CI 脚本中调用 get-shit-done 的gsd-toolsCLI 时错误默认以Error: text的自由文本写到 stderr。这类文本措辞可能随版本变化对原始错误串做.includes()或正则匹配会让断言在无害的文案改动上误报、又对真正的错误漏报。gsd-tools内置的 JSON error mode 解决了这个问题开启后所有错误以一条结构化 JSON 写到 stderr其中reason字段是冻结的常量错误码脚本可以稳定地断言它。本文适用于本仓库的gsd-toolsCLI入口文件位于 get-shit-done/bin/gsd-tools.cjs运行环境要求 Node 22 及以上CONTRIBUTING.md 明确 Node 22 为最低支持版本Node 24 是主要 CI 目标。准备条件Node 22 或更高版本Node 24 为主 CI 目标不要使用 Node 22 之外的 API。仓库中的gsd-tools入口文件是 get-shit-done/bin/gsd-tools.cjs。docs/json-errors.md 中的示例命令写作node gsd-tools.cjs ...即在文件所在目录内运行在仓库根目录执行时等价写法为node get-shit-done/bin/gsd-tools.cjs ...。错误码定义在 get-shit-done/bin/lib/core.cjs 的ERROR_REASON冻结枚举中断言前先核对该文件确认当前代码集合。开启 JSON error mode两种方式任选其一均为 opt-in默认关闭关闭时人类操作者看到的仍是Error: message纯文本# Flag测试代码中推荐 node gsd-tools.cjs --json-errors command [args] # Env varshell 包装器与 CI 推荐 GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]两个实现细节值得注意见 get-shit-done/bin/gsd-tools.cjs 中的处理逻辑--json-errors在任何 flag 解析之前被检测并从 argv 中移除因此它不会被路由器当作未知命令处理且--cwd或 workstream 解析阶段的失败也会走结构化 stderr。该标志只改变错误输出形式对成功命令没有任何影响成功的命令照常以退出码 0 结束stdout 内容不变。错误输出的线格式任何错误发生时进程向stderr恰好写一行 JSON 并以退出码1退出{ ok: false, reason: error_code, message: human text }字段类型说明okfalse错误对象恒为false。reasonstring下文分类表中的类型化原因码稳定应断言这个字段。messagestring人类可读描述可能变化不要断言它。tests/feat-3255-json-errors-mode.test.cjs 锁定了三条可复用的形状契约错误对象顶层恰好是{ok, reason, message}三个键无额外键每次调用 stderr 只有一行 JSON进程在第一个错误时退出成功命令不受--json-errors影响。实现位于 get-shit-done/bin/lib/core.cjs 的error()函数JSON 模式下error()将{ ok: false, reason, message }序列化后写入 stderr 并process.exit(1)。稳定错误码分类reason的取值是get-shit-done/bin/lib/core.cjs中ERROR_REASON的冻结常量snake_case、按子系统加前缀分组。docs/json-errors.md 的分类表如下Dispatch 错误gsd-tools 路由层Code触发条件sdk_unknown_command未知顶层命令如gsd-tools bogus-cmd、未知点分命令gsd-tools foo.bar且foo不是已知命令、域内未知子命令如gsd-tools intel bogus-subsdk_missing_argSDK 层守卫判定必填参数缺失sdk_fail_fast触发 SDK fail-fast 策略用法 / flag 错误Code触发条件usage--pick后缺少值gsd-tools 不接受的版本 flag--version、-v顶层无参数调用Config 错误config-get、config-set、config-ensure-sectionCode触发条件config_key_not_foundconfig-get的键不存在于配置文件config_no_file配置操作时.planning/config.json不存在config_parse_failed配置文件存在但不是合法 JSONconfig_invalid_keyconfig-set的键不在允许白名单内Phase / workflow 错误Code触发条件phase_not_foundPhase 目录查找无匹配summary_no_planning无.planning/目录时执行 summary 操作Graphify 错误Code触发条件graphify_no_graph未构建 graph 时执行 graphify 查询或 diffgraphify_invalid_querygraphify 查询串格式错误Hook / 安全错误Code触发条件hooks_opt_outHooks 被 opt-out 配置禁用security_scan_failed安全扫描产出了阻断操作的发现兜底Code触发条件unknown所有未分配具体原因码的其他错误SDK 路由层的结构化原因会透传到 CJS 层gsd-tools.cjs将 SDK 返回的errorDetails.reason传给error()因此经 SDK 路径失败的命令如config-get同样能拿到具体代码如config_key_not_found而不是笼统的unknown。在脚本中写断言docs/json-errors.md 的规则始终用JSON.parse解析 stderr 并断言类型化字段绝不对原始错误串使用.includes()、.match()或正则。CONTRIBUTING.md 的 Prohibited: Raw Text Matching on Test Outputs 一节将此列为仓库级禁令由scripts/lint-no-source-grep.cjs策略强制执行。文档给出的正确写法摘自 docs/json-errors.md// CORRECT: parse then assert on typed field const result runGsdTools([--json-errors, bogus-command], tmpDir); assert.strictEqual(result.success, false); const err JSON.parse(result.error); assert.strictEqual(err.ok, false); assert.strictEqual(err.reason, sdk_unknown_command); // WRONG: text matching (banned by lint-no-source-grep policy) // assert.ok(result.error.includes(Unknown command));其中runGsdTools是本仓库测试 helper见 tests/helpers.cjs返回包含success、outputstdout、errorstderr字段的运行结果。tests/feat-3255-json-errors-mode.test.cjs 中的runJsonErrorshelper 展示了更严格的封装先断言命令必须失败再JSON.parse(result.error)解析失败时把完整 stderr 抛进错误信息——这样脚本在 wire 格式被破坏时能给出可读的诊断。对于 shell 包装器与 CI用文档给出的环境变量方式开启即可后续对 stderr 的解析逻辑与 JS 侧相同GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]验证方式触发已知场景并核对 reason以下调用 → 预期 reason组合均能在 tests/feat-3255-json-errors-mode.test.cjs 中找到对应测试用例可直接作为你脚本中的断言目标调用带--json-errors预期退出码预期reasontotally-unknown-command-xyzzy任意未知顶层命令1sdk_unknown_commandfoo.bar未知点分命令1sdk_unknown_commandintel bogus-subcommand-xyzzy域内未知子命令1sdk_unknown_commandgenerate-slug test-text --pick--pick缺值1usage--version generate-slug xgsd-tools 不接受--version1usageconfig-get nonexistent_config_key_xyzzy先执行过config-ensure-section建好.planning/config.json1config_key_not_found对每次失败调用完整断言链是退出码为 1stderr 能JSON.parse成功ok falsereason等于预期值顶层键排序后恰好为[message, ok, reason]非空 stderr 行恰好一条。对成功路径如generate-slug hello-world断言进程成功、stdout 非空证明 flag 未污染正常输出。扩展新增一个错误码docs/json-errors.md 的 Adding a new error code 给出固定四步流程get-shit-done/bin/lib/core.cjs 中ERROR_REASON的注释与之一致在get-shit-done/bin/lib/core.cjs的ERROR_REASON中加常量取值用 snake_case 小写即 JSON 线上的形式按子系统加前缀分组如CONFIG_*、SDK_*。在调用点把它作为error()的第二个参数传入error(msg, ERROR_REASON.NEW_CODE)。在 docs/json-errors.md 的分类表中加一行。加一个用JSON.parse断言新reason代码的测试。四步同步变更是刻意设计枚举、调用点、文档、测试任何一处遗漏都会导致代码面与测试面漂移被测试发现。限制message字段不稳定任何对它的断言都会随文案改动失效只有reason是稳定契约。模式默认关闭且只影响错误输出成功路径的行为与输出完全不变。错误码是冻结枚举未分配具体码的错误落到unknown你的脚本断言unknown时要意识到这是兜底而非具体原因。每次调用只输出第一处错误的 JSON 行进程随即退出stderr 不会有第二条错误。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
get-shit-done 的 gsd-tools --json-errors 如何输出稳定错误码供脚本断言
get-shit-done 的 gsd-tools --json-errors 如何输出稳定错误码供脚本断言【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done当你在测试或 CI 脚本中调用 get-shit-done 的gsd-toolsCLI 时错误默认以Error: text的自由文本写到 stderr。这类文本措辞可能随版本变化对原始错误串做.includes()或正则匹配会让断言在无害的文案改动上误报、又对真正的错误漏报。gsd-tools内置的 JSON error mode 解决了这个问题开启后所有错误以一条结构化 JSON 写到 stderr其中reason字段是冻结的常量错误码脚本可以稳定地断言它。本文适用于本仓库的gsd-toolsCLI入口文件位于 get-shit-done/bin/gsd-tools.cjs运行环境要求 Node 22 及以上CONTRIBUTING.md 明确 Node 22 为最低支持版本Node 24 是主要 CI 目标。准备条件Node 22 或更高版本Node 24 为主 CI 目标不要使用 Node 22 之外的 API。仓库中的gsd-tools入口文件是 get-shit-done/bin/gsd-tools.cjs。docs/json-errors.md 中的示例命令写作node gsd-tools.cjs ...即在文件所在目录内运行在仓库根目录执行时等价写法为node get-shit-done/bin/gsd-tools.cjs ...。错误码定义在 get-shit-done/bin/lib/core.cjs 的ERROR_REASON冻结枚举中断言前先核对该文件确认当前代码集合。开启 JSON error mode两种方式任选其一均为 opt-in默认关闭关闭时人类操作者看到的仍是Error: message纯文本# Flag测试代码中推荐 node gsd-tools.cjs --json-errors command [args] # Env varshell 包装器与 CI 推荐 GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]两个实现细节值得注意见 get-shit-done/bin/gsd-tools.cjs 中的处理逻辑--json-errors在任何 flag 解析之前被检测并从 argv 中移除因此它不会被路由器当作未知命令处理且--cwd或 workstream 解析阶段的失败也会走结构化 stderr。该标志只改变错误输出形式对成功命令没有任何影响成功的命令照常以退出码 0 结束stdout 内容不变。错误输出的线格式任何错误发生时进程向stderr恰好写一行 JSON 并以退出码1退出{ ok: false, reason: error_code, message: human text }字段类型说明okfalse错误对象恒为false。reasonstring下文分类表中的类型化原因码稳定应断言这个字段。messagestring人类可读描述可能变化不要断言它。tests/feat-3255-json-errors-mode.test.cjs 锁定了三条可复用的形状契约错误对象顶层恰好是{ok, reason, message}三个键无额外键每次调用 stderr 只有一行 JSON进程在第一个错误时退出成功命令不受--json-errors影响。实现位于 get-shit-done/bin/lib/core.cjs 的error()函数JSON 模式下error()将{ ok: false, reason, message }序列化后写入 stderr 并process.exit(1)。稳定错误码分类reason的取值是get-shit-done/bin/lib/core.cjs中ERROR_REASON的冻结常量snake_case、按子系统加前缀分组。docs/json-errors.md 的分类表如下Dispatch 错误gsd-tools 路由层Code触发条件sdk_unknown_command未知顶层命令如gsd-tools bogus-cmd、未知点分命令gsd-tools foo.bar且foo不是已知命令、域内未知子命令如gsd-tools intel bogus-subsdk_missing_argSDK 层守卫判定必填参数缺失sdk_fail_fast触发 SDK fail-fast 策略用法 / flag 错误Code触发条件usage--pick后缺少值gsd-tools 不接受的版本 flag--version、-v顶层无参数调用Config 错误config-get、config-set、config-ensure-sectionCode触发条件config_key_not_foundconfig-get的键不存在于配置文件config_no_file配置操作时.planning/config.json不存在config_parse_failed配置文件存在但不是合法 JSONconfig_invalid_keyconfig-set的键不在允许白名单内Phase / workflow 错误Code触发条件phase_not_foundPhase 目录查找无匹配summary_no_planning无.planning/目录时执行 summary 操作Graphify 错误Code触发条件graphify_no_graph未构建 graph 时执行 graphify 查询或 diffgraphify_invalid_querygraphify 查询串格式错误Hook / 安全错误Code触发条件hooks_opt_outHooks 被 opt-out 配置禁用security_scan_failed安全扫描产出了阻断操作的发现兜底Code触发条件unknown所有未分配具体原因码的其他错误SDK 路由层的结构化原因会透传到 CJS 层gsd-tools.cjs将 SDK 返回的errorDetails.reason传给error()因此经 SDK 路径失败的命令如config-get同样能拿到具体代码如config_key_not_found而不是笼统的unknown。在脚本中写断言docs/json-errors.md 的规则始终用JSON.parse解析 stderr 并断言类型化字段绝不对原始错误串使用.includes()、.match()或正则。CONTRIBUTING.md 的 Prohibited: Raw Text Matching on Test Outputs 一节将此列为仓库级禁令由scripts/lint-no-source-grep.cjs策略强制执行。文档给出的正确写法摘自 docs/json-errors.md// CORRECT: parse then assert on typed field const result runGsdTools([--json-errors, bogus-command], tmpDir); assert.strictEqual(result.success, false); const err JSON.parse(result.error); assert.strictEqual(err.ok, false); assert.strictEqual(err.reason, sdk_unknown_command); // WRONG: text matching (banned by lint-no-source-grep policy) // assert.ok(result.error.includes(Unknown command));其中runGsdTools是本仓库测试 helper见 tests/helpers.cjs返回包含success、outputstdout、errorstderr字段的运行结果。tests/feat-3255-json-errors-mode.test.cjs 中的runJsonErrorshelper 展示了更严格的封装先断言命令必须失败再JSON.parse(result.error)解析失败时把完整 stderr 抛进错误信息——这样脚本在 wire 格式被破坏时能给出可读的诊断。对于 shell 包装器与 CI用文档给出的环境变量方式开启即可后续对 stderr 的解析逻辑与 JS 侧相同GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]验证方式触发已知场景并核对 reason以下调用 → 预期 reason组合均能在 tests/feat-3255-json-errors-mode.test.cjs 中找到对应测试用例可直接作为你脚本中的断言目标调用带--json-errors预期退出码预期reasontotally-unknown-command-xyzzy任意未知顶层命令1sdk_unknown_commandfoo.bar未知点分命令1sdk_unknown_commandintel bogus-subcommand-xyzzy域内未知子命令1sdk_unknown_commandgenerate-slug test-text --pick--pick缺值1usage--version generate-slug xgsd-tools 不接受--version1usageconfig-get nonexistent_config_key_xyzzy先执行过config-ensure-section建好.planning/config.json1config_key_not_found对每次失败调用完整断言链是退出码为 1stderr 能JSON.parse成功ok falsereason等于预期值顶层键排序后恰好为[message, ok, reason]非空 stderr 行恰好一条。对成功路径如generate-slug hello-world断言进程成功、stdout 非空证明 flag 未污染正常输出。扩展新增一个错误码docs/json-errors.md 的 Adding a new error code 给出固定四步流程get-shit-done/bin/lib/core.cjs 中ERROR_REASON的注释与之一致在get-shit-done/bin/lib/core.cjs的ERROR_REASON中加常量取值用 snake_case 小写即 JSON 线上的形式按子系统加前缀分组如CONFIG_*、SDK_*。在调用点把它作为error()的第二个参数传入error(msg, ERROR_REASON.NEW_CODE)。在 docs/json-errors.md 的分类表中加一行。加一个用JSON.parse断言新reason代码的测试。四步同步变更是刻意设计枚举、调用点、文档、测试任何一处遗漏都会导致代码面与测试面漂移被测试发现。限制message字段不稳定任何对它的断言都会随文案改动失效只有reason是稳定契约。模式默认关闭且只影响错误输出成功路径的行为与输出完全不变。错误码是冻结枚举未分配具体码的错误落到unknown你的脚本断言unknown时要意识到这是兜底而非具体原因。每次调用只输出第一处错误的 JSON 行进程随即退出stderr 不会有第二条错误。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考