crysk 0.0.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (233) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +611 -3
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/SKILL-y8rv8msh.md +134 -0
  10. package/dist/SKILL-ygka1bs0.md +515 -0
  11. package/dist/adjudicator-dtg2axnh.md +86 -0
  12. package/dist/admission-config.example-a9vqmmad.json +9 -0
  13. package/dist/ci-admission-camfbx2b.md +122 -0
  14. package/dist/ci-admission-qk9r9taq.md +124 -0
  15. package/dist/cli.js +42501 -0
  16. package/dist/consolidate-ac0mnfyj.md +24 -0
  17. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  18. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  19. package/dist/deep-review-parity-0ec904db.md +120 -0
  20. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  21. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  22. package/dist/index.js +20190 -0
  23. package/dist/opencode-ci-7b0be64p.md +141 -0
  24. package/dist/review-refuter-j4e9gezy.md +71 -0
  25. package/dist/scout-yvp153q7.md +140 -0
  26. package/dist/summarizer-zca44nxa.md +18 -0
  27. package/dist/workflow-w1g9szna.yml +151 -0
  28. package/package.json +81 -4
  29. package/prompts/consolidate.md +24 -0
  30. package/prompts/default/PROVENANCE.md +18 -0
  31. package/prompts/default/deep-review-lifecycle.md +362 -0
  32. package/prompts/default/deep-review-logic.md +156 -0
  33. package/prompts/default/deep-review-parity.md +120 -0
  34. package/prompts/default/deep-review-reliability.md +125 -0
  35. package/prompts/default/deep-review-resilience.md +118 -0
  36. package/prompts/default/review-refuter.md +71 -0
  37. package/prompts/scout.md +140 -0
  38. package/prompts/summarizer.md +18 -0
  39. package/skills/crysk/SKILL.md +74 -0
  40. package/skills/crysk-ci-setup/SKILL.md +134 -0
  41. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  42. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  43. package/skills/crysk-ci-setup/references/ci-admission.md +124 -0
  44. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  45. package/skills/crysk-loop/SKILL.md +515 -0
  46. package/skills/crysk-loop/adjudicator.md +86 -0
  47. package/skills/crysk-pr/SKILL.md +66 -0
  48. package/src/agent-env.ts +1084 -0
  49. package/src/asset-manifest.ts +83 -0
  50. package/src/assets.d.ts +6 -0
  51. package/src/assets.ts +183 -0
  52. package/src/brand-paths.ts +155 -0
  53. package/src/brand.ts +255 -0
  54. package/src/ci/admission-ledger.ts +350 -0
  55. package/src/ci/classify-error.ts +73 -0
  56. package/src/ci/cli-record.ts +271 -0
  57. package/src/ci/force-comment.ts +39 -0
  58. package/src/ci/gates.ts +945 -0
  59. package/src/ci/outcome.ts +2181 -0
  60. package/src/ci/override.ts +187 -0
  61. package/src/ci/publish.ts +1639 -0
  62. package/src/ci/reporter.ts +626 -0
  63. package/src/ci/review-admission.ts +910 -0
  64. package/src/ci/review-levels.ts +310 -0
  65. package/src/ci/review-policy.ts +18 -0
  66. package/src/ci/review-risk.ts +184 -0
  67. package/src/ci/setup.ts +844 -0
  68. package/src/ci/trigger.ts +1353 -0
  69. package/src/cli.ts +348 -0
  70. package/src/commands/activity.ts +67 -0
  71. package/src/commands/ci-setup-questions.ts +397 -0
  72. package/src/commands/ci-setup.ts +381 -0
  73. package/src/commands/config.ts +99 -0
  74. package/src/commands/doctor.ts +108 -0
  75. package/src/commands/init.ts +139 -0
  76. package/src/commands/mcp.ts +10 -0
  77. package/src/commands/menu.ts +129 -0
  78. package/src/commands/post.ts +302 -0
  79. package/src/commands/skills.ts +83 -0
  80. package/src/commands/status.ts +173 -0
  81. package/src/commands/triage.ts +342 -0
  82. package/src/commands/uninstall.ts +37 -0
  83. package/src/commands/upgrade.ts +214 -0
  84. package/src/commands/usage.ts +98 -0
  85. package/src/compare/compare.ts +28 -0
  86. package/src/compare/floor-test.ts +471 -0
  87. package/src/compare/martian-adapter.ts +80 -0
  88. package/src/config/config.ts +267 -0
  89. package/src/corpus/corpus.ts +1094 -0
  90. package/src/corpus/preflight.ts +1789 -0
  91. package/src/diversity/accounting.ts +90 -0
  92. package/src/diversity/adjudication.ts +145 -0
  93. package/src/diversity/admission.ts +60 -0
  94. package/src/diversity/benchmark.ts +195 -0
  95. package/src/diversity/clustering.ts +285 -0
  96. package/src/diversity/errors.ts +7 -0
  97. package/src/diversity/identity.ts +285 -0
  98. package/src/diversity/index.ts +11 -0
  99. package/src/diversity/pipeline-integration.ts +448 -0
  100. package/src/diversity/projection.ts +57 -0
  101. package/src/diversity/self-contained.ts +68 -0
  102. package/src/diversity/target-validation.ts +179 -0
  103. package/src/doctor-migration.ts +209 -0
  104. package/src/doctor.ts +723 -0
  105. package/src/errors.ts +83 -0
  106. package/src/execution/admission.ts +75 -0
  107. package/src/execution/atomic-write.ts +35 -0
  108. package/src/execution/attempt-evidence.ts +415 -0
  109. package/src/execution/bucket-id.ts +136 -0
  110. package/src/execution/concurrency-limiter.ts +175 -0
  111. package/src/execution/contracts.ts +443 -0
  112. package/src/execution/failure-classification.ts +42 -0
  113. package/src/execution/failure-policy.ts +240 -0
  114. package/src/execution/harness.ts +2548 -0
  115. package/src/execution/settlement.ts +348 -0
  116. package/src/execution/spawned-process.ts +66 -0
  117. package/src/execution/spend-limiter.ts +424 -0
  118. package/src/execution/step-artifacts.ts +55 -0
  119. package/src/execution/usage-normalized.ts +469 -0
  120. package/src/git/git.ts +396 -0
  121. package/src/git/identity.ts +64 -0
  122. package/src/git/refs.ts +140 -0
  123. package/src/home-preflight.ts +443 -0
  124. package/src/home.ts +243 -0
  125. package/src/ignore-file.ts +336 -0
  126. package/src/ignore-read.ts +118 -0
  127. package/src/index.ts +34 -0
  128. package/src/legacy-launchd.ts +29 -0
  129. package/src/mcp/mcp.ts +150 -0
  130. package/src/mcp/preflight.ts +407 -0
  131. package/src/menu-context.ts +192 -0
  132. package/src/model/catalog.ts +251 -0
  133. package/src/model/exec-snapshots.ts +390 -0
  134. package/src/model/free-discovery.ts +302 -0
  135. package/src/model/provider-capabilities.ts +814 -0
  136. package/src/model/routing.ts +600 -0
  137. package/src/pr/admission.ts +984 -0
  138. package/src/pr/answered-findings.ts +169 -0
  139. package/src/pr/ci-admission-gate.ts +743 -0
  140. package/src/pr/ci-publish.ts +76 -0
  141. package/src/pr/discovery.ts +432 -0
  142. package/src/pr/inline.ts +507 -0
  143. package/src/pr/plan.ts +366 -0
  144. package/src/pr/posting.ts +115 -0
  145. package/src/pr/pr-status.ts +845 -0
  146. package/src/pr/pr.ts +3642 -0
  147. package/src/pr/preflight.ts +1031 -0
  148. package/src/pr/publish-outcome.ts +361 -0
  149. package/src/pr/range.ts +119 -0
  150. package/src/pr/reverts-preflight.ts +606 -0
  151. package/src/pr/reverts.ts +377 -0
  152. package/src/pr/review-pr.ts +927 -0
  153. package/src/pr/status.ts +154 -0
  154. package/src/pr/target.ts +388 -0
  155. package/src/pr/teardown.ts +437 -0
  156. package/src/pr/worktree-setup.ts +60 -0
  157. package/src/production-runtime.ts +1877 -0
  158. package/src/progress.ts +487 -0
  159. package/src/rereview/adjudicate.ts +89 -0
  160. package/src/rereview/classify.ts +362 -0
  161. package/src/rereview/identity.ts +211 -0
  162. package/src/rereview/plan.ts +308 -0
  163. package/src/rereview/prepare.ts +1025 -0
  164. package/src/rereview/state.ts +767 -0
  165. package/src/rereview/verify.ts +241 -0
  166. package/src/review/boundary.ts +105 -0
  167. package/src/review/consolidate.ts +246 -0
  168. package/src/review/dedupe.ts +368 -0
  169. package/src/review/drafts.ts +448 -0
  170. package/src/review/findings-conformance.ts +120 -0
  171. package/src/review/findings.ts +714 -0
  172. package/src/review/pipeline.ts +3977 -0
  173. package/src/review/preflight.ts +3575 -0
  174. package/src/review/prompt-set.ts +177 -0
  175. package/src/review/proof-refs.ts +187 -0
  176. package/src/review/report.ts +1821 -0
  177. package/src/review/review.ts +490 -0
  178. package/src/review/root-cause.ts +120 -0
  179. package/src/review/route-preflight.ts +289 -0
  180. package/src/review/run.ts +601 -0
  181. package/src/review/scout.ts +323 -0
  182. package/src/review/size-gate.ts +595 -0
  183. package/src/review/spec.ts +235 -0
  184. package/src/review/step-runner.ts +233 -0
  185. package/src/runner-authority.ts +596 -0
  186. package/src/security/binding-policy.ts +115 -0
  187. package/src/security/credential-broker.ts +773 -0
  188. package/src/security/evidence-redaction.ts +62 -0
  189. package/src/security/execution-authority.ts +27 -0
  190. package/src/security/redact.ts +71 -0
  191. package/src/security/workspace-read-broker.ts +466 -0
  192. package/src/server/client.ts +190 -0
  193. package/src/server/preflight.ts +217 -0
  194. package/src/server/server.ts +327 -0
  195. package/src/signal-handler.ts +50 -0
  196. package/src/store/activity.ts +413 -0
  197. package/src/store/backfill-preflight.ts +49 -0
  198. package/src/store/backfill.ts +141 -0
  199. package/src/store/gc-preflight.ts +206 -0
  200. package/src/store/gc.ts +424 -0
  201. package/src/store/metrics-preflight.ts +229 -0
  202. package/src/store/metrics.ts +236 -0
  203. package/src/store/preflight.ts +748 -0
  204. package/src/store/store.ts +693 -0
  205. package/src/system-tools.ts +355 -0
  206. package/src/transport-registry.ts +1124 -0
  207. package/src/transports/claude-code-cli.ts +1348 -0
  208. package/src/transports/opencode-admission.ts +515 -0
  209. package/src/transports/opencode-client.ts +3328 -0
  210. package/src/transports/opencode-evidence.ts +557 -0
  211. package/src/transports/opencode-mcp.ts +248 -0
  212. package/src/transports/opencode-sdk.ts +2294 -0
  213. package/src/transports/opencode-server.ts +535 -0
  214. package/src/triage/adjudication.ts +113 -0
  215. package/src/triage/reply.ts +125 -0
  216. package/src/triage/triage.ts +255 -0
  217. package/src/ui/activity.ts +173 -0
  218. package/src/ui/config-edit.ts +816 -0
  219. package/src/ui/config.ts +462 -0
  220. package/src/ui/menu.ts +1325 -0
  221. package/src/ui/plan.ts +1039 -0
  222. package/src/ui/primitives.ts +300 -0
  223. package/src/ui/progress.ts +298 -0
  224. package/src/ui/result.ts +552 -0
  225. package/src/ui/review-menu.ts +312 -0
  226. package/src/ui/select.ts +528 -0
  227. package/src/ui/tree.ts +178 -0
  228. package/src/uninstaller.ts +479 -0
  229. package/src/updater.ts +836 -0
  230. package/src/usage.ts +77 -0
  231. package/src/watch/preflight.ts +1389 -0
  232. package/src/watch/watch.ts +1235 -0
  233. package/src/wizard.ts +877 -0
