graphitect 0.2.0__py3-none-any.whl

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 (336) hide show
  1. graphify/__init__.py +30 -0
  2. graphify/__main__.py +757 -0
  3. graphify/_minhash.py +107 -0
  4. graphify/affected.py +318 -0
  5. graphify/always_on/agents-md.md +12 -0
  6. graphify/always_on/antigravity-rules.md +14 -0
  7. graphify/always_on/claude-md.md +9 -0
  8. graphify/always_on/gemini-md.md +9 -0
  9. graphify/always_on/kiro-steering.md +5 -0
  10. graphify/always_on/vscode-instructions.md +17 -0
  11. graphify/analyze.py +769 -0
  12. graphify/benchmark.py +152 -0
  13. graphify/build.py +2300 -0
  14. graphify/cache.py +1746 -0
  15. graphify/callflow_html.py +2051 -0
  16. graphify/cargo_introspect.py +109 -0
  17. graphify/cli.py +4745 -0
  18. graphify/cluster.py +409 -0
  19. graphify/command-kilo.md +15 -0
  20. graphify/cross_repo_calls.py +216 -0
  21. graphify/cross_repo_types.py +75 -0
  22. graphify/csharp_dispatch.py +154 -0
  23. graphify/dedup.py +1213 -0
  24. graphify/detect.py +2566 -0
  25. graphify/diagnostics.py +406 -0
  26. graphify/export.py +1349 -0
  27. graphify/exporters/__init__.py +1 -0
  28. graphify/exporters/base.py +14 -0
  29. graphify/exporters/graphdb.py +173 -0
  30. graphify/exporters/html.py +637 -0
  31. graphify/extract.py +7856 -0
  32. graphify/extractors/MIGRATION.md +107 -0
  33. graphify/extractors/__init__.py +66 -0
  34. graphify/extractors/apex.py +215 -0
  35. graphify/extractors/base.py +85 -0
  36. graphify/extractors/bash.py +579 -0
  37. graphify/extractors/blade.py +53 -0
  38. graphify/extractors/commonlisp.py +540 -0
  39. graphify/extractors/csharp.py +448 -0
  40. graphify/extractors/dart.py +564 -0
  41. graphify/extractors/dm.py +494 -0
  42. graphify/extractors/elixir.py +241 -0
  43. graphify/extractors/engine.py +6509 -0
  44. graphify/extractors/fortran.py +311 -0
  45. graphify/extractors/go.py +527 -0
  46. graphify/extractors/json_config.py +240 -0
  47. graphify/extractors/julia.py +289 -0
  48. graphify/extractors/markdown.py +408 -0
  49. graphify/extractors/models.py +131 -0
  50. graphify/extractors/objc.py +566 -0
  51. graphify/extractors/ocaml.py +289 -0
  52. graphify/extractors/pascal.py +688 -0
  53. graphify/extractors/pascal_forms.py +196 -0
  54. graphify/extractors/powershell.py +522 -0
  55. graphify/extractors/razor.py +192 -0
  56. graphify/extractors/resolution.py +3584 -0
  57. graphify/extractors/robot.py +296 -0
  58. graphify/extractors/rust.py +470 -0
  59. graphify/extractors/sln.py +92 -0
  60. graphify/extractors/sql.py +720 -0
  61. graphify/extractors/terraform.py +181 -0
  62. graphify/extractors/verilog.py +329 -0
  63. graphify/extractors/zig.py +181 -0
  64. graphify/file_slice.py +246 -0
  65. graphify/global_graph.py +194 -0
  66. graphify/google_workspace.py +237 -0
  67. graphify/hooks.py +933 -0
  68. graphify/ids.py +93 -0
  69. graphify/ingest.py +358 -0
  70. graphify/install.py +2366 -0
  71. graphify/llm.py +3544 -0
  72. graphify/manifest.py +4 -0
  73. graphify/manifest_ingest.py +311 -0
  74. graphify/mcp_ingest.py +386 -0
  75. graphify/multigraph_compat.py +212 -0
  76. graphify/pascal_resolution.py +129 -0
  77. graphify/paths.py +436 -0
  78. graphify/pg_introspect.py +165 -0
  79. graphify/prs.py +770 -0
  80. graphify/querylog.py +80 -0
  81. graphify/reflect.py +882 -0
  82. graphify/report.py +346 -0
  83. graphify/resolver_registry.py +85 -0
  84. graphify/ruby_resolution.py +242 -0
  85. graphify/scip_ingest.py +363 -0
  86. graphify/security.py +460 -0
  87. graphify/semantic_cleanup.py +336 -0
  88. graphify/serve.py +2608 -0
  89. graphify/skill-agents.md +710 -0
  90. graphify/skill-aider.md +1283 -0
  91. graphify/skill-amp.md +710 -0
  92. graphify/skill-claw.md +713 -0
  93. graphify/skill-codex.md +710 -0
  94. graphify/skill-copilot.md +713 -0
  95. graphify/skill-devin.md +1410 -0
  96. graphify/skill-droid.md +710 -0
  97. graphify/skill-kilo.md +722 -0
  98. graphify/skill-kiro.md +713 -0
  99. graphify/skill-opencode.md +705 -0
  100. graphify/skill-pi.md +713 -0
  101. graphify/skill-trae.md +711 -0
  102. graphify/skill-vscode.md +709 -0
  103. graphify/skill-windows.md +755 -0
  104. graphify/skill.md +713 -0
  105. graphify/skills/agents/references/add-watch.md +56 -0
  106. graphify/skills/agents/references/exports.md +87 -0
  107. graphify/skills/agents/references/extraction-spec.md +70 -0
  108. graphify/skills/agents/references/github-and-merge.md +46 -0
  109. graphify/skills/agents/references/hooks.md +33 -0
  110. graphify/skills/agents/references/query.md +311 -0
  111. graphify/skills/agents/references/transcribe.md +52 -0
  112. graphify/skills/agents/references/update.md +210 -0
  113. graphify/skills/amp/references/add-watch.md +56 -0
  114. graphify/skills/amp/references/exports.md +87 -0
  115. graphify/skills/amp/references/extraction-spec.md +70 -0
  116. graphify/skills/amp/references/github-and-merge.md +46 -0
  117. graphify/skills/amp/references/hooks.md +33 -0
  118. graphify/skills/amp/references/query.md +311 -0
  119. graphify/skills/amp/references/transcribe.md +52 -0
  120. graphify/skills/amp/references/update.md +210 -0
  121. graphify/skills/claude/references/add-watch.md +56 -0
  122. graphify/skills/claude/references/exports.md +87 -0
  123. graphify/skills/claude/references/extraction-spec.md +70 -0
  124. graphify/skills/claude/references/github-and-merge.md +46 -0
  125. graphify/skills/claude/references/hooks.md +33 -0
  126. graphify/skills/claude/references/query.md +311 -0
  127. graphify/skills/claude/references/transcribe.md +52 -0
  128. graphify/skills/claude/references/update.md +210 -0
  129. graphify/skills/claw/references/add-watch.md +56 -0
  130. graphify/skills/claw/references/exports.md +87 -0
  131. graphify/skills/claw/references/extraction-spec.md +31 -0
  132. graphify/skills/claw/references/github-and-merge.md +46 -0
  133. graphify/skills/claw/references/hooks.md +33 -0
  134. graphify/skills/claw/references/query.md +311 -0
  135. graphify/skills/claw/references/transcribe.md +52 -0
  136. graphify/skills/claw/references/update.md +210 -0
  137. graphify/skills/codex/references/add-watch.md +56 -0
  138. graphify/skills/codex/references/exports.md +87 -0
  139. graphify/skills/codex/references/extraction-spec.md +31 -0
  140. graphify/skills/codex/references/github-and-merge.md +46 -0
  141. graphify/skills/codex/references/hooks.md +33 -0
  142. graphify/skills/codex/references/query.md +311 -0
  143. graphify/skills/codex/references/transcribe.md +52 -0
  144. graphify/skills/codex/references/update.md +210 -0
  145. graphify/skills/copilot/references/add-watch.md +56 -0
  146. graphify/skills/copilot/references/exports.md +87 -0
  147. graphify/skills/copilot/references/extraction-spec.md +70 -0
  148. graphify/skills/copilot/references/github-and-merge.md +46 -0
  149. graphify/skills/copilot/references/hooks.md +33 -0
  150. graphify/skills/copilot/references/query.md +311 -0
  151. graphify/skills/copilot/references/transcribe.md +52 -0
  152. graphify/skills/copilot/references/update.md +210 -0
  153. graphify/skills/droid/references/add-watch.md +56 -0
  154. graphify/skills/droid/references/exports.md +87 -0
  155. graphify/skills/droid/references/extraction-spec.md +70 -0
  156. graphify/skills/droid/references/github-and-merge.md +46 -0
  157. graphify/skills/droid/references/hooks.md +33 -0
  158. graphify/skills/droid/references/query.md +311 -0
  159. graphify/skills/droid/references/transcribe.md +52 -0
  160. graphify/skills/droid/references/update.md +210 -0
  161. graphify/skills/kilo/references/add-watch.md +56 -0
  162. graphify/skills/kilo/references/exports.md +87 -0
  163. graphify/skills/kilo/references/extraction-spec.md +70 -0
  164. graphify/skills/kilo/references/github-and-merge.md +46 -0
  165. graphify/skills/kilo/references/hooks.md +33 -0
  166. graphify/skills/kilo/references/query.md +311 -0
  167. graphify/skills/kilo/references/transcribe.md +52 -0
  168. graphify/skills/kilo/references/update.md +210 -0
  169. graphify/skills/kiro/references/add-watch.md +56 -0
  170. graphify/skills/kiro/references/exports.md +87 -0
  171. graphify/skills/kiro/references/extraction-spec.md +31 -0
  172. graphify/skills/kiro/references/github-and-merge.md +46 -0
  173. graphify/skills/kiro/references/hooks.md +33 -0
  174. graphify/skills/kiro/references/query.md +311 -0
  175. graphify/skills/kiro/references/transcribe.md +52 -0
  176. graphify/skills/kiro/references/update.md +210 -0
  177. graphify/skills/opencode/references/add-watch.md +56 -0
  178. graphify/skills/opencode/references/exports.md +87 -0
  179. graphify/skills/opencode/references/extraction-spec.md +70 -0
  180. graphify/skills/opencode/references/github-and-merge.md +46 -0
  181. graphify/skills/opencode/references/hooks.md +33 -0
  182. graphify/skills/opencode/references/query.md +311 -0
  183. graphify/skills/opencode/references/transcribe.md +52 -0
  184. graphify/skills/opencode/references/update.md +210 -0
  185. graphify/skills/pi/references/add-watch.md +56 -0
  186. graphify/skills/pi/references/exports.md +87 -0
  187. graphify/skills/pi/references/extraction-spec.md +31 -0
  188. graphify/skills/pi/references/github-and-merge.md +46 -0
  189. graphify/skills/pi/references/hooks.md +33 -0
  190. graphify/skills/pi/references/query.md +311 -0
  191. graphify/skills/pi/references/transcribe.md +52 -0
  192. graphify/skills/pi/references/update.md +210 -0
  193. graphify/skills/trae/references/add-watch.md +56 -0
  194. graphify/skills/trae/references/exports.md +87 -0
  195. graphify/skills/trae/references/extraction-spec.md +70 -0
  196. graphify/skills/trae/references/github-and-merge.md +46 -0
  197. graphify/skills/trae/references/hooks.md +35 -0
  198. graphify/skills/trae/references/query.md +311 -0
  199. graphify/skills/trae/references/transcribe.md +52 -0
  200. graphify/skills/trae/references/update.md +210 -0
  201. graphify/skills/vscode/references/add-watch.md +56 -0
  202. graphify/skills/vscode/references/exports.md +87 -0
  203. graphify/skills/vscode/references/extraction-spec.md +70 -0
  204. graphify/skills/vscode/references/github-and-merge.md +46 -0
  205. graphify/skills/vscode/references/hooks.md +33 -0
  206. graphify/skills/vscode/references/query.md +311 -0
  207. graphify/skills/vscode/references/transcribe.md +52 -0
  208. graphify/skills/vscode/references/update.md +210 -0
  209. graphify/skills/windows/references/add-watch.md +56 -0
  210. graphify/skills/windows/references/exports.md +87 -0
  211. graphify/skills/windows/references/extraction-spec.md +70 -0
  212. graphify/skills/windows/references/github-and-merge.md +46 -0
  213. graphify/skills/windows/references/hooks.md +33 -0
  214. graphify/skills/windows/references/query.md +311 -0
  215. graphify/skills/windows/references/transcribe.md +52 -0
  216. graphify/skills/windows/references/update.md +210 -0
  217. graphify/symbol_resolution.py +556 -0
  218. graphify/transcribe.py +186 -0
  219. graphify/tree_html.py +603 -0
  220. graphify/validate.py +95 -0
  221. graphify/watch.py +2280 -0
  222. graphify/wiki.py +405 -0
  223. graphitect/__init__.py +28 -0
  224. graphitect/__main__.py +4 -0
  225. graphitect/_vendor/__init__.py +2 -0
  226. graphitect/_vendor/archify/LICENSE +22 -0
  227. graphitect/_vendor/archify/SKILL.md +137 -0
  228. graphitect/_vendor/archify/THIRD_PARTY_NOTICES.md +69 -0
  229. graphitect/_vendor/archify/assets/JetBrainsMono-OFL.txt +93 -0
  230. graphitect/_vendor/archify/assets/template.html +14935 -0
  231. graphitect/_vendor/archify/bin/archify.mjs +2091 -0
  232. graphitect/_vendor/archify/bin/open-artifact.mjs +86 -0
  233. graphitect/_vendor/archify/bin/preview.mjs +653 -0
  234. graphitect/_vendor/archify/bin/visual-check.mjs +829 -0
  235. graphitect/_vendor/archify/brand-marks/README.md +31 -0
  236. graphitect/_vendor/archify/brand-marks/catalog.json +131 -0
  237. graphitect/_vendor/archify/delta/architecture-delta.mjs +1221 -0
  238. graphitect/_vendor/archify/examples/agent-run.lifecycle.json +60 -0
  239. graphitect/_vendor/archify/examples/agent-tool-call.workflow.json +94 -0
  240. graphitect/_vendor/archify/examples/async-job-roundtrip.sequence.json +61 -0
  241. graphitect/_vendor/archify/examples/brand-aware-delivery.architecture.json +47 -0
  242. graphitect/_vendor/archify/examples/cache-miss-request.sequence.json +82 -0
  243. graphitect/_vendor/archify/examples/checkout-platform.base.architecture.json +31 -0
  244. graphitect/_vendor/archify/examples/checkout-platform.head.architecture.json +31 -0
  245. graphitect/_vendor/archify/examples/dataflow-product-analytics.html +15045 -0
  246. graphitect/_vendor/archify/examples/deployment-release.lifecycle.json +49 -0
  247. graphitect/_vendor/archify/examples/event-stream.dataflow.json +57 -0
  248. graphitect/_vendor/archify/examples/incident-response.workflow.json +64 -0
  249. graphitect/_vendor/archify/examples/lifecycle-agent-run.html +14980 -0
  250. graphitect/_vendor/archify/examples/product-analytics.dataflow.json +76 -0
  251. graphitect/_vendor/archify/examples/production-deployment.architecture.json +71 -0
  252. graphitect/_vendor/archify/examples/release-delivery.workflow.json +62 -0
  253. graphitect/_vendor/archify/examples/sequence-cache-miss-request.html +15060 -0
  254. graphitect/_vendor/archify/examples/web-app-rendered.html +15009 -0
  255. graphitect/_vendor/archify/examples/web-app.architecture.json +46 -0
  256. graphitect/_vendor/archify/examples/workflow-agent-tool-call-rendered.html +15051 -0
  257. graphitect/_vendor/archify/migrations/workflow-v2.mjs +279 -0
  258. graphitect/_vendor/archify/package-lock.json +149 -0
  259. graphitect/_vendor/archify/package.json +39 -0
  260. graphitect/_vendor/archify/recipes/scenarios.mjs +391 -0
  261. graphitect/_vendor/archify/references/authoring-contract.md +243 -0
  262. graphitect/_vendor/archify/references/brand-marks.md +65 -0
  263. graphitect/_vendor/archify/references/delivery-contract.md +120 -0
  264. graphitect/_vendor/archify/references/viewer-runtime.md +45 -0
  265. graphitect/_vendor/archify/renderers/architecture/grid.mjs +62 -0
  266. graphitect/_vendor/archify/renderers/architecture/render-architecture.mjs +1078 -0
  267. graphitect/_vendor/archify/renderers/dataflow/README.md +104 -0
  268. graphitect/_vendor/archify/renderers/dataflow/render-dataflow.mjs +483 -0
  269. graphitect/_vendor/archify/renderers/lifecycle/README.md +115 -0
  270. graphitect/_vendor/archify/renderers/lifecycle/render-lifecycle.mjs +561 -0
  271. graphitect/_vendor/archify/renderers/sequence/README.md +114 -0
  272. graphitect/_vendor/archify/renderers/sequence/render-sequence.mjs +464 -0
  273. graphitect/_vendor/archify/renderers/shared/brand-marks.mjs +563 -0
  274. graphitect/_vendor/archify/renderers/shared/cli.mjs +218 -0
  275. graphitect/_vendor/archify/renderers/shared/desktop-readability.mjs +26 -0
  276. graphitect/_vendor/archify/renderers/shared/diagnostics.mjs +127 -0
  277. graphitect/_vendor/archify/renderers/shared/engineering-profiles.mjs +157 -0
  278. graphitect/_vendor/archify/renderers/shared/generated-brand-marks.mjs +2003 -0
  279. graphitect/_vendor/archify/renderers/shared/generated-validators.mjs +13 -0
  280. graphitect/_vendor/archify/renderers/shared/geometry.mjs +1423 -0
  281. graphitect/_vendor/archify/renderers/shared/i18n.mjs +595 -0
  282. graphitect/_vendor/archify/renderers/shared/layout-report.mjs +40 -0
  283. graphitect/_vendor/archify/renderers/shared/legend.mjs +217 -0
  284. graphitect/_vendor/archify/renderers/shared/output-path.mjs +340 -0
  285. graphitect/_vendor/archify/renderers/shared/repository-evidence.mjs +238 -0
  286. graphitect/_vendor/archify/renderers/shared/repository-location.mjs +58 -0
  287. graphitect/_vendor/archify/renderers/shared/text-fit.mjs +49 -0
  288. graphitect/_vendor/archify/renderers/shared/utils.mjs +232 -0
  289. graphitect/_vendor/archify/renderers/shared/validator.mjs +86 -0
  290. graphitect/_vendor/archify/renderers/workflow/README.md +223 -0
  291. graphitect/_vendor/archify/renderers/workflow/render-workflow.mjs +35 -0
  292. graphitect/_vendor/archify/renderers/workflow/workflow-compiler.mjs +4400 -0
  293. graphitect/_vendor/archify/renderers/workflow/workflow-migration-geometry.mjs +144 -0
  294. graphitect/_vendor/archify/schemas/README.md +211 -0
  295. graphitect/_vendor/archify/schemas/architecture.schema.json +178 -0
  296. graphitect/_vendor/archify/schemas/common.schema.json +115 -0
  297. graphitect/_vendor/archify/schemas/dataflow.schema.json +243 -0
  298. graphitect/_vendor/archify/schemas/lifecycle.schema.json +266 -0
  299. graphitect/_vendor/archify/schemas/sequence.schema.json +223 -0
  300. graphitect/_vendor/archify/schemas/workflow.schema.json +428 -0
  301. graphitect/_vendor/archify/scripts/check-render-output.mjs +836 -0
  302. graphitect/_vendor/archify/scripts/check-update.mjs +1667 -0
  303. graphitect/_vendor/archify/scripts/generate-brand-marks.mjs +141 -0
  304. graphitect/_vendor/archify/scripts/generate-validators.mjs +66 -0
  305. graphitect/_vendor/archify/scripts/render-examples.mjs +26 -0
  306. graphitect/_vendor/archify/scripts/update-contract.mjs +182 -0
  307. graphitect/_vendor/archify/skill-release.json +10 -0
  308. graphitect/cli.py +981 -0
  309. graphitect/deliver/__init__.py +5 -0
  310. graphitect/deliver/archify_adapter.py +1877 -0
  311. graphitect/deliver/archify_ir.py +160 -0
  312. graphitect/deliver/archify_repair.py +135 -0
  313. graphitect/deliver/doc_compiler.py +916 -0
  314. graphitect/ground/__init__.py +5 -0
  315. graphitect/ground/describe_source.py +27 -0
  316. graphitect/ground/fullread_source.py +56 -0
  317. graphitect/ground/graphify_source.py +107 -0
  318. graphitect/models.py +118 -0
  319. graphitect/skill/SKILL.md +80 -0
  320. graphitect/skill/agents/openai.yaml +4 -0
  321. graphitect/synthesize/__init__.py +5 -0
  322. graphitect/synthesize/engine.py +281 -0
  323. graphitect/synthesize/llm_backend.py +331 -0
  324. graphitect/synthesize/questions.py +139 -0
  325. graphitect/synthesize/rubric.py +104 -0
  326. graphitect-0.2.0.dist-info/METADATA +284 -0
  327. graphitect-0.2.0.dist-info/RECORD +336 -0
  328. graphitect-0.2.0.dist-info/WHEEL +5 -0
  329. graphitect-0.2.0.dist-info/entry_points.txt +2 -0
  330. graphitect-0.2.0.dist-info/licenses/LICENSE +21 -0
  331. graphitect-0.2.0.dist-info/licenses/LICENSE-ARCHIFY-MIT +22 -0
  332. graphitect-0.2.0.dist-info/licenses/LICENSE-GRAPHIFY-APACHE-2.0 +202 -0
  333. graphitect-0.2.0.dist-info/licenses/LICENSE-GRAPHIFY-MIT +21 -0
  334. graphitect-0.2.0.dist-info/licenses/NOTICE-ARCHIFY-THIRD-PARTY.md +69 -0
  335. graphitect-0.2.0.dist-info/licenses/NOTICE-GRAPHIFY +8 -0
  336. graphitect-0.2.0.dist-info/top_level.txt +2 -0
