@arcforge/platform 2.0.166

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 (207) hide show
  1. package/README.md +31 -0
  2. package/package.json +69 -0
  3. package/src/bin/supervisor.ts +102 -0
  4. package/src/bin/test-api.ts +30 -0
  5. package/src/bin/test-preload.ts +308 -0
  6. package/src/bin/update-helper.ts +32 -0
  7. package/src/build/bench/CLAUDE.md +106 -0
  8. package/src/build/bench/SPEC.md +209 -0
  9. package/src/build/bench/agents.ts +105 -0
  10. package/src/build/bench/axes.ts +84 -0
  11. package/src/build/bench/bench.ts +96 -0
  12. package/src/build/bench/discover.ts +147 -0
  13. package/src/build/bench/index.ts +7 -0
  14. package/src/build/bench/log.ts +47 -0
  15. package/src/build/bench/matrix.ts +23 -0
  16. package/src/build/bench/preload.ts +440 -0
  17. package/src/build/bench/prepare.ts +61 -0
  18. package/src/build/bench/projection.ts +112 -0
  19. package/src/build/bench/resolve.ts +54 -0
  20. package/src/build/bench/runner.ts +309 -0
  21. package/src/build/bench/schema/extract.ts +148 -0
  22. package/src/build/bench/schema/index.ts +2 -0
  23. package/src/build/bench/schema/schema.ts +95 -0
  24. package/src/build/bench/schema/worker.ts +30 -0
  25. package/src/build/bench/typegen.ts +119 -0
  26. package/src/build/bench/workspace/files.ts +139 -0
  27. package/src/build/bench/workspace/handle.ts +133 -0
  28. package/src/build/bench/workspace/index.ts +11 -0
  29. package/src/build/bench/workspace/workspace.ts +14 -0
  30. package/src/build/blueprint/blueprint.ts +398 -0
  31. package/src/build/blueprint/cognet/abi.ts +207 -0
  32. package/src/build/blueprint/cognet/bundle-worker.ts +93 -0
  33. package/src/build/blueprint/cognet/bundle.ts +664 -0
  34. package/src/build/blueprint/cognet/cognet.ts +249 -0
  35. package/src/build/blueprint/cognet/index.ts +10 -0
  36. package/src/build/blueprint/cognet/manifest.ts +38 -0
  37. package/src/build/blueprint/cognet/resolve.ts +113 -0
  38. package/src/build/blueprint/collisions.ts +51 -0
  39. package/src/build/blueprint/index.ts +29 -0
  40. package/src/build/blueprint/modules/entries.ts +117 -0
  41. package/src/build/blueprint/modules/index.ts +300 -0
  42. package/src/build/blueprint/modules/meta.ts +174 -0
  43. package/src/build/blueprint/scan/boot.ts +34 -0
  44. package/src/build/blueprint/scan/cognetImports.ts +56 -0
  45. package/src/build/blueprint/scan/components.ts +45 -0
  46. package/src/build/blueprint/scan/config.ts +234 -0
  47. package/src/build/blueprint/scan/configImports.ts +232 -0
  48. package/src/build/blueprint/scan/declare-worker.ts +61 -0
  49. package/src/build/blueprint/scan/declare.ts +393 -0
  50. package/src/build/blueprint/scan/h3-globals.ts +137 -0
  51. package/src/build/blueprint/scan/knowledge.ts +101 -0
  52. package/src/build/blueprint/scan/middleware.ts +110 -0
  53. package/src/build/blueprint/scan/moduleImports.ts +79 -0
  54. package/src/build/blueprint/scan/plugins.ts +93 -0
  55. package/src/build/blueprint/scan/promptPackages.ts +45 -0
  56. package/src/build/blueprint/scan/prompts.ts +164 -0
  57. package/src/build/blueprint/scan/published.ts +131 -0
  58. package/src/build/blueprint/scan/resolve.ts +398 -0
  59. package/src/build/blueprint/scan/routes.ts +109 -0
  60. package/src/build/blueprint/scan/scripts.ts +119 -0
  61. package/src/build/blueprint/scan/tool-bundle-worker.ts +69 -0
  62. package/src/build/blueprint/scan/tools.ts +610 -0
  63. package/src/build/blueprint/types.ts +28 -0
  64. package/src/build/extensions/config.ts +261 -0
  65. package/src/build/extensions/edit.ts +684 -0
  66. package/src/build/extensions/extensions.ts +731 -0
  67. package/src/build/extensions/index.ts +10 -0
  68. package/src/build/extensions/load.ts +350 -0
  69. package/src/build/extensions/registrations.ts +189 -0
  70. package/src/build/extensions/store.ts +200 -0
  71. package/src/build/frame/frame.ts +145 -0
  72. package/src/build/frame/index.ts +5 -0
  73. package/src/build/frame/migrate.ts +246 -0
  74. package/src/build/project/bundle/agent.ts +382 -0
  75. package/src/build/project/bundle/artifacts.ts +88 -0
  76. package/src/build/project/bundle/assets.ts +385 -0
  77. package/src/build/project/bundle/bundle.ts +160 -0
  78. package/src/build/project/bundle/imports.ts +102 -0
  79. package/src/build/project/bundle/index.ts +16 -0
  80. package/src/build/project/bundle/module.ts +130 -0
  81. package/src/build/project/bundle/source.ts +136 -0
  82. package/src/build/project/bundle/stage.ts +97 -0
  83. package/src/build/project/bundle/types.ts +111 -0
  84. package/src/build/project/cognet.ts +156 -0
  85. package/src/build/project/create/agent.ts +52 -0
  86. package/src/build/project/create/bench.ts +81 -0
  87. package/src/build/project/create/cognet.ts +102 -0
  88. package/src/build/project/create/extension.ts +63 -0
  89. package/src/build/project/create/module.ts +43 -0
  90. package/src/build/project/create/profile.ts +102 -0
  91. package/src/build/project/create/prompt.ts +68 -0
  92. package/src/build/project/create/templates.ts +88 -0
  93. package/src/build/project/deploy.ts +96 -0
  94. package/src/build/project/index.ts +40 -0
  95. package/src/build/project/installer.ts +616 -0
  96. package/src/build/project/kinds.ts +374 -0
  97. package/src/build/project/links.ts +33 -0
  98. package/src/build/project/manifest/bunfig.ts +139 -0
  99. package/src/build/project/manifest/config.ts +246 -0
  100. package/src/build/project/manifest/env.ts +184 -0
  101. package/src/build/project/manifest/index.ts +9 -0
  102. package/src/build/project/manifest/manifest.ts +49 -0
  103. package/src/build/project/manifest/model.ts +124 -0
  104. package/src/build/project/manifest/package.ts +386 -0
  105. package/src/build/project/manifest/text.ts +19 -0
  106. package/src/build/project/models/fetch.ts +123 -0
  107. package/src/build/project/models/index.ts +8 -0
  108. package/src/build/project/models/models.ts +111 -0
  109. package/src/build/project/models/specifier.ts +106 -0
  110. package/src/build/project/models/store.ts +202 -0
  111. package/src/build/project/modules/hash.ts +31 -0
  112. package/src/build/project/modules/index.ts +5 -0
  113. package/src/build/project/modules/lock.ts +78 -0
  114. package/src/build/project/modules/modules.ts +155 -0
  115. package/src/build/project/prepare.ts +709 -0
  116. package/src/build/project/project.ts +253 -0
  117. package/src/build/project/projects.ts +164 -0
  118. package/src/build/project/propagation.ts +120 -0
  119. package/src/build/project/publish/verify.ts +312 -0
  120. package/src/build/project/publish.ts +155 -0
  121. package/src/build/project/reconcile.ts +93 -0
  122. package/src/build/project/specifier.ts +42 -0
  123. package/src/build/project/tree.ts +615 -0
  124. package/src/build/project/treecache.ts +356 -0
  125. package/src/build/project/typegen/axon-dts.ts +362 -0
  126. package/src/build/project/typegen/cognet-dts.ts +91 -0
  127. package/src/build/project/typegen/components.ts +45 -0
  128. package/src/build/project/typegen/env.ts +59 -0
  129. package/src/build/project/typegen/generators.ts +108 -0
  130. package/src/build/project/typegen/hooks.ts +71 -0
  131. package/src/build/project/typegen/index.ts +137 -0
  132. package/src/build/project/typegen/prompt-dts.ts +40 -0
  133. package/src/build/project/typegen/prompts.ts +36 -0
  134. package/src/build/project/typegen/registry-dts.ts +109 -0
  135. package/src/build/project/typegen/scripts.ts +37 -0
  136. package/src/build/project/typegen/tools.ts +31 -0
  137. package/src/build/project/typegen/tsconfig.ts +243 -0
  138. package/src/build/project/typegen/tui-dts.ts +120 -0
  139. package/src/build/project/typegen/write.ts +40 -0
  140. package/src/build/project/verify.ts +268 -0
  141. package/src/build/project/watcher.ts +266 -0
  142. package/src/build/runtime/agent.ts +550 -0
  143. package/src/build/runtime/escalations.ts +159 -0
  144. package/src/build/runtime/index.ts +15 -0
  145. package/src/build/runtime/instances.ts +604 -0
  146. package/src/build/runtime/profile.ts +91 -0
  147. package/src/build/runtime/progress.ts +143 -0
  148. package/src/build/runtime/requests.ts +167 -0
  149. package/src/build/runtime/resolve.ts +159 -0
  150. package/src/build/runtime/runtime.ts +233 -0
  151. package/src/build/runtime/sessions/index.ts +5 -0
  152. package/src/build/runtime/sessions/record.ts +145 -0
  153. package/src/build/runtime/sessions/sessions.ts +240 -0
  154. package/src/build/runtime/zeno.ts +120 -0
  155. package/src/index.ts +11 -0
  156. package/src/link/agent-main.ts +395 -0
  157. package/src/link/index.ts +70 -0
  158. package/src/link/services.ts +120 -0
  159. package/src/platform.ts +293 -0
  160. package/src/procs/index.ts +15 -0
  161. package/src/procs/tree.ts +177 -0
  162. package/src/services/cloud.ts +419 -0
  163. package/src/services/control/client.ts +126 -0
  164. package/src/services/control/dispatch.ts +156 -0
  165. package/src/services/control/index.ts +17 -0
  166. package/src/services/control/protocol.ts +179 -0
  167. package/src/services/control/server.ts +241 -0
  168. package/src/services/deployments.ts +81 -0
  169. package/src/services/files.ts +329 -0
  170. package/src/services/index.ts +5 -0
  171. package/src/services/mic/capture.ts +248 -0
  172. package/src/services/mic/config.ts +109 -0
  173. package/src/services/mic/fft.ts +93 -0
  174. package/src/services/mic/index.ts +139 -0
  175. package/src/services/mic/visualizer.ts +46 -0
  176. package/src/services/ollama/catalog.ts +122 -0
  177. package/src/services/ollama/http.ts +124 -0
  178. package/src/services/ollama/index.ts +13 -0
  179. package/src/services/ollama/models.ts +153 -0
  180. package/src/services/ollama/ollama.ts +89 -0
  181. package/src/services/ollama/registry.ts +112 -0
  182. package/src/services/ollama/types.ts +72 -0
  183. package/src/services/prompts.ts +76 -0
  184. package/src/services/registry.ts +220 -0
  185. package/src/services/resources/hardware.ts +125 -0
  186. package/src/services/resources/index.ts +6 -0
  187. package/src/services/resources/reservations.ts +162 -0
  188. package/src/services/resources/resources.ts +156 -0
  189. package/src/services/running/index.ts +1 -0
  190. package/src/services/running/running.ts +200 -0
  191. package/src/services/store/disk.ts +97 -0
  192. package/src/services/store/index.ts +15 -0
  193. package/src/services/store/store.ts +729 -0
  194. package/src/services/store/types.ts +303 -0
  195. package/src/services/test/child.ts +150 -0
  196. package/src/services/test/events.ts +102 -0
  197. package/src/services/test/files.ts +26 -0
  198. package/src/services/test/frames.ts +39 -0
  199. package/src/services/test/index.ts +7 -0
  200. package/src/services/test/runner.ts +122 -0
  201. package/src/services/test/types.ts +26 -0
  202. package/src/services/update/contract.ts +77 -0
  203. package/src/services/update/index.ts +12 -0
  204. package/src/services/update/installer.ts +139 -0
  205. package/src/services/update/updates.ts +137 -0
  206. package/src/utils/fs.ts +148 -0
  207. package/src/utils/tsast.ts +102 -0
