@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,300 @@
1
+ import { basename, join } from "node:path"
2
+ import type { AxonKnowledge, AxonMiddleware, AxonModule, AxonPlugin, AxonPrompt, AxonRoute, AxonScript, AxonTool, ModuleEntry } from "@arcforge/types"
3
+ import type { ResolvedModulePath } from "../scan/moduleImports"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { Plugins } from "../scan/plugins"
6
+ import { Prompts } from "../scan/prompts"
7
+ import { Knowledge } from "../scan/knowledge"
8
+ import { Routes } from "../scan/routes"
9
+ import { Middleware } from "../scan/middleware"
10
+ import { Scripts } from "../scan/scripts"
11
+ import { Tools } from "../scan/tools"
12
+ import type { ScanWarning } from "../types"
13
+ import { flatten, sourceRoot } from "./entries"
14
+ import { readMeta } from "./meta"
15
+
16
+ /**
17
+ * Modules — the one composite scanner. Resolves declared + installed modules
18
+ * and runs the SAME scanners against each module root that run against the
19
+ * agent. Module scanning can never drift from agent scanning because there
20
+ * is no second implementation.
21
+ *
22
+ * Sources, in precedence order:
23
+ * 1. Source modules declared in axon.config.ts (defineModule imports) —
24
+ * developed in place, win over an installed copy of the same name.
25
+ * 2. Local modules in modules/ that were not explicitly imported.
26
+ * 3. Registry modules declared as strings in axon.config.ts, resolved out
27
+ * of node_modules where the package manager put them.
28
+ *
29
+ * Declaration is the config, always. A package present in node_modules but
30
+ * absent from axon.config.ts contributes nothing: it may be a transitive
31
+ * dependency of another module, and a transitive dependency must never
32
+ * silently add tools to an agent's surface. This used to work the other
33
+ * way round — anything in the module store was active — which made the
34
+ * agent's tool surface a property of the filesystem rather than of a file
35
+ * the author reads and reviews.
36
+ */
37
+
38
+ /** One module's discovered surface, attributed for collision reporting. */
39
+ export type ModuleSurface = {
40
+ name: string
41
+ prompts: AxonPrompt[]
42
+ /** Already namespaced by module name — see the Knowledge() call below. */
43
+ knowledge: AxonKnowledge[]
44
+ scripts: AxonScript[]
45
+ tools: AxonTool[]
46
+ routes: AxonRoute[]
47
+ plugins: AxonPlugin[]
48
+ middleware: AxonMiddleware[]
49
+ }
50
+
51
+ export type ModulesResult = {
52
+ modules: AxonModule[]
53
+ surfaces: ModuleSurface[]
54
+ warnings: ScanWarning[]
55
+ }
56
+
57
+ export async function Modules(opts: {
58
+ root: string
59
+ declared: ModuleEntry[]
60
+ /** Statically-resolved source paths, positional to `declared`. */
61
+ modulePaths: ResolvedModulePath[]
62
+ }): Promise<ModulesResult> {
63
+ const entries = await flatten(opts.declared, opts.modulePaths)
64
+ const modules: AxonModule[] = []
65
+ const surfaces: ModuleSurface[] = []
66
+ const warnings: ScanWarning[] = []
67
+ const claimed = new Set<string>()
68
+
69
+ // A declared entry whose import could not be resolved to a file is a
70
+ // silent-no-tools trap — surface it. This is the class of failure that
71
+ // used to happen invisibly when defineModule guessed a path from the stack.
72
+ for (const resolved of opts.modulePaths) {
73
+ if (resolved.kind === "unresolved") {
74
+ warnings.push({ domain: "modules", error: `unresolved module declaration — ${resolved.detail}` })
75
+ }
76
+ }
77
+
78
+ // ── 1. Declared source modules ───────────────────────────────────────────
79
+ for (const entry of entries) {
80
+ if (entry.kind !== "source") continue
81
+ const root = sourceRoot(entry)
82
+ const name = await moduleName(root)
83
+ claimed.add(name)
84
+ await scanModule({ root, name, configPath: entry.configPath, options: entry.options, modules, surfaces, warnings })
85
+ }
86
+
87
+ // ── 2. Unimported local modules (modules/ directory) ────────────────────
88
+ const modulesDir = join(opts.root, "modules")
89
+ for (const dir of await fsx.list(modulesDir)) {
90
+ if (claimed.has(dir)) continue // source module owns this name
91
+
92
+ const declared = entries.find(e => e.kind === "registry" && e.name.split("/").pop() === dir)
93
+ const root = join(modulesDir, dir)
94
+ await scanModule({
95
+ root,
96
+ name: dir,
97
+ configPath: join(root, "module.config.ts"),
98
+ options: declared?.options ?? {},
99
+ modules,
100
+ surfaces,
101
+ warnings,
102
+ })
103
+ }
104
+
105
+ // ── 3. Declared registry modules (node_modules/) ─────────────────────────
106
+ for (const entry of entries) {
107
+ if (entry.kind !== "registry") continue
108
+
109
+ const root = join(opts.root, "node_modules", ...entry.name.split("/"))
110
+ if (!fsx.exists(root)) {
111
+ warnings.push({
112
+ domain: "modules",
113
+ error: `module "${entry.name}" is declared in axon.config.ts but not installed — run \`axon install\``,
114
+ })
115
+ continue
116
+ }
117
+
118
+ const name = await moduleName(root)
119
+ if (claimed.has(name)) {
120
+ // A source module of the same name wins — developing in place
121
+ // beats the installed copy. But the user declared BOTH, so say
122
+ // so: silently dropping a declaration is how an install appears
123
+ // to succeed while contributing nothing.
124
+ warnings.push({
125
+ domain: "modules",
126
+ error: `module "${entry.name}" is also imported from source as "${name}" — the source module is used and the installed copy ignored. Remove one declaration from axon.config.ts.`,
127
+ })
128
+ continue
129
+ }
130
+ claimed.add(name)
131
+ await scanModule({ root, name, configPath: join(root, "module.config.ts"), options: entry.options, modules, surfaces, warnings })
132
+ }
133
+
134
+ return { modules, surfaces, warnings }
135
+ }
136
+
137
+ // ─── One module ───────────────────────────────────────────────────────────────
138
+
139
+ async function scanModule(opts: {
140
+ root: string
141
+ name: string
142
+ /** Absolute path to this module's module.config.ts — carried into the blueprint for boot-time import. */
143
+ configPath: string
144
+ options: Record<string, unknown>
145
+ modules: AxonModule[]
146
+ surfaces: ModuleSurface[]
147
+ warnings: ScanWarning[]
148
+ }): Promise<void> {
149
+ const { root, name, configPath } = opts
150
+
151
+ if (!fsx.exists(configPath)) {
152
+ opts.warnings.push({ domain: "modules", error: `module "${name}" at ${root} has no module.config.ts — skipped` })
153
+ return
154
+ }
155
+
156
+ /**
157
+ * A module listed twice is two INSTANCES, not two copies of its code.
158
+ *
159
+ * Each instance contributes its own AxonModule (so its options reach the
160
+ * runtime), but the module's files are scanned ONCE: a second copy of
161
+ * the same plugin would run the same capture loop twice, each seeing
162
+ * every instance, and produce duplicate channels from a single device.
163
+ * Same for its tools and prompts, which would collide with themselves.
164
+ *
165
+ * The instance-specific part is entirely `options`, and that is what the
166
+ * plugin reads through `axon.modules.all()`.
167
+ */
168
+ const alreadyScanned = opts.surfaces.some(surface => surface.name === name)
169
+
170
+ const meta = await readMeta(configPath)
171
+
172
+ const [prompts, scripts, tools, routes, plugins, middleware, knowledge] = await Promise.all([
173
+ // Every scanner degrades for a MODULE — see each scanner's `required`.
174
+ // The agent's own source (blueprint.ts) stays strict: it is what the
175
+ // author wrote, and running a subset of it is an agent nobody asked
176
+ // for. A module is a dependency, and a broken one must not cost the
177
+ // user the terminal they need in order to remove it.
178
+ Prompts(root, { required: false }),
179
+ Scripts(root, { required: false }),
180
+ Tools(root, { required: false }),
181
+ Routes(root, { required: false }),
182
+ Plugins(root, { required: false }),
183
+ // Degrades to a BLOCKER, not a skip — a guard that failed to load must
184
+ // never leave its routes unguarded. See scan/middleware.ts.
185
+ Middleware(root, { required: false }),
186
+ // Prefixed with the module's name so its material cannot shadow the
187
+ // agent's own — two corpora on the same subject is the normal case,
188
+ // and a silent shadow would advertise a file the model never gets.
189
+ Knowledge(root, { prefix: name, required: false }),
190
+ ])
191
+ const scanWarnings: string[] = []
192
+ for (const scanned of [prompts, scripts, tools, routes, plugins, middleware, knowledge]) {
193
+ // Tagged on the DOMAIN, not smuggled into the message: the message is
194
+ // the scanner's own sentence and a renderer showing a structured error
195
+ // beside it would otherwise print the module name twice.
196
+ opts.warnings.push(...scanned.warnings.map(w => ({ ...w, domain: `${w.domain}:${name}` })))
197
+ scanWarnings.push(...scanned.warnings.map(w => w.error))
198
+ }
199
+
200
+ /**
201
+ * What this module lost, as one sentence for the model.
202
+ *
203
+ * Collected here rather than derived later because this is the only place
204
+ * that knows WHICH module a warning came from — by the time they reach the
205
+ * blueprint's flat list, the association is a string prefix.
206
+ */
207
+ const degraded = scanWarnings.length > 0 ? scanWarnings.join("; ") : undefined
208
+
209
+ // Each tool file scanned inside a module stays its own AxonTool — same
210
+ // shape as an agent's own src/tools/*.ts, just re-tagged with this
211
+ // module's origin/modulePath. This is what keeps declaration (typegen,
212
+ // renderScope) and execution (toCapsuleTools, one real file per
213
+ // AxonTool.entryPath) in lockstep: one file in, one namespace out, no
214
+ // collapse step that execution then has to reconstruct or diverge from.
215
+ //
216
+ // KNOWN GAP (see debt.md): `flat` is inherited from Tools(), which sets it
217
+ // for an agent's own src/tools. A module's tools therefore install as
218
+ // top-level globals rather than under the module's name, contradicting the
219
+ // documented `github.*` prefixing. An agent tool and a module tool both
220
+ // exporting `openPr` currently produce two identical declarations in one
221
+ // `declare global` block, and the capsule's Object.assign over flat tools
222
+ // means whichever loads last silently wins. merge() cannot catch it: it
223
+ // dedupes on the TOOL name (the filename), while the collision is between
224
+ // the FUNCTION names inside them.
225
+ //
226
+ // Not simply cleared here: registry modules export one object named after
227
+ // the file (`export const prs = {...}`), which is written for flat
228
+ // placement — namespacing them without changing that convention yields
229
+ // `prs.prs.list()`. Fixing this properly means deciding the module tool
230
+ // namespace (module name vs filename) and migrating the registry with it.
231
+ const moduleTools: AxonTool[] = tools.entries.map(tool => ({
232
+ ...tool,
233
+ origin: "module",
234
+ modulePath: root,
235
+ }))
236
+
237
+ if (!alreadyScanned) {
238
+ opts.surfaces.push({
239
+ name,
240
+ prompts: prompts.entries,
241
+ knowledge: knowledge.entries,
242
+ scripts: scripts.entries,
243
+ tools: moduleTools,
244
+ routes: routes.entries,
245
+ plugins: plugins.entries,
246
+ middleware: middleware.entries,
247
+ })
248
+ }
249
+
250
+ // Registry identity, when the module ships a package.json. Uninstall and
251
+ // reinstall address a module by its package name — the short `name`
252
+ // above is for namespacing and cannot round-trip to the registry.
253
+ const pkg = await modulePackage(root)
254
+
255
+ opts.modules.push({
256
+ name,
257
+ ...(pkg.name ? { packageName: pkg.name } : {}),
258
+ ...(pkg.version ? { version: pkg.version } : {}),
259
+ root,
260
+ configPath,
261
+ automerge: meta.automerge ?? true,
262
+ env: meta.env,
263
+ optionsSchema: meta.optionsSchema,
264
+ prompts: prompts.entries,
265
+ scripts: scripts.entries,
266
+ tools: moduleTools,
267
+ ...(Object.keys(opts.options).length > 0 ? { options: opts.options } : {}),
268
+ ...(fsx.exists(join(root, "server")) ? { serverPath: join(root, "server") } : {}),
269
+ ...(fsx.exists(join(root, "server", "api")) ? { apiPath: join(root, "server", "api") } : {}),
270
+ ...(fsx.exists(join(root, "data", "knowledge")) ? { knowledgePath: join(root, "data", "knowledge") } : {}),
271
+ ...(degraded ? { degraded } : {}),
272
+ })
273
+ }
274
+
275
+ /** package.json name (short form) or directory basename. */
276
+ async function moduleName(root: string): Promise<string> {
277
+ const text = await fsx.readText(join(root, "package.json"))
278
+ if (text) {
279
+ const raw = (JSON.parse(text) as { name?: string }).name
280
+ if (raw) return raw.includes("/") ? raw.split("/").pop()! : raw
281
+ }
282
+ return basename(root)
283
+ }
284
+
285
+ /** A module's package.json identity — absent for a bare directory module. */
286
+ async function modulePackage(root: string): Promise<{ name?: string; version?: string }> {
287
+ const text = await fsx.readText(join(root, "package.json"))
288
+ if (!text) return {}
289
+ try {
290
+ const { name, version } = JSON.parse(text) as { name?: string; version?: string }
291
+ return { ...(name ? { name } : {}), ...(version ? { version } : {}) }
292
+ } catch {
293
+ // A malformed package.json is the module author's problem, surfaced
294
+ // by the scanners that actually need to read it — identity is
295
+ // optional metadata and must not fail the whole scan.
296
+ return {}
297
+ }
298
+ }
299
+
300
+
@@ -0,0 +1,174 @@
1
+ import type TsNamespace from "typescript"
2
+ import type { ModuleOptionSchema } from "@arcforge/types"
3
+ import { fsx } from "../../../utils/fs"
4
+
5
+ /**
6
+ * `typescript` is ~175ms of module evaluation, and this module is reached for
7
+ * every module a blueprint scans — so importing it eagerly meant an agent paid
8
+ * the compiler's load before knowing whether it had any modules at all.
9
+ *
10
+ * Bound on first use. The helpers below use `ts` as a value and `TsNamespace`
11
+ * for the node types they take, so the one gate in readMeta() serves all of
12
+ * them without changing a signature.
13
+ */
14
+ let ts!: typeof TsNamespace
15
+ let loading: Promise<void> | null = null
16
+ function loadTs(): Promise<void> {
17
+ loading ??= import("typescript").then(mod => { ts = mod.default })
18
+ return loading
19
+ }
20
+
21
+ /**
22
+ * Static metadata of one module.config.ts — automerge flag, env schema,
23
+ * options schema. AST only; module code is never executed at scan time.
24
+ */
25
+ export type ModuleMeta = {
26
+ /** null = not declared (defaults to true downstream). */
27
+ automerge: boolean | null
28
+ env: Record<string, { required: boolean; description?: string }>
29
+ optionsSchema: Record<string, ModuleOptionSchema>
30
+ }
31
+
32
+ export async function readMeta(configPath: string): Promise<ModuleMeta> {
33
+ const meta: ModuleMeta = { automerge: null, env: {}, optionsSchema: {} }
34
+
35
+ const content = await fsx.readText(configPath)
36
+ if (content === null) return meta
37
+
38
+ await loadTs()
39
+ const src = ts.createSourceFile(configPath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
40
+
41
+ function visit(node: TsNamespace.Node) {
42
+ if (
43
+ ts.isCallExpression(node) &&
44
+ ts.isIdentifier(node.expression) &&
45
+ node.expression.text === "defineModule" &&
46
+ node.arguments[0] &&
47
+ ts.isObjectLiteralExpression(node.arguments[0])
48
+ ) {
49
+ const arg = node.arguments[0]
50
+ meta.automerge = boolProp(arg, "automerge")
51
+
52
+ const envObj = objectProp(arg, "env")
53
+ if (envObj) meta.env = readEnvSchema(envObj)
54
+
55
+ const optionsObj = objectProp(arg, "options")
56
+ if (optionsObj) meta.optionsSchema = readOptionsSchema(optionsObj)
57
+ }
58
+ ts.forEachChild(node, visit)
59
+ }
60
+
61
+ ts.forEachChild(src, visit)
62
+ return meta
63
+ }
64
+
65
+ // ─── Object-literal readers ───────────────────────────────────────────────────
66
+
67
+ function propKey(prop: TsNamespace.ObjectLiteralElementLike): string | null {
68
+ if (!ts.isPropertyAssignment(prop)) return null
69
+ if (ts.isIdentifier(prop.name)) return prop.name.text
70
+ if (ts.isStringLiteral(prop.name)) return prop.name.text
71
+ return null
72
+ }
73
+
74
+ /**
75
+ * Strip `as const` / `as T` and parenthesised wrappers to reach the literal.
76
+ * The module authoring style writes `type: "boolean" as const`, so every
77
+ * reader below must see through the AsExpression or it reads the wrong shape
78
+ * (e.g. a boolean option's type silently falling back to "string").
79
+ */
80
+ function unwrap(node: TsNamespace.Expression): TsNamespace.Expression {
81
+ let current = node
82
+ while (ts.isAsExpression(current) || ts.isParenthesizedExpression(current) || ts.isSatisfiesExpression(current)) {
83
+ current = current.expression
84
+ }
85
+ return current
86
+ }
87
+
88
+ function boolProp(obj: TsNamespace.ObjectLiteralExpression, key: string): boolean | null {
89
+ for (const prop of obj.properties) {
90
+ if (propKey(prop) !== key || !ts.isPropertyAssignment(prop)) continue
91
+ const init = unwrap(prop.initializer)
92
+ if (init.kind === ts.SyntaxKind.TrueKeyword) return true
93
+ if (init.kind === ts.SyntaxKind.FalseKeyword) return false
94
+ }
95
+ return null
96
+ }
97
+
98
+ function stringProp(obj: TsNamespace.ObjectLiteralExpression, key: string): string | null {
99
+ for (const prop of obj.properties) {
100
+ if (propKey(prop) !== key || !ts.isPropertyAssignment(prop)) continue
101
+ const init = unwrap(prop.initializer)
102
+ if (ts.isStringLiteral(init)) return init.text
103
+ }
104
+ return null
105
+ }
106
+
107
+ function objectProp(obj: TsNamespace.ObjectLiteralExpression, key: string): TsNamespace.ObjectLiteralExpression | null {
108
+ for (const prop of obj.properties) {
109
+ if (propKey(prop) !== key || !ts.isPropertyAssignment(prop)) continue
110
+ if (ts.isObjectLiteralExpression(prop.initializer)) return prop.initializer
111
+ }
112
+ return null
113
+ }
114
+
115
+ function literalValue(nodeIn: TsNamespace.Expression): unknown {
116
+ const node = unwrap(nodeIn)
117
+ if (ts.isStringLiteral(node)) return node.text
118
+ if (ts.isNumericLiteral(node)) return Number(node.text)
119
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return true
120
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return false
121
+ return undefined
122
+ }
123
+
124
+ function readEnvSchema(envObj: TsNamespace.ObjectLiteralExpression): ModuleMeta["env"] {
125
+ const env: ModuleMeta["env"] = {}
126
+ for (const prop of envObj.properties) {
127
+ const key = propKey(prop)
128
+ if (!key || !ts.isPropertyAssignment(prop) || !ts.isObjectLiteralExpression(prop.initializer)) continue
129
+ const required = boolProp(prop.initializer, "required") ?? false
130
+ const description = stringProp(prop.initializer, "description")
131
+ env[key] = { required, ...(description !== null ? { description } : {}) }
132
+ }
133
+ return env
134
+ }
135
+
136
+ const VALID_OPTION_TYPES = new Set(["string", "number", "boolean"])
137
+
138
+ function readOptionsSchema(optionsObj: TsNamespace.ObjectLiteralExpression): Record<string, ModuleOptionSchema> {
139
+ const schema: Record<string, ModuleOptionSchema> = {}
140
+
141
+ for (const prop of optionsObj.properties) {
142
+ const key = propKey(prop)
143
+ if (!key || !ts.isPropertyAssignment(prop) || !ts.isObjectLiteralExpression(prop.initializer)) continue
144
+ const inner = prop.initializer
145
+
146
+ const rawType = stringProp(inner, "type") ?? "string"
147
+ const entry: ModuleOptionSchema = {
148
+ type: VALID_OPTION_TYPES.has(rawType) ? (rawType as "string" | "number" | "boolean") : "string",
149
+ }
150
+
151
+ const description = stringProp(inner, "description")
152
+ if (description !== null) entry.description = description
153
+
154
+ const required = boolProp(inner, "required")
155
+ if (required !== null) entry.required = required
156
+
157
+ for (const p of inner.properties) {
158
+ if (propKey(p) !== "default" || !ts.isPropertyAssignment(p)) continue
159
+ const value = literalValue(p.initializer)
160
+ if (value !== undefined) entry.default = value
161
+ }
162
+
163
+ for (const p of inner.properties) {
164
+ if (propKey(p) !== "enum" || !ts.isPropertyAssignment(p)) continue
165
+ if (!ts.isArrayLiteralExpression(p.initializer)) continue
166
+ const values = p.initializer.elements.map(literalValue).filter(v => v !== undefined)
167
+ if (values.length > 0) entry.enum = values
168
+ }
169
+
170
+ schema[key] = entry
171
+ }
172
+
173
+ return schema
174
+ }
@@ -0,0 +1,34 @@
1
+ import { join } from "node:path"
2
+ import { fsx } from "../../../utils/fs"
3
+ import type { ScanWarning } from "../types"
4
+
5
+ export type BootScan =
6
+ | { boot: string; warnings: ScanWarning[] } // static — pre-read, rendered as-is
7
+ | { bootFilePath: string; warnings: ScanWarning[] } // dynamic — the runtime renders this fresh, per tick
8
+ | { warnings: ScanWarning[] } // no boot file at all
9
+
10
+ /**
11
+ * Boot — the agent's base context: src/boot.md (static) or src/boot.vue
12
+ * (dynamic). Static content lands on blueprint.boot pre-read. Dynamic boot
13
+ * is a runtime concern — only the file path is noted here; the runtime
14
+ * renders it fresh with live axon access, on its own schedule.
15
+ */
16
+ export async function Boot(root: string): Promise<BootScan> {
17
+ const vuePath = join(root, "src", "boot.vue")
18
+ const mdPath = join(root, "src", "boot.md")
19
+
20
+ if (fsx.exists(vuePath)) {
21
+ return { bootFilePath: vuePath, warnings: [] }
22
+ }
23
+
24
+ if (fsx.exists(mdPath)) {
25
+ // Null here means the file vanished between the exists() check and the
26
+ // read — a race, not a state worth a warning. An unreadable file throws
27
+ // (FILE_UNREADABLE) rather than arriving as null.
28
+ const content = await fsx.readText(mdPath)
29
+ if (content === null) return { warnings: [] }
30
+ return { boot: content, warnings: [] }
31
+ }
32
+
33
+ return { warnings: [] }
34
+ }
@@ -0,0 +1,56 @@
1
+ import { dirname } from "node:path"
2
+ import {
3
+ collectDefaultImports,
4
+ findConfigProperty,
5
+ parseConfig,
6
+ resolveBinding,
7
+ type ResolvedDeclaration,
8
+ } from "./configImports"
9
+
10
+ /**
11
+ * Static resolution of a config file's `cognet:` declaration to the absolute
12
+ * `cognet.config.ts` path of a SOURCE cognet.
13
+ *
14
+ * The mirror of resolveModulePaths(), and deliberately so: "how do I point at
15
+ * local source" has one answer in this codebase, not two. An author writes
16
+ * either a registry string or an imported binding, and both mean the same
17
+ * thing they mean for a module.
18
+ *
19
+ * ```ts
20
+ * cognet: "@axon/zero" // registry
21
+ * cognet: Vehicle // source, from its import
22
+ * ```
23
+ *
24
+ * Singular, not an array — an agent has one brain — so this returns one
25
+ * result rather than a positional list, and there is no [entry, options]
26
+ * tuple form to unwrap.
27
+ *
28
+ * A config with no `cognet:` at all resolves to null, which prepare reads as
29
+ * "track the registry default", distinct from a declared-but-unresolvable
30
+ * entry that must fail loudly.
31
+ */
32
+
33
+ /** The config filenames a cognet import may point at. */
34
+ const COGNET_CONFIGS = ["cognet.config.ts", "cognet.config.js"] as const
35
+
36
+ /**
37
+ * Resolve the config's `cognet:` entry. Returns null when the field is
38
+ * absent — the agent declared no brain and inherits the default.
39
+ */
40
+ export async function resolveCognetPath(configFilePath: string): Promise<ResolvedDeclaration | null> {
41
+ const src = await parseConfig(configFilePath)
42
+ if (!src) return null
43
+
44
+ const cognetProperty = findConfigProperty(src, "cognet")
45
+ if (!cognetProperty) return null
46
+
47
+ return resolveBinding({
48
+ element: cognetProperty,
49
+ imports: collectDefaultImports(src),
50
+ configDir: dirname(configFilePath),
51
+ configFilePath,
52
+ configNames: COGNET_CONFIGS,
53
+ factory: "defineCognet",
54
+ label: "cognet",
55
+ })
56
+ }
@@ -0,0 +1,45 @@
1
+ import { join } from "node:path"
2
+ import { fsx } from "../../../utils/fs"
3
+ import type { Scanned } from "../types"
4
+
5
+ export type PromptComponent = {
6
+ /** PascalCase name used in templates, e.g. "ScoutingBasics". */
7
+ name: string
8
+ /** Absolute path to the .vue file. */
9
+ filePath: string
10
+ }
11
+
12
+ /**
13
+ * Components — prompt components of ONE root, flat by convention. Not part
14
+ * of the blueprint object: consumed by typegen and by prompt rendering.
15
+ * Cross-root precedence (agent over module) is the caller's merge, same as
16
+ * every other surface.
17
+ *
18
+ * Two layouts, one walker. An agent or module keeps components under
19
+ * src/prompts/components/; a prompt PACKAGE is the folder itself, so its
20
+ * components sit at components/ off the root. `dir` is how the flat layout
21
+ * reuses this rather than duplicating it — the same seam Prompts() already
22
+ * has, and for the same reason.
23
+ */
24
+ export async function Components(root: string, opts?: { dir?: string }): Promise<Scanned<PromptComponent>> {
25
+ const dir = opts?.dir ? join(root, opts.dir) : join(root, "src", "prompts", "components")
26
+ const entries: PromptComponent[] = []
27
+
28
+ for (const file of await fsx.list(dir)) {
29
+ if (!file.endsWith(".vue")) continue
30
+ entries.push({
31
+ name: pascalCase(file.replace(/\.vue$/, "")),
32
+ filePath: join(dir, file),
33
+ })
34
+ }
35
+
36
+ return { entries, warnings: [] }
37
+ }
38
+
39
+ /** "scouting-basics" → "ScoutingBasics" */
40
+ function pascalCase(name: string): string {
41
+ return name
42
+ .split("-")
43
+ .map(s => s.charAt(0).toUpperCase() + s.slice(1))
44
+ .join("")
45
+ }