@picassohq/cli 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (230) hide show
  1. package/agents/browser_agent.yaml +53 -0
  2. package/agents/code_reviewer.yaml +49 -0
  3. package/agents/codebase_investigator.yaml +70 -0
  4. package/agents/design_auditor.yaml +50 -0
  5. package/agents/devex_auditor.yaml +50 -0
  6. package/agents/doc_writer.yaml +54 -0
  7. package/agents/engineering_architect.yaml +51 -0
  8. package/agents/generalist.yaml +55 -0
  9. package/agents/migration_planner.yaml +51 -0
  10. package/agents/product_reviewer.yaml +48 -0
  11. package/agents/qa_operator.yaml +52 -0
  12. package/agents/release_engineer.yaml +50 -0
  13. package/agents/security_auditor.yaml +62 -0
  14. package/agents/test_writer.yaml +52 -0
  15. package/assets/first-light-lockup.png +0 -0
  16. package/assets/first-light-tagline.png +0 -0
  17. package/assets/house/README.md +26 -0
  18. package/assets/house/auraone-banner.png +0 -0
  19. package/assets/house/auraone-logo.png +0 -0
  20. package/assets/house/kiro-prism-banner.png +0 -0
  21. package/assets/house/kiro-prism-logo.png +0 -0
  22. package/assets/house/picasso-banner.png +0 -0
  23. package/assets/house/picasso-logo.png +0 -0
  24. package/assets/wordmark-app.png +0 -0
  25. package/assets/wordmark-tight.png +0 -0
  26. package/assets/wordmark.png +0 -0
  27. package/design/styles.css +1042 -0
  28. package/dist/build-info.json +37 -0
  29. package/dist/index.js +3028 -0
  30. package/goals/cli-hardening.yaml +40 -0
  31. package/goals/repo-maintenance.yaml +40 -0
  32. package/package.json +49 -4
  33. package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
  34. package/runtime/dsh/picasso-ecosystem.community.json +185 -0
  35. package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
  36. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
  37. package/runtime/dsh/picasso-isolation.patch.yml +25 -0
  38. package/runtime/dsh/picasso-providers.patch.yml +373 -0
  39. package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
  40. package/runtime/dsh/picasso-sdk.patch.yml +204 -0
  41. package/runtime/engine-manifest.json +214 -0
  42. package/runtime/package.json +6 -0
  43. package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
  44. package/runtime/packages/picasso-cache-probe/index.js +477 -0
  45. package/runtime/packages/picasso-cache-probe/package.json +38 -0
  46. package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
  47. package/runtime/packages/picasso-commands/fresh-review.js +573 -0
  48. package/runtime/packages/picasso-commands/index.js +497 -0
  49. package/runtime/packages/picasso-commands/package.json +28 -0
  50. package/runtime/packages/picasso-instructions/conflicts.js +115 -0
  51. package/runtime/packages/picasso-instructions/formats.js +145 -0
  52. package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
  53. package/runtime/packages/picasso-instructions/glob.js +114 -0
  54. package/runtime/packages/picasso-instructions/globals.js +90 -0
  55. package/runtime/packages/picasso-instructions/imports.js +123 -0
  56. package/runtime/packages/picasso-instructions/index.js +326 -0
  57. package/runtime/packages/picasso-instructions/modes.js +64 -0
  58. package/runtime/packages/picasso-instructions/package.json +30 -0
  59. package/runtime/packages/picasso-instructions/parse.js +134 -0
  60. package/runtime/packages/picasso-instructions/report.js +161 -0
  61. package/runtime/packages/picasso-instructions/resolve.js +939 -0
  62. package/runtime/packages/picasso-instructions/scan.js +181 -0
  63. package/runtime/packages/picasso-instructions/settings.js +150 -0
  64. package/runtime/packages/picasso-instructions/skills.js +345 -0
  65. package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
  66. package/runtime/packages/picasso-lean-context/index.js +6049 -0
  67. package/runtime/packages/picasso-lean-context/package.json +26 -0
  68. package/runtime/packages/picasso-lean-context/timeline.js +417 -0
  69. package/runtime/packages/picasso-librarian/classify.js +146 -0
  70. package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
  71. package/runtime/packages/picasso-librarian/index.js +878 -0
  72. package/runtime/packages/picasso-librarian/notes.js +159 -0
  73. package/runtime/packages/picasso-librarian/package.json +34 -0
  74. package/runtime/packages/picasso-librarian/state.js +478 -0
  75. package/runtime/packages/picasso-memory/index.js +1184 -0
  76. package/runtime/packages/picasso-memory/package.json +21 -0
  77. package/runtime/packages/picasso-model-router/connections.js +895 -0
  78. package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
  79. package/runtime/packages/picasso-model-router/index.js +1081 -0
  80. package/runtime/packages/picasso-model-router/package.json +30 -0
  81. package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
  82. package/runtime/packages/picasso-options/index.js +263 -0
  83. package/runtime/packages/picasso-options/package.json +28 -0
  84. package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
  85. package/runtime/packages/picasso-progress-reports/index.js +267 -0
  86. package/runtime/packages/picasso-progress-reports/package.json +30 -0
  87. package/runtime/packages/picasso-progress-reports/report.js +235 -0
  88. package/runtime/packages/picasso-sdk-server/aside.js +128 -0
  89. package/runtime/packages/picasso-sdk-server/connections.js +38 -0
  90. package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
  91. package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
  92. package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
  93. package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
  94. package/runtime/packages/picasso-sdk-server/goal.js +131 -0
  95. package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
  96. package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
  97. package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
  98. package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
  99. package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
  100. package/runtime/packages/picasso-sdk-server/index.js +886 -0
  101. package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
  102. package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
  103. package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
  104. package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
  105. package/runtime/packages/picasso-sdk-server/package.json +50 -0
  106. package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
  107. package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
  108. package/runtime/packages/picasso-sdk-server/queue.js +322 -0
  109. package/runtime/packages/picasso-sdk-server/requester.js +43 -0
  110. package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
  111. package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
  112. package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
  113. package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
  114. package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
  115. package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
  116. package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
  117. package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
  118. package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
  119. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
  120. package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
  121. package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
  122. package/runtime/packages/picasso-web-search/backends.js +350 -0
  123. package/runtime/packages/picasso-web-search/config.js +121 -0
  124. package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
  125. package/runtime/packages/picasso-web-search/failure.js +111 -0
  126. package/runtime/packages/picasso-web-search/format.js +35 -0
  127. package/runtime/packages/picasso-web-search/index.js +66 -0
  128. package/runtime/packages/picasso-web-search/package.json +38 -0
  129. package/runtime/packages/picasso-web-search/router.js +155 -0
  130. package/runtime/packages/picasso-x-reader/circle.js +324 -0
  131. package/runtime/packages/picasso-x-reader/command.js +169 -0
  132. package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
  133. package/runtime/packages/picasso-x-reader/index.js +170 -0
  134. package/runtime/packages/picasso-x-reader/package.json +39 -0
  135. package/runtime/packages/picasso-x-reader/read.js +370 -0
  136. package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
  137. package/runtime/packages/picasso-x-reader/settings.js +131 -0
  138. package/runtime/packages/picasso-x-reader/urls.js +154 -0
  139. package/runtime/packages/picasso-x-reader/xmd.js +512 -0
  140. package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
  141. package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
  142. package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
  143. package/runtime/plugins/picasso-auto-approve/package.json +28 -0
  144. package/runtime/plugins/picasso-browser/index.js +424 -0
  145. package/runtime/plugins/picasso-browser/package.json +28 -0
  146. package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
  147. package/runtime/plugins/picasso-checkpoints/index.js +885 -0
  148. package/runtime/plugins/picasso-checkpoints/package.json +29 -0
  149. package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
  150. package/runtime/plugins/picasso-commands/index.js +497 -0
  151. package/runtime/plugins/picasso-commands/package.json +28 -0
  152. package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
  153. package/runtime/plugins/picasso-instructions/formats.js +145 -0
  154. package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
  155. package/runtime/plugins/picasso-instructions/glob.js +114 -0
  156. package/runtime/plugins/picasso-instructions/globals.js +90 -0
  157. package/runtime/plugins/picasso-instructions/imports.js +123 -0
  158. package/runtime/plugins/picasso-instructions/index.js +326 -0
  159. package/runtime/plugins/picasso-instructions/modes.js +64 -0
  160. package/runtime/plugins/picasso-instructions/package.json +30 -0
  161. package/runtime/plugins/picasso-instructions/parse.js +134 -0
  162. package/runtime/plugins/picasso-instructions/report.js +161 -0
  163. package/runtime/plugins/picasso-instructions/resolve.js +939 -0
  164. package/runtime/plugins/picasso-instructions/scan.js +181 -0
  165. package/runtime/plugins/picasso-instructions/settings.js +150 -0
  166. package/runtime/plugins/picasso-instructions/skills.js +345 -0
  167. package/runtime/plugins/picasso-lean-context/index.js +6049 -0
  168. package/runtime/plugins/picasso-lean-context/package.json +26 -0
  169. package/runtime/plugins/picasso-lean-context/timeline.js +417 -0
  170. package/runtime/plugins/picasso-librarian/classify.js +146 -0
  171. package/runtime/plugins/picasso-librarian/index.js +878 -0
  172. package/runtime/plugins/picasso-librarian/notes.js +159 -0
  173. package/runtime/plugins/picasso-librarian/package.json +34 -0
  174. package/runtime/plugins/picasso-librarian/state.js +478 -0
  175. package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
  176. package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
  177. package/runtime/plugins/picasso-mail/inbox.js +207 -0
  178. package/runtime/plugins/picasso-mail/index.js +293 -0
  179. package/runtime/plugins/picasso-mail/package.json +22 -0
  180. package/runtime/plugins/picasso-memory/index.js +1184 -0
  181. package/runtime/plugins/picasso-memory/package.json +21 -0
  182. package/runtime/plugins/picasso-model-router/connections.js +895 -0
  183. package/runtime/plugins/picasso-model-router/index.js +1081 -0
  184. package/runtime/plugins/picasso-model-router/package.json +30 -0
  185. package/runtime/plugins/picasso-options/index.js +263 -0
  186. package/runtime/plugins/picasso-options/package.json +28 -0
  187. package/runtime/plugins/picasso-progress-reports/index.js +267 -0
  188. package/runtime/plugins/picasso-progress-reports/package.json +30 -0
  189. package/runtime/plugins/picasso-progress-reports/report.js +235 -0
  190. package/runtime/plugins/picasso-provider-models/index.js +436 -0
  191. package/runtime/plugins/picasso-provider-models/package.json +28 -0
  192. package/runtime/plugins/picasso-repo-index/index.js +1850 -0
  193. package/runtime/plugins/picasso-repo-index/package.json +28 -0
  194. package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
  195. package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
  196. package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
  197. package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
  198. package/runtime/plugins/picasso-trackers/index.js +895 -0
  199. package/runtime/plugins/picasso-trackers/package.json +28 -0
  200. package/runtime/plugins/picasso-web-search/backends.js +350 -0
  201. package/runtime/plugins/picasso-web-search/config.js +121 -0
  202. package/runtime/plugins/picasso-web-search/failure.js +111 -0
  203. package/runtime/plugins/picasso-web-search/format.js +35 -0
  204. package/runtime/plugins/picasso-web-search/index.js +66 -0
  205. package/runtime/plugins/picasso-web-search/package.json +38 -0
  206. package/runtime/plugins/picasso-web-search/router.js +155 -0
  207. package/runtime/plugins/picasso-x-reader/circle.js +324 -0
  208. package/runtime/plugins/picasso-x-reader/command.js +169 -0
  209. package/runtime/plugins/picasso-x-reader/index.js +170 -0
  210. package/runtime/plugins/picasso-x-reader/package.json +39 -0
  211. package/runtime/plugins/picasso-x-reader/read.js +370 -0
  212. package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
  213. package/runtime/plugins/picasso-x-reader/settings.js +131 -0
  214. package/runtime/plugins/picasso-x-reader/urls.js +154 -0
  215. package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
  216. package/runtime/relay/attachment-text.mjs +737 -0
  217. package/runtime/relay/companion/companion.css +126 -0
  218. package/runtime/relay/companion/companion.js +648 -0
  219. package/runtime/relay/companion/icon.svg +5 -0
  220. package/runtime/relay/companion/index.html +25 -0
  221. package/runtime/relay/companion/manifest.json +13 -0
  222. package/runtime/relay/companion/sw.js +41 -0
  223. package/runtime/relay/main.mjs +37252 -0
  224. package/runtime/relay/model-listing.mjs +614 -0
  225. package/runtime/relay/versions-routes.mjs +1198 -0
  226. package/runtime/verify-plugins.mjs +205 -0
  227. package/runtime-lock/package-lock.json +10779 -0
  228. package/runtime-lock/package.json +7 -0
  229. package/scripts/install-runtime.mjs +400 -0
  230. package/README.md +0 -3
