@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,329 @@
1
+ import { readdir, readFile } from "node:fs/promises"
2
+ import { join, relative, sep } from "node:path"
3
+
4
+ /**
5
+ * Files — the working tree under one root, as a searchable list of paths.
6
+ *
7
+ * Owns exactly one sentence: list the paths under `root` that a person might
8
+ * want to reference. It is the source behind the TUI's `@` palette and knows
9
+ * nothing about palettes, modes or drafts.
10
+ *
11
+ * Two decisions shape it:
12
+ *
13
+ * **The tree is indexed once, not walked per keystroke.** A palette filters on
14
+ * every character; a recursive readdir per character over a real repo is not
15
+ * something a 100ms render budget survives. One walk produces a flat list and
16
+ * every subsequent query is an in-memory filter — the same reasoning as the
17
+ * registry catalogue, for the same reason.
18
+ *
19
+ * **Staleness is resolved explicitly, never on a timer.** The index is walked
20
+ * once and held until someone calls `invalidate()`. Not an fs.watch, which
21
+ * costs descriptors over a large tree for the entire session to serve a list
22
+ * the user opens occasionally; and not a TTL, because the consumer calls
23
+ * `ensure()` from inside a reactive computed — anything that can spontaneously
24
+ * decide to re-walk turns that into a render loop. A path created seconds ago
25
+ * and missing from the list is recoverable (the user types it); a pegged core
26
+ * is not.
27
+ */
28
+ export function Files(opts: FilesOpts) {
29
+ const root = opts.root
30
+ const maxEntries = opts.maxEntries ?? 200_000
31
+ const maxDepth = opts.maxDepth ?? 12
32
+
33
+ let index: FileEntry[] | null = null
34
+ let truncated = false
35
+ // The in-flight walk, so N keystrokes arriving before the first resolves
36
+ // share one traversal instead of starting N of them.
37
+ let walking: Promise<FileEntry[]> | null = null
38
+
39
+ /**
40
+ * NOT `async`. The in-flight promise has to be published SYNCHRONOUSLY, in
41
+ * the same tick as the check that found none — an `async` body suspends at
42
+ * its first `await` (reading .gitignore) with `walking` still null, and
43
+ * every caller arriving in that window starts a walk of its own. On the
44
+ * TUI's path those callers are consecutive renders, so the "shared" walk
45
+ * became one full traversal per keystroke.
46
+ */
47
+ function ensure(): Promise<FileEntry[]> {
48
+ if (index !== null) return Promise.resolve(index)
49
+ if (walking) return walking
50
+
51
+ walking = ignoresFor(root)
52
+ .then(ignore => walk(root, ignore, maxEntries, maxDepth))
53
+ .then(result => {
54
+ index = result.entries
55
+ truncated = result.truncated
56
+ return result.entries
57
+ })
58
+ .finally(() => {
59
+ walking = null
60
+ })
61
+
62
+ return walking
63
+ }
64
+
65
+ return {
66
+ /** The root every entry's path is relative to. */
67
+ root: root,
68
+
69
+ /**
70
+ * True when the last walk stopped at `maxEntries` or `maxDepth` and the
71
+ * index is therefore INCOMPLETE. Exposed because a truncated list is
72
+ * indistinguishable from a complete one by inspection, and a consumer
73
+ * showing "no matches" over a partial index would be stating something
74
+ * it does not know.
75
+ */
76
+ get truncated(): boolean { return truncated },
77
+
78
+ /**
79
+ * Every indexed entry, walking the tree on first call. Callers filter
80
+ * it themselves — matching is a UI concern (the TUI ranks with its own
81
+ * chunk matcher) and baking one strategy in here would force every
82
+ * consumer to accept it.
83
+ */
84
+ list: ensure,
85
+
86
+ /**
87
+ * The immediate children of one directory, relative to root ("" is the
88
+ * root itself). Served off the same index — browsing and searching are
89
+ * two views of one walk, not two mechanisms.
90
+ */
91
+ async children(dir: string): Promise<FileEntry[]> {
92
+ const entries = await ensure()
93
+ const prefix = dir === "" ? "" : dir.endsWith("/") ? dir : `${dir}/`
94
+ return entries.filter(entry => {
95
+ if (!entry.path.startsWith(prefix)) return false
96
+ const rest = entry.path.slice(prefix.length)
97
+ return rest.length > 0 && !rest.includes("/")
98
+ })
99
+ },
100
+
101
+ /** Drop the index so the next call re-walks — after a checkout, a scaffold, a clone. */
102
+ invalidate(): void {
103
+ index = null
104
+ truncated = false
105
+ },
106
+ }
107
+ }
108
+
109
+ export type FilesT = ReturnType<typeof Files>
110
+
111
+ export type FilesOpts = {
112
+ /** The directory every path is listed relative to. */
113
+ root: string
114
+ /**
115
+ * Hard cap on indexed entries — a guard against a root that turns out to be
116
+ * `/` or a home directory, where an unbounded walk would hang the caller
117
+ * with no way to tell it apart from a slow disk.
118
+ *
119
+ * Set high enough that a real project never reaches it: hitting the cap
120
+ * means paths are MISSING from the list, and a palette that silently omits
121
+ * the file you are searching for is worse than one that takes another
122
+ * hundred milliseconds. This repo (29G, ~54k tracked entries) indexes in
123
+ * ~300ms — the cap is for pathological roots, not large ones. When it does
124
+ * bite, `truncated` says so rather than leaving the caller to guess.
125
+ */
126
+ maxEntries?: number
127
+ /**
128
+ * How deep the walk descends. Bounds the walk by SHAPE where `maxEntries`
129
+ * bounds it by output — the two are not substitutes, since a level's queue
130
+ * is built in full before the entry cap is next consulted.
131
+ */
132
+ maxDepth?: number
133
+ }
134
+
135
+ export type FileEntry = {
136
+ /** Path relative to the root, POSIX-separated — what a user types and what an agent receives. */
137
+ path: string
138
+ /** The final segment, for matching a name without its directories. */
139
+ name: string
140
+ /** Directories are listed too: they are navigable, and referencing one is meaningful. */
141
+ directory: boolean
142
+ }
143
+
144
+ /**
145
+ * Always skipped, regardless of what .gitignore says.
146
+ *
147
+ * Two classes, one rule: directories holding code nobody wrote here and nobody
148
+ * references by hand. `.git` is machine state; the rest are dependency trees
149
+ * that dominate both the walk and every result list while being the last thing
150
+ * a person means by `@`.
151
+ *
152
+ * Skipped unconditionally rather than left to .gitignore because they are
153
+ * frequently NOT ignored — a vendored `.venv` in this repo contributed 29k of
154
+ * 83k entries and every one of the deepest paths in the tree. Relying on the
155
+ * ignore file to catch them means the walk's cost depends on someone else's
156
+ * hygiene.
157
+ */
158
+ const ALWAYS_SKIP = new Set([
159
+ ".git",
160
+ "node_modules",
161
+ // Python: virtualenvs (both conventional names) and bytecode caches.
162
+ ".venv",
163
+ "venv",
164
+ "__pycache__",
165
+ // Rust, Go, Java/Kotlin — build and dependency output.
166
+ "target",
167
+ "vendor",
168
+ ".gradle",
169
+ ])
170
+
171
+ /**
172
+ * The root's own ignore rules, read once per walk.
173
+ *
174
+ * Deliberately a SUBSET of gitignore syntax. Three forms are honoured, and they
175
+ * are the ones that actually do the work of keeping a walk small:
176
+ *
177
+ * dist a bare name, ignored at any depth
178
+ * **&#47;dist the same thing written explicitly — the DOMINANT idiom
179
+ * /apps/x/dist anchored to the root
180
+ *
181
+ * `**&#47;name` is stripped to a bare name rather than discarded. Treating it as an
182
+ * unsupported "glob" is what made this useless on a real repo: 48 of the 49
183
+ * patterns in this one are written that way, so discarding them meant walking
184
+ * every `dist`, `.output` and `target` in a 29G tree — the whole cost the
185
+ * ignore file existed to avoid.
186
+ *
187
+ * Patterns with an INTERIOR wildcard (`*.log`, `build-*`) are still skipped:
188
+ * matching those needs real glob semantics, and the cost of missing one is a
189
+ * palette row, not a hung walk. Negations (`!`) and nested per-directory ignore
190
+ * files are also unsupported. If this ever needs to be exact, take a
191
+ * dependency — do not grow this function.
192
+ */
193
+ async function ignoresFor(root: string): Promise<Ignore> {
194
+ const names = new Set<string>()
195
+ const anchored = new Set<string>()
196
+
197
+ let text: string
198
+ try {
199
+ text = await readFile(join(root, ".gitignore"), "utf8")
200
+ } catch {
201
+ // No .gitignore is the normal case for most directories, not a failure.
202
+ // Any other read error (permissions) means the same thing here: walk
203
+ // with the built-in skips alone. Nothing downstream is wrong without it.
204
+ return { names, anchored }
205
+ }
206
+
207
+ for (const raw of text.split("\n")) {
208
+ const line = raw.trim()
209
+ if (!line || line.startsWith("#") || line.startsWith("!")) continue
210
+
211
+ // Strip a trailing "/**" ("node_modules/**") and a trailing slash
212
+ // ("dist/") — both mean the directory itself.
213
+ let pattern = line.replace(/\/\*\*$/, "").replace(/\/$/, "")
214
+ // A leading "**/" means "at any depth", which is precisely what a bare
215
+ // name already means here.
216
+ const anyDepth = pattern.startsWith("**/")
217
+ if (anyDepth) pattern = pattern.slice(3)
218
+
219
+ if (!pattern) continue
220
+ if (pattern.includes("*") || pattern.includes("?")) continue // interior wildcards need real globbing
221
+
222
+ if (!anyDepth && pattern.includes("/")) anchored.add(pattern.replace(/^\//, ""))
223
+ else names.add(pattern)
224
+ }
225
+
226
+ return { names, anchored }
227
+ }
228
+
229
+ type Ignore = {
230
+ /** Bare names ignored at any depth ("dist", ".env"). */
231
+ names: Set<string>
232
+ /** Root-relative paths ("apps/foo/dist"). */
233
+ anchored: Set<string>
234
+ }
235
+
236
+ /**
237
+ * Breadth-first so the cap, when it bites, keeps the shallow paths — the ones
238
+ * a person is most likely to be reaching for. A depth-first walk that hit the
239
+ * limit would return one deep branch and nothing else.
240
+ *
241
+ * Two properties this walk must have, both learned the hard way:
242
+ *
243
+ * **It yields.** A tree this size is tens of thousands of `readdir` calls, and
244
+ * awaiting them in one uninterrupted chain starves the caller's event loop —
245
+ * in the TUI that means the render loop stops and the whole terminal appears
246
+ * hung behind a "reading working tree..." row. Handing control back every
247
+ * YIELD_EVERY directories keeps the app responsive while it indexes.
248
+ *
249
+ * **It is depth-capped.** `maxEntries` alone is not a bound on TIME: the queue
250
+ * for one level is built before the cap is next checked, so a pathological tree
251
+ * can do enormous work between checks. A depth limit bounds the walk by shape
252
+ * rather than by output, and nothing a person references by hand lives 12
253
+ * directories down.
254
+ */
255
+ async function walk(root: string, ignore: Ignore, maxEntries: number, maxDepth: number): Promise<WalkResult> {
256
+ const out: FileEntry[] = []
257
+ let queue: string[] = [""]
258
+ let depth = 0
259
+ let sinceYield = 0
260
+
261
+ while (queue.length > 0 && out.length < maxEntries && depth <= maxDepth) {
262
+ const next: string[] = []
263
+
264
+ for (const dir of queue) {
265
+ if (out.length >= maxEntries) break
266
+
267
+ // Give the event loop a turn. setTimeout rather than a resolved
268
+ // promise: a microtask yield still blocks rendering, because the
269
+ // whole microtask queue drains before the loop moves on.
270
+ if (++sinceYield >= YIELD_EVERY) {
271
+ sinceYield = 0
272
+ await new Promise(resolve => setTimeout(resolve, 0))
273
+ }
274
+
275
+ let dirents
276
+ try {
277
+ dirents = await readdir(join(root, dir), { withFileTypes: true })
278
+ } catch {
279
+ // Unreadable directory (permissions, a symlink to nowhere, a
280
+ // race with something deleting it mid-walk). Skipping it is
281
+ // correct and local: the rest of the tree is still listable,
282
+ // and failing the whole walk over one directory would make the
283
+ // palette unusable because of a directory nobody asked about.
284
+ continue
285
+ }
286
+
287
+ for (const dirent of dirents) {
288
+ if (out.length >= maxEntries) break
289
+ if (ALWAYS_SKIP.has(dirent.name)) continue
290
+ if (ignore.names.has(dirent.name)) continue
291
+
292
+ const path = dir === "" ? dirent.name : `${dir}/${dirent.name}`
293
+ if (ignore.anchored.has(path)) continue
294
+
295
+ // A symlinked directory is not descended: a link pointing at an
296
+ // ancestor makes the walk non-terminating, and there is no
297
+ // cheap way to tell that case from a benign one. The link
298
+ // itself is still listed, so it remains referenceable.
299
+ const directory = dirent.isDirectory()
300
+ out.push({ path: path, name: dirent.name, directory: directory })
301
+ if (directory && dirent.isSymbolicLink() === false) next.push(path)
302
+ }
303
+ }
304
+
305
+ queue = next
306
+ depth++
307
+ }
308
+
309
+ // Either bound stopping the walk with work left means the index is partial:
310
+ // the entry cap bit, or a level remained unvisited when the depth cap did.
311
+ return {
312
+ entries: out,
313
+ truncated: out.length >= maxEntries || queue.length > 0,
314
+ }
315
+ }
316
+
317
+ type WalkResult = {
318
+ entries: FileEntry[]
319
+ /** The walk stopped at a bound rather than at the end of the tree. */
320
+ truncated: boolean
321
+ }
322
+
323
+ /** Directories read between event-loop yields. Small enough to stay responsive, large enough not to pay a timer per directory. */
324
+ const YIELD_EVERY = 50
325
+
326
+ /** Normalize an absolute path under `root` to the relative, POSIX form used by entries. */
327
+ export function toEntryPath(root: string, absolute: string): string {
328
+ return relative(root, absolute).split(sep).join("/")
329
+ }
@@ -0,0 +1,5 @@
1
+ export * from "./cloud"
2
+ export * from "./deployments"
3
+ export * from "./mic"
4
+ export * from "./ollama"
5
+ export * from "./registry"
@@ -0,0 +1,248 @@
1
+ /**
2
+ * capture — owns the audio capture child process and the raw PCM byte
3
+ * stream. Two consumers of the same bytes: the full accumulated recording
4
+ * (for STT, wrapped as a real WAV file on stop) and a rolling window of
5
+ * the most recent samples (for the FFT tick to read from).
6
+ *
7
+ * Detects whichever capture tool is ALREADY on the machine — arecord
8
+ * (ships with ALSA, essentially always present on Linux), sox, or ffmpeg
9
+ * — and uses the first one found. This never installs anything itself:
10
+ * shelling `sudo apt-get install` from inside a running TUI means a
11
+ * password prompt fighting VTerm's own raw terminal mode for control,
12
+ * which is both a bad user-trust story and, in practice, garbles the
13
+ * screen. If none of the three exist, this fails loudly with a clear
14
+ * "install one of these" message — the same honest failure mode, just
15
+ * without ever mutating the user's system on their behalf.
16
+ */
17
+ import { err } from "@arcforge/err"
18
+
19
+ type CaptureBackend = "arecord" | "sox" | "ffmpeg"
20
+
21
+ export type CaptureOpts = {
22
+ sampleRate: number
23
+ /** Rolling window length in samples — must cover at least one FFT frame. */
24
+ windowSamples: number
25
+ }
26
+
27
+ /** Priority order per platform — first one found on $PATH wins. Windows has no reliable always-present CLI capture tool, so sox/ffmpeg only. */
28
+ function detectBackend(): CaptureBackend | null {
29
+ const candidates: CaptureBackend[] =
30
+ process.platform === "darwin" ? ["sox", "ffmpeg"]
31
+ : process.platform === "win32" ? ["sox", "ffmpeg"]
32
+ : ["arecord", "sox", "ffmpeg"] // linux and other unix
33
+
34
+ for (const cmd of candidates) {
35
+ if (Bun.which(cmd)) return cmd
36
+ }
37
+ return null
38
+ }
39
+
40
+ /** Spawn args per backend — all produce raw signed 16-bit LE PCM, mono, at opts.sampleRate, on stdout. */
41
+ function buildArgs(backend: CaptureBackend, sampleRate: number): string[] {
42
+ const rate = String(sampleRate)
43
+
44
+ if (backend === "arecord") {
45
+ return ["-t", "raw", "-f", "S16_LE", "-r", rate, "-c", "1", "-"]
46
+ }
47
+
48
+ if (backend === "sox") {
49
+ if (process.platform === "darwin") {
50
+ return ["-d", "-r", rate, "-c", "1", "-e", "signed-integer", "-b", "16", "-t", "raw", "-"]
51
+ }
52
+ if (process.platform === "win32") {
53
+ return ["-d", "-r", rate, "-c", "1", "-e", "signed-integer", "-b", "16", "-t", "raw", "-"]
54
+ }
55
+ return ["-t", "alsa", "default", "-r", rate, "-c", "1", "-e", "signed-integer", "-b", "16", "-t", "raw", "-"]
56
+ }
57
+
58
+ // ffmpeg
59
+ if (process.platform === "darwin") {
60
+ return ["-f", "avfoundation", "-i", ":0", "-ac", "1", "-ar", rate, "-f", "s16le", "-"]
61
+ }
62
+ if (process.platform === "win32") {
63
+ return ["-f", "dshow", "-i", "audio=default", "-ac", "1", "-ar", rate, "-f", "s16le", "-"]
64
+ }
65
+ return ["-f", "alsa", "-i", "default", "-ac", "1", "-ar", rate, "-f", "s16le", "-"]
66
+ }
67
+
68
+ export function Capture(opts: CaptureOpts) {
69
+ let proc: ReturnType<typeof Bun.spawn> | null = null
70
+ /**
71
+ * Typed by what is consumed, not by whose ReadableStream this is.
72
+ *
73
+ * Bun's global `ReadableStreamDefaultReader` carries `readMany`; the one
74
+ * from `stream/web` (which `Bun.spawn().stdout` is typed as under the
75
+ * extension's tsconfig) does not. Naming either concrete type makes the
76
+ * assignment a compile error under the other, and the previous `as` cast
77
+ * only moved which side failed. Only `read` and `cancel` are ever called,
78
+ * and both types satisfy this — so it is the honest contract.
79
+ */
80
+ let stdoutReader: {
81
+ read(): Promise<{ value?: Uint8Array; done: boolean }>
82
+ cancel(): Promise<unknown>
83
+ } | null = null
84
+ let pumping = false
85
+
86
+ // Full recording — every byte captured this session, for the STT blob.
87
+ const chunks: Uint8Array[] = []
88
+
89
+ // Rolling window — most recent windowSamples worth of samples (16-bit PCM = 2 bytes/sample), for FFT.
90
+ const windowBytes = opts.windowSamples * 2
91
+ let ring = new Uint8Array(windowBytes)
92
+ let ringFilled = 0
93
+
94
+ function pushToRing(chunk: Uint8Array): void {
95
+ if (chunk.length >= windowBytes) {
96
+ ring.set(chunk.subarray(chunk.length - windowBytes))
97
+ ringFilled = windowBytes
98
+ return
99
+ }
100
+ // Shift left, append new bytes at the end.
101
+ ring.copyWithin(0, chunk.length)
102
+ ring.set(chunk, windowBytes - chunk.length)
103
+ ringFilled = Math.min(windowBytes, ringFilled + chunk.length)
104
+ }
105
+
106
+ async function pump(): Promise<void> {
107
+ if (!stdoutReader) return
108
+ pumping = true
109
+ try {
110
+ while (pumping) {
111
+ const { value, done } = await stdoutReader.read()
112
+ if (done) break
113
+ if (value) {
114
+ chunks.push(value)
115
+ pushToRing(value)
116
+ }
117
+ }
118
+ } catch {
119
+ // Reader errors on kill()/stream close — expected during stop(), not a real failure.
120
+ }
121
+ }
122
+
123
+ return {
124
+ async start(): Promise<void> {
125
+ if (proc) throw err("MIC_ALREADY_CAPTURING")
126
+
127
+ const backend = detectBackend()
128
+ if (!backend) {
129
+ throw err("MIC_CAPTURE_UNAVAILABLE")
130
+ }
131
+
132
+ proc = Bun.spawn(
133
+ [backend, ...buildArgs(backend, opts.sampleRate)],
134
+ // stdin must never inherit the real TTY — VTerm has it in raw
135
+ // mode with mouse tracking enabled, and Bun.spawn defaults
136
+ // stdin to "inherit" when unset. Without this, the capture
137
+ // process ends up sharing the terminal's input stream, and
138
+ // mouse-tracking escape sequences get garbled onto the screen.
139
+ { stdin: "ignore", stdout: "pipe", stderr: "pipe" }
140
+ )
141
+
142
+ // `Bun.spawn().stdout` is `number | ReadableStream` — a raw fd when
143
+ // stdout is inherited/piped to a file, a stream under `"pipe"`.
144
+ // We pass `"pipe"` above, so a stream is what must come back;
145
+ // testing for the capability narrows the union AND catches the
146
+ // case where it did not, which the previous falsy check missed
147
+ // (an fd of 3 is truthy and has no getReader).
148
+ const stdout = proc.stdout
149
+ if (typeof stdout !== "object" || stdout === null || !("getReader" in stdout)) {
150
+ proc.kill()
151
+ proc = null
152
+ throw err("MIC_CAPTURE_FAILED", { detail: `${backend} produced no stdout stream`, context: { backend } })
153
+ }
154
+
155
+ stdoutReader = stdout.getReader()
156
+ void pump()
157
+
158
+ // The backend prints a startup banner then blocks capturing — a
159
+ // fast, cheap exit (e.g. no device available) surfaces as the
160
+ // process exiting before this resolves. Give it a moment to
161
+ // prove it's actually running.
162
+ const exitedEarly = await Promise.race([
163
+ proc.exited.then(() => true),
164
+ new Promise<false>(resolve => setTimeout(() => resolve(false), 200)),
165
+ ])
166
+ if (exitedEarly) {
167
+ const code = await proc.exited
168
+ proc = null
169
+ throw err("MIC_CAPTURE_FAILED", { detail: `${backend} exited immediately (code ${code}) — is a microphone available?`, context: { backend, exitCode: code } })
170
+ }
171
+ },
172
+
173
+ /** Latest window of samples as Float32 in [-1, 1], most recent last. Empty if not enough audio captured yet. */
174
+ currentWindow(): Float32Array {
175
+ const out = new Float32Array(opts.windowSamples)
176
+ if (ringFilled < windowBytes) return out // not full yet — caller treats as silence
177
+
178
+ const view = new DataView(ring.buffer, ring.byteOffset, ring.byteLength)
179
+ for (let i = 0; i < opts.windowSamples; i++) {
180
+ out[i] = view.getInt16(i * 2, true) / 32768
181
+ }
182
+ return out
183
+ },
184
+
185
+ isCapturing(): boolean {
186
+ return proc !== null
187
+ },
188
+
189
+ /** Stops capture and returns the full recording as a playable WAV blob. */
190
+ async stop(): Promise<Blob> {
191
+ pumping = false
192
+ if (proc) {
193
+ proc.kill()
194
+ await proc.exited.catch(() => {})
195
+ }
196
+ await stdoutReader?.cancel().catch(() => {})
197
+ proc = null
198
+ stdoutReader = null
199
+
200
+ const pcm = concatChunks(chunks)
201
+ chunks.length = 0
202
+ ring = new Uint8Array(windowBytes)
203
+ ringFilled = 0
204
+
205
+ return wrapWav(pcm, opts.sampleRate)
206
+ },
207
+ }
208
+ }
209
+
210
+ export type CaptureT = ReturnType<typeof Capture>
211
+
212
+ function concatChunks(chunks: Uint8Array[]): Uint8Array {
213
+ const total = chunks.reduce((sum, c) => sum + c.length, 0)
214
+ const out = new Uint8Array(total)
215
+ let offset = 0
216
+ for (const chunk of chunks) {
217
+ out.set(chunk, offset)
218
+ offset += chunk.length
219
+ }
220
+ return out
221
+ }
222
+
223
+ /** Wraps raw 16-bit mono PCM in a standard WAV header — the STT endpoint expects a real audio file, not a bare byte stream. */
224
+ function wrapWav(pcm: Uint8Array, sampleRate: number): Blob {
225
+ const header = new ArrayBuffer(44)
226
+ const view = new DataView(header)
227
+ const dataSize = pcm.length
228
+
229
+ function writeString(offset: number, str: string) {
230
+ for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i))
231
+ }
232
+
233
+ writeString(0, "RIFF")
234
+ view.setUint32(4, 36 + dataSize, true)
235
+ writeString(8, "WAVE")
236
+ writeString(12, "fmt ")
237
+ view.setUint32(16, 16, true) // fmt chunk size
238
+ view.setUint16(20, 1, true) // PCM
239
+ view.setUint16(22, 1, true) // mono
240
+ view.setUint32(24, sampleRate, true)
241
+ view.setUint32(28, sampleRate * 2, true) // byte rate (16-bit mono)
242
+ view.setUint16(32, 2, true) // block align
243
+ view.setUint16(34, 16, true) // bits per sample
244
+ writeString(36, "data")
245
+ view.setUint32(40, dataSize, true)
246
+
247
+ return new Blob([header, pcm.slice().buffer], { type: "audio/wav" })
248
+ }