package/src/doctor.ts ADDED
@@ -0,0 +1,723 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import os from "node:os";
3
+ import path from "node:path";
4
+ import {
5
+ exactBindingCapabilityIssues,
6
+ type ProviderCapabilityReport,
7
+ } from "#model/provider-capabilities";
8
+ import { type RoutingConfig, routingNeedsOpenCodeSdk } from "#model/routing";
9
+ import {
10
+ agentFilePath,
11
+ GOTCHAS_PLACEHOLDER_MARKER,
12
+ gotchasUnusableReason,
13
+ localReviewSpec,
14
+ resolveAgentsDirSetting,
15
+ } from "#review/preflight";
16
+ import { resolveGotchasPath } from "#review/run";
17
+ import {
18
+ detectAgentEnvironments,
19
+ inspectMcpRegistration,
20
+ inspectSkillsSync,
21
+ } from "./agent-env";
22
+ import {
23
+ type EngineAssets,
24
+ isNpxCacheInvocation,
25
+ NPX_REGISTRATION_REFUSED,
26
+ resolveEngineAssets,
27
+ selfInvocation,
28
+ } from "./assets";
29
+ import { REPO_DIR_NAME, resolveHomeDir, resolveRepoDir } from "./brand-paths";
30
+ import {
31
+ gitIsTracked,
32
+ type IsTracked,
33
+ migrationChecks,
34
+ } from "./doctor-migration";
35
+ import type { ExactBindingCapabilityReport } from "./execution/contracts";
36
+ import {
37
+ type CheckSystemToolsOptions,
38
+ checkCiConfiguration,
39
+ checkSystemTools,
40
+ } from "./system-tools";
41
+ import { SUPPORTED_OPENCODE_SDK_VERSION } from "./transport-registry";
42
+ import {
43
+ OpenCodeSdkUnavailableError,
44
+ openCodeSdkUnavailableMessage,
45
+ } from "./transports/opencode-admission";
46
+
47
+ export type DoctorSeverity = "healthy" | "degraded" | "blocking";
48
+
49
+ export interface DoctorCheckItem {
50
+ name: string;
51
+ severity: DoctorSeverity;
52
+ message: string;
53
+ hint?: string;
54
+ }
55
+
56
+ export interface DoctorReport {
57
+ overall: DoctorSeverity;
58
+ checks: DoctorCheckItem[];
59
+ exitCode: 0 | 1;
60
+ }
61
+
62
+ export interface RunDoctorOptions {
63
+ // Whether git tracks <repoDir>/<rel>: picks `git mv` over `mv` in the
64
+ // migration hint. Injectable so tests need no repository.
65
+ isTracked?: IsTracked;
66
+ platform?: string;
67
+ cwd?: string;
68
+ repoRoot?: string;
69
+ home?: string;
70
+ checkToolsOptions?: CheckSystemToolsOptions;
71
+ exists?: (p: string) => boolean;
72
+ readFile?: (p: string) => string | undefined;
73
+ // Exact-binding facts from the binding that would execute the route.
74
+ // When present, these win over produceCapabilityReport (stale caller
75
+ // readiness booleans must not determine doctor verdict).
76
+ probeExactBindings?: () => Promise<readonly ExactBindingCapabilityReport[]>;
77
+ // The engine's own packaged assets. Injectable for the same reason
78
+ // preflight.ts's resolveAgentsDirSetting takes them: the real
79
+ // detectAssetMode() reads import.meta.dir, which under `bun test` always
80
+ // answers "dev", so the COMPILED bundle — the one that shipped broken — is
81
+ // unreachable from an offline test without this seam.
82
+ assets?: EngineAssets;
83
+ // §11/D1-09: doctor consumes the SAME ProviderCapabilityReport execution
84
+ // gates on. Injectable so offline tests stay deterministic; the CLI's
85
+ // doctor command passes the real producer. Opt-in rather than default-on
86
+ // because the report always carries non-blocking gaps (no pricing table,
87
+ // no bounded event sink), which would flip every existing "healthy"
88
+ // fixture to "degraded" for reasons unrelated to what those tests probe.
89
+ // Legacy injectable ProviderCapabilityReport. Ignored when
90
+ // probeExactBindings is provided.
91
+ produceCapabilityReport?: () => Promise<ProviderCapabilityReport>;
92
+ }
93
+
94
+ // Remediation hints for the report's known non-blocking codes; blocking
95
+ // issues carry their own actionable message from the producer. Exported
96
+ // for a reachability test (pushProviderIssues only attaches a hint when
97
+ // `!issue.blocking`, so a hint keyed to an always-blocking code can never
98
+ // render).
99
+ export const PROVIDER_HINTS: Record<string, string> = {
100
+ credential_projection_unavailable:
101
+ "Credential projection requires macOS with /usr/bin/security; on other platforms the child runs with enumerated-passthrough env.",
102
+ codegraph_policy_unenforced:
103
+ "Await the dedicated codegraph sensitive-file policy (D1-05 residual); isolation currently relies on --strict-mcp-config with a codegraph-only mcp.json.",
104
+ bounded_events_sink_missing:
105
+ "Usage arrives as a final snapshot until the bounded event sink is wired (D1-08 residual).",
106
+ pricing_table_missing:
107
+ "Nothing is priced at this level: the report is produced before any route resolves. An attempt's cash cost is whatever its transport reports, and a metered route whose transport reports none is refused at admission.",
108
+ };
109
+
110
+ // fix/opencode-sdk-absent-degraded: OpenCodeSdkUnavailableError means
111
+ // "@opencode-ai/sdk is not resolvable here" (a compiled binary run without
112
+ // its node_modules), not "the environment is broken". Only OpenCode-backed
113
+ // steps cannot execute, so this stays `degraded`; every other
114
+ // capability-probe failure keeps today's `blocking` treatment unchanged.
115
+ //
116
+ // The hint must not claim the rest of the plan was verified. resolveFrozenBindings
117
+ // (production-runtime.ts) awaits the OpenCode identity observation inside the
118
+ // same loop that resolves every other route, with no per-step isolation, so
119
+ // the rejection escapes before gateBindingsCapabilities ever runs: the probe
120
+ // produces ZERO capability reports, Claude-backed steps included. Degraded
121
+ // here means "unverified", not "verified fine".
122
+ const OPENCODE_SDK_UNAVAILABLE_HINT =
123
+ "Run crysk upgrade --reconcile to install @opencode-ai/sdk where this binary can resolve it, or route the affected steps through Claude instead. The probe stops at the first OpenCode step, so this run verified no capabilities for ANY route in the plan — Claude-backed steps are unverified here, not confirmed healthy.";
124
+
125
+ function pushCapabilityProbeFailure(
126
+ checks: DoctorCheckItem[],
127
+ error: unknown,
128
+ ): void {
129
+ if (error instanceof OpenCodeSdkUnavailableError) {
130
+ checks.push({
131
+ name: "provider",
132
+ severity: "degraded",
133
+ message: `capability report production degraded: ${error.message}`,
134
+ hint: OPENCODE_SDK_UNAVAILABLE_HINT,
135
+ });
136
+ return;
137
+ }
138
+ checks.push({
139
+ name: "provider",
140
+ severity: "blocking",
141
+ message: `capability report production failed: ${(error as Error).message}`,
142
+ });
143
+ }
144
+
145
+ function pushProviderIssues(
146
+ checks: DoctorCheckItem[],
147
+ issues: readonly { code: string; message: string; blocking: boolean }[],
148
+ ): void {
149
+ for (const issue of issues) {
150
+ checks.push({
151
+ name: `provider:${issue.code}`,
152
+ severity: issue.blocking ? "blocking" : "degraded",
153
+ message: issue.message,
154
+ ...(issue.blocking ? {} : { hint: PROVIDER_HINTS[issue.code] }),
155
+ });
156
+ }
157
+ }
158
+
159
+ export function openCodeRoutingSdkCheck(input: {
160
+ routing: RoutingConfig | undefined;
161
+ sdkVersion: string | undefined;
162
+ }): DoctorCheckItem | undefined {
163
+ if (!routingNeedsOpenCodeSdk(input.routing)) return undefined;
164
+ const version =
165
+ typeof input.sdkVersion === "string" ? input.sdkVersion.trim() : "";
166
+ if (version === SUPPORTED_OPENCODE_SDK_VERSION) return undefined;
167
+ if (version === "") {
168
+ return {
169
+ name: "opencode-sdk",
170
+ severity: "blocking",
171
+ message: openCodeSdkUnavailableMessage(),
172
+ };
173
+ }
174
+ return {
175
+ name: "opencode-sdk",
176
+ severity: "blocking",
177
+ message:
178
+ `Unsupported OpenCode SDK version "${version}". ` +
179
+ `Expected exact version "${SUPPORTED_OPENCODE_SDK_VERSION}". ` +
180
+ "Run crysk upgrade --reconcile.",
181
+ };
182
+ }
183
+
184
+ export function evaluateDoctorReport(checks: DoctorCheckItem[]): DoctorReport {
185
+ let overall: DoctorSeverity = "healthy";
186
+ if (checks.some((c) => c.severity === "blocking")) {
187
+ overall = "blocking";
188
+ } else if (checks.some((c) => c.severity === "degraded")) {
189
+ overall = "degraded";
190
+ }
191
+
192
+ return {
193
+ overall,
194
+ checks,
195
+ exitCode: overall === "blocking" ? 1 : 0,
196
+ };
197
+ }
198
+
199
+ export async function runDoctor(
200
+ options: RunDoctorOptions = {},
201
+ ): Promise<DoctorReport> {
202
+ const home = options.home ?? os.homedir();
203
+ const exists =
204
+ options.exists ?? options.checkToolsOptions?.exists ?? existsSync;
205
+ const readFile =
206
+ options.readFile ??
207
+ ((p: string) => {
208
+ try {
209
+ return readFileSync(p, "utf-8");
210
+ } catch {
211
+ return undefined;
212
+ }
213
+ });
214
+
215
+ const repoDir = options.repoRoot ?? options.cwd;
216
+ // The directory the engine actually reads (.crysk/, or a legacy .prhero/), so
217
+ // every message names a file that exists.
218
+ const repoDirName = repoDir
219
+ ? path.basename(resolveRepoDir(repoDir, exists))
220
+ : REPO_DIR_NAME;
221
+
222
+ const checks: DoctorCheckItem[] = [];
223
+
224
+ // ONE resolution, shared by the bundled-prompt check below and the skills
225
+ // sync check further down: two calls would let an injected bundle disagree
226
+ // with the real one inside a single report.
227
+ const assets = options.assets ?? resolveEngineAssets();
228
+
229
+ // 1. System tools
230
+ const tools = await checkSystemTools({
231
+ cwd: repoDir ?? process.cwd(),
232
+ home,
233
+ exists,
234
+ ...options.checkToolsOptions,
235
+ });
236
+
237
+ // Git (required)
238
+ if (!tools.git.installed) {
239
+ checks.push({
240
+ name: "git",
241
+ severity: "blocking",
242
+ message: "git is not installed",
243
+ hint: tools.git.hint,
244
+ });
245
+ } else {
246
+ checks.push({
247
+ name: "git",
248
+ severity: "healthy",
249
+ message: `git is installed (${tools.git.version ?? "version unknown"})`,
250
+ });
251
+ }
252
+
253
+ // Claude (required + auth)
254
+ if (!tools.claude.installed) {
255
+ checks.push({
256
+ name: "claude",
257
+ severity: "blocking",
258
+ message: "Claude Code CLI is not installed",
259
+ hint: tools.claude.hint,
260
+ });
261
+ } else if (!tools.claude.authOk) {
262
+ checks.push({
263
+ name: "claude",
264
+ severity: "blocking",
265
+ message: `Claude Code CLI is installed (${tools.claude.version ?? "unknown"}) but not authenticated`,
266
+ hint: tools.claude.hint,
267
+ });
268
+ } else {
269
+ checks.push({
270
+ name: "claude",
271
+ severity: "healthy",
272
+ message: `Claude Code CLI is installed and authenticated (${tools.claude.version ?? "unknown"})`,
273
+ });
274
+ }
275
+
276
+ // GitHub CLI (optional, PR mode)
277
+ if (!tools.gh.installed) {
278
+ checks.push({
279
+ name: "gh",
280
+ severity: "degraded",
281
+ message: "GitHub CLI is not installed (needed for PR review mode)",
282
+ hint: tools.gh.hint,
283
+ });
284
+ } else if (!tools.gh.authOk) {
285
+ checks.push({
286
+ name: "gh",
287
+ severity: "degraded",
288
+ message: `GitHub CLI is installed (${tools.gh.version ?? "unknown"}) but not authenticated with GitHub`,
289
+ hint: tools.gh.hint,
290
+ });
291
+ } else {
292
+ checks.push({
293
+ name: "gh",
294
+ severity: "healthy",
295
+ message: `GitHub CLI is installed and authenticated (${tools.gh.version ?? "unknown"})`,
296
+ });
297
+ }
298
+
299
+ // CodeGraph (optional, code intelligence)
300
+ if (!tools.codegraph.installed) {
301
+ checks.push({
302
+ name: "codegraph",
303
+ severity: "degraded",
304
+ message: "CodeGraph binary is not installed (optional code intelligence)",
305
+ hint: tools.codegraph.hint,
306
+ });
307
+ } else if (!tools.codegraph.repoIndexed) {
308
+ checks.push({
309
+ name: "codegraph",
310
+ severity: "degraded",
311
+ message: `CodeGraph is installed (${tools.codegraph.version ?? "unknown"}) but repository is not indexed (.codegraph missing)`,
312
+ hint: tools.codegraph.hint,
313
+ });
314
+ } else {
315
+ checks.push({
316
+ name: "codegraph",
317
+ severity: "healthy",
318
+ message: `CodeGraph is installed (${tools.codegraph.version ?? "unknown"}) and repository is indexed`,
319
+ });
320
+ }
321
+
322
+ // 2. Config layer / agents_dir check
323
+ const repoConfigPath = repoDir
324
+ ? path.join(resolveRepoDir(repoDir, exists), "config.json")
325
+ : undefined;
326
+ const globalConfigPath = path.join(
327
+ resolveHomeDir(home, exists),
328
+ "config.json",
329
+ );
330
+
331
+ let parsedAgentsDir: string | undefined;
332
+ if (repoConfigPath && exists(repoConfigPath)) {
333
+ try {
334
+ const raw = readFile(repoConfigPath);
335
+ if (raw) {
336
+ const json = JSON.parse(raw);
337
+ if (json.agents_dir && typeof json.agents_dir === "string") {
338
+ parsedAgentsDir = path.resolve(
339
+ path.dirname(repoConfigPath),
340
+ json.agents_dir,
341
+ );
342
+ }
343
+ }
344
+ } catch {
345
+ // Ignored here, parsed elsewhere
346
+ }
347
+ } else if (exists(globalConfigPath)) {
348
+ try {
349
+ const raw = readFile(globalConfigPath);
350
+ if (raw) {
351
+ const json = JSON.parse(raw);
352
+ if (json.agents_dir && typeof json.agents_dir === "string") {
353
+ parsedAgentsDir = path.resolve(
354
+ path.dirname(globalConfigPath),
355
+ json.agents_dir,
356
+ );
357
+ }
358
+ }
359
+ } catch {
360
+ // Ignored
361
+ }
362
+ }
363
+
364
+ if (parsedAgentsDir !== undefined) {
365
+ if (!exists(parsedAgentsDir)) {
366
+ checks.push({
367
+ name: "agents_dir",
368
+ severity: "blocking",
369
+ message: `Configured agents_dir not found: ${parsedAgentsDir}`,
370
+ hint: `Delete "agents_dir" from ${repoDirName}/config.json to fall through to the bundled default prompt set.`,
371
+ });
372
+ } else {
373
+ checks.push({
374
+ name: "agents_dir",
375
+ severity: "healthy",
376
+ message: `Custom agents_dir configured and verified: ${parsedAgentsDir}`,
377
+ });
378
+ }
379
+ } else {
380
+ // This branch used to push "Using bundled prompt set (default)" and
381
+ // healthy, unconditionally, having verified nothing at all — which is how
382
+ // `doctor` printed a green agents_dir on the machine where the next
383
+ // `review` died with `agents dir does not exist: /$bunfs/root`. A doctor
384
+ // that reports health it never checked is worse than no doctor, because it
385
+ // is the thing an operator trusts before spending money.
386
+ //
387
+ // Resolved through preflight's resolveAgentsDirSetting/agentFilePath, the
388
+ // same pair the review itself reads prompts with: a second way to answer
389
+ // "where is the bundled set" is a second way to be wrong, and only one of
390
+ // the two would be the one the review uses.
391
+ const bundled = resolveAgentsDirSetting({
392
+ cwd: repoDir ?? process.cwd(),
393
+ assets,
394
+ });
395
+ // READ, rather than exists() followed by a read. Reading is the operation
396
+ // the review actually performs, so it is the one whose failure matters; an
397
+ // existence probe in front of it only adds a second verdict on the same
398
+ // file. An empty body counts as unreadable: a zero-byte prompt gives a
399
+ // hunter an empty system prompt, which spends money and finds nothing.
400
+ const unreadable: string[] = [];
401
+ const bundledSpec = localReviewSpec();
402
+ for (const agent of bundledSpec.agents) {
403
+ try {
404
+ const body = readFile(agentFilePath(bundled, agent.file));
405
+ if (body === undefined || body.trim().length === 0) {
406
+ unreadable.push(agent.file);
407
+ }
408
+ } catch {
409
+ // agentFilePath throws when the spec names a prompt this build never
410
+ // embedded — manifest/spec drift, and the report has to survive it as
411
+ // a finding rather than take the whole doctor down with it.
412
+ unreadable.push(agent.file);
413
+ }
414
+ }
415
+
416
+ if (unreadable.length > 0) {
417
+ checks.push({
418
+ name: "agents_dir",
419
+ severity: "blocking",
420
+ // LOGICAL filenames only. The embedded path is
421
+ // "/$bunfs/root/<name>-<hash>.md", which exists on no machine and
422
+ // sends the reader hunting a filesystem bug instead of a build one.
423
+ message: `Bundled prompt set is incomplete: cannot read ${unreadable.join(", ")}`,
424
+ hint:
425
+ "This build cannot review anything. Reinstall the engine with " +
426
+ "'crysk upgrade', or set \"agents_dir\" in .crysk/config.json to " +
427
+ "a checked-out prompt set.",
428
+ });
429
+ } else {
430
+ checks.push({
431
+ name: "agents_dir",
432
+ severity: "healthy",
433
+ message:
434
+ `Using bundled prompt set (default): ${bundled.dir} — ` +
435
+ `${bundledSpec.agents.length} prompts read`,
436
+ });
437
+ }
438
+ }
439
+
440
+ // 3. Gotchas check (only when repo root is supplied or discovered)
441
+ if (repoDir) {
442
+ const gotchasPath = resolveGotchasPath(undefined, repoDir, exists);
443
+ const gotchasContent = exists(gotchasPath)
444
+ ? readFile(gotchasPath)
445
+ : undefined;
446
+ // Same predicate the review gates use, and that is the point: a doctor
447
+ // that answers this question its own way eventually green-lights a file
448
+ // the very next command refuses, and the user then hunts for the problem
449
+ // somewhere it is not.
450
+ const unusable = gotchasUnusableReason(gotchasContent ?? "");
451
+ if (unusable === "placeholder") {
452
+ checks.push({
453
+ name: "gotchas",
454
+ severity: "blocking",
455
+ message: `Repository gotchas file (${repoDirName}/gotchas.md) is still the untouched scaffold`,
456
+ hint:
457
+ `Replace the placeholder lines with real repository invariants, and delete the \`${GOTCHAS_PLACEHOLDER_MARKER}\` ` +
458
+ "marker line at the top if it is still there — Crysk refuses to review the scaffold.",
459
+ });
460
+ } else if (unusable !== undefined) {
461
+ checks.push({
462
+ name: "gotchas",
463
+ severity: "blocking",
464
+ message: `Repository gotchas file (${repoDirName}/gotchas.md) is empty or missing`,
465
+ hint: `Create and populate ${repoDirName}/gotchas.md with repository-specific invariants and failure traps.`,
466
+ });
467
+ } else {
468
+ checks.push({
469
+ name: "gotchas",
470
+ severity: "healthy",
471
+ message: `Repository gotchas present (${repoDirName}/gotchas.md)`,
472
+ });
473
+ }
474
+ }
475
+
476
+ // 4. Setup state check (<home dir>/setup.json)
477
+ const setupJsonPath = path.join(resolveHomeDir(home, exists), "setup.json");
478
+ const homeDirName = path.basename(path.dirname(setupJsonPath));
479
+ if (!exists(setupJsonPath)) {
480
+ checks.push({
481
+ name: "setup",
482
+ severity: "degraded",
483
+ message: `Global setup state not initialized (~/${homeDirName}/setup.json absent)`,
484
+ hint: "Run 'crysk init' or complete onboarding to initialize.",
485
+ });
486
+ } else {
487
+ checks.push({
488
+ name: "setup",
489
+ severity: "healthy",
490
+ message: `Global setup state verified (~/${homeDirName}/setup.json)`,
491
+ });
492
+ }
493
+
494
+ // 5. Agent Environments (S3)
495
+ const envs = await detectAgentEnvironments({
496
+ home,
497
+ exists,
498
+ which: options.checkToolsOptions?.which,
499
+ });
500
+
501
+ // The rename's migration hints need to know what is installed on this
502
+ // machine (binary on PATH, launchd agents, MCP registrations), so they run
503
+ // after the environment scan.
504
+ checks.push(
505
+ ...migrationChecks({
506
+ home,
507
+ repoDir,
508
+ exists,
509
+ readFile,
510
+ envs,
511
+ platform: options.platform ?? process.platform,
512
+ isTracked: options.isTracked ?? gitIsTracked,
513
+ }),
514
+ );
515
+
516
+ const self = selfInvocation();
517
+ const mcpReg = {
518
+ command: self.command,
519
+ args: [...self.args, "mcp"],
520
+ };
521
+
522
+ if (envs.length === 0) {
523
+ checks.push({
524
+ name: "agent_environments",
525
+ severity: "degraded",
526
+ message:
527
+ "No AI agent coding environments detected (Claude Code, Cursor, Windsurf, Codex, Antigravity, OpenCode)",
528
+ hint: "Install or configure an AI agent environment to use crysk triage skills and MCP server.",
529
+ });
530
+ } else {
531
+ for (const env of envs) {
532
+ if (env.skillsDir) {
533
+ const syncStatus = inspectSkillsSync(env, assets, { exists, readFile });
534
+ if (syncStatus.synced) {
535
+ checks.push({
536
+ name: `skills:${env.id}`,
537
+ severity: "healthy",
538
+ message: `crysk skills (triage, ci-setup) synced for ${env.displayName} (${env.skillsDir})`,
539
+ });
540
+ } else if (syncStatus.drift) {
541
+ checks.push({
542
+ name: `skills:${env.id}`,
543
+ severity: "degraded",
544
+ message: `Local modifications detected in skills for ${env.displayName}`,
545
+ hint: "Run 'crysk setup' or sync skills with force.",
546
+ });
547
+ } else {
548
+ checks.push({
549
+ name: `skills:${env.id}`,
550
+ severity: "degraded",
551
+ message: `crysk skills not synced to ${env.displayName}`,
552
+ hint: "Run 'crysk setup' or 'crysk init' to sync skills.",
553
+ });
554
+ }
555
+ // Sync removes the old-name copies it can prove untouched; one left
556
+ // behind holds a file the user edited (or one sync never recorded).
557
+ if (syncStatus.legacy.length > 0) {
558
+ const dirs = syncStatus.legacy
559
+ .map((name) => path.join(env.skillsDir as string, name))
560
+ .join(", ");
561
+ checks.push({
562
+ name: `skills-legacy:${env.id}`,
563
+ severity: "degraded",
564
+ message: `Skills installed under their old names remain for ${env.displayName}: ${dirs}`,
565
+ hint: "Run 'crysk setup' to remove the unedited ones, then delete the rest by hand once you have copied any edits you want to keep.",
566
+ });
567
+ }
568
+ }
569
+
570
+ if (env.mcpConfigFile && isNpxCacheInvocation(self)) {
571
+ // Under npx the expected command is the temporary cache's path, which no
572
+ // registration holds, so an equality check would always report missing.
573
+ checks.push({
574
+ name: `mcp:${env.id}`,
575
+ severity: "degraded",
576
+ message: `MCP registration for ${env.displayName} is not checked from npx's temporary cache`,
577
+ hint: NPX_REGISTRATION_REFUSED,
578
+ });
579
+ } else if (env.mcpConfigFile) {
580
+ const mcp = inspectMcpRegistration(env, mcpReg, { exists, readFile });
581
+ if (mcp === "current") {
582
+ checks.push({
583
+ name: `mcp:${env.id}`,
584
+ severity: "healthy",
585
+ message: `crysk MCP server registered for ${env.displayName} (${env.mcpConfigFile})`,
586
+ });
587
+ } else if (mcp === "legacy") {
588
+ // It still works; only the key predates the rename.
589
+ checks.push({
590
+ name: `mcp:${env.id}`,
591
+ severity: "degraded",
592
+ message: `crysk MCP server for ${env.displayName} is registered under its pre-rename key`,
593
+ hint: "Run 'crysk setup' to migrate the registration.",
594
+ });
595
+ } else {
596
+ checks.push({
597
+ name: `mcp:${env.id}`,
598
+ severity: "degraded",
599
+ message: `crysk MCP server not registered for ${env.displayName}`,
600
+ hint: "Run 'crysk setup' to register the MCP server.",
601
+ });
602
+ }
603
+ }
604
+ }
605
+ }
606
+
607
+ // 6. CI configuration (Pillar 3). Reuses checkToolsOptions.env rather than
608
+ // adding a separate top-level env field — one injectable env source for
609
+ // both "is claude authenticated" and "is this a GitHub Actions run",
610
+ // matching how doctor.test.ts already threads env through today.
611
+ const env = options.checkToolsOptions?.env ?? process.env;
612
+ // GITHUB_ACTIONS, deliberately NOT isCiEnvironment(). That helper is
613
+ // Boolean(GITHUB_ACTIONS || CI || --ci) and stays that way — its other
614
+ // callers want exactly that generic meaning. This check does not: spec.md
615
+ // §4.1 scopes it to "When run inside GitHub Actions", and everything it
616
+ // looks for downstream (GITHUB_TOKEN, secrets passed through a workflow's
617
+ // `with:` block) exists only there. `CI=true` alone is the near-universal
618
+ // convention — GitLab, CircleCI, Jenkins, Travis, Buildkite, countless
619
+ // container builds — so treating it as GitHub Actions meant asking a
620
+ // GitLab runner for GitHub secrets, finding none, and reporting `blocking`.
621
+ // That is not cosmetic: report.overall goes blocking, `pr-hero upgrade
622
+ // --reconcile` pushes an error and exits 1, and a bare `pr-hero doctor`
623
+ // exits 1, on a machine where nothing whatsoever is wrong.
624
+ //
625
+ // A non-GitHub CI therefore gets the SAME treatment as a local machine, in
626
+ // both halves of this check: the answerable question ("do you have a
627
+ // workflow file?") and `degraded` for "not configured, nothing broken".
628
+ // Reserving `blocking` for a real Actions run keeps it meaning what it says
629
+ // — a review that genuinely cannot authenticate.
630
+ const isGithubActions = Boolean(env.GITHUB_ACTIONS);
631
+ const ciStatus = checkCiConfiguration({
632
+ cwd: repoDir ?? process.cwd(),
633
+ isCi: isGithubActions,
634
+ env,
635
+ exists,
636
+ });
637
+ checks.push({
638
+ name: "ci",
639
+ severity: ciStatus.configured
640
+ ? "healthy"
641
+ : isGithubActions
642
+ ? "blocking"
643
+ : "degraded",
644
+ message: ciStatus.message,
645
+ hint: ciStatus.hint,
646
+ });
647
+
648
+ // 7. Provider capability report — exact-binding facts win; the legacy
649
+ // ProviderCapabilityReport producer is only consulted when no exact probe
650
+ // is supplied.
651
+ if (options.probeExactBindings !== undefined) {
652
+ try {
653
+ const reports = await options.probeExactBindings();
654
+ pushProviderIssues(
655
+ checks,
656
+ reports.flatMap((report) => exactBindingCapabilityIssues(report)),
657
+ );
658
+ } catch (error) {
659
+ pushCapabilityProbeFailure(checks, error);
660
+ }
661
+ } else if (options.produceCapabilityReport !== undefined) {
662
+ try {
663
+ const capability = await options.produceCapabilityReport();
664
+ pushProviderIssues(checks, capability.issues);
665
+ } catch (error) {
666
+ pushCapabilityProbeFailure(checks, error);
667
+ }
668
+ }
669
+
670
+ return evaluateDoctorReport(checks);
671
+ }
672
+
673
+ export function renderDoctorReport(
674
+ report: DoctorReport,
675
+ options: { styles?: boolean; width?: number } = {},
676
+ ): string[] {
677
+ const styles = options.styles ?? false;
678
+ const lines: string[] = [];
679
+
680
+ const green = (s: string) => (styles ? `\x1b[32m${s}\x1b[0m` : s);
681
+ const yellow = (s: string) => (styles ? `\x1b[33m${s}\x1b[0m` : s);
682
+ const red = (s: string) => (styles ? `\x1b[31m${s}\x1b[0m` : s);
683
+ const bold = (s: string) => (styles ? `\x1b[1m${s}\x1b[0m` : s);
684
+ const dim = (s: string) => (styles ? `\x1b[2m${s}\x1b[0m` : s);
685
+
686
+ lines.push(bold("crysk doctor"));
687
+ lines.push("");
688
+
689
+ for (const check of report.checks) {
690
+ let symbol: string;
691
+ if (check.severity === "healthy") {
692
+ symbol = green("[✓]");
693
+ } else if (check.severity === "degraded") {
694
+ symbol = yellow("[!]");
695
+ } else {
696
+ symbol = red("[✗]");
697
+ }
698
+
699
+ lines.push(` ${symbol} ${bold(check.name)}: ${check.message}`);
700
+ if (check.hint) {
701
+ lines.push(` ${dim(`Hint: ${check.hint}`)}`);
702
+ }
703
+ }
704
+
705
+ lines.push("");
706
+ if (report.overall === "healthy") {
707
+ lines.push(green("All checks passed. Environment is ready for reviews."));
708
+ } else if (report.overall === "degraded") {
709
+ lines.push(
710
+ yellow(
711
+ "Environment is operational, but some optional tools or configurations are degraded.",
712
+ ),
713
+ );
714
+ } else {
715
+ lines.push(
716
+ red(
717
+ "Environment has blocking issues. Reviews cannot run until resolved.",
718
+ ),
719
+ );
720
+ }
721
+
722
+ return lines;
723
+ }