graphitect/cli.py ADDED
@@ -0,0 +1,981 @@
1
+ """graphitect CLI - argparse-based, no framework dependency, matching
2
+ graphify's own convention (plain sys.argv dispatch, see graphify/cli.py).
3
+
4
+ `build` is the product command. The older Ground -> Synthesize -> Deliver
5
+ subcommands remain available for debugging and advanced workflows.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import json
12
+ import os
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+ from importlib import resources as importlib_resources
17
+ from pathlib import Path
18
+
19
+ from .deliver import archify_adapter, doc_compiler
20
+ from .ground import describe_source, graphify_source
21
+ from .models import AgentNarrative, Confidence, GroundedUnderstanding
22
+ from .synthesize import engine
23
+ from .synthesize.llm_backend import resolve_backend
24
+ from .synthesize.questions import apply_answer, read_answers, resolve_questions
25
+ from .synthesize.rubric import mine_rationale
26
+
27
+ _USAGE = """\
28
+ graphitect - grounded, sourced design docs for a system you already built
29
+
30
+ Usage:
31
+ graphitect build <path> [--title TITLE] [--no-diagram]
32
+ [--ollama-local | --ollama-key KEY] [--anthropic-key KEY] [--gemini-key KEY]
33
+ [-o report.html]
34
+ graphitect ground <path> [--mode graphify|describe] [--description TEXT] [-o out.json]
35
+ graphitect synthesize <ground.json|understanding.json> [--repo PATH] [--diagram-kind KIND]
36
+ [--ollama-local | --ollama-key KEY] [--anthropic-key KEY] [--gemini-key KEY]
37
+ [--answers answers.json] [--non-interactive] [-o out.json]
38
+ graphitect deliver <understanding.json> --title TITLE [-o out]
39
+ graphitect agent prepare <path> [-o .graphitect-agent]
40
+ graphitect agent compile <workspace> [--repo PATH] [--title TITLE] [--answers answers.json]
41
+ [--no-diagram] [-o report.html]
42
+ graphitect skill export [--host codex|claude-code] [--output SKILL_DIRECTORY] [--force]
43
+
44
+ graphitect --help
45
+ """
46
+
47
+
48
+ def _skill_bundle() -> dict[str, str]:
49
+ """Read the portable Agent Skills bundle from installed package data."""
50
+ root = importlib_resources.files("graphitect").joinpath("skill")
51
+ return {
52
+ "SKILL.md": root.joinpath("SKILL.md").read_text(encoding="utf-8"),
53
+ "agents/openai.yaml": root.joinpath("agents", "openai.yaml").read_text(encoding="utf-8"),
54
+ }
55
+
56
+
57
+ def _cmd_skill_export(args: argparse.Namespace) -> int:
58
+ """Export the same portable skill to a host's discovery location."""
59
+ if args.output:
60
+ destination = Path(args.output)
61
+ elif args.host == "codex":
62
+ destination = Path.cwd() / ".agents" / "skills" / "graphitect"
63
+ elif args.host == "claude-code":
64
+ destination = Path.cwd() / ".claude" / "skills" / "graphitect"
65
+ else:
66
+ print("error: --output is required when no host is selected", file=sys.stderr)
67
+ return 2
68
+
69
+ if destination.exists() and not args.force:
70
+ print(
71
+ f"error: skill destination already exists: {destination} (use --force to replace it)",
72
+ file=sys.stderr,
73
+ )
74
+ return 2
75
+
76
+ destination.mkdir(parents=True, exist_ok=True)
77
+ for relative_path, content in _skill_bundle().items():
78
+ target = destination / relative_path
79
+ target.parent.mkdir(parents=True, exist_ok=True)
80
+ target.write_text(content, encoding="utf-8")
81
+ print(f"Exported Graphitect skill to {destination}")
82
+ return 0
83
+
84
+
85
+ def _backend_args(args: argparse.Namespace):
86
+ return resolve_backend(
87
+ anthropic_key=getattr(args, "anthropic_key", None) or os.environ.get("ANTHROPIC_API_KEY"),
88
+ gemini_key=getattr(args, "gemini_key", None)
89
+ or os.environ.get("GEMINI_API_KEY")
90
+ or os.environ.get("GOOGLE_API_KEY"),
91
+ ollama_key=getattr(args, "ollama_key", None) or os.environ.get("OLLAMA_API_KEY"),
92
+ ollama_base_url=getattr(args, "ollama_base_url", None),
93
+ ollama_model=getattr(args, "ollama_model", None),
94
+ ollama_local=getattr(args, "ollama_local", False),
95
+ )
96
+
97
+
98
+ def _render_archify_views(
99
+ understanding: GroundedUnderstanding,
100
+ title: str,
101
+ overview_path: Path,
102
+ story_path: Path,
103
+ sequence_path: Path,
104
+ full_path: Path,
105
+ *,
106
+ archify_bin: str | None,
107
+ auto_install: bool,
108
+ repair_backend,
109
+ max_repair_iterations: int,
110
+ ) -> tuple[
111
+ str,
112
+ str | None,
113
+ str | None,
114
+ str | None,
115
+ Exception | None,
116
+ Exception | None,
117
+ Exception | None,
118
+ ]:
119
+ """Render the reliable overview plus optional Sequence, Workflow, and Full modes.
120
+
121
+ Section 1 remains available if an enhanced mode cannot be validated. The
122
+ caller receives the exceptions so it can disclose missing modes instead
123
+ of silently claiming a Story or Full rollup exists.
124
+ """
125
+ common = {
126
+ "archify_bin": archify_bin,
127
+ "auto_install": auto_install,
128
+ "repair_backend": repair_backend,
129
+ "max_repair_iterations": max_repair_iterations,
130
+ }
131
+ archify_adapter.render(understanding, title, overview_path, view="overview", **common)
132
+ overview_html = overview_path.read_text(encoding="utf-8")
133
+ story_html = None
134
+ story_error = None
135
+ try:
136
+ archify_adapter.render_workflow_story(
137
+ understanding,
138
+ title,
139
+ story_path,
140
+ archify_bin=archify_bin,
141
+ auto_install=auto_install,
142
+ )
143
+ story_html = story_path.read_text(encoding="utf-8")
144
+ except (FileNotFoundError, subprocess.CalledProcessError, ValueError) as exc:
145
+ story_error = exc
146
+ sequence_html = None
147
+ sequence_error = None
148
+ try:
149
+ archify_adapter.render_sequence_trace(
150
+ understanding,
151
+ title,
152
+ sequence_path,
153
+ archify_bin=archify_bin,
154
+ auto_install=auto_install,
155
+ )
156
+ sequence_html = sequence_path.read_text(encoding="utf-8")
157
+ except (FileNotFoundError, subprocess.CalledProcessError, ValueError) as exc:
158
+ sequence_error = exc
159
+ try:
160
+ archify_adapter.render(understanding, title, full_path, view="full", **common)
161
+ return (
162
+ overview_html,
163
+ story_html,
164
+ sequence_html,
165
+ full_path.read_text(encoding="utf-8"),
166
+ story_error,
167
+ sequence_error,
168
+ None,
169
+ )
170
+ except (FileNotFoundError, subprocess.CalledProcessError) as exc:
171
+ return overview_html, story_html, sequence_html, None, story_error, sequence_error, exc
172
+
173
+
174
+ def _cmd_build(args: argparse.Namespace) -> int:
175
+ """One repository in, one self-contained HTML report out."""
176
+ repo_path = Path(args.path).resolve()
177
+ if not repo_path.is_dir():
178
+ print(f"error: repository path is not a directory: {repo_path}", file=sys.stderr)
179
+ return 2
180
+
181
+ output_path = Path(args.output) if args.output else Path.cwd() / f"{repo_path.name}-graphitect.html"
182
+ if output_path.suffix.lower() != ".html":
183
+ output_path = output_path.with_suffix(".html")
184
+ output_path = output_path.resolve()
185
+ output_path.parent.mkdir(parents=True, exist_ok=True)
186
+ title = args.title or repo_path.name
187
+
188
+ build_temp = tempfile.TemporaryDirectory(prefix="graphitect-build-")
189
+ try:
190
+ temp_root = Path(build_temp.name)
191
+ try:
192
+ grounding = {
193
+ "mode": "graphify",
194
+ **graphify_source.ground(repo_path, output_dir=temp_root / "graphify-out"),
195
+ }
196
+ except (FileNotFoundError, subprocess.CalledProcessError) as exc:
197
+ print(f"error: bundled Graphify analysis failed: {exc}", file=sys.stderr)
198
+ return 1
199
+
200
+ try:
201
+ backend = _backend_args(args)
202
+ except RuntimeError:
203
+ backend = None
204
+ except ImportError as exc:
205
+ print(f"error: bundled LLM provider support is unavailable: {exc}", file=sys.stderr)
206
+ return 1
207
+
208
+ if backend is None:
209
+ understanding = engine.synthesize_diagram_only(grounding, diagram_kind="architecture")
210
+ explanation_available = False
211
+ else:
212
+ understanding = engine.synthesize(
213
+ grounding, repo_path, backend, diagram_kind="architecture"
214
+ )
215
+ explanation_available = True
216
+
217
+ diagram_html = None
218
+ story_diagram_html = None
219
+ sequence_diagram_html = None
220
+ full_diagram_html = None
221
+ story_chapter_count = None
222
+ story_hover_details = None
223
+ sequence_message_count = None
224
+ overview_connection_count = None
225
+ full_connection_count = None
226
+ if not args.no_diagram:
227
+ overview_path = temp_root / "architecture-overview.html"
228
+ story_path = temp_root / "architecture-story.html"
229
+ sequence_path = temp_root / "architecture-sequence.html"
230
+ full_path = temp_root / "architecture-full.html"
231
+ try:
232
+ (
233
+ diagram_html,
234
+ story_diagram_html,
235
+ sequence_diagram_html,
236
+ full_diagram_html,
237
+ story_error,
238
+ sequence_error,
239
+ full_error,
240
+ ) = _render_archify_views(
241
+ understanding,
242
+ title,
243
+ overview_path,
244
+ story_path,
245
+ sequence_path,
246
+ full_path,
247
+ archify_bin=args.archify_bin,
248
+ auto_install=False,
249
+ repair_backend=None if args.no_repair else backend,
250
+ max_repair_iterations=args.max_repair_iterations,
251
+ )
252
+ except (FileNotFoundError, subprocess.CalledProcessError) as exc:
253
+ print(f"error: mandatory diagram generation failed: {exc}", file=sys.stderr)
254
+ return 1
255
+ if story_error is not None:
256
+ print(
257
+ f"warning: workflow story could not be rendered; kept the overview ({story_error})",
258
+ file=sys.stderr,
259
+ )
260
+ elif story_diagram_html is not None:
261
+ story_chapter_count = len(
262
+ archify_adapter.to_workflow_spec(understanding, title)["meta"]["views"]
263
+ )
264
+ story_hover_details = archify_adapter.workflow_hover_details(understanding)
265
+ if sequence_error is not None:
266
+ print(
267
+ f"note: sequence trace was not shown; it needs two consecutive direct Graphify calls/invocations ({sequence_error})",
268
+ file=sys.stderr,
269
+ )
270
+ elif sequence_diagram_html is not None:
271
+ sequence_message_count = len(
272
+ archify_adapter.to_sequence_spec(understanding, title)["messages"]
273
+ )
274
+ if full_error is not None:
275
+ print(
276
+ f"warning: full architecture rollup could not be rendered; kept the available modes ({full_error})",
277
+ file=sys.stderr,
278
+ )
279
+ else:
280
+ overview_connection_count = len(
281
+ archify_adapter.to_architecture_ir(understanding, title, view="overview").connections
282
+ )
283
+ full_connection_count = len(
284
+ archify_adapter.to_architecture_ir(understanding, title, view="full").connections
285
+ )
286
+
287
+ node_id_remap = archify_adapter.node_id_remap(understanding) if diagram_html else None
288
+ report = doc_compiler.to_html(
289
+ understanding,
290
+ title,
291
+ diagram_svg=diagram_html,
292
+ story_diagram_svg=story_diagram_html,
293
+ story_hover_details=story_hover_details,
294
+ sequence_diagram_svg=sequence_diagram_html,
295
+ full_diagram_svg=full_diagram_html,
296
+ story_chapter_count=story_chapter_count,
297
+ sequence_message_count=sequence_message_count,
298
+ overview_connection_count=overview_connection_count,
299
+ full_connection_count=full_connection_count,
300
+ node_id_remap=node_id_remap,
301
+ explanation_available=explanation_available,
302
+ diagram_opted_out=args.no_diagram,
303
+ )
304
+ staged_path = output_path.with_name(f".{output_path.name}.tmp")
305
+ staged_path.write_text(report, encoding="utf-8")
306
+ staged_path.replace(output_path)
307
+ print(f"Wrote self-contained Graphitect report to {output_path}")
308
+ return 0
309
+ finally:
310
+ build_temp.cleanup()
311
+
312
+
313
+ def _cmd_ground(args: argparse.Namespace) -> int:
314
+ repo_path = Path(args.path)
315
+ if args.mode == "describe":
316
+ if not args.description:
317
+ print("error: --description is required for --mode describe", file=sys.stderr)
318
+ return 2
319
+ claims = describe_source.ground(args.description)
320
+ payload = {"mode": "describe", "claims": [c.model_dump() for c in claims]}
321
+ else:
322
+ graphed = graphify_source.ground(repo_path)
323
+ payload = {"mode": "graphify", **graphed}
324
+
325
+ out = Path(args.output) if args.output else repo_path / "graphitect-ground.json"
326
+ out.parent.mkdir(parents=True, exist_ok=True)
327
+ out.write_text(json.dumps(payload, indent=2), encoding="utf-8")
328
+ print(f"Wrote grounding data to {out}")
329
+ return 0
330
+
331
+
332
+ def _cmd_agent_prepare(args: argparse.Namespace) -> int:
333
+ """Prepare deterministic evidence for a Codex/Claude-style host model.
334
+
335
+ This command deliberately does not resolve an LLM backend. The installed
336
+ agent reads the source packet and writes ``narrative.json`` with its own
337
+ model; ``agent compile`` later validates and renders that work.
338
+ """
339
+ repo_path = Path(args.path).resolve()
340
+ if not repo_path.is_dir():
341
+ print(f"error: repository path is not a directory: {repo_path}", file=sys.stderr)
342
+ return 2
343
+
344
+ workspace = Path(args.output).resolve()
345
+ workspace.mkdir(parents=True, exist_ok=True)
346
+ try:
347
+ grounding = {
348
+ "mode": "graphify",
349
+ **graphify_source.ground(repo_path, output_dir=workspace / "graphify-out"),
350
+ }
351
+ except (FileNotFoundError, subprocess.CalledProcessError) as exc:
352
+ print(f"error: bundled Graphify analysis failed: {exc}", file=sys.stderr)
353
+ return 1
354
+
355
+ files = {
356
+ "grounding": "grounding.json",
357
+ "context": "agent-context.md",
358
+ "narrative": "narrative.json",
359
+ "narrative_schema": "narrative.schema.json",
360
+ }
361
+ (workspace / files["grounding"]).write_text(json.dumps(grounding, indent=2), encoding="utf-8")
362
+ (workspace / files["context"]).write_text(engine.build_context(grounding, repo_path), encoding="utf-8")
363
+ (workspace / files["narrative"]).write_text(
364
+ AgentNarrative().model_dump_json(indent=2), encoding="utf-8"
365
+ )
366
+ (workspace / files["narrative_schema"]).write_text(
367
+ json.dumps(AgentNarrative.model_json_schema(), indent=2), encoding="utf-8"
368
+ )
369
+ (workspace / "manifest.json").write_text(
370
+ json.dumps({"schema_version": 1, "repo_path": str(repo_path), "files": files}, indent=2),
371
+ encoding="utf-8",
372
+ )
373
+ print(f"Prepared host-model workspace at {workspace}")
374
+ return 0
375
+
376
+
377
+ def _load_agent_workspace(workspace: Path, repo_override: str | None) -> tuple[Path, dict, AgentNarrative]:
378
+ """Load a workspace written by ``agent prepare`` without trusting paths inside it."""
379
+ try:
380
+ manifest = json.loads((workspace / "manifest.json").read_text(encoding="utf-8"))
381
+ if manifest.get("schema_version") != 1:
382
+ raise ValueError("unsupported manifest schema")
383
+ files = manifest["files"]
384
+ if files != {
385
+ "grounding": "grounding.json",
386
+ "context": "agent-context.md",
387
+ "narrative": "narrative.json",
388
+ "narrative_schema": "narrative.schema.json",
389
+ }:
390
+ raise ValueError("workspace manifest has unexpected artifact paths")
391
+ grounding = json.loads((workspace / files["grounding"]).read_text(encoding="utf-8"))
392
+ narrative = AgentNarrative.model_validate_json(
393
+ (workspace / files["narrative"]).read_text(encoding="utf-8")
394
+ )
395
+ repo_path = Path(repo_override or manifest["repo_path"]).resolve()
396
+ except (KeyError, OSError, TypeError, ValueError) as exc:
397
+ raise ValueError(f"invalid agent workspace: {exc}") from exc
398
+
399
+ if not repo_path.is_dir():
400
+ raise ValueError(f"repository path is not a directory: {repo_path}")
401
+ if grounding.get("mode") != "graphify":
402
+ raise ValueError("agent workspace must contain Graphify grounding")
403
+ return repo_path, grounding, narrative
404
+
405
+
406
+ def _downgrade_unsupported_agent_claims(understanding: GroundedUnderstanding) -> GroundedUnderstanding:
407
+ """The host has no author-answer channel until ``--answers`` is applied.
408
+
409
+ A host narrative therefore cannot claim a user said something, and every
410
+ other confirmed assertion needs at least one citation for the verifier to
411
+ check. Answers added by the shared question flow below remain valid user
412
+ evidence because they are appended after this gate.
413
+ """
414
+ def downgrade(claim):
415
+ if claim.confidence != Confidence.CONFIRMED:
416
+ return claim
417
+ if claim.cites and not any(evidence.source == "user" for evidence in claim.cites):
418
+ return claim
419
+ return claim.model_copy(
420
+ update={
421
+ "confidence": Confidence.INFERRED,
422
+ "text": f"{claim.text} (citation could not be independently verified)",
423
+ }
424
+ )
425
+
426
+ for section in understanding.doc:
427
+ section.claims = [downgrade(claim) for claim in section.claims]
428
+ for tradeoff in section.tradeoffs:
429
+ tradeoff.decision = downgrade(tradeoff.decision)
430
+ tradeoff.pros = [downgrade(claim) for claim in tradeoff.pros]
431
+ tradeoff.cons = [downgrade(claim) for claim in tradeoff.cons]
432
+ return understanding
433
+
434
+
435
+ def _cmd_agent_compile(args: argparse.Namespace) -> int:
436
+ """Verify a host-authored narrative and render one self-contained report."""
437
+ workspace = Path(args.workspace).resolve()
438
+ try:
439
+ repo_path, grounding, narrative = _load_agent_workspace(workspace, args.repo)
440
+ except ValueError as exc:
441
+ print(f"error: {exc}", file=sys.stderr)
442
+ return 2
443
+
444
+ real_node_ids = {node["id"] for node in grounding.get("nodes", []) if "id" in node}
445
+ for section in narrative.doc:
446
+ section.related_node_ids = [node_id for node_id in section.related_node_ids if node_id in real_node_ids]
447
+
448
+ understanding = _downgrade_unsupported_agent_claims(
449
+ GroundedUnderstanding(
450
+ diagram_kind="architecture",
451
+ nodes=grounding.get("nodes", []),
452
+ edges=grounding.get("edges", []),
453
+ doc=narrative.doc,
454
+ community_labels=grounding.get("community_labels", {}),
455
+ )
456
+ )
457
+ understanding = engine.verify_understanding(understanding, repo_path)
458
+ try:
459
+ understanding = _resolve_pending_questions(
460
+ understanding,
461
+ workspace,
462
+ argparse.Namespace(answers=args.answers, non_interactive=True),
463
+ )
464
+ except (OSError, TypeError, ValueError) as exc:
465
+ print(f"error: invalid --answers file: {exc}", file=sys.stderr)
466
+ return 2
467
+
468
+ (workspace / "understanding.json").write_text(
469
+ understanding.model_dump_json(indent=2), encoding="utf-8"
470
+ )
471
+ if not understanding.pending_questions:
472
+ (workspace / "graphitect-questions.json").write_text("[]\n", encoding="utf-8")
473
+
474
+ output_path = Path(args.output) if args.output else workspace / f"{repo_path.name}-graphitect.html"
475
+ if output_path.suffix.lower() != ".html":
476
+ output_path = output_path.with_suffix(".html")
477
+ output_path = output_path.resolve()
478
+ output_path.parent.mkdir(parents=True, exist_ok=True)
479
+ title = args.title or repo_path.name
480
+
481
+ diagram_html = None
482
+ story_diagram_html = None
483
+ sequence_diagram_html = None
484
+ full_diagram_html = None
485
+ story_chapter_count = None
486
+ story_hover_details = None
487
+ sequence_message_count = None
488
+ overview_connection_count = None
489
+ full_connection_count = None
490
+ render_temp = tempfile.TemporaryDirectory(prefix="graphitect-agent-")
491
+ try:
492
+ if not args.no_diagram:
493
+ temp_root = Path(render_temp.name)
494
+ try:
495
+ (
496
+ diagram_html,
497
+ story_diagram_html,
498
+ sequence_diagram_html,
499
+ full_diagram_html,
500
+ story_error,
501
+ sequence_error,
502
+ full_error,
503
+ ) = _render_archify_views(
504
+ understanding,
505
+ title,
506
+ temp_root / "architecture-overview.html",
507
+ temp_root / "architecture-story.html",
508
+ temp_root / "architecture-sequence.html",
509
+ temp_root / "architecture-full.html",
510
+ archify_bin=args.archify_bin,
511
+ auto_install=not args.no_auto_install,
512
+ repair_backend=None,
513
+ max_repair_iterations=0,
514
+ )
515
+ except (FileNotFoundError, subprocess.CalledProcessError) as exc:
516
+ print(f"error: mandatory diagram generation failed: {exc}", file=sys.stderr)
517
+ return 1
518
+ if story_error is not None:
519
+ print(f"warning: workflow story could not be rendered ({story_error})", file=sys.stderr)
520
+ elif story_diagram_html is not None:
521
+ story_chapter_count = len(
522
+ archify_adapter.to_workflow_spec(understanding, title)["meta"]["views"]
523
+ )
524
+ story_hover_details = archify_adapter.workflow_hover_details(understanding)
525
+ if sequence_error is not None:
526
+ print(f"note: sequence trace was not shown ({sequence_error})", file=sys.stderr)
527
+ elif sequence_diagram_html is not None:
528
+ sequence_message_count = len(
529
+ archify_adapter.to_sequence_spec(understanding, title)["messages"]
530
+ )
531
+ if full_error is None:
532
+ overview_connection_count = len(
533
+ archify_adapter.to_architecture_ir(understanding, title, view="overview").connections
534
+ )
535
+ full_connection_count = len(
536
+ archify_adapter.to_architecture_ir(understanding, title, view="full").connections
537
+ )
538
+ else:
539
+ print(f"warning: full architecture rollup could not be rendered ({full_error})", file=sys.stderr)
540
+
541
+ report = doc_compiler.to_html(
542
+ understanding,
543
+ title,
544
+ diagram_svg=diagram_html,
545
+ story_diagram_svg=story_diagram_html,
546
+ story_hover_details=story_hover_details,
547
+ sequence_diagram_svg=sequence_diagram_html,
548
+ full_diagram_svg=full_diagram_html,
549
+ story_chapter_count=story_chapter_count,
550
+ sequence_message_count=sequence_message_count,
551
+ overview_connection_count=overview_connection_count,
552
+ full_connection_count=full_connection_count,
553
+ node_id_remap=archify_adapter.node_id_remap(understanding) if diagram_html else None,
554
+ explanation_available=True,
555
+ diagram_opted_out=args.no_diagram,
556
+ )
557
+ staged_path = output_path.with_name(f".{output_path.name}.tmp")
558
+ staged_path.write_text(report, encoding="utf-8")
559
+ staged_path.replace(output_path)
560
+ finally:
561
+ render_temp.cleanup()
562
+
563
+ print(f"Wrote host-model Graphitect report to {output_path}")
564
+ return 0
565
+
566
+
567
+ def _resolve_pending_questions(
568
+ understanding: GroundedUnderstanding, pending_dir: Path, args: argparse.Namespace
569
+ ) -> GroundedUnderstanding:
570
+ """Shared by both synthesize paths below: fold in --answers if given,
571
+ otherwise resolve interactively or write graphitect-questions.json.
572
+
573
+ pending_dir is where the *output* understanding.json is going, not
574
+ wherever --repo happens to point - --repo is only ever a read-only
575
+ reference for mining rationale from someone else's source tree, and
576
+ defaulting the questions file into it silently wrote into a live
577
+ project directory that had nothing to do with this output (confirmed
578
+ live: a stray graphitect-questions.json landed inside FundersAI, only
579
+ invisible to git by luck of an unrelated broad *.json ignore rule).
580
+ """
581
+ claims_by_id: dict[str, object] = {}
582
+ for section in understanding.doc:
583
+ for i, claim in enumerate(section.claims):
584
+ claims_by_id[f"{section.heading}::{i}"] = claim
585
+
586
+ pending = understanding.pending_questions
587
+
588
+ if args.answers:
589
+ answers = read_answers(Path(args.answers))
590
+ for claim_id, answer_text in answers.items():
591
+ if claim_id in claims_by_id:
592
+ claims_by_id[claim_id] = apply_answer(claims_by_id[claim_id], answer_text)
593
+ pending = [q for q in pending if q.claim_id not in answers]
594
+ elif pending:
595
+ pending_path = pending_dir / "graphitect-questions.json"
596
+ claims_by_id, pending = resolve_questions(
597
+ pending, claims_by_id, pending_path, non_interactive=args.non_interactive
598
+ )
599
+ if pending:
600
+ print(f"{len(pending)} question(s) written to {pending_path}")
601
+
602
+ for section in understanding.doc:
603
+ for i in range(len(section.claims)):
604
+ claim_id = f"{section.heading}::{i}"
605
+ section.claims[i] = claims_by_id[claim_id]
606
+ understanding.pending_questions = pending
607
+ return understanding
608
+
609
+
610
+ def _cmd_synthesize(args: argparse.Namespace) -> int:
611
+ """Two input shapes, detected by whether `diagram_kind` is present:
612
+
613
+ - Raw grounding data (from `graphitect ground`, has a "mode" key): runs
614
+ the LLM draft step (graphitect.synthesize.engine) to produce Claims/
615
+ DesignDocSections for the first time, then verifies and queues
616
+ questions - needs a configured standalone backend. Installed agent
617
+ hosts instead use ``graphitect agent prepare`` / ``agent compile``.
618
+ - An already-synthesized GroundedUnderstanding: re-runs only the
619
+ deterministic rubric mining pass (no LLM call) on whatever's still
620
+ `inferred` - useful after new evidence appears (a README update) or
621
+ for hand-authored test inputs.
622
+ """
623
+ repo_path = Path(args.repo) if args.repo else Path.cwd()
624
+ # encoding="utf-8" is required, not cosmetic: Path.read_text() without it
625
+ # uses the platform default (cp1252 on Windows), which crashes on any
626
+ # non-ASCII byte - confirmed live against FundersAI's real 7,885-node
627
+ # graph, whose labels/community names include real-world unicode content
628
+ # a small hand-authored test file would never happen to contain.
629
+ raw = json.loads(Path(args.understanding).read_text(encoding="utf-8"))
630
+
631
+ if "diagram_kind" in raw:
632
+ understanding = GroundedUnderstanding.model_validate(raw)
633
+ for section in understanding.doc:
634
+ for i, claim in enumerate(section.claims):
635
+ if claim.confidence != Confidence.CONFIRMED:
636
+ evidence = mine_rationale(repo_path, claim.text, claim.text.split())
637
+ if evidence:
638
+ claim = claim.model_copy(
639
+ update={"confidence": Confidence.CONFIRMED, "cites": [*claim.cites, evidence]}
640
+ )
641
+ section.claims[i] = claim
642
+ understanding = engine.verify_understanding(understanding, repo_path)
643
+ else:
644
+ try:
645
+ backend = resolve_backend(
646
+ anthropic_key=args.anthropic_key or os.environ.get("ANTHROPIC_API_KEY"),
647
+ gemini_key=args.gemini_key
648
+ or os.environ.get("GEMINI_API_KEY")
649
+ or os.environ.get("GOOGLE_API_KEY"),
650
+ ollama_key=args.ollama_key or os.environ.get("OLLAMA_API_KEY"),
651
+ ollama_base_url=args.ollama_base_url,
652
+ ollama_model=args.ollama_model,
653
+ ollama_local=args.ollama_local,
654
+ )
655
+ except ImportError as exc:
656
+ # A key WAS given but the matching optional dependency isn't
657
+ # installed (e.g. --anthropic-key without
658
+ # the combined Graphitect install) - a real, user-fixable
659
+ # misconfiguration, not "no key at all". Keep failing loudly
660
+ # rather than silently falling back, since the user clearly
661
+ # intended a specific backend to be used here.
662
+ print(f"error: {exc}", file=sys.stderr)
663
+ return 2
664
+ except RuntimeError as exc:
665
+ # No key configured at all. Graphify-mode grounding still has
666
+ # real, deterministic diagram data with zero LLM involvement
667
+ # (nodes/edges/community_labels) - only the narrative `doc` ever
668
+ # needed a model, so hand back diagram-only data instead of
669
+ # failing outright and producing nothing (Naman, 12 Sep 2026:
670
+ # "the diagram is a must"). `describe` mode has no structural
671
+ # data to fall back on - a free-text description genuinely needs
672
+ # the LLM to become anything at all, so it keeps failing loudly.
673
+ if raw.get("mode") != "graphify" or not raw.get("nodes"):
674
+ print(f"error: {exc}", file=sys.stderr)
675
+ return 2
676
+ print(
677
+ "warning: no LLM backend available - producing diagram data only, no "
678
+ "design doc rationale (set ANTHROPIC_API_KEY/GEMINI_API_KEY/OLLAMA_API_KEY, "
679
+ "or use `graphitect agent prepare` from an installed Agent Skill)",
680
+ file=sys.stderr,
681
+ )
682
+ understanding = engine.synthesize_diagram_only(raw, diagram_kind=args.diagram_kind)
683
+ else:
684
+ understanding = engine.synthesize(raw, repo_path, backend, diagram_kind=args.diagram_kind)
685
+
686
+ out = Path(args.output) if args.output else Path(args.understanding)
687
+ out.parent.mkdir(parents=True, exist_ok=True)
688
+
689
+ try:
690
+ understanding = _resolve_pending_questions(understanding, out.parent, args)
691
+ except (OSError, TypeError, ValueError) as exc:
692
+ print(f"error: invalid --answers file: {exc}", file=sys.stderr)
693
+ return 2
694
+
695
+ out.write_text(understanding.model_dump_json(indent=2), encoding="utf-8")
696
+ print(f"Wrote synthesized understanding to {out}")
697
+ return 0
698
+
699
+
700
+ def _resolve_repair_backend(args: argparse.Namespace):
701
+ """Best-effort: unlike synthesize's resolve_backend() call, a missing or
702
+ unusable LLM backend here is not an error - layout repair is a bonus on
703
+ top of the deterministic heuristic (plan.md's layout-quality note), not
704
+ something `deliver` should ever require. Any key already exported for
705
+ `synthesize` (env vars) is picked up automatically for free.
706
+ """
707
+ try:
708
+ return resolve_backend(
709
+ anthropic_key=args.anthropic_key or os.environ.get("ANTHROPIC_API_KEY"),
710
+ gemini_key=args.gemini_key
711
+ or os.environ.get("GEMINI_API_KEY")
712
+ or os.environ.get("GOOGLE_API_KEY"),
713
+ ollama_key=args.ollama_key or os.environ.get("OLLAMA_API_KEY"),
714
+ ollama_base_url=args.ollama_base_url,
715
+ ollama_model=args.ollama_model,
716
+ ollama_local=args.ollama_local,
717
+ )
718
+ except (RuntimeError, ImportError):
719
+ return None
720
+
721
+
722
+ def _cmd_deliver(args: argparse.Namespace) -> int:
723
+ understanding = GroundedUnderstanding.model_validate_json(
724
+ Path(args.understanding).read_text(encoding="utf-8")
725
+ )
726
+ out_base = Path(args.output) if args.output else Path("graphitect-deliverable")
727
+ out_base.parent.mkdir(parents=True, exist_ok=True)
728
+ repair_backend = None if args.no_repair else _resolve_repair_backend(args)
729
+
730
+ md_path = out_base.with_suffix(".md")
731
+ md_path.write_text(doc_compiler.to_markdown(understanding, args.title), encoding="utf-8")
732
+ print(f"Wrote design doc to {md_path}")
733
+
734
+ diagram_svg = None
735
+ story_diagram_svg = None
736
+ sequence_diagram_svg = None
737
+ full_diagram_svg = None
738
+ story_chapter_count = None
739
+ story_hover_details = None
740
+ sequence_message_count = None
741
+ overview_connection_count = None
742
+ full_connection_count = None
743
+ if understanding.diagram_kind == "architecture" and understanding.nodes:
744
+ # NOTE: out_base.with_name(...).with_suffix(".html") looked right but
745
+ # isn't - .with_suffix() replaces the *last* suffix rather than
746
+ # appending, so with_name(name + ".archify").with_suffix(".html")
747
+ # silently collapses back to the exact same path as html_path below
748
+ # (confirmed live: both evaluated to "live-test6.html"). It "worked"
749
+ # only because this reads the file before html_path overwrites it -
750
+ # a fragile coincidence, not a real distinct intermediate file.
751
+ overview_archify_html = out_base.parent / f"{out_base.name}.overview.archify.html"
752
+ story_archify_html = out_base.parent / f"{out_base.name}.story.archify.html"
753
+ sequence_archify_html = out_base.parent / f"{out_base.name}.sequence.archify.html"
754
+ full_archify_html = out_base.parent / f"{out_base.name}.full.archify.html"
755
+ try:
756
+ (
757
+ diagram_svg,
758
+ story_diagram_svg,
759
+ sequence_diagram_svg,
760
+ full_diagram_svg,
761
+ story_error,
762
+ sequence_error,
763
+ full_error,
764
+ ) = _render_archify_views(
765
+ understanding,
766
+ args.title,
767
+ overview_archify_html,
768
+ story_archify_html,
769
+ sequence_archify_html,
770
+ full_archify_html,
771
+ archify_bin=args.archify_bin,
772
+ auto_install=not args.no_auto_install,
773
+ repair_backend=repair_backend,
774
+ max_repair_iterations=args.max_repair_iterations,
775
+ )
776
+ print(f"Rendered overview diagram via archify ({overview_archify_html})")
777
+ if story_error is None:
778
+ print(f"Rendered workflow story via archify ({story_archify_html})")
779
+ story_chapter_count = len(
780
+ archify_adapter.to_workflow_spec(understanding, args.title)["meta"]["views"]
781
+ )
782
+ story_hover_details = archify_adapter.workflow_hover_details(understanding)
783
+ else:
784
+ print(
785
+ f"warning: workflow story could not be rendered; kept the overview ({story_error})",
786
+ file=sys.stderr,
787
+ )
788
+ if sequence_error is None:
789
+ print(f"Rendered evidence-gated sequence trace via archify ({sequence_archify_html})")
790
+ sequence_message_count = len(
791
+ archify_adapter.to_sequence_spec(understanding, args.title)["messages"]
792
+ )
793
+ else:
794
+ print(
795
+ f"note: sequence trace was not shown; it needs two consecutive direct Graphify calls/invocations ({sequence_error})",
796
+ file=sys.stderr,
797
+ )
798
+ if full_error is None:
799
+ print(f"Rendered full architecture rollup via archify ({full_archify_html})")
800
+ overview_connection_count = len(
801
+ archify_adapter.to_architecture_ir(understanding, args.title, view="overview").connections
802
+ )
803
+ full_connection_count = len(
804
+ archify_adapter.to_architecture_ir(understanding, args.title, view="full").connections
805
+ )
806
+ else:
807
+ print(
808
+ f"warning: full architecture rollup could not be rendered; kept the available modes ({full_error})",
809
+ file=sys.stderr,
810
+ )
811
+ except FileNotFoundError as exc:
812
+ print(f"warning: skipped diagram render - {exc}", file=sys.stderr)
813
+ except subprocess.CalledProcessError as exc:
814
+ # archify's own layout validator rejected the generated IR (e.g.
815
+ # edges crossing unrelated components on a dense real-world
816
+ # graph) - graphitect's grid heuristic doesn't do real connection
817
+ # routing yet (see plan.md's layout-quality note), so this is a
818
+ # known, reachable case on large graphs, not a crash-worthy bug.
819
+ # Still deliver the design doc without a diagram rather than
820
+ # dying with a raw traceback and producing nothing at all. If an
821
+ # LLM repair backend was available, it already got a chance
822
+ # (archify_repair.repair_and_deliver) and still didn't converge
823
+ # within --max-repair-iterations.
824
+ attempted = "with LLM repair" if repair_backend is not None else "no repair backend available"
825
+ print(
826
+ f"warning: skipped diagram render - archify rejected the layout "
827
+ f"({attempted}) ({exc})",
828
+ file=sys.stderr,
829
+ )
830
+
831
+ # Only needed (and only meaningful) when a diagram actually got embedded -
832
+ # doc_compiler.node_id_remap default (identity) is fine when there's no
833
+ # diagram_svg to highlight into at all.
834
+ node_id_remap = archify_adapter.node_id_remap(understanding) if diagram_svg else None
835
+
836
+ html_path = out_base.with_suffix(".html")
837
+ html_path.write_text(
838
+ doc_compiler.to_html(
839
+ understanding,
840
+ args.title,
841
+ diagram_svg=diagram_svg,
842
+ story_diagram_svg=story_diagram_svg,
843
+ story_hover_details=story_hover_details,
844
+ sequence_diagram_svg=sequence_diagram_svg,
845
+ full_diagram_svg=full_diagram_svg,
846
+ story_chapter_count=story_chapter_count,
847
+ sequence_message_count=sequence_message_count,
848
+ overview_connection_count=overview_connection_count,
849
+ full_connection_count=full_connection_count,
850
+ node_id_remap=node_id_remap,
851
+ ),
852
+ encoding="utf-8",
853
+ )
854
+ print(f"Wrote design doc (HTML) to {html_path}")
855
+ return 0
856
+
857
+
858
+ def build_parser() -> argparse.ArgumentParser:
859
+ parser = argparse.ArgumentParser(prog="graphitect", usage=_USAGE, add_help=True)
860
+ sub = parser.add_subparsers(dest="command")
861
+
862
+ p_build = sub.add_parser("build", help="analyze a repository and write one HTML report")
863
+ p_build.add_argument("path")
864
+ p_build.add_argument("--title")
865
+ p_build.add_argument("--no-diagram", action="store_true")
866
+ p_build.add_argument("--archify-bin", help=argparse.SUPPRESS)
867
+ p_build.add_argument("--anthropic-key")
868
+ p_build.add_argument("--gemini-key")
869
+ p_build.add_argument("--ollama-key")
870
+ p_build.add_argument("--ollama-base-url")
871
+ p_build.add_argument("--ollama-model")
872
+ p_build.add_argument("--ollama-local", action="store_true")
873
+ p_build.add_argument("--no-repair", action="store_true")
874
+ p_build.add_argument("--max-repair-iterations", type=int, default=3)
875
+ p_build.add_argument("-o", "--output")
876
+ p_build.set_defaults(func=_cmd_build)
877
+
878
+ p_ground = sub.add_parser("ground")
879
+ p_ground.add_argument("path")
880
+ p_ground.add_argument("--mode", choices=["graphify", "describe"], default="graphify")
881
+ p_ground.add_argument("--description")
882
+ p_ground.add_argument("-o", "--output")
883
+ p_ground.set_defaults(func=_cmd_ground)
884
+
885
+ p_synth = sub.add_parser("synthesize")
886
+ p_synth.add_argument("understanding")
887
+ p_synth.add_argument("--repo")
888
+ p_synth.add_argument("--diagram-kind", default="architecture")
889
+ p_synth.add_argument("--anthropic-key")
890
+ p_synth.add_argument("--gemini-key")
891
+ p_synth.add_argument("--ollama-key", help="Ollama Cloud API key (free tier)")
892
+ p_synth.add_argument("--ollama-base-url", help="override, e.g. for a self-hosted Ollama server")
893
+ p_synth.add_argument("--ollama-model", help="default: llama3.1")
894
+ p_synth.add_argument(
895
+ "--ollama-local", action="store_true", help="use a local Ollama server, no key needed"
896
+ )
897
+ p_synth.add_argument("--answers")
898
+ p_synth.add_argument("--non-interactive", action="store_true")
899
+ p_synth.add_argument("-o", "--output")
900
+ p_synth.set_defaults(func=_cmd_synthesize)
901
+
902
+ p_deliver = sub.add_parser("deliver")
903
+ p_deliver.add_argument("understanding")
904
+ p_deliver.add_argument("--title", required=True)
905
+ p_deliver.add_argument(
906
+ "--archify-bin", help="e.g. 'node /path/to/archify/bin/archify.mjs' if not on PATH"
907
+ )
908
+ p_deliver.add_argument(
909
+ "--no-auto-install",
910
+ action="store_true",
911
+ help=argparse.SUPPRESS,
912
+ )
913
+ p_deliver.add_argument("--anthropic-key")
914
+ p_deliver.add_argument("--gemini-key")
915
+ p_deliver.add_argument("--ollama-key", help="Ollama Cloud API key (free tier)")
916
+ p_deliver.add_argument("--ollama-base-url", help="override, e.g. for a self-hosted Ollama server")
917
+ p_deliver.add_argument("--ollama-model", help="default: llama3.1")
918
+ p_deliver.add_argument(
919
+ "--ollama-local", action="store_true", help="use a local Ollama server, no key needed"
920
+ )
921
+ p_deliver.add_argument(
922
+ "--no-repair",
923
+ action="store_true",
924
+ help="don't attempt LLM-driven layout repair even if a backend key is available",
925
+ )
926
+ p_deliver.add_argument(
927
+ "--max-repair-iterations",
928
+ type=int,
929
+ default=3,
930
+ help="max archify-deliver attempts when a repair backend is available (default: 3)",
931
+ )
932
+ p_deliver.add_argument("-o", "--output")
933
+ p_deliver.set_defaults(func=_cmd_deliver)
934
+
935
+ p_agent = sub.add_parser(
936
+ "agent", help="prepare or compile a no-key handoff for an installed agent host"
937
+ )
938
+ p_agent_sub = p_agent.add_subparsers(dest="agent_command", required=True)
939
+ p_agent_prepare = p_agent_sub.add_parser(
940
+ "prepare", help="write grounded evidence for the host model; never calls an LLM"
941
+ )
942
+ p_agent_prepare.add_argument("path")
943
+ p_agent_prepare.add_argument("-o", "--output", default=".graphitect-agent")
944
+ p_agent_prepare.set_defaults(func=_cmd_agent_prepare)
945
+
946
+ p_agent_compile = p_agent_sub.add_parser(
947
+ "compile", help="verify a host-written narrative and write one self-contained report"
948
+ )
949
+ p_agent_compile.add_argument("workspace")
950
+ p_agent_compile.add_argument("--repo", help="override the repository path recorded during prepare")
951
+ p_agent_compile.add_argument("--title")
952
+ p_agent_compile.add_argument("--answers")
953
+ p_agent_compile.add_argument("--no-diagram", action="store_true")
954
+ p_agent_compile.add_argument("--archify-bin", help=argparse.SUPPRESS)
955
+ p_agent_compile.add_argument("--no-auto-install", action="store_true", help=argparse.SUPPRESS)
956
+ p_agent_compile.add_argument("-o", "--output")
957
+ p_agent_compile.set_defaults(func=_cmd_agent_compile)
958
+
959
+ p_skill = sub.add_parser("skill", help="export the portable Graphitect Agent Skill")
960
+ p_skill_sub = p_skill.add_subparsers(dest="skill_command", required=True)
961
+ p_skill_export = p_skill_sub.add_parser("export", help="write a Graphitect skill bundle")
962
+ p_skill_export.add_argument("--host", choices=["codex", "claude-code"])
963
+ p_skill_export.add_argument(
964
+ "--output",
965
+ help="destination skill directory for another Agent Skills-compatible host",
966
+ )
967
+ p_skill_export.add_argument(
968
+ "--force", action="store_true", help="replace files in an existing skill directory"
969
+ )
970
+ p_skill_export.set_defaults(func=_cmd_skill_export)
971
+
972
+ return parser
973
+
974
+
975
+ def main(argv: list[str] | None = None) -> None:
976
+ parser = build_parser()
977
+ args = parser.parse_args(argv)
978
+ if not getattr(args, "command", None):
979
+ print(_USAGE)
980
+ sys.exit(0 if argv and "--help" in argv else 1)
981
+ sys.exit(args.func(args))