@@ -0,0 +1,1850 @@
1
+ // @picasso/repo-index — a durable per-workspace code index (files + symbols + imports + line text) inside the dsh
2
+ // engine, plus the RepoWiki surface (`repoIndex/*`) and the `repo_search` / `repo_map` model tools.
3
+ //
4
+ // dsh has no code index: `session-query-sqlite` is session-doc FTS, `dsh-file-reference-local` a per-call filename
5
+ // scan, `dsh-tool-fs-search` a ripgrep call. This plugin owns one SQLite store per workspace under config `root`
6
+ // (the relay mounts `dshHomePath('repo-index')`); each workspace gets `<root>/<name>-<fingerprint>/index.sqlite`.
7
+ // The store is `node:sqlite` — zero npm dependencies, durable across Host restarts, FTS5 for content rows when the
8
+ // runtime's SQLite carries it (a plain `lines` table + LIKE scan is the fallback). Lexical first, per B07: no
9
+ // embedding model is verified, so nothing here requires one.
10
+ //
11
+ // Facts are extracted by a JavaScript port of `crates/indexer`'s RegexFactExtractor (TS/JS, Rust, Python — the crate
12
+ // is the reference impl), extended with Swift (the host app's own language) and Markdown headings. Content rows go
13
+ // to every text file under an extension allowlist; secret-shaped names (.env, *.pem, id_*, .netrc…) are never
14
+ // indexed at all.
15
+ //
16
+ // Remote service `repoIndex` (direct methods — `repoIndex/<method>`; the PRD and the relay's convenience
17
+ // routes name them `wiki/list`, `wiki/page`, `wiki/ask`, `wiki/generate`, and the workspace arg is `cwd` —
18
+ // the same `{cwd}` key the `/index/*` and `/wiki/*` REST surfaces forward):
19
+ // status(cwd) -> {state, files, symbols, imports, lines, bytes, indexedAt, dirty, stalePages}
20
+ // reindex(cwd, full, signal) -> status after an incremental (default) or full rebuild
21
+ // search(cwd, query, limit, path) -> {items:[{kind,path,line,endLine,name,symbolKind,snippet,score}], total}
22
+ // symbols(cwd, query, path, kinds, limit) -> {items:[{path,kind,name,line}]}
23
+ // file(cwd, path) -> {path,language,size,lines,symbols,imports}
24
+ // map(cwd, depth) -> {dirs, externals, edges} for `repo_map`
25
+ // 'wiki/list'(cwd) -> {items:[{id,title,stale,updatedAt,sections}]}
26
+ // 'wiki/page'(cwd, id) -> {id,title,stale,updatedAt,sections:[{id,title,text,citations}]}
27
+ // 'wiki/ask'(cwd, question, limit, provider, model, signal) -> {answer, citations, grounded, synthesized, model?}
28
+ // 'wiki/generate'(cwd, provider, model, pages, signal) -> {pages:[summaries], skipped}
29
+ //
30
+ // Every Remote method lazily opens (and on first use builds) that workspace's index — the `openAt: first-search`
31
+ // cadence of the session-query patch. `status` never builds: an unindexed workspace reports `state: 'empty'`.
32
+ // Invalidation is the PRD's fallback seam made primary: `fs/write-intent`/`fs/edit-intent` (every dsh tool
33
+ // write/edit passes through them) plus `fs/observed` where emitted mark the touched path dirty and a debounced
34
+ // flush re-indexes just that file; a stat-only mtime/size scan on each query catches edits dsh never saw
35
+ // (editors, git checkouts). Changed paths mark the wiki pages that cite them `stale`.
36
+ //
37
+ // `wikiAsk` and `wikiGenerate` route through dsh's own llm service (`ctx.llm.prepareCall`) when a provider/model
38
+ // pair is supplied by the caller or the mount config — the same session-route machinery a turn uses, so the key
39
+ // stays inside dsh. Before calling, the plugin resolves the route's `apiKeyEnv` through `ctx.credentials.resolve`
40
+ // (KIRO_PRISM_API_KEY for the default kiro-prism route) to report `authenticated` honestly; the value is never
41
+ // returned, logged, or sent anywhere but the route's own adapter. With no route, ask and generate still work:
42
+ // pages are built deterministically from index facts, and answers degrade to the retrieved excerpts — grounded, no
43
+ // hallucination surface. A question with zero retrieval answers `grounded: false`, never an invention.
44
+ //
45
+ // `repo_search`/`repo_map` register on `ctx.tools` when mounted (soft — the Remote surface works without them) and
46
+ // resolve the workspace from the calling agent's `workingDirectory`. An opt-in `agent/pre-step` grounding splice
47
+ // (config `preStepInject`, OFF by default) folds top-K index hits into turn 1 for "how does X work" prompts, sourced
48
+ // `{kind: 'picasso-repo-index'}` so clients can label it — the picasso-memory recall precedent.
49
+ import { createHash } from 'node:crypto';
50
+ import { mkdirSync, statSync } from 'node:fs';
51
+ import { readdir, readFile, realpath, stat } from 'node:fs/promises';
52
+ import { homedir } from 'node:os';
53
+ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
54
+ import { setTimeout as delay } from 'node:timers/promises';
55
+
56
+ let DatabaseSync;
57
+ try {
58
+ ({ DatabaseSync } = await import('node:sqlite'));
59
+ } catch {
60
+ DatabaseSync = undefined; // Node < 22.5: the plugin reports store-unavailable instead of failing to load.
61
+ }
62
+
63
+ export const name = 'picasso-repo-index';
64
+ /** The dsh release this plugin is written and tested against (Picasso pins the engine to it). */
65
+ export const dshTarget = '0.2.2-rc.3';
66
+ export const SERVICE_KEY = 'repoIndex';
67
+ const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods';
68
+
69
+ export const SCHEMA_VERSION = 1;
70
+ export const STORE_DIRNAME = 'repo-index';
71
+ export const DEFAULT_MAX_FILE_BYTES = 1_000_000;
72
+ export const DEFAULT_MAX_FILES = 60_000;
73
+ export const DEFAULT_SCAN_INTERVAL_MS = 1_500;
74
+ export const DIRTY_FLUSH_MS = 400;
75
+ const SEARCH_CANDIDATE_LIMIT = 600;
76
+ const DEFAULT_SEARCH_LIMIT = 20;
77
+ const MAX_SEARCH_LIMIT = 50;
78
+ const SNIPPET_RADIUS = 2;
79
+ const SNIPPET_MAX_CHARS = 480;
80
+ const ASK_CONTEXT_LINES = 14;
81
+ const ASK_MAX_INPUT_BYTES = 48 * 1024;
82
+ const ASK_MAX_OUTPUT_TOKENS = 2048;
83
+ const ASK_TIMEOUT_MS = 60_000;
84
+ const WIKI_PAGE_CAP = 12;
85
+ const WIKI_CITATION_CAP = 24;
86
+ const SOURCE_KIND = 'picasso-repo-index';
87
+
88
+ export class RepoIndexError extends Error {
89
+ constructor(code, message, details = {}) {
90
+ super(message);
91
+ this.name = 'RemoteError';
92
+ this.code = `repoIndex/${code}`;
93
+ this.details = details;
94
+ this.isDSHRemoteError = true;
95
+ }
96
+ }
97
+
98
+ const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
99
+ const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined);
100
+ const statSafe = (path) => { try { return statSync(path); } catch { return undefined; } };
101
+
102
+ // ── Languages and hygiene ────────────────────────────────────────────────────────────────────────────────
103
+
104
+ /** Extension → stored language id. A file whose extension is not listed is not indexed at all. */
105
+ export const LANGUAGES = {
106
+ ts: 'typescript', tsx: 'typescript', mts: 'typescript', cts: 'typescript',
107
+ js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript',
108
+ rs: 'rust',
109
+ py: 'python', pyw: 'python', pyi: 'python',
110
+ swift: 'swift',
111
+ go: 'go', java: 'java', kt: 'kotlin', kts: 'kotlin', scala: 'scala',
112
+ c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', cxx: 'cpp', hpp: 'cpp', hh: 'cpp',
113
+ cs: 'csharp', rb: 'ruby', php: 'php', lua: 'lua', pl: 'perl', pm: 'perl', r: 'r',
114
+ ex: 'elixir', exs: 'elixir', erl: 'erlang', hrl: 'erlang', clj: 'clojure', cljs: 'clojure',
115
+ hs: 'haskell', ml: 'ocaml', mli: 'ocaml', zig: 'zig', dart: 'dart', nim: 'nim',
116
+ sh: 'shell', bash: 'shell', zsh: 'shell', fish: 'shell',
117
+ md: 'markdown', markdown: 'markdown', mdx: 'markdown', txt: 'text', rst: 'text', adoc: 'text',
118
+ json: 'json', jsonc: 'json', yml: 'yaml', yaml: 'yaml', toml: 'toml', ini: 'ini', cfg: 'ini',
119
+ xml: 'xml', html: 'html', htm: 'html', css: 'css', scss: 'css', less: 'css', svg: 'xml',
120
+ sql: 'sql', graphql: 'graphql', gql: 'graphql', proto: 'protobuf',
121
+ tf: 'terraform', vue: 'vue', svelte: 'svelte', astro: 'astro', prisma: 'prisma',
122
+ };
123
+
124
+ /** Known extensionless (or dot-name) files worth a content row. */
125
+ const KNOWN_FILES = new Map([
126
+ ['makefile', 'text'], ['dockerfile', 'text'], ['license', 'text'], ['licence', 'text'],
127
+ ['cmakelists.txt', 'text'], ['gemfile', 'ruby'], ['rakefile', 'ruby'], ['podfile', 'ruby'],
128
+ ['brewfile', 'ruby'], ['justfile', 'text'], ['.gitignore', 'text'], ['.gitattributes', 'text'],
129
+ ['.dockerignore', 'text'], ['.editorconfig', 'ini'], ['package.swift', 'swift'], ['cartfile', 'text'],
130
+ ['readme', 'markdown'], ['changelog', 'markdown'], ['contributing', 'markdown'],
131
+ ]);
132
+
133
+ /** The crate's ignore list (crates/indexer/src/lib.rs) plus the Mac-native build dirs this repo actually has. */
134
+ export const DEFAULT_IGNORED_DIRS = [
135
+ '.git', '.hg', '.svn', '.idea', '.vscode', '.turbo', '.next', '.nuxt', '.cache', '.parcel-cache',
136
+ 'node_modules', 'bower_components', 'vendor', 'target', 'dist', 'build', 'out', 'coverage',
137
+ '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.tox', '.venv', 'venv', 'env',
138
+ 'DerivedData', '.build', 'Pods', '.gradle', '.pio', 'Carthage', 'PicassoEngine', 'Library',
139
+ ];
140
+
141
+ /** Names whose contents are never indexed — a code index must not become a secret store, nor a blob store. */
142
+ const SECRET_NAME = /^\.env($|\.)|\.(pem|key|p12|pfx|jks|keystore|asc|kdbx)$|^id_(rsa|dsa|ecdsa|ed25519)|^\.(netrc|npmrc|pypirc|htpasswd|pgpass)$|\.(sqlite3?|db|zip|gz|tgz|tar|rar|7z|dmg|pkg|png|jpe?g|gif|webp|ico|icns|pdf|woff2?|ttf|otf|eot|mp[34]|mov|wav|aiff|so|dylib|a|o|wasm|jar|class|pyc|pyo|bin|xcarchive|ipa|app|framework|xcframework|lockb)$/i;
143
+
144
+ /** `undefined` skips the file. */
145
+ export function languageOf(path) {
146
+ const name = basename(path);
147
+ if (SECRET_NAME.test(name)) return undefined;
148
+ const lower = name.toLowerCase();
149
+ if (KNOWN_FILES.has(lower)) return KNOWN_FILES.get(lower);
150
+ if (/^(readme|changelog|contributing)\.(md|markdown|mdx|txt|rst)$/i.test(name)) return 'markdown';
151
+ const ext = extname(lower).slice(1);
152
+ return ext ? LANGUAGES[ext] : undefined;
153
+ }
154
+
155
+ // ── The crates/indexer RegexFactExtractor, ported ────────────────────────────────────────────────────────
156
+
157
+ const TS_IMPORT_FROM = /^\s*import\s+(?:([\s\S]*?)\s+from\s+)?["']([^"']+)["']/;
158
+ const TS_SIDE_IMPORT = /^\s*import\s*["']([^"']+)["']/;
159
+ const TS_SYMBOL = /^\s*(?:export\s+)?(?:default\s+)?(?:(?:async\s+)?function\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*)|interface\s+([A-Za-z_$][\w$]*)|type\s+([A-Za-z_$][\w$]*)|enum\s+([A-Za-z_$][\w$]*)|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:function|\([^)]*\)\s*=>|[A-Za-z_$][\w$]*\s*=>))/;
160
+ const RUST_USE = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([^;]+);/;
161
+ const RUST_SYMBOL = /^\s*(?:pub(?:\([^)]*\))?\s+)?(?:(?:async\s+)?fn\s+([A-Za-z_]\w*)|struct\s+([A-Za-z_]\w*)|enum\s+([A-Za-z_]\w*)|trait\s+([A-Za-z_]\w*)|impl(?:\s*<[^>]+>)?\s+([A-Za-z_][\w:<>]*)|(?:const|static)\s+([A-Z_][A-Z0-9_]*))/;
162
+ const PY_IMPORT_FROM = /^\s*from\s+([A-Za-z_][\w.]*|\.+[A-Za-z_][\w.]*)\s+import\s+(.+)$/;
163
+ const PY_IMPORT = /^\s*import\s+(.+)$/;
164
+ const PY_SYMBOL = /^\s*(?:(?:async\s+)?def\s+([A-Za-z_]\w*)|class\s+([A-Za-z_]\w*))/;
165
+ // Beyond the crate: Swift (this app's own language — B07 marks it "acceptable" to skip; a regex pass is cheap) and
166
+ // Markdown headings (the PRD's "docs/markdown chunk facts").
167
+ const SWIFT_IMPORT = /^\s*(?:@\w+\s+)?(?:public\s+|private\s+|internal\s+|fileprivate\s+|open\s+)?import\s+([A-Za-z_][\w.]*)/;
168
+ const SWIFT_SYMBOL = /^\s*(?:(?:public|private|internal|fileprivate|open|static|class|final|override|mutating|nonmutating|lazy|weak|unowned|indirect|convenience|required|isolated|nonisolated|distributed|async)\s+|@\w+(?:\([^)]*\))?\s+)*(?:(class|struct|enum|protocol|actor|extension|typealias)\s+([A-Za-z_]\w*)|func\s+([A-Za-z_]\w*)|(?:let|var)\s+([A-Za-z_]\w*)\s*[:=])/;
169
+ const MD_HEADING = /^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/;
170
+
171
+ function tsImportItems(items) {
172
+ if (!items) return [];
173
+ const cleaned = items.replace(/[{*}]/g, ' ').replace(/ as /g, ' ');
174
+ return cleaned
175
+ .split(',')
176
+ .flatMap((part) => part.trim().split(/\s+/).slice(0, 1))
177
+ .filter((part) => part.length > 0 && part !== 'from');
178
+ }
179
+
180
+ function rustUseItems(module) {
181
+ const open = module.indexOf('{');
182
+ const close = module.lastIndexOf('}');
183
+ if (open >= 0 && close > open) {
184
+ return module.slice(open + 1, close).split(',').map((part) => part.trim()).filter((part) => part && part !== 'self');
185
+ }
186
+ const last = module.split('::').pop()?.trim();
187
+ return last ? [last] : [];
188
+ }
189
+
190
+ function pythonImportItems(items) {
191
+ return items
192
+ .split(',')
193
+ .map((item) => item.trim().split(/\s+/)[0]?.replace(/^[()]+|[()]+$/g, '') ?? '')
194
+ .filter(Boolean);
195
+ }
196
+
197
+ /** First non-undefined capture group → {kind, name} (the crate's `first_named_capture`). */
198
+ function firstNamed(match, names) {
199
+ for (const [index, kind] of names) {
200
+ const value = match[index + 1];
201
+ if (value !== undefined) return { kind, name: value };
202
+ }
203
+ return undefined;
204
+ }
205
+
206
+ const TS_KINDS = [[0, 'function'], [1, 'class'], [2, 'interface'], [3, 'typealias'], [4, 'enum'], [5, 'function']];
207
+ const RUST_KINDS = [[0, 'function'], [1, 'struct'], [2, 'enum'], [3, 'trait'], [4, 'impl'], [5, 'const']];
208
+ const PY_KINDS = [[0, 'function'], [1, 'class']];
209
+
210
+ /**
211
+ * `extractFacts(relPath, language, source)` → `{symbols, imports}` — symbol rows `{path,language,kind,name,line}`
212
+ * and import rows `{path,language,module,imported,line}`, mirroring `ExtractedFacts` in crates/indexer.
213
+ */
214
+ export function extractFacts(path, language, source) {
215
+ const symbols = [];
216
+ const imports = [];
217
+ const lines = source.split('\n');
218
+ const push = (kind, symbolName, line) => symbols.push({ path, language, kind, name: symbolName, line });
219
+ const use = (module, imported, line) => imports.push({ path, language, module, imported, line });
220
+
221
+ for (let i = 0; i < lines.length; i += 1) {
222
+ const line = lines[i];
223
+ const at = i + 1;
224
+ switch (language) {
225
+ case 'typescript':
226
+ case 'javascript': {
227
+ const from = TS_IMPORT_FROM.exec(line);
228
+ if (from) use(from[2], tsImportItems(from[1]), at);
229
+ else {
230
+ const side = TS_SIDE_IMPORT.exec(line);
231
+ if (side) use(side[1], [], at);
232
+ }
233
+ const sym = TS_SYMBOL.exec(line);
234
+ if (sym) {
235
+ const named = firstNamed(sym, TS_KINDS);
236
+ if (named) push(named.kind, named.name, at);
237
+ }
238
+ break;
239
+ }
240
+ case 'rust': {
241
+ const dep = RUST_USE.exec(line);
242
+ if (dep) use(dep[1].trim(), rustUseItems(dep[1]), at);
243
+ const sym = RUST_SYMBOL.exec(line);
244
+ if (sym) {
245
+ const named = firstNamed(sym, RUST_KINDS);
246
+ if (named) push(named.kind, named.name, at);
247
+ }
248
+ break;
249
+ }
250
+ case 'python': {
251
+ const from = PY_IMPORT_FROM.exec(line);
252
+ if (from) use(from[1], pythonImportItems(from[2]), at);
253
+ else {
254
+ const plain = PY_IMPORT.exec(line);
255
+ if (plain) for (const module of pythonImportItems(plain[1])) use(module, [], at);
256
+ }
257
+ const sym = PY_SYMBOL.exec(line);
258
+ if (sym) {
259
+ const named = firstNamed(sym, PY_KINDS);
260
+ if (named) push(named.kind, named.name, at);
261
+ }
262
+ break;
263
+ }
264
+ case 'swift': {
265
+ const dep = SWIFT_IMPORT.exec(line);
266
+ if (dep) use(dep[1], [], at);
267
+ const sym = SWIFT_SYMBOL.exec(line);
268
+ if (sym) {
269
+ if (sym[2] !== undefined) push(sym[1] === 'typealias' ? 'typealias' : sym[1], sym[2], at);
270
+ else if (sym[3] !== undefined) push('function', sym[3], at);
271
+ else if (sym[4] !== undefined) push('variable', sym[4], at);
272
+ }
273
+ break;
274
+ }
275
+ case 'markdown': {
276
+ const heading = MD_HEADING.exec(line);
277
+ if (heading) push('heading', heading[1].trim(), at);
278
+ break;
279
+ }
280
+ default:
281
+ break;
282
+ }
283
+ }
284
+ return { symbols, imports };
285
+ }
286
+
287
+ // ── Lexical machinery ────────────────────────────────────────────────────────────────────────────────────
288
+
289
+ /** Query/index terms: lowercase alphanumeric/underscore runs, length ≥ 2, at most 12. */
290
+ export function terms(textValue) {
291
+ const out = [];
292
+ const seen = new Set();
293
+ for (const match of String(textValue ?? '').toLowerCase().matchAll(/[a-z0-9_]{2,}/g)) {
294
+ if (!seen.has(match[0])) {
295
+ seen.add(match[0]);
296
+ out.push(match[0]);
297
+ if (out.length >= 12) break;
298
+ }
299
+ }
300
+ return out;
301
+ }
302
+
303
+ /**
304
+ * The `spread` column: one line with identifiers split (`indexCodebase` → `index Codebase`) and separators spaced,
305
+ * so `codebase` finds `indexCodebase` even though the raw line never contains the word.
306
+ */
307
+ export function spreadLine(line) {
308
+ return String(line)
309
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
310
+ .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
311
+ .replace(/[_$@#./\\:~+*"'`|<>=!?,;()[\]{}-]+/g, ' ');
312
+ }
313
+
314
+ /** One safe FTS5 MATCH expression over (code, spread): prefix terms OR'd; `''` when the query has no terms. */
315
+ export function matchExpression(query) {
316
+ const list = terms(query);
317
+ if (list.length === 0) return '';
318
+ return list.map((term) => `{code spread} : "${term}"*`).join(' OR ');
319
+ }
320
+
321
+ /** How many of `termList` a stored line carries (raw or identifier-split). */
322
+ function lineCoverage(line, termList) {
323
+ const raw = String(line ?? '').toLowerCase();
324
+ const words = spreadLine(String(line ?? '')).toLowerCase().split(' ');
325
+ let hits = 0;
326
+ for (const term of termList) {
327
+ if (raw.includes(term) || words.some((word) => word.startsWith(term))) hits += 1;
328
+ }
329
+ return hits;
330
+ }
331
+
332
+ // ── The store (node:sqlite; FTS5 when the runtime's SQLite has it) ───────────────────────────────────────
333
+
334
+ const SCHEMA = `
335
+ CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT);
336
+ CREATE TABLE IF NOT EXISTS files(
337
+ path TEXT PRIMARY KEY,
338
+ language TEXT NOT NULL,
339
+ size INTEGER NOT NULL,
340
+ lines INTEGER NOT NULL,
341
+ mtime_ms REAL NOT NULL
342
+ );
343
+ CREATE TABLE IF NOT EXISTS symbols(path TEXT NOT NULL, kind TEXT NOT NULL, name TEXT NOT NULL, line INTEGER NOT NULL);
344
+ CREATE INDEX IF NOT EXISTS symbols_name ON symbols(name);
345
+ CREATE INDEX IF NOT EXISTS symbols_path ON symbols(path);
346
+ CREATE TABLE IF NOT EXISTS imports(path TEXT NOT NULL, module TEXT NOT NULL, imported TEXT NOT NULL, line INTEGER NOT NULL);
347
+ CREATE INDEX IF NOT EXISTS imports_module ON imports(module);
348
+ CREATE INDEX IF NOT EXISTS imports_path ON imports(path);
349
+ CREATE TABLE IF NOT EXISTS lines(id INTEGER PRIMARY KEY, path TEXT NOT NULL, line INTEGER NOT NULL, code TEXT, spread TEXT);
350
+ CREATE INDEX IF NOT EXISTS lines_path ON lines(path);
351
+ CREATE TABLE IF NOT EXISTS wiki(
352
+ id TEXT PRIMARY KEY,
353
+ title TEXT NOT NULL,
354
+ sections TEXT NOT NULL,
355
+ sources TEXT NOT NULL,
356
+ updated_at TEXT NOT NULL,
357
+ stale INTEGER NOT NULL DEFAULT 0
358
+ );
359
+ `;
360
+
361
+ const FTS_SCHEMA = `
362
+ CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(code, spread, content='lines', content_rowid='id');
363
+ CREATE TRIGGER IF NOT EXISTS lines_ai AFTER INSERT ON lines BEGIN INSERT INTO docs(rowid, code, spread) VALUES (new.id, new.code, new.spread); END;
364
+ CREATE TRIGGER IF NOT EXISTS lines_ad AFTER DELETE ON lines BEGIN INSERT INTO docs(docs, rowid, code, spread) VALUES('delete', old.id, old.code, old.spread); END;
365
+ CREATE TRIGGER IF NOT EXISTS lines_au AFTER UPDATE ON lines BEGIN INSERT INTO docs(docs, rowid, code, spread) VALUES('delete', old.id, old.code, old.spread); INSERT INTO docs(rowid, code, spread) VALUES (new.id, new.code, new.spread); END;
366
+ `;
367
+
368
+ function safeParse(raw, fallback) {
369
+ try { return JSON.parse(raw); } catch { return fallback; }
370
+ }
371
+
372
+ const escapeLike = (value) => String(value).replace(/[\\%_]/g, (m) => `\\${m}`);
373
+
374
+ /**
375
+ * The on-disk shape under `<storeRoot>/<fingerprint>/index.sqlite`. All writes go through one `DatabaseSync`
376
+ * connection per workspace; callers serialize mutations on `WorkspaceIndex.tail`.
377
+ */
378
+ export class Store {
379
+ constructor(dir, { fts } = {}) {
380
+ if (DatabaseSync === undefined) throw new RepoIndexError('store-unavailable', 'This dsh runtime has no node:sqlite — the repo index needs Node 22.5 or newer.');
381
+ this.dir = dir;
382
+ this.file = join(dir, 'index.sqlite');
383
+ mkdirSync(dir, { recursive: true });
384
+ this.db = new DatabaseSync(this.file);
385
+ this.db.exec('PRAGMA journal_mode = WAL');
386
+ this.db.exec('PRAGMA synchronous = NORMAL');
387
+ this.db.exec(SCHEMA);
388
+ this.fts = fts === false ? false : this.probeFts();
389
+ }
390
+
391
+ probeFts() {
392
+ try {
393
+ this.db.exec(FTS_SCHEMA);
394
+ this.db.prepare('SELECT rowid FROM docs WHERE docs MATCH ? LIMIT 1').get('probe');
395
+ return true;
396
+ } catch {
397
+ return false;
398
+ }
399
+ }
400
+
401
+ meta(key) {
402
+ return this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key)?.value;
403
+ }
404
+
405
+ putMeta(key, value) {
406
+ this.db.prepare('INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, String(value));
407
+ }
408
+
409
+ /** path → {language, size, lines, mtimeMs} for every indexed file. */
410
+ fileRows() {
411
+ const rows = this.db.prepare('SELECT path, language, size, lines, mtime_ms AS mtimeMs FROM files').all();
412
+ return new Map(rows.map((row) => [row.path, row]));
413
+ }
414
+
415
+ counts() {
416
+ const one = (sql) => this.db.prepare(sql).get().n;
417
+ return {
418
+ files: one('SELECT count(*) AS n FROM files'),
419
+ symbols: one('SELECT count(*) AS n FROM symbols'),
420
+ imports: one('SELECT count(*) AS n FROM imports'),
421
+ lines: one('SELECT count(*) AS n FROM lines'),
422
+ bytes: this.db.prepare('SELECT coalesce(sum(size),0) AS n FROM files').get().n,
423
+ };
424
+ }
425
+
426
+ /** Replace one file's rows (facts + line content) — callers wrap batches in a transaction. */
427
+ upsertFile(row, facts, lineRows) {
428
+ this.removeFileRows(row.path);
429
+ this.db.prepare('INSERT INTO files(path, language, size, lines, mtime_ms) VALUES (?, ?, ?, ?, ?)').run(row.path, row.language, row.size, row.lines, row.mtimeMs);
430
+ const insertSymbol = this.db.prepare('INSERT INTO symbols(path, kind, name, line) VALUES (?, ?, ?, ?)');
431
+ for (const s of facts.symbols) insertSymbol.run(s.path, s.kind, s.name, s.line);
432
+ const insertImport = this.db.prepare('INSERT INTO imports(path, module, imported, line) VALUES (?, ?, ?, ?)');
433
+ for (const i of facts.imports) insertImport.run(i.path, i.module, JSON.stringify(i.imported), i.line);
434
+ const insertLine = this.db.prepare('INSERT INTO lines(path, line, code, spread) VALUES (?, ?, ?, ?)');
435
+ for (const l of lineRows) insertLine.run(row.path, l.line, l.code, l.spread);
436
+ }
437
+
438
+ removeFileRows(path) {
439
+ this.db.prepare('DELETE FROM lines WHERE path = ?').run(path);
440
+ this.db.prepare('DELETE FROM symbols WHERE path = ?').run(path);
441
+ this.db.prepare('DELETE FROM imports WHERE path = ?').run(path);
442
+ this.db.prepare('DELETE FROM files WHERE path = ?').run(path);
443
+ }
444
+
445
+ fileRow(path) {
446
+ const row = this.db.prepare('SELECT path, language, size, lines, mtime_ms AS mtimeMs FROM files WHERE path = ?').get(path);
447
+ if (!row) return undefined;
448
+ return {
449
+ ...row,
450
+ symbols: this.db.prepare('SELECT kind, name, line FROM symbols WHERE path = ? ORDER BY line').all(path),
451
+ imports: this.db.prepare('SELECT module, imported, line FROM imports WHERE path = ? ORDER BY line').all(path)
452
+ .map((i) => ({ module: i.module, imported: safeParse(i.imported, []), line: i.line })),
453
+ };
454
+ }
455
+
456
+ /** FTS5-recalled candidate rows `{path, line, code, rank}`; LIKE fallback when FTS5 is absent. */
457
+ matchRows(expr, termList, limit) {
458
+ if (this.fts && expr) {
459
+ try {
460
+ return this.db
461
+ .prepare('SELECT l.path AS path, l.line AS line, l.code AS code, docs.rank AS rank FROM docs JOIN lines l ON l.id = docs.rowid WHERE docs MATCH ? ORDER BY rank LIMIT ?')
462
+ .all(expr, limit);
463
+ } catch {
464
+ return [];
465
+ }
466
+ }
467
+ if (termList.length === 0) return [];
468
+ const where = termList.map(() => 'lower(l.code) LIKE ?').join(' OR ');
469
+ const params = termList.map((term) => `%${term}%`);
470
+ return this.db.prepare(`SELECT path, line, code, 0 AS rank FROM lines l WHERE ${where} LIMIT ?`).all(...params, limit);
471
+ }
472
+
473
+ /** Every stored line of a file (search re-scoring, ask context). */
474
+ fileLines(path) {
475
+ return this.db.prepare('SELECT line, code FROM lines WHERE path = ? ORDER BY line').all(path);
476
+ }
477
+
478
+ fileSlice(path, from, to) {
479
+ return this.db.prepare('SELECT line, code FROM lines WHERE path = ? AND line BETWEEN ? AND ? ORDER BY line').all(path, from, to);
480
+ }
481
+
482
+ /**
483
+ * Symbol rows, exact → prefix → substring name match (each run, deduped by path:line:name, shorter names first),
484
+ * optional directory prefix and kind filters.
485
+ */
486
+ symbolRows({ query, path, kinds, limit }) {
487
+ const filters = [];
488
+ const params = [];
489
+ if (path) {
490
+ const dir = path.replace(/\/+$/, '');
491
+ // A directory prefix means `dir/…`; pass an exact file path to match it directly.
492
+ filters.push("(path LIKE ? ESCAPE '\\' OR path = ?)");
493
+ params.push(`${escapeLike(dir)}/%`, dir);
494
+ }
495
+ if (Array.isArray(kinds) && kinds.length) { filters.push(`kind IN (${kinds.map(() => '?').join(',')})`); params.push(...kinds); }
496
+ const suffix = filters.length ? ` AND ${filters.join(' AND ')}` : '';
497
+ if (!query) {
498
+ return this.db.prepare(`SELECT path, kind, name, line FROM symbols WHERE 1=1${suffix} ORDER BY name, path, line LIMIT ?`).all(...params, limit);
499
+ }
500
+ const seen = new Set();
501
+ const rows = [];
502
+ const escaped = escapeLike(query);
503
+ for (const pattern of [escaped, `${escaped}%`, `%${escaped}%`]) {
504
+ if (rows.length >= limit) break;
505
+ const found = this.db
506
+ .prepare(`SELECT path, kind, name, line FROM symbols WHERE name LIKE ? ESCAPE '\\'${suffix} ORDER BY length(name), name, path, line LIMIT ?`)
507
+ .all(pattern, ...params, limit);
508
+ for (const row of found) {
509
+ const key = `${row.path}:${row.line}:${row.name}`;
510
+ if (seen.has(key)) continue;
511
+ seen.add(key);
512
+ rows.push(row);
513
+ }
514
+ }
515
+ return rows.slice(0, limit);
516
+ }
517
+
518
+ moduleCounts(limit) {
519
+ return this.db.prepare('SELECT module, count(*) AS uses, min(path) AS path, min(line) AS line FROM imports GROUP BY module ORDER BY uses DESC, module LIMIT ?').all(limit);
520
+ }
521
+
522
+ importRows(limit = 100_000) {
523
+ return this.db.prepare('SELECT path, module, imported, line FROM imports LIMIT ?').all(limit)
524
+ .map((row) => ({ ...row, imported: safeParse(row.imported, []) }));
525
+ }
526
+
527
+ languageCounts() {
528
+ return this.db.prepare('SELECT language, count(*) AS files, coalesce(sum(size),0) AS bytes FROM files GROUP BY language ORDER BY files DESC').all();
529
+ }
530
+
531
+ topDirs() {
532
+ return this.db.prepare("SELECT CASE WHEN instr(path, '/') = 0 THEN '.' ELSE substr(path, 1, instr(path, '/') - 1) END AS dir, count(*) AS files, coalesce(sum(size),0) AS bytes FROM files GROUP BY dir ORDER BY files DESC").all();
533
+ }
534
+
535
+ firstPathUnder(dir) {
536
+ const pattern = dir === '.' ? '%' : `${escapeLike(dir)}/%`;
537
+ return this.db.prepare("SELECT path FROM files WHERE path LIKE ? ESCAPE '\\' ORDER BY path LIMIT 1").get(pattern)?.path;
538
+ }
539
+
540
+ /** A directory's headliner symbols: types first, then functions; headings never headline. */
541
+ dirSymbols(dir, limit) {
542
+ const pattern = dir === '.' ? '%' : `${escapeLike(dir)}/%`;
543
+ return this.db.prepare("SELECT path, kind, name, line FROM symbols WHERE path LIKE ? ESCAPE '\\' AND kind != 'heading' ORDER BY CASE kind WHEN 'class' THEN 0 WHEN 'interface' THEN 1 WHEN 'struct' THEN 2 WHEN 'trait' THEN 3 WHEN 'enum' THEN 4 WHEN 'function' THEN 5 ELSE 6 END, name LIMIT ?").all(pattern, limit);
544
+ }
545
+
546
+ wikiRows() {
547
+ return this.db.prepare('SELECT id, title, sections, sources, updated_at AS updatedAt, stale FROM wiki ORDER BY id').all()
548
+ .map((row) => ({ ...row, sections: safeParse(row.sections, []), sources: safeParse(row.sources, []), stale: row.stale === 1 }));
549
+ }
550
+
551
+ wikiRow(id) {
552
+ const row = this.db.prepare('SELECT id, title, sections, sources, updated_at AS updatedAt, stale FROM wiki WHERE id = ?').get(id);
553
+ if (!row) return undefined;
554
+ return { ...row, sections: safeParse(row.sections, []), sources: safeParse(row.sources, []), stale: row.stale === 1 };
555
+ }
556
+
557
+ putWiki(page) {
558
+ this.db.prepare('INSERT INTO wiki(id, title, sections, sources, updated_at, stale) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET title = excluded.title, sections = excluded.sections, sources = excluded.sources, updated_at = excluded.updated_at, stale = excluded.stale')
559
+ .run(page.id, page.title, JSON.stringify(page.sections), JSON.stringify(page.sources), page.updatedAt, page.stale ? 1 : 0);
560
+ }
561
+
562
+ /** Pages whose citation set touches a changed path go stale; returns how many flipped. */
563
+ markWikiStale(changedPaths) {
564
+ if (changedPaths.length === 0) return 0;
565
+ const changed = new Set(changedPaths);
566
+ let marked = 0;
567
+ for (const row of this.db.prepare('SELECT id, sources FROM wiki WHERE stale = 0').all()) {
568
+ if (safeParse(row.sources, []).some((path) => changed.has(path))) {
569
+ this.db.prepare('UPDATE wiki SET stale = 1 WHERE id = ?').run(row.id);
570
+ marked += 1;
571
+ }
572
+ }
573
+ return marked;
574
+ }
575
+
576
+ wikiStaleCount() {
577
+ return this.db.prepare('SELECT count(*) AS n FROM wiki WHERE stale = 1').get().n;
578
+ }
579
+
580
+ /** Bytes the store occupies on disk (main + wal + shm). */
581
+ storageBytes() {
582
+ let bytes = 0;
583
+ for (const suffix of ['', '-wal', '-shm']) bytes += statSafe(this.file + suffix)?.size ?? 0;
584
+ return bytes;
585
+ }
586
+
587
+ clearAll() {
588
+ this.db.exec('DELETE FROM lines; DELETE FROM symbols; DELETE FROM imports; DELETE FROM files; DELETE FROM meta; DELETE FROM wiki;');
589
+ }
590
+
591
+ close() {
592
+ try { this.db.close(); } catch { /* already closed */ }
593
+ }
594
+ }
595
+
596
+ // ── Workspace index: build, refresh, query, wiki ─────────────────────────────────────────────────────────
597
+
598
+ /** `<storeRoot>/<basename>-<hash16>/` — durable per-workspace home, one sqlite inside. */
599
+ export function workspaceDirName(absRoot) {
600
+ const hash = createHash('sha256').update(resolve(absRoot), 'utf8').digest('hex').slice(0, 16);
601
+ return `${basename(absRoot).replace(/[^\w.-]+/g, '_') || 'workspace'}-${hash}`;
602
+ }
603
+
604
+ const topDir = (path) => (path.includes('/') ? path.split('/')[0] : '.');
605
+
606
+ export class WorkspaceIndex {
607
+ constructor({ root, storeRoot, config = {}, log = () => undefined }) {
608
+ this.root = root; // absolute, resolved
609
+ this.config = config;
610
+ this.log = log;
611
+ this.ignoredDirs = new Set([...DEFAULT_IGNORED_DIRS, ...(Array.isArray(config.ignore) ? config.ignore.filter((d) => typeof d === 'string') : [])]);
612
+ this.maxFileBytes = Number.isInteger(config.maxFileBytes) && config.maxFileBytes > 0 ? config.maxFileBytes : DEFAULT_MAX_FILE_BYTES;
613
+ this.maxFiles = Number.isInteger(config.maxFiles) && config.maxFiles > 0 ? config.maxFiles : DEFAULT_MAX_FILES;
614
+ this.scanIntervalMs = Number.isInteger(config.scanIntervalMs) && config.scanIntervalMs >= 0 ? config.scanIntervalMs : DEFAULT_SCAN_INTERVAL_MS;
615
+ this.includeHidden = config.includeHidden === true;
616
+ this.dir = join(storeRoot, workspaceDirName(root));
617
+ this.store = undefined;
618
+ this.dirty = new Set();
619
+ this.building = false;
620
+ this.progress = { seen: 0, indexed: 0 };
621
+ this.lastScan = 0;
622
+ this.tail = Promise.resolve();
623
+ this.flushTimer = undefined;
624
+ }
625
+
626
+ open() {
627
+ if (!this.store) this.store = new Store(this.dir, { fts: this.config.fts });
628
+ return this.store;
629
+ }
630
+
631
+ serial(body) {
632
+ const run = this.tail.then(body, body);
633
+ this.tail = run.catch(() => undefined);
634
+ return run;
635
+ }
636
+
637
+ /** Lock-held ensure: open the store, cold-build when empty. */
638
+ async ensureStore(signal) {
639
+ const store = this.open();
640
+ if (store.meta('workspace') !== this.root) store.putMeta('workspace', this.root);
641
+ if (store.counts().files === 0 && !this.building) await this.build(signal);
642
+ return store;
643
+ }
644
+
645
+ /** `ensure` = lazy first build; every read path calls it. */
646
+ async ensure(signal) {
647
+ return this.serial(() => this.ensureStore(signal));
648
+ }
649
+
650
+ /** The walk: `{abs, rel, language}` per indexable file; ignore dirs, hidden names, caps applied. */
651
+ async *walk() {
652
+ const stack = [''];
653
+ let seen = 0;
654
+ while (stack.length > 0) {
655
+ const dir = stack.pop();
656
+ const absDir = dir === '' ? this.root : join(this.root, dir);
657
+ let entries;
658
+ try {
659
+ entries = await readdir(absDir, { withFileTypes: true });
660
+ } catch {
661
+ continue;
662
+ }
663
+ entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
664
+ for (const entry of entries) {
665
+ if (seen >= this.maxFiles) return;
666
+ const nameOf = entry.name;
667
+ const rel = dir === '' ? nameOf : `${dir}/${nameOf}`;
668
+ if (!this.includeHidden && nameOf.startsWith('.') && !KNOWN_FILES.has(nameOf.toLowerCase())) continue;
669
+ const abs = join(this.root, rel);
670
+ if (entry.isDirectory()) {
671
+ if (this.ignoredDirs.has(nameOf)) continue;
672
+ stack.push(rel);
673
+ } else if (entry.isFile() || entry.isSymbolicLink()) {
674
+ const language = languageOf(nameOf);
675
+ if (language === undefined) continue;
676
+ seen += 1;
677
+ yield { abs, rel, language };
678
+ }
679
+ }
680
+ }
681
+ }
682
+
683
+ /** Read + extract one file's rows; `undefined` when it should not be (or cannot be) indexed. */
684
+ async fileFacts({ abs, rel, language }) {
685
+ let info;
686
+ try {
687
+ info = await stat(abs);
688
+ } catch {
689
+ return undefined;
690
+ }
691
+ if (!info.isFile() || info.size > this.maxFileBytes) return undefined;
692
+ let source;
693
+ try {
694
+ source = await readFile(abs, 'utf8');
695
+ } catch {
696
+ return undefined;
697
+ }
698
+ if (source.includes('\u0000')) return undefined; // binary behind a text extension
699
+ const rawLines = source.split('\n');
700
+ const lineRows = rawLines.map((code, i) => ({ line: i + 1, code, spread: spreadLine(code) }));
701
+ const facts = extractFacts(rel, language, source);
702
+ return {
703
+ row: { path: rel, language, size: info.size, lines: rawLines.length, mtimeMs: info.mtimeMs },
704
+ facts,
705
+ lineRows,
706
+ };
707
+ }
708
+
709
+ /** Cold build: walk, extract, write in chunked transactions so the Host keeps answering while we index. */
710
+ async build(signal) {
711
+ this.building = true;
712
+ this.progress = { seen: 0, indexed: 0 };
713
+ const started = Date.now();
714
+ try {
715
+ const store = this.open();
716
+ let skipped = 0;
717
+ let bytes = 0;
718
+ let lines = 0;
719
+ let batch = [];
720
+ const flush = () => {
721
+ if (batch.length === 0) return;
722
+ store.db.exec('BEGIN');
723
+ try {
724
+ for (const item of batch) store.upsertFile(item.row, item.facts, item.lineRows);
725
+ store.db.exec('COMMIT');
726
+ } catch (error) {
727
+ store.db.exec('ROLLBACK');
728
+ throw error;
729
+ }
730
+ batch = [];
731
+ };
732
+ for await (const file of this.walk()) {
733
+ signal?.throwIfAborted?.();
734
+ this.progress.seen += 1;
735
+ const facts = await this.fileFacts(file);
736
+ if (!facts) {
737
+ skipped += 1;
738
+ continue;
739
+ }
740
+ bytes += facts.row.size;
741
+ lines += facts.row.lines;
742
+ batch.push(facts);
743
+ this.progress.indexed += 1;
744
+ if (batch.length >= 200) {
745
+ flush();
746
+ await delay(0); // stay responsive: the Host shares this thread
747
+ }
748
+ }
749
+ flush();
750
+ const now = new Date().toISOString();
751
+ store.putMeta('workspace', this.root);
752
+ store.putMeta('schema', SCHEMA_VERSION);
753
+ store.putMeta('indexedAt', now);
754
+ store.putMeta('stats', JSON.stringify({
755
+ filesSeen: this.progress.seen,
756
+ filesIndexed: this.progress.indexed,
757
+ filesSkipped: skipped,
758
+ bytesIndexed: bytes,
759
+ linesIndexed: lines,
760
+ elapsedMs: Date.now() - started,
761
+ fts: store.fts,
762
+ }));
763
+ this.lastScan = Date.now();
764
+ this.dirty.clear();
765
+ } finally {
766
+ this.building = false;
767
+ }
768
+ }
769
+
770
+ /** Lock-held incremental pass — see `refresh` for the public entry. */
771
+ async refreshStore({ paths, force = false, signal } = {}) {
772
+ const store = await this.ensureStore(signal);
773
+ if (!force && paths === undefined && Date.now() - this.lastScan < this.scanIntervalMs) return { changed: [], removed: [], scanned: false };
774
+ const rows = store.fileRows();
775
+ const changed = [];
776
+ const removed = [];
777
+ if (paths === undefined) {
778
+ const seen = new Set();
779
+ for await (const file of this.walk()) {
780
+ seen.add(file.rel);
781
+ const row = rows.get(file.rel);
782
+ if (!row) {
783
+ changed.push(file);
784
+ continue;
785
+ }
786
+ const info = await stat(file.abs).catch(() => undefined);
787
+ if (!info || !info.isFile() || info.mtimeMs !== row.mtimeMs || info.size !== row.size) changed.push(file);
788
+ }
789
+ for (const path of rows.keys()) if (!seen.has(path)) removed.push(path);
790
+ this.lastScan = Date.now();
791
+ this.dirty.clear(); // a full tree scan subsumes every queued path
792
+ } else {
793
+ for (const rel of new Set(paths)) {
794
+ if (!this.isIndexableRel(rel)) {
795
+ removed.push(rel); // dropped from the index if a stale row ever existed
796
+ continue;
797
+ }
798
+ const abs = join(this.root, rel);
799
+ const info = await stat(abs).catch(() => undefined);
800
+ const language = languageOf(rel);
801
+ if (!info || !info.isFile()) removed.push(rel);
802
+ else {
803
+ const row = rows.get(rel);
804
+ if (!row || row.mtimeMs !== info.mtimeMs || row.size !== info.size) changed.push({ abs, rel, language });
805
+ }
806
+ }
807
+ }
808
+ if (removed.length) {
809
+ store.db.exec('BEGIN');
810
+ try {
811
+ for (const path of removed) store.removeFileRows(path);
812
+ store.db.exec('COMMIT');
813
+ } catch (error) {
814
+ store.db.exec('ROLLBACK');
815
+ throw error;
816
+ }
817
+ }
818
+ const done = [];
819
+ for (const file of changed) {
820
+ signal?.throwIfAborted?.();
821
+ const facts = await this.fileFacts(file);
822
+ if (!facts) {
823
+ store.db.exec('BEGIN');
824
+ try { store.removeFileRows(file.rel); store.db.exec('COMMIT'); } catch (e) { store.db.exec('ROLLBACK'); throw e; }
825
+ removed.push(file.rel);
826
+ continue;
827
+ }
828
+ store.db.exec('BEGIN');
829
+ try {
830
+ store.upsertFile(facts.row, facts.facts, facts.lineRows);
831
+ store.db.exec('COMMIT');
832
+ } catch (error) {
833
+ store.db.exec('ROLLBACK');
834
+ throw error;
835
+ }
836
+ done.push(file.rel);
837
+ }
838
+ const touched = [...done, ...removed];
839
+ if (touched.length) {
840
+ store.markWikiStale(touched);
841
+ store.putMeta('updatedAt', new Date().toISOString());
842
+ }
843
+ if (paths !== undefined) for (const rel of paths) this.dirty.delete(rel); // flushed — changed or not
844
+ else for (const rel of touched) this.dirty.delete(rel);
845
+ return { changed: done, removed, scanned: true };
846
+ }
847
+
848
+ /**
849
+ * The incremental pass: a stat-only diff of the tree against `files`, or just the dirty set when `paths` is
850
+ * given (the fs-observed flush). Debounced by `scanIntervalMs` for tree scans.
851
+ */
852
+ async refresh(options = {}) {
853
+ return this.serial(() => this.refreshStore(options));
854
+ }
855
+
856
+ /**
857
+ * A workspace-relative path the index would ever hold: not escaping the root, no ignored or hidden component,
858
+ * and a recognized name. Shared by the dirty-path flush and `markDirty`.
859
+ */
860
+ isIndexableRel(rel) {
861
+ if (typeof rel !== 'string' || rel === '' || isAbsolute(rel)) return false;
862
+ const parts = rel.split('/');
863
+ if (parts.includes('..')) return false;
864
+ for (const part of parts.slice(0, -1)) {
865
+ if (this.ignoredDirs.has(part)) return false;
866
+ if (!this.includeHidden && part.startsWith('.')) return false;
867
+ }
868
+ const nameOf = parts[parts.length - 1];
869
+ if (!this.includeHidden && nameOf.startsWith('.') && !KNOWN_FILES.has(nameOf.toLowerCase())) return false;
870
+ return languageOf(nameOf) !== undefined;
871
+ }
872
+
873
+ /** `fs/observed` marked this absolute path; relative it and queue the debounced single-file flush. */
874
+ markDirty(absPath) {
875
+ const rel = relative(this.root, absPath).split(sep).join('/');
876
+ if (!this.isIndexableRel(rel)) return false;
877
+ this.dirty.add(rel);
878
+ if (this.flushTimer === undefined) {
879
+ this.flushTimer = setTimeout(() => {
880
+ this.flushTimer = undefined;
881
+ const pending = [...this.dirty];
882
+ this.refresh({ paths: pending }).catch(() => undefined);
883
+ }, DIRTY_FLUSH_MS);
884
+ this.flushTimer.unref?.();
885
+ }
886
+ return true;
887
+ }
888
+
889
+ state() {
890
+ const store = this.open();
891
+ const counts = store.counts();
892
+ const stats = safeParse(store.meta('stats') ?? '{}', {});
893
+ return {
894
+ workspace: this.root,
895
+ fingerprint: basename(this.dir),
896
+ state: this.building ? 'indexing' : counts.files === 0 ? 'empty' : this.dirty.size > 0 ? 'stale' : 'ready',
897
+ files: counts.files,
898
+ symbols: counts.symbols,
899
+ imports: counts.imports,
900
+ lines: counts.lines,
901
+ bytes: counts.bytes,
902
+ dirty: this.dirty.size,
903
+ indexedAt: store.meta('indexedAt'),
904
+ updatedAt: store.meta('updatedAt') ?? store.meta('indexedAt'),
905
+ stats,
906
+ stalePages: store.wikiStaleCount(),
907
+ fts: store.fts,
908
+ storageBytes: store.storageBytes(),
909
+ ...(this.building ? { progress: { ...this.progress } } : {}),
910
+ };
911
+ }
912
+
913
+ // ── Queries ────────────────────────────────────────────────────────────────────────────────────────────
914
+
915
+ /**
916
+ * Lexical recall + in-process re-rank. FTS5 (or the LIKE fallback) names candidate files; the stored `lines`
917
+ * rows are re-scored by term coverage and clustered into `path:line` chunks — no disk reads at query time.
918
+ */
919
+ async search(query, { limit = DEFAULT_SEARCH_LIMIT, path: pathPrefix, kinds } = {}) {
920
+ await this.serial(async () => {
921
+ await this.ensureStore();
922
+ await this.refreshStore();
923
+ });
924
+ const store = this.open();
925
+ const termList = terms(query);
926
+ const items = [];
927
+ const cap = Math.min(Math.max(1, Math.floor(limit)), MAX_SEARCH_LIMIT);
928
+ const prefix = pathPrefix ? `${pathPrefix.replace(/\/+$/, '')}/` : undefined;
929
+
930
+ // Symbol leg: name hits outrank text chunks (exact, then each term's prefix/substring).
931
+ if (termList.length > 0) {
932
+ const seen = new Set();
933
+ const queries = [...new Set([termList[0], ...termList.filter((t) => t.length >= 3)])];
934
+ for (const q of queries) {
935
+ for (const row of store.symbolRows({ query: q, path: prefix?.slice(0, -1), kinds, limit: cap })) {
936
+ const key = `${row.path}:${row.line}:${row.name}`;
937
+ if (seen.has(key)) continue;
938
+ seen.add(key);
939
+ const lname = row.name.toLowerCase();
940
+ items.push({
941
+ kind: 'symbol',
942
+ path: row.path,
943
+ line: row.line,
944
+ endLine: row.line,
945
+ name: row.name,
946
+ symbolKind: row.kind,
947
+ snippet: this.snippetFor(row.path, row.line),
948
+ score: 100 + (lname === q ? 12 : lname.startsWith(q) ? 6 : 0) + termList.length,
949
+ });
950
+ }
951
+ }
952
+ }
953
+
954
+ const rows = store.matchRows(matchExpression(query), termList, SEARCH_CANDIDATE_LIMIT);
955
+ const byPath = new Map();
956
+ for (const row of rows) {
957
+ if (prefix && !row.path.startsWith(prefix) && row.path !== prefix.slice(0, -1)) continue;
958
+ let list = byPath.get(row.path);
959
+ if (!list) byPath.set(row.path, (list = []));
960
+ list.push(row);
961
+ }
962
+ for (const [path, hits] of byPath) {
963
+ const scored = hits
964
+ .map((hit) => ({ ...hit, coverage: lineCoverage(hit.code ?? '', termList) }))
965
+ .filter((hit) => hit.coverage > 0)
966
+ .sort((a, b) => a.line - b.line);
967
+ const chunks = [];
968
+ for (const hit of scored) {
969
+ const last = chunks[chunks.length - 1];
970
+ if (last && hit.line - last.endLine <= SNIPPET_RADIUS * 2 + 1) {
971
+ last.endLine = hit.line;
972
+ last.score += hit.coverage;
973
+ } else {
974
+ chunks.push({ path, line: hit.line, endLine: hit.line, score: hit.coverage });
975
+ }
976
+ }
977
+ for (const chunk of chunks.sort((a, b) => b.score - a.score).slice(0, 2)) {
978
+ items.push({
979
+ kind: 'chunk',
980
+ path,
981
+ line: chunk.line,
982
+ endLine: chunk.endLine,
983
+ snippet: this.snippetFor(path, chunk.line, chunk.endLine),
984
+ score: 10 + chunk.score,
985
+ });
986
+ }
987
+ }
988
+
989
+ items.sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || a.line - b.line);
990
+ const seen = new Set();
991
+ const symbolLines = new Set(items.filter((i) => i.kind === 'symbol').map((i) => `${i.path}:${i.line}`));
992
+ const deduped = [];
993
+ for (const item of items) {
994
+ const key = `${item.path}:${item.line}:${item.name ?? ''}`;
995
+ if (seen.has(key)) continue;
996
+ if (item.kind === 'chunk' && symbolLines.has(`${item.path}:${item.line}`)) continue; // the symbol row covers it
997
+ seen.add(key);
998
+ deduped.push(item);
999
+ if (deduped.length >= cap) break;
1000
+ }
1001
+ return { items: deduped, total: deduped.length, terms: termList };
1002
+ }
1003
+
1004
+ /** ~5 lines around `line` (`endLine` widens the window), from the stored content. */
1005
+ snippetFor(path, line, endLine) {
1006
+ const from = Math.max(1, line - SNIPPET_RADIUS);
1007
+ const to = Math.max(line + SNIPPET_RADIUS, endLine ?? line);
1008
+ const rows = this.open().fileSlice(path, from, to).filter((row) => (row.code ?? '').trim() !== '');
1009
+ let out = rows.map((row) => row.code.trim()).join('\n');
1010
+ if (out.length > SNIPPET_MAX_CHARS) out = `${out.slice(0, SNIPPET_MAX_CHARS)}…`;
1011
+ return out;
1012
+ }
1013
+
1014
+ async symbols({ query, path, kinds, limit = 100 } = {}) {
1015
+ await this.serial(async () => {
1016
+ await this.ensureStore();
1017
+ await this.refreshStore();
1018
+ });
1019
+ const kindList = typeof kinds === 'string' && kinds ? kinds.split(',').map((k) => k.trim().toLowerCase()).filter(Boolean) : undefined;
1020
+ const items = this.open().symbolRows({ query: text(query), path: text(path), kinds: kindList, limit: Math.min(Math.max(1, Math.floor(limit)), 500) });
1021
+ return { items: items.map((row) => ({ path: row.path, kind: row.kind, name: row.name, line: row.line })) };
1022
+ }
1023
+
1024
+ async file(path) {
1025
+ const rel = requireRelative(path);
1026
+ await this.serial(async () => {
1027
+ await this.ensureStore();
1028
+ await this.refreshStore();
1029
+ });
1030
+ const row = this.open().fileRow(rel);
1031
+ if (!row) throw new RepoIndexError('not-found', `${rel} is not in the index.`, { path: rel });
1032
+ return { path: row.path, language: row.language, size: row.size, lines: row.lines, symbols: row.symbols, imports: row.imports };
1033
+ }
1034
+
1035
+ /**
1036
+ * The `repo_map` answer: top-level dirs with file/symbol counts and headliners, the external module ranking,
1037
+ * and top-dir → top-dir edges resolved from relative imports.
1038
+ */
1039
+ async map({ depth = 2 } = {}) {
1040
+ void depth;
1041
+ await this.serial(async () => {
1042
+ await this.ensureStore();
1043
+ await this.refreshStore();
1044
+ });
1045
+ const store = this.open();
1046
+ const dirs = store.topDirs().map((row) => ({
1047
+ dir: row.dir,
1048
+ files: row.files,
1049
+ bytes: row.bytes,
1050
+ symbols: store.dirSymbols(row.dir, 500).length,
1051
+ top: store.dirSymbols(row.dir, 5).map((s) => ({ name: s.name, kind: s.kind, path: s.path, line: s.line })),
1052
+ }));
1053
+ const knownPaths = store.fileRows();
1054
+ const { externals, edges } = this.dependencyRollup(store, knownPaths);
1055
+ return {
1056
+ dirs: dirs.slice(0, 40),
1057
+ externals: externals.slice(0, 40),
1058
+ edges: edges.slice(0, 40),
1059
+ };
1060
+ }
1061
+
1062
+ /** Shared by `map` and the dependencies page: external module ranking + top-dir edges from relative imports. */
1063
+ dependencyRollup(store, knownPaths) {
1064
+ const external = new Map();
1065
+ const edges = new Map();
1066
+ for (const row of store.importRows()) {
1067
+ const module = row.module;
1068
+ if (module.startsWith('.') || module.startsWith('/')) {
1069
+ const target = resolveImport(row.path, module, knownPaths);
1070
+ if (target) {
1071
+ const from = topDir(row.path);
1072
+ const to = topDir(target);
1073
+ if (from !== to) {
1074
+ const key = `${from}→${to}`;
1075
+ const edge = edges.get(key) ?? { from, to, count: 0, path: row.path, line: row.line };
1076
+ edge.count += 1;
1077
+ edges.set(key, edge);
1078
+ }
1079
+ }
1080
+ } else if (!/^(crate|self|super|std|core|alloc)(::|$)/.test(module)) {
1081
+ const hit = external.get(module) ?? { module, count: 0, path: row.path, line: row.line };
1082
+ hit.count += 1;
1083
+ external.set(module, hit);
1084
+ }
1085
+ }
1086
+ return {
1087
+ externals: [...external.values()].sort((a, b) => b.count - a.count || (a.module < b.module ? -1 : 1)),
1088
+ edges: [...edges.values()].sort((a, b) => b.count - a.count || (a.from < b.from ? -1 : 1)),
1089
+ };
1090
+ }
1091
+
1092
+ // ── RepoWiki ──────────────────────────────────────────────────────────────────────────────────────────
1093
+
1094
+ /** Page ids the deterministic generator emits; `pages` args subset it. */
1095
+ static WIKI_PAGES = ['architecture', 'modules', 'dependencies', 'conventions'];
1096
+
1097
+ async wikiList() {
1098
+ await this.serial(async () => {
1099
+ await this.ensureStore();
1100
+ await this.refreshStore();
1101
+ });
1102
+ return {
1103
+ items: this.open().wikiRows().map((page) => ({
1104
+ id: page.id, title: page.title, stale: page.stale, updatedAt: page.updatedAt, sections: page.sections.length,
1105
+ })),
1106
+ };
1107
+ }
1108
+
1109
+ async wikiPage(id) {
1110
+ const pageId = requireId(id);
1111
+ await this.serial(async () => {
1112
+ await this.ensureStore();
1113
+ await this.refreshStore();
1114
+ });
1115
+ const row = this.open().wikiRow(pageId);
1116
+ if (!row) throw new RepoIndexError('not-found', `No wiki page ${JSON.stringify(pageId)} — generate the wiki first.`, { id: pageId });
1117
+ return { id: row.id, title: row.title, stale: row.stale, updatedAt: row.updatedAt, sections: row.sections };
1118
+ }
1119
+
1120
+ /**
1121
+ * Deterministic pages built from index facts — every sentence cites `path:line` rows that exist in the store.
1122
+ * `pages` subsets the four ids; absent = stale ∪ missing (regeneration touches only what changed). When the
1123
+ * caller or config names a provider/model, each section's prose is rewritten by the model — citations are
1124
+ * never model output; they are the index rows the section was built from.
1125
+ */
1126
+ async wikiGenerate({ provider, model, pages, llm, signal } = {}) {
1127
+ return this.serial(async () => {
1128
+ const store = await this.ensureStore(signal);
1129
+ await this.refreshStore({ force: true, signal });
1130
+ const wanted = Array.isArray(pages) && pages.length ? pages.filter((p) => WorkspaceIndex.WIKI_PAGES.includes(p)) : undefined;
1131
+ const existing = new Map(store.wikiRows().map((row) => [row.id, row]));
1132
+ const todo = wanted ?? WorkspaceIndex.WIKI_PAGES.filter((id) => !existing.has(id) || existing.get(id).stale);
1133
+ const written = [];
1134
+ const skipped = [];
1135
+ const synthesize = llm ? makeSynthesizer({ llm, provider, model, signal }) : undefined;
1136
+ for (const id of todo) {
1137
+ signal?.throwIfAborted?.();
1138
+ const page = await this.generatePage(id, store, synthesize);
1139
+ if (!page) {
1140
+ skipped.push(id);
1141
+ continue;
1142
+ }
1143
+ store.putWiki(page);
1144
+ written.push({ id: page.id, title: page.title, stale: false, updatedAt: page.updatedAt, sections: page.sections.length });
1145
+ }
1146
+ return { pages: written, skipped };
1147
+ });
1148
+ }
1149
+
1150
+ async generatePage(id, store, synthesize) {
1151
+ const now = new Date().toISOString();
1152
+ const finish = async (title, sections) => {
1153
+ const known = store.fileRows();
1154
+ const kept = sections
1155
+ .map((section) => ({ ...section, citations: section.citations.filter((cite) => cite && known.has(cite.path)) }))
1156
+ .filter((section) => section.text && section.citations.length > 0);
1157
+ if (kept.length === 0) return undefined;
1158
+ if (synthesize) {
1159
+ for (const section of kept) {
1160
+ const evidence = section.citations.slice(0, 8).map((cite) => `[${cite.path}:${cite.line}] ${cite.note ?? ''}`).join('\n');
1161
+ const better = await synthesize({ title: section.title, text: section.text, evidence });
1162
+ if (better) section.text = better;
1163
+ }
1164
+ }
1165
+ const sources = [...new Set(kept.flatMap((section) => section.citations.map((cite) => cite.path)))].slice(0, 400);
1166
+ return { id, title, sections: kept.slice(0, WIKI_PAGE_CAP * 3), sources, updatedAt: now, stale: false };
1167
+ };
1168
+
1169
+ switch (id) {
1170
+ case 'architecture': return finish('Architecture', this.pageArchitecture(store));
1171
+ case 'modules': return finish('Modules', this.pageModules(store));
1172
+ case 'dependencies': return finish('Dependencies', this.pageDependencies(store));
1173
+ case 'conventions': return finish('Conventions', this.pageConventions(store));
1174
+ default: return undefined;
1175
+ }
1176
+ }
1177
+
1178
+ pageArchitecture(store) {
1179
+ const sections = [];
1180
+ const counts = store.counts();
1181
+ const langs = store.languageCounts();
1182
+ const langText = langs.slice(0, 4).map((row) => `${row.files} ${row.language}`).join(', ');
1183
+ const cites = [];
1184
+ for (const manifest of ['package.json', 'Cargo.toml', 'pyproject.toml', 'Package.swift', 'go.mod', 'README.md', 'pnpm-workspace.yaml']) {
1185
+ if (store.fileRow(manifest)) cites.push({ path: manifest, line: 1, note: `Root ${manifest}` });
1186
+ }
1187
+ const lead = langs[0];
1188
+ if (lead) {
1189
+ const example = store.db.prepare('SELECT path FROM files WHERE language = ? ORDER BY path LIMIT 1').get(lead.language)?.path;
1190
+ if (example) cites.push({ path: example, line: 1, note: `One of ${lead.files} ${lead.language} files` });
1191
+ }
1192
+ if (cites.length > 0) {
1193
+ sections.push({
1194
+ id: 'shape', title: 'Shape',
1195
+ text: `This workspace has ${counts.files} indexed files (${counts.lines.toLocaleString('en-US')} lines) — ${langText || 'no recognized code'} — with ${counts.symbols} symbols and ${counts.imports} imports on record.`,
1196
+ citations: cites.slice(0, 8),
1197
+ });
1198
+ }
1199
+
1200
+ const entryCites = [];
1201
+ const entryNotes = [];
1202
+ for (const manifest of ['package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod', 'Package.swift']) {
1203
+ if (!store.fileRow(manifest)) continue;
1204
+ const manifestLines = store.fileLines(manifest);
1205
+ for (const needle of ['"main"', '"exports"', '"bin"', '[lib]', '[[bin]]']) {
1206
+ const hit = manifestLines.find((row) => (row.code ?? '').includes(needle));
1207
+ if (hit) {
1208
+ entryCites.push({ path: manifest, line: hit.line, note: `${manifest} ${needle}` });
1209
+ entryNotes.push(`${manifest} declares ${needle}`);
1210
+ break;
1211
+ }
1212
+ }
1213
+ }
1214
+ const entryNames = new Set(['index.ts', 'index.tsx', 'index.js', 'main.ts', 'main.rs', 'lib.rs', 'main.py', '__main__.py', 'main.go', 'app.swift']);
1215
+ for (const path of store.fileRows().keys()) {
1216
+ if (entryNames.has(basename(path).toLowerCase())) entryCites.push({ path, line: 1, note: `Entry point ${basename(path)}` });
1217
+ if (entryCites.length >= 14) break;
1218
+ }
1219
+ if (entryCites.length > 0) {
1220
+ sections.push({
1221
+ id: 'entry-points', title: 'Entry points',
1222
+ text: entryNotes.length ? `Code enters through ${entryNotes.slice(0, 3).join('; ')}; the conventional entry files are cited alongside.` : 'The conventional entry files are cited below.',
1223
+ citations: entryCites.slice(0, 12),
1224
+ });
1225
+ }
1226
+
1227
+ const dirs = store.topDirs().slice(0, 8);
1228
+ if (dirs.length > 1) {
1229
+ sections.push({
1230
+ id: 'layout', title: 'Top-level layout',
1231
+ text: `The tree spreads across ${dirs.length} populated top-level directories; the largest are ${dirs.slice(0, 3).map((d) => `${d.dir === '.' ? 'the root' : `${d.dir}/`} (${d.files} files)`).join(', ')}.`,
1232
+ citations: dirs.flatMap((d) => {
1233
+ const file = store.firstPathUnder(d.dir);
1234
+ return file ? [{ path: file, line: 1, note: `${d.dir === '.' ? 'root' : `${d.dir}/`}: ${d.files} files` }] : [];
1235
+ }).slice(0, 8),
1236
+ });
1237
+ }
1238
+ return sections;
1239
+ }
1240
+
1241
+ pageModules(store) {
1242
+ const sections = [];
1243
+ for (const dir of store.topDirs().slice(0, WIKI_PAGE_CAP)) {
1244
+ const headliners = store.dirSymbols(dir.dir, 6);
1245
+ const label = dir.dir === '.' ? 'Root files' : `${dir.dir}/`;
1246
+ const listing = headliners.slice(0, 5).map((s) => `\`${s.name}\` (${s.kind})`).join(', ');
1247
+ sections.push({
1248
+ id: `dir-${dir.dir === '.' ? 'root' : dir.dir.replace(/[^\w-]+/g, '_')}`,
1249
+ title: label,
1250
+ text: listing
1251
+ ? `${label} holds ${dir.files} files. Notable symbols: ${listing}.`
1252
+ : `${label} holds ${dir.files} files of configuration, docs or assets.`,
1253
+ citations: headliners.map((s) => ({ path: s.path, line: s.line, note: `${s.kind} ${s.name}` })),
1254
+ });
1255
+ }
1256
+ return sections;
1257
+ }
1258
+
1259
+ pageDependencies(store) {
1260
+ const sections = [];
1261
+ const knownPaths = store.fileRows();
1262
+ const { externals, edges } = this.dependencyRollup(store, knownPaths);
1263
+ const external = externals.slice(0, 20);
1264
+ if (external.length > 0) {
1265
+ sections.push({
1266
+ id: 'external', title: 'External packages',
1267
+ text: `The workspace imports ${external.length} distinct external modules; the heaviest are ${external.slice(0, 5).map((e) => `\`${e.module}\` (${e.count}×)`).join(', ')}.`,
1268
+ citations: external.map((e) => ({ path: e.path, line: e.line, note: `imports ${e.module}` })),
1269
+ });
1270
+ }
1271
+ const wiring = edges.slice(0, 15);
1272
+ if (wiring.length > 0) {
1273
+ sections.push({
1274
+ id: 'internal', title: 'Internal wiring',
1275
+ text: `Across the top-level directories, the strongest dependency edges are ${wiring.slice(0, 5).map((e) => `${e.from === '.' ? 'root' : `${e.from}/`} → ${e.to === '.' ? 'root' : `${e.to}/`} (${e.count}×)`).join(', ')}.`,
1276
+ citations: wiring.map((e) => ({ path: e.path, line: e.line, note: `${e.from} → ${e.to}` })),
1277
+ });
1278
+ }
1279
+ return sections;
1280
+ }
1281
+
1282
+ pageConventions(store) {
1283
+ const sections = [];
1284
+ const paths = [...store.fileRows().keys()];
1285
+ const testFiles = paths.filter((p) => /(^|\/)(test|tests|__tests__|__test__|spec|fixtures?|testdata)\//.test(p) || /\.(test|spec)\.[^.]+$/.test(p) || /(_test|_spec)\.[^.]+$/.test(p) || /^(test|spec|tests)_/.test(basename(p)));
1286
+ if (testFiles.length > 0) {
1287
+ sections.push({
1288
+ id: 'tests', title: 'Tests',
1289
+ text: `${testFiles.length} files follow the test convention (\`*.test.*\`, \`*_test.*\`, \`test_*\`, or a tests/ directory).`,
1290
+ citations: testFiles.slice(0, 8).map((p) => ({ path: p, line: 1 })),
1291
+ });
1292
+ }
1293
+ const configNames = ['package.json', 'tsconfig.json', 'tsconfig.base.json', 'pnpm-workspace.yaml', 'turbo.json', 'Cargo.toml', 'pyproject.toml', 'Package.swift', 'vitest.config.ts', '.editorconfig'];
1294
+ const configs = configNames.filter((file) => store.fileRow(file));
1295
+ if (configs.length > 0) {
1296
+ sections.push({
1297
+ id: 'configuration', title: 'Configuration',
1298
+ text: `Build and tooling config lives at the root: ${configs.map((c) => `\`${c}\``).join(', ')}.`,
1299
+ citations: configs.map((c) => ({ path: c, line: 1 })),
1300
+ });
1301
+ }
1302
+ const styles = { kebab: 0, camel: 0, snake: 0, pascal: 0 };
1303
+ const exampleOf = { kebab: undefined, camel: undefined, snake: undefined, pascal: undefined };
1304
+ for (const p of paths) {
1305
+ const stem = basename(p).replace(/\.[^.]+$/, '');
1306
+ let style;
1307
+ if (/^[a-z][a-z0-9]*(-[a-z0-9]+)+$/.test(stem)) style = 'kebab';
1308
+ else if (/^[a-z][a-z0-9]*(_[a-z0-9]+)+$/.test(stem)) style = 'snake';
1309
+ else if (/^[A-Z][A-Za-z0-9]*$/.test(stem)) style = 'pascal';
1310
+ else if (/^[a-z]+[A-Z][A-Za-z0-9]*$/.test(stem)) style = 'camel';
1311
+ if (style) {
1312
+ styles[style] += 1;
1313
+ exampleOf[style] ??= p;
1314
+ }
1315
+ }
1316
+ const dominant = Object.entries(styles).sort((a, b) => b[1] - a[1])[0];
1317
+ if (dominant && dominant[1] > 0 && exampleOf[dominant[0]]) {
1318
+ sections.push({
1319
+ id: 'naming', title: 'Naming',
1320
+ text: `Filenames lean ${dominant[0]}-case (${dominant[1]} of ${paths.length} indexed files).`,
1321
+ citations: [{ path: exampleOf[dominant[0]], line: 1 }],
1322
+ });
1323
+ }
1324
+ const readmes = paths.filter((p) => /^readme(\.[^.]+)?$/i.test(basename(p))).slice(0, 8);
1325
+ if (readmes.length > 0) {
1326
+ sections.push({
1327
+ id: 'docs', title: 'Documentation',
1328
+ text: `${readmes.length} README files document the tree in place.`,
1329
+ citations: readmes.map((p) => ({ path: p, line: 1 })),
1330
+ });
1331
+ }
1332
+ return sections;
1333
+ }
1334
+
1335
+ /**
1336
+ * "How does X work": retrieve → gate → (route ? synthesize : excerpt). No retrieval → `grounded: false` and no
1337
+ * model call (the grounding gate); synthesized answers keep only citations that exist in the index.
1338
+ */
1339
+ async wikiAsk({ question, limit = 8, llm, provider, model, signal } = {}) {
1340
+ const q = requireString(question, 'question');
1341
+ const { items } = await this.search(q, { limit: Math.min(Math.max(1, Math.floor(limit)), 16) });
1342
+ if (items.length === 0) {
1343
+ return {
1344
+ question: q,
1345
+ answer: 'This does not appear in the workspace index — no file, symbol or doc matches. Reindex if the code is new, or rephrase with a symbol or file name.',
1346
+ citations: [],
1347
+ grounded: false,
1348
+ synthesized: false,
1349
+ };
1350
+ }
1351
+ const citations = items.slice(0, 10).map((item) => ({ path: item.path, line: item.line, snippet: (item.snippet ?? '').split('\n')[0] }));
1352
+ const route = provider && model ? { provider, model } : undefined;
1353
+ const store = this.open();
1354
+ if (!route || !llm) {
1355
+ return {
1356
+ question: q,
1357
+ answer: `The index has ${items.length} relevant place${items.length === 1 ? '' : 's'} for this question. Open the citations to read the code — the top hit is ${items[0].path}:${items[0].line}.`,
1358
+ citations,
1359
+ grounded: true,
1360
+ synthesized: false,
1361
+ };
1362
+ }
1363
+ const context = [];
1364
+ let bytes = 0;
1365
+ for (const item of items.slice(0, 10)) {
1366
+ for (const row of store.fileSlice(item.path, item.line, Math.min(item.endLine, item.line + ASK_CONTEXT_LINES))) {
1367
+ const entry = `[${item.path}:${row.line}] ${row.code}`;
1368
+ if (bytes + entry.length > ASK_MAX_INPUT_BYTES) break;
1369
+ bytes += entry.length;
1370
+ context.push(entry);
1371
+ }
1372
+ if (bytes > ASK_MAX_INPUT_BYTES) break;
1373
+ }
1374
+ const system = 'You answer questions about a code workspace using only the supplied index excerpts. Every claim must end with a [path:line] marker copied verbatim from the excerpts. If the excerpts do not answer the question, say that plainly instead of guessing. Be terse — three sentences at most; a Sources list is added for you.';
1375
+ const input = `Question: ${q}\n\nIndex excerpts:\n${context.join('\n')}`;
1376
+ const synthesized = await callLlm(llm, { ...route, system, input, signal, purpose: 'repowiki-ask' });
1377
+ if (!synthesized) {
1378
+ return { question: q, answer: `The index has ${items.length} relevant places, but the model route refused to answer. Open the citations to read the code.`, citations, grounded: true, synthesized: false };
1379
+ }
1380
+ const citedPaths = new Set(store.fileRows().keys());
1381
+ const parsed = [];
1382
+ for (const match of synthesized.matchAll(/\[?([A-Za-z0-9_./@-]+\.[A-Za-z0-9]+):(\d+)\]?/g)) {
1383
+ const rel = citedPaths.has(match[1]) ? match[1] : match[1].replace(/^\.\//, '');
1384
+ if (!citedPaths.has(rel)) continue;
1385
+ const line = Number(match[2]);
1386
+ if (!parsed.some((c) => c.path === rel && c.line === line)) parsed.push({ path: rel, line });
1387
+ }
1388
+ const valid = parsed.slice(0, WIKI_CITATION_CAP);
1389
+ const merged = valid.length > 0 ? valid.map((c) => ({ ...c, snippet: this.snippetFor(c.path, c.line).split('\n')[0] })) : citations;
1390
+ return {
1391
+ question: q,
1392
+ answer: synthesized.trim(),
1393
+ citations: merged,
1394
+ grounded: true,
1395
+ synthesized: true,
1396
+ cited: valid.length > 0,
1397
+ provider: route.provider,
1398
+ model: route.model,
1399
+ };
1400
+ }
1401
+
1402
+ dispose() {
1403
+ if (this.flushTimer) clearTimeout(this.flushTimer);
1404
+ this.flushTimer = undefined;
1405
+ this.store?.close();
1406
+ }
1407
+ }
1408
+
1409
+ /**
1410
+ * Resolve a relative import specifier (`./x`, `../y/z`, `/abs`) against the importer's path — the index can't see
1411
+ * outside the workspace, so `..` above the root drops to nothing. Returns the matched stored path or undefined.
1412
+ */
1413
+ export function resolveImport(fromPath, specifier, knownPaths) {
1414
+ const fromDir = dirname(fromPath);
1415
+ const parts = [];
1416
+ const joined = specifier.startsWith('/') ? specifier : join(fromDir === '.' ? '' : fromDir, specifier);
1417
+ for (const part of joined.split('/')) {
1418
+ if (part === '..') {
1419
+ if (parts.length === 0) return undefined;
1420
+ parts.pop();
1421
+ } else if (part !== '.' && part !== '') parts.push(part);
1422
+ }
1423
+ const stem = parts.join('/');
1424
+ for (const candidate of [stem, `${stem}.ts`, `${stem}.tsx`, `${stem}.js`, `${stem}.jsx`, `${stem}.mjs`, `${stem}.cjs`, `${stem}.mts`, `${stem}.rs`, `${stem}.py`, `${stem}.swift`, `${stem}.go`, `${stem}/index.ts`, `${stem}/index.tsx`, `${stem}/index.js`, `${stem}/mod.rs`, `${stem}/__init__.py`, `${stem}/main.swift`]) {
1425
+ if (knownPaths.has(candidate)) return candidate;
1426
+ }
1427
+ return undefined;
1428
+ }
1429
+
1430
+ /** Optional LLM polish for generated wiki sections: the model writes prose; citations stay index-gathered. */
1431
+ function makeSynthesizer({ llm, provider, model, signal }) {
1432
+ if (!provider || !model || typeof llm?.prepareCall !== 'function') return undefined;
1433
+ return async ({ title, text: body, evidence }) => {
1434
+ const instruction = 'Rewrite this RepoWiki section for a developer new to the repo. One short paragraph, plain words, no invented facts; keep the [path:line] citation markers verbatim where they belong.';
1435
+ const input = `Section: ${title}\nDraft: ${body}\n\nEvidence (cite only these):\n${evidence}`;
1436
+ return callLlm(llm, { provider, model, system: instruction, input, signal, purpose: 'repowiki-generate', maxTokens: 800 });
1437
+ };
1438
+ }
1439
+
1440
+ /** One auxiliary model call through dsh's llm service: prepareCall → stream → assembled text (deltas or blocks). */
1441
+ async function callLlm(llm, { provider, model, system, input, signal, purpose, maxTokens = ASK_MAX_OUTPUT_TOKENS }) {
1442
+ try {
1443
+ const call = await llm.prepareCall({ provider, model, maxTokens }, signal);
1444
+ const options = {
1445
+ ...call.config,
1446
+ messages: [{ role: 'user', content: [{ type: 'text', text: input }], source: { kind: SOURCE_KIND, form: purpose } }],
1447
+ system,
1448
+ purpose,
1449
+ signal,
1450
+ };
1451
+ const byIndex = new Map();
1452
+ const deadlineAt = Date.now() + ASK_TIMEOUT_MS;
1453
+ for await (const chunk of call.stream(options)) {
1454
+ if (Date.now() > deadlineAt) break;
1455
+ if (chunk?.type === 'text-delta' && typeof chunk.text === 'string') byIndex.set(chunk.index ?? 0, (byIndex.get(chunk.index ?? 0) ?? '') + chunk.text);
1456
+ else if (chunk?.type === 'block-end' && chunk.block?.type === 'text' && typeof chunk.block.text === 'string') byIndex.set(chunk.index ?? byIndex.size, chunk.block.text);
1457
+ }
1458
+ const out = [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([, textOut]) => textOut).join('\n').trim();
1459
+ return out || undefined;
1460
+ } catch {
1461
+ return undefined;
1462
+ }
1463
+ }
1464
+
1465
+ // ── The Remote service ───────────────────────────────────────────────────────────────────────────────────
1466
+
1467
+ export class RepoIndex {
1468
+ constructor(options) {
1469
+ this.storeRoot = resolve(options.storeRoot);
1470
+ this.config = options.config ?? {};
1471
+ this.llm = typeof options.llm === 'function' ? options.llm : () => options.llm;
1472
+ this.settings = typeof options.settings === 'function' ? options.settings : () => options.settings;
1473
+ this.credentials = typeof options.credentials === 'function' ? options.credentials : () => options.credentials;
1474
+ this.workingDirectory = typeof options.workingDirectory === 'function' ? options.workingDirectory : () => options.workingDirectory;
1475
+ this.processPath = options.processPath; // ctx.fs.processPath, when mounted
1476
+ this.workspaces = new Map();
1477
+ this.log = options.log ?? (() => undefined);
1478
+ }
1479
+
1480
+ /** Wire `cwd` → a WorkspaceIndex keyed on the resolved absolute path. */
1481
+ async workspace(cwd) {
1482
+ const raw = requireString(cwd, 'cwd');
1483
+ if (!isAbsolute(raw)) throw new RepoIndexError('bad-request', `cwd must be an absolute path (got ${JSON.stringify(raw)}).`, { cwd: raw });
1484
+ let abs;
1485
+ try {
1486
+ abs = await realpath(raw);
1487
+ } catch {
1488
+ throw new RepoIndexError('not-found', `${raw} does not exist or is not readable.`, { cwd: raw });
1489
+ }
1490
+ const info = await stat(abs).catch(() => undefined);
1491
+ if (!info?.isDirectory()) throw new RepoIndexError('not-found', `${raw} is not a directory.`, { cwd: raw });
1492
+ const key = workspaceDirName(abs);
1493
+ let ws = this.workspaces.get(key);
1494
+ if (!ws) {
1495
+ ws = new WorkspaceIndex({ root: abs, storeRoot: this.storeRoot, config: this.config, log: this.log });
1496
+ this.workspaces.set(key, ws);
1497
+ }
1498
+ return ws;
1499
+ }
1500
+
1501
+ async status(cwd) {
1502
+ const ws = await this.workspace(cwd);
1503
+ return ws.state(); // no ensure(): status never triggers the cold build
1504
+ }
1505
+
1506
+ async reindex(cwd, full, signal) {
1507
+ const ws = await this.workspace(cwd);
1508
+ if (full === true) {
1509
+ await ws.serial(async () => {
1510
+ ws.open().clearAll();
1511
+ await ws.build(signal);
1512
+ });
1513
+ } else {
1514
+ await ws.refresh({ force: true, signal });
1515
+ }
1516
+ return ws.state();
1517
+ }
1518
+
1519
+ async search(cwd, query, limit, path) {
1520
+ const q = requireString(query, 'query');
1521
+ const ws = await this.workspace(cwd);
1522
+ return ws.search(q, { limit: typeof limit === 'number' ? limit : DEFAULT_SEARCH_LIMIT, path: text(path) });
1523
+ }
1524
+
1525
+ async symbols(cwd, query, path, kinds, limit) {
1526
+ const ws = await this.workspace(cwd);
1527
+ return ws.symbols({ query: text(query), path: text(path), kinds: text(kinds), limit: typeof limit === 'number' ? limit : 100 });
1528
+ }
1529
+
1530
+ async file(cwd, path) {
1531
+ const ws = await this.workspace(cwd);
1532
+ return ws.file(path);
1533
+ }
1534
+
1535
+ async map(cwd, depth) {
1536
+ const ws = await this.workspace(cwd);
1537
+ return ws.map({ depth: typeof depth === 'number' ? depth : 2 });
1538
+ }
1539
+
1540
+ wikiList(cwd) { return this['wiki/list'](cwd); }
1541
+
1542
+ wikiPage(cwd, id) { return this['wiki/page'](cwd, id); }
1543
+
1544
+ wikiAsk(cwd, question, limit, provider, model, signal) { return this['wiki/ask'](cwd, question, limit, provider, model, signal); }
1545
+
1546
+ wikiGenerate(cwd, provider, model, pages, signal) { return this['wiki/generate'](cwd, provider, model, pages, signal); }
1547
+
1548
+ async 'wiki/list'(cwd) {
1549
+ const ws = await this.workspace(cwd);
1550
+ return ws.wikiList();
1551
+ }
1552
+
1553
+ async 'wiki/page'(cwd, id) {
1554
+ const ws = await this.workspace(cwd);
1555
+ return ws.wikiPage(id);
1556
+ }
1557
+
1558
+ /**
1559
+ * Route resolution: args (the Mac passes the thread's configured provider/model) → mount config. Before any
1560
+ * call the route's `apiKeyEnv` resolves through `ctx.credentials` — KIRO_PRISM_API_KEY for the default
1561
+ * kiro-prism route — so `authenticated` in the reply is true only when dsh actually holds the key. The value
1562
+ * itself never crosses this boundary.
1563
+ */
1564
+ async 'wiki/ask'(cwd, question, limit, provider, model, signal) {
1565
+ const ws = await this.workspace(cwd);
1566
+ const route = this.routeFor(provider, model);
1567
+ const llm = route ? this.llm() : undefined;
1568
+ if (route && llm) {
1569
+ const auth = await this.routeAuth(route.provider);
1570
+ if (auth === false) throw new RepoIndexError('credential-missing', `The ${route.provider} route names an API key dsh does not hold — add it in Settings › Providers, or ask without a route for the grounded excerpts.`, { provider: route.provider });
1571
+ }
1572
+ return ws.wikiAsk({ question, limit: typeof limit === 'number' ? limit : 8, llm, ...(route ?? {}), signal });
1573
+ }
1574
+
1575
+ async 'wiki/generate'(cwd, provider, model, pages, signal) {
1576
+ const ws = await this.workspace(cwd);
1577
+ const route = this.routeFor(provider, model);
1578
+ const llm = route ? this.llm() : undefined;
1579
+ if (route && llm) {
1580
+ const auth = await this.routeAuth(route.provider);
1581
+ if (auth === false) throw new RepoIndexError('credential-missing', `The ${route.provider} route names an API key dsh does not hold — add it in Settings › Providers, or generate without a route for the deterministic pages.`, { provider: route.provider });
1582
+ }
1583
+ const pageIds = Array.isArray(pages) ? pages.filter((p) => typeof p === 'string') : typeof pages === 'string' ? [pages] : undefined;
1584
+ return ws.wikiGenerate({ provider: route?.provider, model: route?.model, pages: pageIds, llm, signal });
1585
+ }
1586
+
1587
+ routeFor(provider, model) {
1588
+ const p = text(provider) ?? text(this.config.provider);
1589
+ const m = text(model) ?? text(this.config.model);
1590
+ return p && m ? { provider: p, model: m } : undefined;
1591
+ }
1592
+
1593
+ /**
1594
+ * Does dsh hold the key this route's profile names? `listConfigurableProviders` + `settings.describe` locate
1595
+ * the profile (the picasso-provider-models shape); a route with no `apiKeyEnv` needs no key. Unverifiable
1596
+ * stores answer `undefined` — ask proceeds and lets the adapter say so itself.
1597
+ */
1598
+ async routeAuth(provider) {
1599
+ let apiKeyEnv;
1600
+ try {
1601
+ const llm = this.llm();
1602
+ const directory = typeof llm?.listConfigurableProviders === 'function' ? llm.listConfigurableProviders() : [];
1603
+ const entry = (Array.isArray(directory) ? directory : []).find((candidate) => candidate.provider === provider);
1604
+ const settings = this.settings();
1605
+ const namespace = typeof settings?.describe === 'function' ? settings.describe().find((candidate) => candidate.ns === entry?.settingsNs) : undefined;
1606
+ let profile = namespace?.value;
1607
+ for (const key of entry?.settingsPath ?? []) profile = (isRecord(profile) || Array.isArray(profile)) ? profile[key] : undefined;
1608
+ apiKeyEnv = text(profile?.apiKeyEnv);
1609
+ } catch {
1610
+ apiKeyEnv = undefined;
1611
+ }
1612
+ if (!apiKeyEnv) return true; // nothing to resolve — the adapter may be keyless or hold its own
1613
+ const credentials = this.credentials();
1614
+ if (!credentials || typeof credentials.resolve !== 'function') return undefined;
1615
+ try {
1616
+ const hit = await credentials.resolve(apiKeyEnv);
1617
+ return typeof hit?.value === 'string' && hit.value.trim() !== '';
1618
+ } catch {
1619
+ return undefined;
1620
+ }
1621
+ }
1622
+
1623
+ /** `fs/observed` listener: an absolute path under a known workspace marks it dirty. */
1624
+ observeFs(target) {
1625
+ const abs = this.pathOf(target);
1626
+ if (!abs) return;
1627
+ for (const ws of this.workspaces.values()) ws.markDirty(abs);
1628
+ // Workspace roots are realpath'd; incoming paths may ride through a symlink (/tmp → /private/tmp).
1629
+ realpath(abs).then((resolved) => {
1630
+ if (resolved !== abs) for (const ws of this.workspaces.values()) ws.markDirty(resolved);
1631
+ }).catch(() => undefined);
1632
+ }
1633
+
1634
+ pathOf(target) {
1635
+ if (target === null || typeof target !== 'object') return undefined;
1636
+ try {
1637
+ const processed = this.processPath?.(target);
1638
+ if (typeof processed === 'string' && isAbsolute(processed)) return processed;
1639
+ } catch { /* fall through to the structural fields */ }
1640
+ for (const key of ['path', 'absolutePath', 'hostPath']) {
1641
+ const value = target[key];
1642
+ if (typeof value === 'string' && isAbsolute(value)) return value;
1643
+ }
1644
+ return undefined;
1645
+ }
1646
+
1647
+ /** The agent's workspace root inside a tool call: dsh's workingDirectory service, then the agent's cwd. */
1648
+ async cwdOf(exec) {
1649
+ let cwd;
1650
+ try {
1651
+ cwd = await this.workingDirectory()?.ensure?.(exec?.agent, exec?.signal);
1652
+ } catch {
1653
+ cwd = undefined;
1654
+ }
1655
+ if (typeof cwd !== 'string' || !cwd) cwd = typeof exec?.agent?.cwd === 'string' ? exec.agent.cwd : undefined;
1656
+ if (!cwd) throw new RepoIndexError('no-workspace', 'This call has no workspace — run it inside a thread folder.');
1657
+ return cwd;
1658
+ }
1659
+
1660
+ dispose() {
1661
+ for (const ws of this.workspaces.values()) ws.dispose();
1662
+ this.workspaces.clear();
1663
+ }
1664
+ }
1665
+
1666
+ // Single-word names only: dsh's HTTP remote route is `/api/<service>/<method>`, so a method named `wiki/list` answered 404
1667
+ // ("HTTP 404 for repoIndex/wiki/list") and the Wiki never loaded. The slash-named methods above stay for direct callers.
1668
+ const REMOTE_METHODS = ['status', 'reindex', 'search', 'symbols', 'file', 'map', 'wikiList', 'wikiPage', 'wikiAsk', 'wikiGenerate'];
1669
+
1670
+ Object.defineProperty(RepoIndex.prototype, REMOTE_METHOD_DESCRIPTOR, {
1671
+ configurable: true,
1672
+ value: Object.freeze({ version: 1, methods: Object.freeze(REMOTE_METHODS.map((method) => Object.freeze({ method, invocation: Object.freeze({ kind: 'direct' }) }))) }),
1673
+ });
1674
+
1675
+ function requireString(value, field) {
1676
+ if (typeof value !== 'string' || value.length === 0 || value.length > 4096) throw new RepoIndexError('bad-request', `${field} must be a non-empty string.`);
1677
+ return value;
1678
+ }
1679
+
1680
+ function requireId(value) {
1681
+ const id = requireString(value, 'id');
1682
+ if (!/^[\w.-]{1,64}$/.test(id)) throw new RepoIndexError('bad-request', 'id must be a simple page id.');
1683
+ return id;
1684
+ }
1685
+
1686
+ function requireRelative(path) {
1687
+ const rel = requireString(path, 'path').replace(/^\.\//, '');
1688
+ if (isAbsolute(rel) || rel.split('/').includes('..')) throw new RepoIndexError('bad-request', 'path must be workspace-relative.', { path });
1689
+ return rel;
1690
+ }
1691
+
1692
+ // ── Model tools ──────────────────────────────────────────────────────────────────────────────────────────
1693
+
1694
+ function registerTools(ctx, service) {
1695
+ const tools = ctx.get('tools');
1696
+ if (!tools || typeof tools.register !== 'function') return () => undefined;
1697
+ const disposes = [];
1698
+ disposes.push(tools.register({
1699
+ name: 'repo_search',
1700
+ description:
1701
+ 'Search this workspace\'s code index — files, symbols, imports and line text — when you need to find where something lives or how it\'s named before reading code. Prefer it over a bare text search for "where/what is X" questions: hits carry path:line citations. The index is lexical (built on first use, refreshed as files change), so it answers instantly.',
1702
+ parameters: {
1703
+ type: 'object',
1704
+ properties: {
1705
+ query: { type: 'string', description: 'What to find — a symbol name, a phrase, or a question\'s keywords.' },
1706
+ path: { type: 'string', description: 'Optional subdirectory prefix to scope the search (e.g. "src/").' },
1707
+ limit: { type: 'integer', description: 'Max hits, default 20 (hard cap 50).', minimum: 1, maximum: 50 },
1708
+ },
1709
+ required: ['query'],
1710
+ additionalProperties: false,
1711
+ },
1712
+ output: {
1713
+ schema: { type: 'object' },
1714
+ render: (_args, value) => {
1715
+ const items = Array.isArray(value?.results) ? value.results : [];
1716
+ if (items.length === 0) return [{ type: 'text', text: 'No index hits.' }];
1717
+ return [{ type: 'text', text: items.map((i) => `${i.path}:${i.line}${i.name ? ` ${i.name}` : ''}${i.symbolKind ? ` (${i.symbolKind})` : ''}\n${i.snippet ?? ''}`).join('\n\n') }];
1718
+ },
1719
+ },
1720
+ isConcurrencySafe: () => true,
1721
+ async execute(args, exec) {
1722
+ const cwd = await service.cwdOf(exec);
1723
+ const ws = await service.workspace(cwd);
1724
+ const { items, total } = await ws.search(String(args?.query ?? ''), { limit: typeof args?.limit === 'number' ? args.limit : DEFAULT_SEARCH_LIMIT, path: text(args?.path) });
1725
+ return { results: items, total, root: cwd };
1726
+ },
1727
+ }));
1728
+ disposes.push(tools.register({
1729
+ name: 'repo_map',
1730
+ description:
1731
+ 'The workspace\'s shape from the code index: top-level directories with file/symbol counts and their notable symbols, the external modules it imports most, and which top-level directories depend on which. Use it to orient in an unfamiliar repo before drilling into files.',
1732
+ parameters: {
1733
+ type: 'object',
1734
+ properties: {
1735
+ depth: { type: 'integer', description: 'Reserved; directory granularity (1-3, default 2).', minimum: 1, maximum: 3 },
1736
+ },
1737
+ additionalProperties: false,
1738
+ },
1739
+ output: {
1740
+ schema: { type: 'object' },
1741
+ render: (_args, value) => {
1742
+ const dirs = Array.isArray(value?.dirs) ? value.dirs : [];
1743
+ const externals = Array.isArray(value?.externals) ? value.externals : [];
1744
+ const lines = ['Top-level directories:', ...dirs.slice(0, 12).map((d) => `- ${d.dir === '.' ? '(root)' : `${d.dir}/`}: ${d.files} files${d.top?.length ? ` — ${d.top.slice(0, 3).map((s) => s.name).join(', ')}` : ''}`)];
1745
+ if (externals.length) lines.push('', 'Heaviest imports:', ...externals.slice(0, 8).map((e) => `- ${e.module} (${e.count}×)`));
1746
+ return [{ type: 'text', text: lines.join('\n') }];
1747
+ },
1748
+ },
1749
+ isConcurrencySafe: () => true,
1750
+ async execute(args, exec) {
1751
+ const cwd = await service.cwdOf(exec);
1752
+ const ws = await service.workspace(cwd);
1753
+ const map = await ws.map({ depth: typeof args?.depth === 'number' ? args.depth : 2 });
1754
+ return { ...map, root: cwd };
1755
+ },
1756
+ }));
1757
+ return () => { for (const dispose of disposes) { try { dispose?.(); } catch { /* registration shape varies */ } } };
1758
+ }
1759
+
1760
+ // ── Cordis entry ─────────────────────────────────────────────────────────────────────────────────────────
1761
+
1762
+ /** `apply(ctx, config)` — provides `repoIndex` (Typert-bound), the tools, and the fs/observed invalidation feed. */
1763
+ export function apply(ctx, config = {}) {
1764
+ const storeRoot = isRecord(config) && typeof config.root === 'string' && config.root
1765
+ ? config.root
1766
+ : join(process.env.DSH_HOME || join(homedir(), '.dsh'), STORE_DIRNAME);
1767
+ const service = new RepoIndex({
1768
+ storeRoot,
1769
+ config: isRecord(config) ? config : {},
1770
+ llm: () => ctx.get('llm'),
1771
+ settings: () => ctx.get('settings'),
1772
+ credentials: () => ctx.get('credentials'),
1773
+ workingDirectory: () => ctx.get('workingDirectory'),
1774
+ // `ctx.fs` throws ("cannot get property "fs" without inject") in dsh 0.2.1-rc.5 unless the plugin injected it, and a
1775
+ // throw while reading it here failed the whole plugin (no `repoIndex` service, so the Wiki answered 404). Read it
1776
+ // lazily and treat a missing fs as "no processed path": `pathOf` falls back to the target's own fields.
1777
+ processPath: (target) => {
1778
+ try {
1779
+ const fs = ctx.fs;
1780
+ return typeof fs?.processPath === 'function' ? fs.processPath(target) : undefined;
1781
+ } catch {
1782
+ return undefined;
1783
+ }
1784
+ },
1785
+ });
1786
+ service.typertRemote = Object.freeze({ service, serviceKey: SERVICE_KEY, namespace: SERVICE_KEY });
1787
+ ctx.provide(SERVICE_KEY, service);
1788
+
1789
+ // Invalidation feed (PRD fallback seam, primary in v1): `fs/write-intent`/`fs/edit-intent` are the intent
1790
+ // hooks every dsh tool write/edit passes through (the picasso-checkpoints precedent); mark the touched path
1791
+ // dirty once `next()` has run so the debounced flush re-reads the landed bytes. `fs/observed` — emitted by
1792
+ // builds that publish a passive fs notification — feeds the same path when present. Anything neither sees
1793
+ // is still caught by the mtime/size scan on each query.
1794
+ const onIntent = async (target, actor, next) => {
1795
+ const intent = typeof next === 'function' ? await next() : undefined;
1796
+ service.observeFs(target);
1797
+ return intent;
1798
+ };
1799
+ ctx.on('fs/write-intent', onIntent);
1800
+ ctx.on('fs/edit-intent', onIntent);
1801
+ ctx.on('fs/observed', (target) => service.observeFs(target));
1802
+
1803
+ let disposeTools = () => undefined;
1804
+ if (typeof ctx.inject === 'function') {
1805
+ ctx.inject(['tools'], () => {
1806
+ disposeTools = registerTools(ctx, service);
1807
+ });
1808
+ } else {
1809
+ disposeTools = registerTools(ctx, service);
1810
+ }
1811
+
1812
+ // Opt-in grounding splice (config preStepInject, OFF by default): "how does X work" prompts get the index's
1813
+ // top hits folded into turn 1 as a sourced user message — the picasso-memory recall precedent.
1814
+ if (config.preStepInject === true) {
1815
+ ctx.on('agent/pre-step', async ({ agent, messages, step, signal }, next) => {
1816
+ const decision = await next();
1817
+ if (step !== 1 || decision?.kind === 'reject' || !Array.isArray(decision?.messages)) return decision;
1818
+ const prompt = decision.messages
1819
+ .filter((m) => m?.role === 'user' && (m.source === undefined || m.source?.kind === 'user'))
1820
+ .map((m) => (Array.isArray(m.content) ? m.content : []).map((p) => (p?.type === 'text' ? p.text : '')).join('\n'))
1821
+ .join('\n');
1822
+ if (!/\b(how does|how do|where is|where are|what does|what do)\b/i.test(prompt)) return decision;
1823
+ const cwd = await service.cwdOf({ agent, signal }).catch(() => undefined);
1824
+ if (!cwd) return decision;
1825
+ const ws = await service.workspace(cwd).catch(() => undefined);
1826
+ if (!ws) return decision;
1827
+ const { items } = await ws.search(prompt, { limit: 5 }).catch(() => ({ items: [] }));
1828
+ if (items.length === 0) return decision;
1829
+ const note = [
1830
+ '<system-reminder>',
1831
+ 'The workspace index matched this prompt; the cited lines are the verified grounding (read the files before claiming more).',
1832
+ ...items.map((i) => `- ${i.path}:${i.line}${i.name ? ` ${i.name}` : ''}`),
1833
+ '</system-reminder>',
1834
+ ].join('\n');
1835
+ const message = Object.freeze({
1836
+ role: 'user',
1837
+ content: Object.freeze([Object.freeze({ type: 'text', text: note })]),
1838
+ source: Object.freeze({ kind: SOURCE_KIND, form: 'grounding', hits: Object.freeze(items.map((i) => `${i.path}:${i.line}`)) }),
1839
+ id: `repo-index-${Date.now()}`,
1840
+ });
1841
+ const lastClaimed = decision.messages.findLastIndex((m) => messages?.includes?.(m));
1842
+ return { ...decision, messages: decision.messages.toSpliced(lastClaimed + 1, 0, message) };
1843
+ });
1844
+ }
1845
+
1846
+ return () => {
1847
+ disposeTools();
1848
+ service.dispose();
1849
+ };
1850
+ }