定錯誤碼供腳本斷言)
get-shit-done 的 gsd-tools --json-errors 如何輸出穩(wěn)定錯誤碼供腳本斷言【免費下載鏈接】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 腳本中調(diào)用 get-shit-done 的gsd-toolsCLI 時錯誤默認以Error: text的自由文本寫到 stderr。這類文本措辭可能隨版本變化對原始錯誤串做.includes()或正則匹配會讓斷言在無害的文案改動上誤報、又對真正的錯誤漏報。gsd-tools內(nèi)置的 JSON error mode 解決了這個問題開啟后所有錯誤以一條結構化 JSON 寫到 stderr其中reason字段是凍結的常量錯誤碼腳本可以穩(wěn)定地斷言它。本文適用于本倉庫的gsd-toolsCLI入口文件位于 get-shit-done/bin/gsd-tools.cjs運行環(huán)境要求 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 ...即在文件所在目錄內(nèi)運行在倉庫根目錄執(zhí)行時等價寫法為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]兩個實現(xiàn)細節(jié)值得注意見 get-shit-done/bin/gsd-tools.cjs 中的處理邏輯--json-errors在任何 flag 解析之前被檢測并從 argv 中移除因此它不會被路由器當作未知命令處理且--cwd或 workstream 解析階段的失敗也會走結構化 stderr。該標志只改變錯誤輸出形式對成功命令沒有任何影響成功的命令照常以退出碼 0 結束stdout 內(nèi)容不變。錯誤輸出的線格式任何錯誤發(fā)生時進程向stderr恰好寫一行 JSON 并以退出碼1退出{ ok: false, reason: error_code, message: human text }字段類型說明okfalse錯誤對象恒為false。reasonstring下文分類表中的類型化原因碼穩(wěn)定應斷言這個字段。messagestring人類可讀描述可能變化不要斷言它。tests/feat-3255-json-errors-mode.test.cjs 鎖定了三條可復用的形狀契約錯誤對象頂層恰好是{ok, reason, message}三個鍵無額外鍵每次調(diào)用 stderr 只有一行 JSON進程在第一個錯誤時退出成功命令不受--json-errors影響。實現(xiàn)位于 get-shit-done/bin/lib/core.cjs 的error()函數(shù)JSON 模式下error()將{ ok: false, reason, message }序列化后寫入 stderr 并process.exit(1)。穩(wěn)定錯誤碼分類reason的取值是get-shit-done/bin/lib/core.cjs中ERROR_REASON的凍結常量snake_case、按子系統(tǒng)加前綴分組。docs/json-errors.md 的分類表如下Dispatch 錯誤gsd-tools 路由層Code觸發(fā)條件sdk_unknown_command未知頂層命令如gsd-tools bogus-cmd、未知點分命令gsd-tools foo.bar且foo不是已知命令、域內(nèi)未知子命令如gsd-tools intel bogus-subsdk_missing_argSDK 層守衛(wèi)判定必填參數(shù)缺失sdk_fail_fast觸發(fā) SDK fail-fast 策略用法 / flag 錯誤Code觸發(fā)條件usage--pick后缺少值gsd-tools 不接受的版本 flag--version、-v頂層無參數(shù)調(diào)用Config 錯誤config-get、config-set、config-ensure-sectionCode觸發(fā)條件config_key_not_foundconfig-get的鍵不存在于配置文件config_no_file配置操作時.planning/config.json不存在config_parse_failed配置文件存在但不是合法 JSONconfig_invalid_keyconfig-set的鍵不在允許白名單內(nèi)Phase / workflow 錯誤Code觸發(fā)條件phase_not_foundPhase 目錄查找無匹配summary_no_planning無.planning/目錄時執(zhí)行 summary 操作Graphify 錯誤Code觸發(fā)條件graphify_no_graph未構建 graph 時執(zhí)行 graphify 查詢或 diffgraphify_invalid_querygraphify 查詢串格式錯誤Hook / 安全錯誤Code觸發(fā)條件hooks_opt_outHooks 被 opt-out 配置禁用security_scan_failed安全掃描產(chǎn)出了阻斷操作的發(fā)現(xiàn)兜底Code觸發(fā)條件unknown所有未分配具體原因碼的其他錯誤SDK 路由層的結構化原因會透傳到 CJS 層gsd-tools.cjs將 SDK 返回的errorDetails.reason傳給error()因此經(jīng) SDK 路徑失敗的命令如config-get同樣能拿到具體代碼如config_key_not_found而不是籠統(tǒng)的unknown。在腳本中寫斷言docs/json-errors.md 的規(guī)則始終用JSON.parse解析 stderr 并斷言類型化字段絕不對原始錯誤串使用.includes()、.match()或正則。CONTRIBUTING.md 的 Prohibited: Raw Text Matching on Test Outputs 一節(jié)將此列為倉庫級禁令由scripts/lint-no-source-grep.cjs策略強制執(zhí)行。文檔給出的正確寫法摘自 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用文檔給出的環(huán)境變量方式開啟即可后續(xù)對 stderr 的解析邏輯與 JS 側(cè)相同GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]驗證方式觸發(fā)已知場景并核對 reason以下調(diào)用 → 預期 reason組合均能在 tests/feat-3255-json-errors-mode.test.cjs 中找到對應測試用例可直接作為你腳本中的斷言目標調(diào)用帶--json-errors預期退出碼預期reasontotally-unknown-command-xyzzy任意未知頂層命令1sdk_unknown_commandfoo.bar未知點分命令1sdk_unknown_commandintel bogus-subcommand-xyzzy域內(nèi)未知子命令1sdk_unknown_commandgenerate-slug test-text --pick--pick缺值1usage--version generate-slug xgsd-tools 不接受--version1usageconfig-get nonexistent_config_key_xyzzy先執(zhí)行過config-ensure-section建好.planning/config.json1config_key_not_found對每次失敗調(diào)用完整斷言鏈是退出碼為 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 線上的形式按子系統(tǒng)加前綴分組如CONFIG_*、SDK_*。在調(diào)用點把它作為error()的第二個參數(shù)傳入error(msg, ERROR_REASON.NEW_CODE)。在 docs/json-errors.md 的分類表中加一行。加一個用JSON.parse斷言新reason代碼的測試。四步同步變更是刻意設計枚舉、調(diào)用點、文檔、測試任何一處遺漏都會導致代碼面與測試面漂移被測試發(fā)現(xiàn)。限制message字段不穩(wěn)定任何對它的斷言都會隨文案改動失效只有reason是穩(wěn)定契約。模式默認關閉且只影響錯誤輸出成功路徑的行為與輸出完全不變。錯誤碼是凍結枚舉未分配具體碼的錯誤落到unknown你的腳本斷言unknown時要意識到這是兜底而非具體原因。每次調(diào)用只輸出第一處錯誤的 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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 get-shit-done 的 gsd-tools --json-errors 如何輸出穩(wěn)定錯誤碼供腳本斷言
get-shit-done 的 gsd-tools --json-errors 如何輸出穩(wěn)定錯誤碼供腳本斷言【免費下載鏈接】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 腳本中調(diào)用 get-shit-done 的gsd-toolsCLI 時錯誤默認以Error: text的自由文本寫到 stderr。這類文本措辭可能隨版本變化對原始錯誤串做.includes()或正則匹配會讓斷言在無害的文案改動上誤報、又對真正的錯誤漏報。gsd-tools內(nèi)置的 JSON error mode 解決了這個問題開啟后所有錯誤以一條結構化 JSON 寫到 stderr其中reason字段是凍結的常量錯誤碼腳本可以穩(wěn)定地斷言它。本文適用于本倉庫的gsd-toolsCLI入口文件位于 get-shit-done/bin/gsd-tools.cjs運行環(huán)境要求 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 ...即在文件所在目錄內(nèi)運行在倉庫根目錄執(zhí)行時等價寫法為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]兩個實現(xiàn)細節(jié)值得注意見 get-shit-done/bin/gsd-tools.cjs 中的處理邏輯--json-errors在任何 flag 解析之前被檢測并從 argv 中移除因此它不會被路由器當作未知命令處理且--cwd或 workstream 解析階段的失敗也會走結構化 stderr。該標志只改變錯誤輸出形式對成功命令沒有任何影響成功的命令照常以退出碼 0 結束stdout 內(nèi)容不變。錯誤輸出的線格式任何錯誤發(fā)生時進程向stderr恰好寫一行 JSON 并以退出碼1退出{ ok: false, reason: error_code, message: human text }字段類型說明okfalse錯誤對象恒為false。reasonstring下文分類表中的類型化原因碼穩(wěn)定應斷言這個字段。messagestring人類可讀描述可能變化不要斷言它。tests/feat-3255-json-errors-mode.test.cjs 鎖定了三條可復用的形狀契約錯誤對象頂層恰好是{ok, reason, message}三個鍵無額外鍵每次調(diào)用 stderr 只有一行 JSON進程在第一個錯誤時退出成功命令不受--json-errors影響。實現(xiàn)位于 get-shit-done/bin/lib/core.cjs 的error()函數(shù)JSON 模式下error()將{ ok: false, reason, message }序列化后寫入 stderr 并process.exit(1)。穩(wěn)定錯誤碼分類reason的取值是get-shit-done/bin/lib/core.cjs中ERROR_REASON的凍結常量snake_case、按子系統(tǒng)加前綴分組。docs/json-errors.md 的分類表如下Dispatch 錯誤gsd-tools 路由層Code觸發(fā)條件sdk_unknown_command未知頂層命令如gsd-tools bogus-cmd、未知點分命令gsd-tools foo.bar且foo不是已知命令、域內(nèi)未知子命令如gsd-tools intel bogus-subsdk_missing_argSDK 層守衛(wèi)判定必填參數(shù)缺失sdk_fail_fast觸發(fā) SDK fail-fast 策略用法 / flag 錯誤Code觸發(fā)條件usage--pick后缺少值gsd-tools 不接受的版本 flag--version、-v頂層無參數(shù)調(diào)用Config 錯誤config-get、config-set、config-ensure-sectionCode觸發(fā)條件config_key_not_foundconfig-get的鍵不存在于配置文件config_no_file配置操作時.planning/config.json不存在config_parse_failed配置文件存在但不是合法 JSONconfig_invalid_keyconfig-set的鍵不在允許白名單內(nèi)Phase / workflow 錯誤Code觸發(fā)條件phase_not_foundPhase 目錄查找無匹配summary_no_planning無.planning/目錄時執(zhí)行 summary 操作Graphify 錯誤Code觸發(fā)條件graphify_no_graph未構建 graph 時執(zhí)行 graphify 查詢或 diffgraphify_invalid_querygraphify 查詢串格式錯誤Hook / 安全錯誤Code觸發(fā)條件hooks_opt_outHooks 被 opt-out 配置禁用security_scan_failed安全掃描產(chǎn)出了阻斷操作的發(fā)現(xiàn)兜底Code觸發(fā)條件unknown所有未分配具體原因碼的其他錯誤SDK 路由層的結構化原因會透傳到 CJS 層gsd-tools.cjs將 SDK 返回的errorDetails.reason傳給error()因此經(jīng) SDK 路徑失敗的命令如config-get同樣能拿到具體代碼如config_key_not_found而不是籠統(tǒng)的unknown。在腳本中寫斷言docs/json-errors.md 的規(guī)則始終用JSON.parse解析 stderr 并斷言類型化字段絕不對原始錯誤串使用.includes()、.match()或正則。CONTRIBUTING.md 的 Prohibited: Raw Text Matching on Test Outputs 一節(jié)將此列為倉庫級禁令由scripts/lint-no-source-grep.cjs策略強制執(zhí)行。文檔給出的正確寫法摘自 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用文檔給出的環(huán)境變量方式開啟即可后續(xù)對 stderr 的解析邏輯與 JS 側(cè)相同GSD_JSON_ERRORS1 node gsd-tools.cjs command [args]驗證方式觸發(fā)已知場景并核對 reason以下調(diào)用 → 預期 reason組合均能在 tests/feat-3255-json-errors-mode.test.cjs 中找到對應測試用例可直接作為你腳本中的斷言目標調(diào)用帶--json-errors預期退出碼預期reasontotally-unknown-command-xyzzy任意未知頂層命令1sdk_unknown_commandfoo.bar未知點分命令1sdk_unknown_commandintel bogus-subcommand-xyzzy域內(nèi)未知子命令1sdk_unknown_commandgenerate-slug test-text --pick--pick缺值1usage--version generate-slug xgsd-tools 不接受--version1usageconfig-get nonexistent_config_key_xyzzy先執(zhí)行過config-ensure-section建好.planning/config.json1config_key_not_found對每次失敗調(diào)用完整斷言鏈是退出碼為 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 線上的形式按子系統(tǒng)加前綴分組如CONFIG_*、SDK_*。在調(diào)用點把它作為error()的第二個參數(shù)傳入error(msg, ERROR_REASON.NEW_CODE)。在 docs/json-errors.md 的分類表中加一行。加一個用JSON.parse斷言新reason代碼的測試。四步同步變更是刻意設計枚舉、調(diào)用點、文檔、測試任何一處遺漏都會導致代碼面與測試面漂移被測試發(fā)現(xiàn)。限制message字段不穩(wěn)定任何對它的斷言都會隨文案改動失效只有reason是穩(wěn)定契約。模式默認關閉且只影響錯誤輸出成功路徑的行為與輸出完全不變。錯誤碼是凍結枚舉未分配具體碼的錯誤落到unknown你的腳本斷言unknown時要意識到這是兜底而非具體原因。每次調(diào)用只輸出第一處錯誤的 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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考