@@ -0,0 +1,243 @@
1
+ import { join } from "node:path"
2
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
3
+ import { err } from "@arcforge/err"
4
+ import { Tree } from "../tree"
5
+ import { Frame, FRAME } from "../../frame"
6
+ import { INLINE_COGNET_DIR, inlineCognetDir } from "../../blueprint/cognet"
7
+ import { COGNET_GLOBALS } from "./cognet-dts"
8
+ import { KINDS, type ProjectKind } from "../kinds"
9
+
10
+ // ── Compiler options ──────────────────────────────────────────────────────────
11
+ //
12
+ // Agent/module/cognet projects get their compiler options by `extends`-ing
13
+ // @arcforge/types/tsconfig.base.json — a real published file resolved through
14
+ // the project's own node_modules. There is no machine-local path resolution:
15
+ // the project declares @arcforge/types + @arcforge/engines as dependencies and
16
+ // `bun install` puts them on disk, so `@arcforge/types` and `import("h3")`
17
+ // resolve the ordinary way. `axon prepare` only writes .agent/ codegen (the
18
+ // .d.ts + a thin extends-only tsconfig) — it never resolves framework paths.
19
+
20
+ const TSCONFIG_BASE = "@arcforge/types/tsconfig.base.json"
21
+
22
+ // ── Tsconfig shapes ───────────────────────────────────────────────────────────
23
+
24
+ // The per-kind `include` globs live in the kind table — see kinds.ts. The one
25
+ // scope that is NOT a kind is an agent's tests/ directory: it gets its own
26
+ // tsconfig specifically so it never sees axon.d.ts's `Axon` (the engine
27
+ // constructor) alongside axon-test.d.ts's `Axon` (the test runtime spawner) in
28
+ // one ambient scope — see axon-dts.ts's file-level comment. Both configs glob
29
+ // `*.d.ts` (so tool-globals.d.ts/prompts.d.ts/etc are picked up automatically)
30
+ // but `exclude` carves out the one file belonging to the OTHER scope.
31
+ //
32
+ // Root-relative, like the kind table's globs, and rebased by the same helper.
33
+ const TESTS_INCLUDE = [
34
+ "./**/*.d.ts",
35
+ "tests/**/*.ts",
36
+ ]
37
+
38
+ // The scope of an agent's inline `cognet/`.
39
+ //
40
+ // The WHOLE folder, not a list of the subdirectories a standalone cognet
41
+ // happens to use. Everything under `cognet/` is brain source by definition —
42
+ // the directory exists for exactly one purpose — so enumerating `src/` and
43
+ // `plugins/` only means a brain written as a flat `cognet/main.ts` gets no
44
+ // globals and reads as broken. The compiler accepts either layout (see
45
+ // resolveCognetMain), and the editor must agree with the compiler.
46
+ const INLINE_COGNET_INCLUDE = [
47
+ "./**/*.d.ts",
48
+ `${INLINE_COGNET_DIR}/**/*.ts`,
49
+ ]
50
+
51
+ /**
52
+ * Rewrite a root-relative glob so it resolves from the generated tsconfig,
53
+ * which sits at `.<dir>/types/` — two levels below the project root.
54
+ *
55
+ * `./`-prefixed globs are left alone: they deliberately name the .d.ts files
56
+ * generated beside the tsconfig itself, so they are already correct wherever
57
+ * that file lands. Everything else gets the prefix, computed from the frame
58
+ * depth rather than hard-coded, so moving the interior another level down is
59
+ * a change to one constant instead of thirty strings in kinds.ts.
60
+ */
61
+ const FRAME_DEPTH = 2
62
+ const UP = "../".repeat(FRAME_DEPTH)
63
+
64
+ function rebase(globs: string[]): string[] {
65
+ return globs.map(glob => (glob.startsWith("./") ? glob : `${UP}${glob}`))
66
+ }
67
+
68
+ // ── Dependency guard ──────────────────────────────────────────────────────────
69
+
70
+ /**
71
+ * The generated tsconfigs `extends` @arcforge/types/tsconfig.base.json and the
72
+ * generated .d.ts references @arcforge/types / @arcforge/engines / h3 — all of
73
+ * which must be installed in the project's node_modules for types to resolve.
74
+ * If they aren't, fail loud with the fix, rather than writing a config that
75
+ * silently degrades every framework symbol to `any`.
76
+ *
77
+ * `Tree.frameworkInstalled` walks the directory tree for
78
+ * node_modules/@arcforge/types on disk — the same check, and the same leaf,
79
+ * prepare uses to decide whether to install. Reading disk rather than resolving
80
+ * avoids two failure modes bun's resolver has: a per-process resolution cache
81
+ * (a miss cached BEFORE prepare's install wrongly persisting after it) and
82
+ * resolution through the global install cache (a hit for a project whose
83
+ * node_modules is empty).
84
+ */
85
+ function assertFrameworkInstalled(projectRoot: string): void {
86
+ if (Tree({ root: projectRoot }).frameworkInstalled()) return
87
+ throw err("FRAMEWORK_NOT_INSTALLED", {
88
+ detail: `@arcforge/types cannot be resolved from ${projectRoot} — `
89
+ + "run `bun install` in the project before `axon prepare`.",
90
+ context: { root: projectRoot },
91
+ })
92
+ }
93
+
94
+ // ── Writers ───────────────────────────────────────────────────────────────────
95
+
96
+ /**
97
+ * The frame of a kind that installs nothing.
98
+ *
99
+ * Everything else `extends` @arcforge/types/tsconfig.base.json out of the
100
+ * project's node_modules. A prompt package has no node_modules by design, so
101
+ * that path resolves to nothing and every symbol silently degrades to `any` —
102
+ * the exact failure assertFrameworkInstalled() exists to prevent elsewhere.
103
+ * These options are therefore stated inline: modern, strict, and checking
104
+ * nothing but the config file's own call.
105
+ */
106
+ function writeStandaloneFrame(root: string, kind: ProjectKind, include: string[]): void {
107
+ const frame = Frame({ root: root, kind: kind })
108
+ const typesDir = frame.ensure("types")
109
+
110
+ writeFileSync(
111
+ join(typesDir, "tsconfig.json"),
112
+ JSON.stringify({
113
+ compilerOptions: {
114
+ target: "ESNext",
115
+ module: "ESNext",
116
+ moduleResolution: "bundler",
117
+ strict: true,
118
+ skipLibCheck: true,
119
+ noEmit: true,
120
+ // Deliberately NOT ["bun"], unlike the published base config
121
+ // this kind cannot extend: a prompt package installs nothing,
122
+ // so naming a @types package here would reference something
123
+ // provably absent from disk and degrade every symbol to `any`.
124
+ types: [],
125
+ },
126
+ include: rebase(include),
127
+ }, null, 2) + "\n",
128
+ "utf-8"
129
+ )
130
+
131
+ ensureRootPointer(join(root, "tsconfig.json"), `./${frame.name}/${FRAME.types}/tsconfig.json`)
132
+ }
133
+
134
+ /** Write a thin extends-only root tsconfig if one isn't already correctly pointed. */
135
+ function ensureRootPointer(rootPath: string, extendsTarget: string): void {
136
+ let needsWrite = !existsSync(rootPath)
137
+ if (!needsWrite) {
138
+ try {
139
+ const existing = JSON.parse(readFileSync(rootPath, "utf-8"))
140
+ if (existing.include || existing.extends !== extendsTarget) needsWrite = true
141
+ } catch {
142
+ needsWrite = true
143
+ }
144
+ }
145
+ if (needsWrite) {
146
+ writeFileSync(rootPath, JSON.stringify({ extends: extendsTarget }, null, 2) + "\n", "utf-8")
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Write a project's frame tsconfig and the thin root pointer into it.
152
+ *
153
+ * One writer for every kind: the frame directory and its `include` globs come
154
+ * from the kind table, and an agent's tests/ scope is the single genuine
155
+ * addition on top. This used to be three near-identical functions that had to
156
+ * be kept in step by hand.
157
+ */
158
+ export function ensureProjectTsConfig(root: string, kind: ProjectKind): void {
159
+ const spec = KINDS[kind]
160
+ if (!spec.frame) return
161
+
162
+ // A kind that installs nothing has no node_modules to resolve through,
163
+ // so its frame must stand alone — it neither extends the published base
164
+ // config nor references a framework package. Guarding on `installs`
165
+ // rather than naming the kind keeps the rule where the reason is.
166
+ if (!spec.installs) {
167
+ writeStandaloneFrame(root, kind, spec.include)
168
+ return
169
+ }
170
+
171
+ assertFrameworkInstalled(root)
172
+
173
+ const frame = Frame({ root: root, kind: kind })
174
+ const typesDir = frame.ensure("types")
175
+ const inlineCognet = kind === "agent" ? inlineCognetDir(root) : null
176
+
177
+ // Agents carve out tests/ — and cognet/ when one is inlined — each of
178
+ // which lives in a sibling config below. Every other kind has one scope.
179
+ //
180
+ // The exclusions are the load-bearing half: three ambient surfaces share
181
+ // this one directory, and a scope that can see another's declarations gets
182
+ // `Axon` (engine constructor) and `Axon` (test spawner), or the agent's
183
+ // globals alongside the cognet's, in the same lexical space.
184
+ const exclude = kind === "agent"
185
+ ? {
186
+ exclude: [
187
+ `${UP}tests/**`,
188
+ "./axon-test.d.ts",
189
+ ...(inlineCognet ? [`${UP}${INLINE_COGNET_DIR}/**`, `./${COGNET_GLOBALS}`] : []),
190
+ ],
191
+ }
192
+ : {}
193
+
194
+ writeFileSync(
195
+ join(typesDir, "tsconfig.json"),
196
+ JSON.stringify({ extends: TSCONFIG_BASE, include: rebase(spec.include), ...exclude }, null, 2) + "\n",
197
+ "utf-8"
198
+ )
199
+
200
+ if (kind === "agent") {
201
+ // tests/ scope — the flip side: sees axon-test.d.ts, never axon.d.ts.
202
+ writeFileSync(
203
+ join(typesDir, "axon-test.tsconfig.json"),
204
+ JSON.stringify({ extends: TSCONFIG_BASE, include: rebase(TESTS_INCLUDE), exclude: ["./axon.d.ts"] }, null, 2) + "\n",
205
+ "utf-8"
206
+ )
207
+
208
+ const testsDir = join(root, "tests")
209
+ if (!existsSync(testsDir)) mkdirSync(testsDir, { recursive: true })
210
+ ensureRootPointer(
211
+ join(testsDir, "tsconfig.json"),
212
+ `../${frame.name}/${FRAME.types}/axon-test.tsconfig.json`,
213
+ )
214
+ }
215
+
216
+ // The inline cognet's own scope: the brain-authoring globals (loop,
217
+ // kernel, phase, system, defineCognet) and NOTHING the agent declares.
218
+ // Written only when the folder exists, so an agent without one carries no
219
+ // config pointing at an empty directory.
220
+ if (inlineCognet) {
221
+ writeFileSync(
222
+ join(typesDir, "cognet.tsconfig.json"),
223
+ JSON.stringify({
224
+ extends: TSCONFIG_BASE,
225
+ include: rebase(INLINE_COGNET_INCLUDE),
226
+ // Everything generated for the AGENT. Listed by name rather
227
+ // than by a glob, because `./**/*.d.ts` in the include above is
228
+ // what picks up the cognet's own declarations — an exclusion
229
+ // broad enough to catch the agent's would catch those too.
230
+ exclude: ["./axon.d.ts", "./axon-test.d.ts", "./tool-globals.d.ts",
231
+ "./prompts.d.ts", "./scripts.d.ts", "./components.d.ts",
232
+ "./env.d.ts", "./hooks.d.ts"],
233
+ }, null, 2) + "\n",
234
+ "utf-8"
235
+ )
236
+ ensureRootPointer(
237
+ join(inlineCognet, "tsconfig.json"),
238
+ `../${frame.name}/${FRAME.types}/cognet.tsconfig.json`,
239
+ )
240
+ }
241
+
242
+ ensureRootPointer(join(root, "tsconfig.json"), `./${frame.name}/${FRAME.types}/tsconfig.json`)
243
+ }
@@ -0,0 +1,120 @@
1
+ import { join } from "node:path"
2
+ import { writeFileSync } from "node:fs"
3
+ import { TUI_CONTRACT } from "@arcforge/types/tui-contract"
4
+ import { Frame, type ProjectKind } from "../../frame"
5
+
6
+ /**
7
+ * The ambient authoring surface for a PROFILE and for EXTENSIONS — the ten
8
+ * globals a user's `main.ts`, `plugins/` and `extensions/` are written
9
+ * against, plus `defineProfile`/`defineExtension`.
10
+ *
11
+ * ── Why this file reads a constant instead of holding the text ───────────────
12
+ *
13
+ * The other ambient frames (cognet, prompt) inline their declarations as a
14
+ * template literal and carry a "must stay in lockstep with X" comment. That is
15
+ * a manual sync, and it is affordable there because both surfaces are small and
16
+ * change about as often as the config file format itself.
17
+ *
18
+ * The TUI contract is neither: it is the whole extension API, it is the thing
19
+ * this feature exists to expose, and it will change while the API settles. A
20
+ * hand-maintained copy of it would drift the first week. So `@arcforge/types`
21
+ * exports its own source text as `TUI_CONTRACT` (generated from
22
+ * `src/tui.ts` at build time — see that package's `scripts/contract.ts`), and
23
+ * this writer only wraps it. One authored file, no duplicate to keep in step.
24
+ *
25
+ * The wrapping is what makes it ambient: `tui.ts` is an ordinary module of
26
+ * exported types, and a profile needs those same types as globals. `export`
27
+ * is stripped and the whole thing goes inside `declare global`.
28
+ *
29
+ * The trailing `export {}` is load-bearing. It makes globals.d.ts a module, so
30
+ * `declare global` is legal — and it is also what lets `moduleDetection: force`
31
+ * (from tsconfig.base.json) treat a user's import-free `main.ts` as a module,
32
+ * which is what makes top-level `await` work there. Removing it breaks both.
33
+ */
34
+ function tuiDts(): string {
35
+ return `// Generated by axon prepare — do not edit.
36
+ // Ambient globals for a profile's main.ts, plugins/ and extensions/.
37
+ // Source: @arcforge/types/src/tui.ts
38
+
39
+ declare global {
40
+ ${TUI_CONTRACT}
41
+
42
+ // ── The globals themselves ───────────────────────────────────────────────
43
+ //
44
+ // Ten, deliberately: everything reachable from the keyboard, and nothing
45
+ // more. They are ambient rather than imported because that is the authoring
46
+ // DX the rest of the platform already uses (cognet's loop/kernel/phase,
47
+ // a prompt's definePrompt) — and because an extension cannot import from a
48
+ // minified CLI bundle, so a handle it must reach for could not be typed.
49
+
50
+ /** The terminal itself — navigation, notifications, lifecycle hooks. */
51
+ const tui: AxonTui
52
+ /** The interaction primitive — registered palettes, and pick/confirm/prompt. */
53
+ const palette: AxonPalette
54
+ /** The \`:\` command tree. */
55
+ const commands: AxonCommands
56
+ /** Key chords. */
57
+ const keys: AxonKeys
58
+ /** Mode switching. */
59
+ const mode: AxonMode
60
+ /** The message box. */
61
+ const input: AxonInput
62
+ /** Agent instances — spawn by name, everything else by instance. */
63
+ const agents: AxonAgents
64
+ /** The terminal's colours, and switching between them. */
65
+ const theme: AxonTheme
66
+ /** The configurable rows above the input bar. */
67
+ const lines: AxonLines
68
+ /** The live values a line can show. */
69
+ const components: AxonComponents
70
+
71
+ /** identity declaration — extension.config.ts only */
72
+ function defineExtension(config?: ExtensionConfig): ExtensionDefinition
73
+
74
+ /** identity declaration — profile.config.ts only */
75
+ function defineProfile(config: ProfileConfig): ProfileDefinition
76
+
77
+ /**
78
+ * Provider factories — what \`providers:\` takes.
79
+ *
80
+ * Declared here rather than imported: a profile directory has no
81
+ * node_modules to resolve through, which is the same constraint the whole
82
+ * frame is built around. The shapes are spelled out for the same reason
83
+ * ProviderEntry itself is spelled out in tui.ts.
84
+ */
85
+ function Axon(options?: ProviderOptions): ProviderEntry
86
+ function Codex(options?: ProviderOptions): ProviderEntry
87
+ function OpenRouter(options?: ProviderOptions): ProviderEntry
88
+ function Ollama(options?: ProviderOptions): ProviderEntry
89
+ function HuggingFace(options?: ProviderOptions): ProviderEntry
90
+ function Mock(script?: unknown): ProviderEntry
91
+
92
+ type ProviderOptions = {
93
+ /** Own credential, for a user supplying one rather than connecting their account. */
94
+ key?: string
95
+ /** Endpoint override — self-hosted daemons, local harnesses. */
96
+ url?: string
97
+ /** Ceiling on concurrent calls a fanned-out role may spend here. */
98
+ slots?: number
99
+ }
100
+ }
101
+
102
+ export {}
103
+ `
104
+ }
105
+
106
+ /**
107
+ * Write globals.d.ts into a profile's or an extension's type frame.
108
+ *
109
+ * Both kinds get the SAME surface. An extension is a profile's main.ts
110
+ * packaged — if an extension could not express what a user's own config can,
111
+ * every gap would become a feature request, so there is one contract and one
112
+ * writer rather than a privileged internal surface and a reduced public one.
113
+ */
114
+ export function generateTuiDts(root: string, kind: ProjectKind): void {
115
+ writeFileSync(
116
+ join(Frame({ root, kind }).ensure("types"), "globals.d.ts"),
117
+ tuiDts(),
118
+ "utf-8",
119
+ )
120
+ }
@@ -0,0 +1,40 @@
1
+ import { writeFileSync } from "node:fs"
2
+ import { join } from "node:path"
3
+ import { Frame, type ProjectKind } from "../../frame"
4
+
5
+ /**
6
+ * Declaration output for one project. Each kind writes into the `types/` area
7
+ * of its own dotted frame directory — .agent/types/, .module/types/, … —
8
+ * whose location comes from Frame() rather than being spelled here, so a new
9
+ * kind cannot silently land in another's frame and the interior layout is
10
+ * decided in exactly one place.
11
+ */
12
+
13
+ /**
14
+ * Every kind typegen can write for — which is every kind.
15
+ *
16
+ * An alias, not a second union. This was spelled out as its own five-member
17
+ * list and had already drifted: adding a kind to the table left typegen
18
+ * rejecting it, with the error surfacing here rather than where the kind was
19
+ * declared. Whether a kind gets declarations is `KINDS[kind].frame`'s job to
20
+ * say, not this type's.
21
+ */
22
+ export type TypegenKind = ProjectKind
23
+
24
+ /** Ensure the project's generated-types dir exists and return it. */
25
+ export function ensureOutDir(root: string, kind: TypegenKind = "agent"): string {
26
+ return Frame({ root: root, kind: kind }).ensure("types")
27
+ }
28
+
29
+ /** Write one declaration file into the project's generated-types dir. */
30
+ export function writeDts(root: string, filename: string, content: string, kind: TypegenKind = "agent"): void {
31
+ writeFileSync(join(ensureOutDir(root, kind), filename), content, "utf-8")
32
+ }
33
+
34
+ /** kebab-case → PascalCase. */
35
+ export function toPascalCase(name: string): string {
36
+ return name
37
+ .split("-")
38
+ .map(s => s.charAt(0).toUpperCase() + s.slice(1))
39
+ .join("")
40
+ }
@@ -0,0 +1,268 @@
1
+ import { join } from "node:path"
2
+ import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs"
3
+ import { satisfies, validRange } from "semver"
4
+ import type { ManifestT } from "./manifest"
5
+
6
+ /**
7
+ * Verify — is what is on disk coherent with what the project declares?
8
+ *
9
+ * THE CONCEPT THIS SYSTEM WAS MISSING. Every dependency incident worth fixing
10
+ * has been the same shape: state on disk disagreed with state in the manifest,
11
+ * and nothing checked before trusting it. Each was then patched with its own
12
+ * bespoke repair bolted to the front of `prepare`:
13
+ *
14
+ * - a package present at the WRONG VERSION passed as installed, because
15
+ * installed-ness was `existsSync(dir)`
16
+ * - a range auto-resolved against a DIFFERENT REGISTRY was honoured as a
17
+ * pin forever, so every install failed on a version that only existed on
18
+ * one machine (@axon/zero@^1.0.5)
19
+ * - a node_modules of DANGLING LINKS read as installed, because the shared
20
+ * tree cache it was grafted onto had been evicted
21
+ * - a cognet whose bundle targets a stale KERNEL ABI compiled and then failed
22
+ * at load
23
+ *
24
+ * Four incidents, four repairs, four places to remember. This is the single
25
+ * question all of them are asking, so a FIFTH incident becomes a new Fault
26
+ * variant rather than another line at the top of prepare.
27
+ *
28
+ * Faults are DESCRIPTIVE, never repaired here. Detection and repair are split
29
+ * deliberately: `--frozen` must be able to ask this exact question and refuse,
30
+ * and a check that fixes what it finds can never fail. The caller decides.
31
+ */
32
+
33
+ /** Why a project's installed state disagrees with what it declares. */
34
+ export type Fault =
35
+ /** Declared but absent from node_modules, or present and unreadable. */
36
+ | { kind: "missing"; name: string; range: string }
37
+ /** Present, but its version falls outside the range now declared. */
38
+ | { kind: "stale"; name: string; range: string; installed: string }
39
+ /**
40
+ * The package's directory is a symlink pointing at something that no
41
+ * longer exists — a graft onto a shared cache tree that has been evicted.
42
+ *
43
+ * Distinct from `missing` because the cause is MACHINE STATE, not the
44
+ * manifest: the user changed nothing and no edit to their config will fix
45
+ * it. Reporting it as missing sends them looking for a typo.
46
+ */
47
+ | { kind: "dangling"; name: string; link: string; target: string }
48
+ /**
49
+ * The range was auto-resolved against a different registry than the one
50
+ * now configured, so it may name a version this registry never had.
51
+ *
52
+ * Only ever reported for ranges Axon WROTE (`axon.trackedFrom`). A range
53
+ * the user pinned carries no origin and is never second-guessed.
54
+ */
55
+ | { kind: "foreign"; name: string; range: string; origin: string; current: string }
56
+ /**
57
+ * Declared at a local `workspace:`/`file:` range while Axon manages it
58
+ * from the registry — this machine will not behave like a fresh clone.
59
+ *
60
+ * Reported, never repaired: pointing an agent at a local checkout on
61
+ * purpose is legitimate, and rewriting someone's manifest on suspicion is
62
+ * worse than the drift.
63
+ */
64
+ | { kind: "shadowed"; name: string; range: string }
65
+ /**
66
+ * bunfig.toml maps a scope at a DIFFERENT registry than the one now
67
+ * configured, so bun would fetch tarballs from the wrong place.
68
+ *
69
+ * The sharpest form of registry mixing, because it splits one install in
70
+ * half: ranges resolve against the current registry while the bytes come
71
+ * from the old one. `trackedFrom` cannot catch it — that describes a
72
+ * range, and this is about where the package is FETCHED.
73
+ */
74
+ | { kind: "registry"; scope: string; mapped: string; current: string }
75
+
76
+ export type VerifyReport = {
77
+ /** True when nothing needs to change on disk. */
78
+ coherent: boolean
79
+ faults: Fault[]
80
+ /**
81
+ * Faults that repair by installing, as opposed to those needing a
82
+ * manifest edit or no action at all. Lets a caller answer "must I install"
83
+ * without re-deriving it from the fault kinds.
84
+ */
85
+ needsInstall: boolean
86
+ }
87
+
88
+ export type VerifyOpts = {
89
+ root: string
90
+ manifest: ManifestT
91
+ /**
92
+ * Every dependency Axon manages, and the range each should be at — the
93
+ * cognet plus registry modules. Anything absent is the user's own
94
+ * dependency and is never inspected.
95
+ */
96
+ managed: Record<string, string>
97
+ /** The registry auto-resolved ranges are attributed to, for `foreign`. */
98
+ registryOrigin: string
99
+ /** Installed version of a package, or null. Supplied by Tree. */
100
+ installedVersion(name: string): string | null
101
+ /** Where a package resolved to, or null. Supplied by Tree. */
102
+ locate(name: string): string | null
103
+ }
104
+
105
+ /** A local range is a deliberate link, not a registry install. */
106
+ function isLocal(range: string): boolean {
107
+ return range.startsWith("workspace:") || range.startsWith("file:")
108
+ }
109
+
110
+ /**
111
+ * The dangling symlink standing where a package should be, if there is one.
112
+ *
113
+ * Checks the package path AND its scope directory, because a grafted tree
114
+ * links whole top-level entries ("@axon"), not individual packages inside
115
+ * them — so an evicted tree shows up one level above the name being resolved.
116
+ */
117
+ function danglingAt(root: string, name: string): { link: string; target: string } | null {
118
+ const [scope] = name.split("/")
119
+ const candidates = [
120
+ join(root, "node_modules", ...name.split("/")),
121
+ ...(name.startsWith("@") ? [join(root, "node_modules", scope!)] : []),
122
+ ]
123
+ for (const link of candidates) {
124
+ try {
125
+ if (!lstatSync(link).isSymbolicLink()) continue
126
+ if (existsSync(link)) continue
127
+ return { link, target: readlinkSync(link) }
128
+ } catch {
129
+ // Not a link, or gone entirely — `missing` covers that case.
130
+ }
131
+ }
132
+ return null
133
+ }
134
+
135
+ /**
136
+ * Is node_modules present but composed ENTIRELY of dangling links?
137
+ *
138
+ * The signature of a grafted project whose cache tree was deleted. Checked as
139
+ * a whole-tree property rather than per package because that is what makes it
140
+ * distinguishable from a partial install still in progress.
141
+ */
142
+ export function graftBroken(root: string): boolean {
143
+ const modules = join(root, "node_modules")
144
+ if (!existsSync(modules)) return false
145
+ let entries: string[]
146
+ try {
147
+ entries = readdirSync(modules).filter(name => !name.startsWith("."))
148
+ } catch {
149
+ return false
150
+ }
151
+ if (entries.length === 0) return false
152
+ return entries.every(entry => {
153
+ const path = join(modules, entry)
154
+ try {
155
+ return lstatSync(path).isSymbolicLink() && !existsSync(path)
156
+ } catch {
157
+ return false
158
+ }
159
+ })
160
+ }
161
+
162
+ /**
163
+ * Compare every managed dependency against what is actually on disk.
164
+ *
165
+ * Pure inspection — reads the manifest and the filesystem, writes nothing.
166
+ */
167
+ export async function verify(opts: VerifyOpts): Promise<VerifyReport> {
168
+ const origins = await opts.manifest.package.dependencies.trackedFrom()
169
+ const faults: Fault[] = []
170
+
171
+ // Where tarballs are FETCHED from, which is a different question than
172
+ // where a range was resolved. A bunfig left pointing at a previous run's
173
+ // registry splits an install in half — current ranges, stale bytes — and
174
+ // nothing about the manifest reveals it.
175
+ //
176
+ // Only scopes Axon actually serves are inspected: an agent legitimately
177
+ // depends on ordinary npm packages, and those must keep resolving against
178
+ // public npm.
179
+ const mappedScopes = await opts.manifest.bunfig.scopes()
180
+ const managedScopes = new Set(
181
+ Object.keys(opts.managed)
182
+ .map(name => opts.manifest.bunfig.scopeOf(name))
183
+ .filter((scope): scope is string => scope !== null),
184
+ )
185
+ for (const [scope, mapped] of Object.entries(mappedScopes)) {
186
+ if (!managedScopes.has(scope)) continue
187
+ if (mapped.startsWith(opts.registryOrigin)) continue
188
+ faults.push({ kind: "registry", scope, mapped, current: opts.registryOrigin })
189
+ }
190
+
191
+ for (const [name, range] of Object.entries(opts.managed)) {
192
+ if (isLocal(range)) {
193
+ // A workspace range on something Axon installs from the registry
194
+ // is reported but never touched. It changes nothing on disk, so it
195
+ // must not make --frozen fail either.
196
+ if (range.startsWith("workspace:")) faults.push({ kind: "shadowed", name, range })
197
+ continue
198
+ }
199
+
200
+ // Origin first: a foreign range makes every other question about this
201
+ // package meaningless, because the range itself names a version that
202
+ // may not exist here. Repairing it re-resolves and the rest follows.
203
+ const origin = origins[name]
204
+ if (origin !== undefined && origin !== opts.registryOrigin) {
205
+ faults.push({ kind: "foreign", name, range, origin, current: opts.registryOrigin })
206
+ continue
207
+ }
208
+
209
+ // A dangling link is checked before absence, because `installedVersion`
210
+ // reports both as null and only one of them is the user's problem.
211
+ const dangling = danglingAt(opts.root, name)
212
+ if (dangling) {
213
+ faults.push({ kind: "dangling", name, ...dangling })
214
+ continue
215
+ }
216
+
217
+ const installed = opts.installedVersion(name)
218
+ if (installed === null) {
219
+ faults.push({ kind: "missing", name, range })
220
+ continue
221
+ }
222
+
223
+ // An unparseable range is not evidence of a problem: it may be a tag
224
+ // or a URL Bun understands and semver does not. Presence is the most
225
+ // that can be checked, and it passed.
226
+ if (!validRange(range)) continue
227
+
228
+ if (!satisfies(installed, range)) {
229
+ faults.push({ kind: "stale", name, range, installed })
230
+ }
231
+ }
232
+
233
+ // Shadowing is deliberately not incoherence: nothing on disk needs to
234
+ // change, so a monorepo must still be able to freeze.
235
+ const actionable = faults.filter(fault => fault.kind !== "shadowed")
236
+
237
+ return {
238
+ faults,
239
+ coherent: actionable.length === 0,
240
+ // A `registry` fault forces an install: the bytes on disk came from
241
+ // the wrong registry, so re-resolving is the only way to correct them.
242
+ needsInstall: actionable.some(fault =>
243
+ fault.kind === "missing" || fault.kind === "stale"
244
+ || fault.kind === "dangling" || fault.kind === "registry"),
245
+ }
246
+ }
247
+
248
+ /** Render faults as the reason an install is running — or why `--frozen` refused. */
249
+ export function describeFaults(faults: Fault[]): string {
250
+ return faults
251
+ .map(fault => {
252
+ switch (fault.kind) {
253
+ case "missing":
254
+ return `${fault.name} (${fault.range}) is declared but not installed`
255
+ case "stale":
256
+ return `${fault.name} is at ${fault.installed}, outside the declared ${fault.range}`
257
+ case "dangling":
258
+ return `${fault.name} points at ${fault.target}, which no longer exists`
259
+ case "foreign":
260
+ return `${fault.name} (${fault.range}) was resolved against ${fault.origin}, not ${fault.current}`
261
+ case "shadowed":
262
+ return `${fault.name} is pinned to a local copy (${fault.range})`
263
+ case "registry":
264
+ return `@${fault.scope} fetches from ${fault.mapped}, not ${fault.current}`
265
+ }
266
+ })
267
+ .join("; ")
268
+ }