ctxtop 0.0.0-stage → 4.1.0

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 (262) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +166 -0
  4. package/LICENSE +27 -0
  5. package/README.md +350 -2
  6. package/SECURITY.md +22 -0
  7. package/agents/ah-flash-scout.md +25 -0
  8. package/assets/advanced_view_loaded_420px.png +0 -0
  9. package/assets/hero-demo.svg +188 -0
  10. package/assets/logo.svg +19 -0
  11. package/assets/simple_view_lean_420px.png +0 -0
  12. package/assets/simple_view_loaded_420px.png +0 -0
  13. package/assets/social-preview.svg +72 -0
  14. package/assets/zone_c_step3_shield_full.png +0 -0
  15. package/bin/ah-statusline.mjs +175 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1799 -0
  18. package/commands/cost-radar.md +11 -0
  19. package/commands/evolve.md +10 -0
  20. package/commands/handoff.md +10 -0
  21. package/commands/horizon.md +10 -0
  22. package/commands/inspect.md +10 -0
  23. package/commands/precheck.md +10 -0
  24. package/config/default_flightcheck.json +133 -0
  25. package/config/modelCatalog.json +785 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +577 -0
  28. package/hooks/handlers/config-change.mjs +402 -0
  29. package/hooks/handlers/hookIo.mjs +311 -0
  30. package/hooks/handlers/hookIpcClient.mjs +83 -0
  31. package/hooks/handlers/post-model-switch.mjs +111 -0
  32. package/hooks/handlers/post-tool-use.mjs +366 -0
  33. package/hooks/handlers/pre-model-switch.mjs +1048 -0
  34. package/hooks/handlers/pre-tool-use.mjs +632 -0
  35. package/hooks/handlers/stop-gate.mjs +526 -0
  36. package/hooks/handlers/user-prompt-submit.mjs +367 -0
  37. package/hooks/hooks.json +131 -0
  38. package/hooks/post_invocation.mjs +13 -0
  39. package/hooks/post_tool_use.mjs +25 -0
  40. package/hooks/pre_invocation.mjs +14 -0
  41. package/hooks/pre_tool_use.mjs +97 -0
  42. package/hooks/register.js +726 -0
  43. package/hooks/session_start.mjs +24 -0
  44. package/hooks/stop.mjs +23 -0
  45. package/hooks.json +56 -0
  46. package/package.json +110 -4
  47. package/packages/antigravity/package.json +14 -0
  48. package/packages/antigravity/src/index.mjs +1 -0
  49. package/packages/claude-code/package.json +14 -0
  50. package/packages/claude-code/src/index.mjs +2 -0
  51. package/packages/core/package.json +14 -0
  52. package/packages/core/src/index.mjs +1 -0
  53. package/packages/engine-node/package.json +14 -0
  54. package/packages/engine-node/src/index.mjs +1 -0
  55. package/packages/mcp/package.json +17 -0
  56. package/packages/mcp/src/server.mjs +396 -0
  57. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  58. package/packages/pro/README-SIGNING.md +30 -0
  59. package/packages/pro/package.json +16 -0
  60. package/packages/pro/src/index.mjs +3 -0
  61. package/packages/pro/src/team_finops_pack.mjs +241 -0
  62. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  63. package/plugin.json +36 -0
  64. package/rules/AGENTS.md +10 -0
  65. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  66. package/sidecars/horizon-daemon/server.mjs +2038 -0
  67. package/sidecars/horizon-daemon/sidecar.json +19 -0
  68. package/skills/cost-radar/SKILL.md +21 -0
  69. package/skills/evolve/SKILL.md +21 -0
  70. package/skills/handoff/SKILL.md +50 -0
  71. package/skills/horizon/SKILL.md +17 -0
  72. package/skills/inspect/SKILL.md +18 -0
  73. package/skills/precheck/SKILL.md +44 -0
  74. package/src/adapters/antigravity/index.mjs +109 -0
  75. package/src/adapters/claude-code/index.mjs +194 -0
  76. package/src/cli/cost_radar.mjs +70 -0
  77. package/src/cli/doctor.mjs +351 -0
  78. package/src/cli/horizon_hud.mjs +888 -0
  79. package/src/cli/init.mjs +425 -0
  80. package/src/cli/postmortem.mjs +515 -0
  81. package/src/coach/cacheGravityRouter.mjs +12 -0
  82. package/src/config/modelCatalog.json +704 -0
  83. package/src/config/platformQuirks.json +19 -0
  84. package/src/core/action_queue.mjs +264 -0
  85. package/src/core/ag_bridge.mjs +346 -0
  86. package/src/core/atomic_io.mjs +124 -0
  87. package/src/core/baseline.mjs +607 -0
  88. package/src/core/blindspot_sensors.mjs +399 -0
  89. package/src/core/bucket_b_runtime.mjs +1200 -0
  90. package/src/core/classifier.mjs +1757 -0
  91. package/src/core/coach/circuit_breakers.mjs +650 -0
  92. package/src/core/coach/contradiction_auditor.mjs +239 -0
  93. package/src/core/coach/effort_advisor.mjs +143 -0
  94. package/src/core/coach/handoff_hydrator.mjs +483 -0
  95. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  96. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  97. package/src/core/coach/reflector_queue.mjs +505 -0
  98. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  99. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  100. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  101. package/src/core/coach/task_quota_router.mjs +955 -0
  102. package/src/core/coach/turn_zero_gate.mjs +574 -0
  103. package/src/core/compaction_coach.mjs +1126 -0
  104. package/src/core/config.mjs +214 -0
  105. package/src/core/constants.mjs +1987 -0
  106. package/src/core/detectors_det01_to_16.mjs +1523 -0
  107. package/src/core/doc_indexer.mjs +338 -0
  108. package/src/core/episodic_memory.mjs +135 -0
  109. package/src/core/fts5_output_compressor.mjs +359 -0
  110. package/src/core/git_ledger.mjs +189 -0
  111. package/src/core/handoff_audit.mjs +558 -0
  112. package/src/core/history.mjs +221 -0
  113. package/src/core/hook_diagnostics.mjs +158 -0
  114. package/src/core/horizon_classifier.mjs +326 -0
  115. package/src/core/horizon_config.mjs +802 -0
  116. package/src/core/host_watchdog.mjs +200 -0
  117. package/src/core/layer5_hygiene.mjs +1084 -0
  118. package/src/core/log_resolver.mjs +231 -0
  119. package/src/core/mcp_auditor.mjs +138 -0
  120. package/src/core/micro_skills_store.mjs +91 -0
  121. package/src/core/offenders.mjs +161 -0
  122. package/src/core/parser.mjs +1997 -0
  123. package/src/core/path_canonicalizer.mjs +73 -0
  124. package/src/core/paths.mjs +311 -0
  125. package/src/core/prefix_cache_shield.mjs +386 -0
  126. package/src/core/pro_license.mjs +385 -0
  127. package/src/core/prompt_rubric.mjs +518 -0
  128. package/src/core/pruner.mjs +433 -0
  129. package/src/core/quota.mjs +1860 -0
  130. package/src/core/rsi_instinct_engine.mjs +1197 -0
  131. package/src/core/rsl_clash_auditor.mjs +423 -0
  132. package/src/core/rsl_distiller.mjs +372 -0
  133. package/src/core/rsl_ledger.mjs +969 -0
  134. package/src/core/rsl_triage.mjs +909 -0
  135. package/src/core/sanitizer.mjs +121 -0
  136. package/src/core/session_auditor.mjs +658 -0
  137. package/src/core/session_forensics.mjs +303 -0
  138. package/src/core/session_timeline.mjs +358 -0
  139. package/src/core/settings.mjs +99 -0
  140. package/src/core/shared/detectors.mjs +1342 -0
  141. package/src/core/shared/fnv1a64.mjs +85 -0
  142. package/src/core/shared/handoff_schema.mjs +123 -0
  143. package/src/core/shared/index.mjs +5 -0
  144. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  145. package/src/core/shared/micro_skills.mjs +1 -0
  146. package/src/core/shared/plugin_validator.mjs +202 -0
  147. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  148. package/src/core/shield_manager.mjs +1417 -0
  149. package/src/core/sidecar_store.mjs +302 -0
  150. package/src/core/sprint_metrics.mjs +366 -0
  151. package/src/core/sqlite_client.mjs +283 -0
  152. package/src/core/storage_doctor.mjs +358 -0
  153. package/src/core/subagents.mjs +609 -0
  154. package/src/core/swarm_topology.mjs +360 -0
  155. package/src/core/task_quota_router.mjs +1656 -0
  156. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  157. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  158. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  159. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  160. package/src/core/timeline_svg.mjs +236 -0
  161. package/src/core/tool_surgeon.mjs +305 -0
  162. package/src/core/trajectory_stitcher.mjs +645 -0
  163. package/src/core/u_shaped_optimizer.mjs +789 -0
  164. package/src/core/wal_hygiene.mjs +233 -0
  165. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  166. package/src/core-isomorphic/catalog/index.mjs +1 -0
  167. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  168. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  169. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  170. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  171. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  172. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  173. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  174. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  175. package/src/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  176. package/src/core-isomorphic/config/anthropicModelCatalog.json +606 -0
  177. package/src/core-isomorphic/config/catalogLoader.mjs +1268 -0
  178. package/src/core-isomorphic/config/horizonConfig.mjs +1055 -0
  179. package/src/core-isomorphic/control/callTree.mjs +338 -0
  180. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  181. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  182. package/src/core-isomorphic/control/index.mjs +49 -0
  183. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  184. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  185. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  186. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  187. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  188. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  189. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  190. package/src/core-isomorphic/economics/cacheGravity.mjs +369 -0
  191. package/src/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  192. package/src/core-isomorphic/economics/driftLatency.mjs +433 -0
  193. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  194. package/src/core-isomorphic/economics/index.mjs +47 -0
  195. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  196. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  197. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  198. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  199. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  200. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  201. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  202. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  203. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  204. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  205. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  206. package/src/core-isomorphic/index.js +27 -0
  207. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  208. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  209. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  210. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  211. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1156 -0
  212. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  213. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  214. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  215. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1237 -0
  216. package/src/core-isomorphic/ui/modViews.mjs +1504 -0
  217. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  218. package/src/core-isomorphic/ustf/index.mjs +7 -0
  219. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  220. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  221. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  222. package/src/demo/synthetic_states.mjs +661 -0
  223. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  224. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  225. package/src/diagnostics/doctorEngine.mjs +295 -0
  226. package/src/engine-node/db/index.mjs +58 -0
  227. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  228. package/src/engine-node/db/probe.mjs +342 -0
  229. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  230. package/src/engine-node/index.mjs +12 -0
  231. package/src/engine-node/ipc/client.mjs +447 -0
  232. package/src/engine-node/ipc/index.mjs +22 -0
  233. package/src/engine-node/ipc/protocol.mjs +177 -0
  234. package/src/engine-node/ipc/server.mjs +445 -0
  235. package/src/engine-node/offloader/index.mjs +6 -0
  236. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  237. package/src/engine-node/sensors/blindspots.mjs +376 -0
  238. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  239. package/src/engine-node/sensors/index.mjs +7 -0
  240. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  241. package/src/hooks/claude_rsl_hook.mjs +288 -0
  242. package/src/hooks/portfolio_runtime.mjs +858 -0
  243. package/src/hooks/post_invocation.mjs +611 -0
  244. package/src/hooks/pre_invocation.mjs +1725 -0
  245. package/src/hooks/session_start.mjs +199 -0
  246. package/src/shims/agy_cli_compressor.mjs +705 -0
  247. package/src/shims/agy_git_guard.mjs +749 -0
  248. package/src/shims/ah_log_query.mjs +39 -0
  249. package/src/ui/costRadarSvg.mjs +6 -0
  250. package/src/ui/horizonGrid.mjs +1 -0
  251. package/src/ui/horizonPanelHtml.mjs +1 -0
  252. package/src/ui/horizon_panel.css +167 -0
  253. package/src/ui/horizon_panel.js +212 -0
  254. package/src/ui/modViews.mjs +1 -0
  255. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  256. package/src/utils/nodeIo.mjs +59 -0
  257. package/src/utils/runtime.mjs +1 -0
  258. package/src/utils/sessionCalibration.mjs +657 -0
  259. package/src/webview/advanced_view.html +1808 -0
  260. package/src/webview/horizon_panel.html +12397 -0
  261. package/src/webview/registry.mjs +80 -0
  262. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,338 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @file src/core/doc_indexer.mjs
4
+ * Zero-Token Structural Document & Log Indexer (`< 20ms`, zero LLM calls).
5
+ *
6
+ * Exposes programmatic helpers (`resolveIndexPath`, `checkIndex`, `buildIndex`, `sliceFile`)
7
+ * and CLI flags:
8
+ * - `--check <file> [--cwd <dir>]` -> exits `0` (`FRESH`), `1` (`STALE`), or `2` (`MISSING`)
9
+ * - `--build <file> [--cwd <dir>]` -> writes cached `.index.md` under `.agents/cache/indices/`
10
+ * - `--slice <file> <start_line> <end_line>` -> prints 1-indexed line-numbered output
11
+ */
12
+
13
+ import fs from 'node:fs';
14
+ import path from 'node:path';
15
+ import crypto from 'node:crypto';
16
+ import { fileURLToPath } from 'node:url';
17
+ import { atomicWriteFileSync } from './atomic_io.mjs';
18
+ import {
19
+ isForbiddenSkuPath,
20
+ compareIndexFreshness,
21
+ buildStructuralIndexMarkdown,
22
+ formatSlicedLines
23
+ } from '../core-isomorphic/guards/docIndexCore.mjs';
24
+
25
+ export { isForbiddenSkuPath, compareIndexFreshness, buildStructuralIndexMarkdown, formatSlicedLines };
26
+
27
+ /**
28
+ * Computes canonical LF-normalized SHA-256 hex digest of text content.
29
+ *
30
+ * @param {string} rawText
31
+ * @returns {string}
32
+ */
33
+ export function computeFileContentSha256(rawText = '') {
34
+ const normalized = String(rawText ?? '').replace(/\r\n/g, '\n');
35
+ return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex');
36
+ }
37
+
38
+ /**
39
+ * Resolves the gitignored `.agents/cache/indices/<slug>_<hash>.index.md` target path
40
+ * so indexing never dirties `git status` alongside workspace source files.
41
+ * Callers may pass `options.indexPath` when indexing an already-gitignored temp/cache file.
42
+ *
43
+ * @param {string} filePath
44
+ * @param {object} [options={}]
45
+ * @param {string} [options.cwd]
46
+ * @param {string} [options.indexPath]
47
+ * @returns {string}
48
+ */
49
+ export function resolveIndexPath(filePath, options = {}) {
50
+ if (typeof options.indexPath === 'string' && options.indexPath.trim()) {
51
+ return path.resolve(options.indexPath.trim());
52
+ }
53
+ const baseCwd = path.resolve(options.cwd || process.cwd());
54
+ const absFile = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(baseCwd, filePath);
55
+ const relRaw = path.relative(baseCwd, absFile).replace(/\\/g, '/');
56
+ const isInsideWorkspace = !relRaw.startsWith('..') && !path.isAbsolute(relRaw);
57
+
58
+ // If the file itself already lives inside a gitignored cache/tmp folder, allow adjacent `.index.md`
59
+ if (
60
+ isInsideWorkspace &&
61
+ /^(?:\.agents\/(?:tmp|cache|telemetry)|\.claude\/cache)\//i.test(relRaw)
62
+ ) {
63
+ return `${absFile}.index.md`;
64
+ }
65
+
66
+ const keyBasis = isInsideWorkspace ? relRaw : absFile.replace(/\\/g, '/');
67
+ const pathHash = crypto.createHash('sha256').update(keyBasis, 'utf8').digest('hex').slice(0, 12);
68
+ const safeSlug = (isInsideWorkspace ? relRaw : path.basename(absFile))
69
+ .replace(/[^A-Za-z0-9._-]+/g, '_')
70
+ .replace(/^_+|_+$/g, '')
71
+ .slice(-72);
72
+ return path.join(baseCwd, '.agents', 'cache', 'indices', `${safeSlug}_${pathHash}.index.md`);
73
+ }
74
+
75
+ function isBlockedTargetPath(absFile, baseCwd) {
76
+ const rel = path.relative(baseCwd, absFile).replace(/\\/g, '/');
77
+ return isForbiddenSkuPath(absFile) || isForbiddenSkuPath(rel);
78
+ }
79
+
80
+ /**
81
+ * Checks whether `<file>`'s structural index is `FRESH` (`0`), `STALE` (`1`), or `MISSING` (`2`).
82
+ *
83
+ * @param {string} filePath
84
+ * @param {object} [options={}]
85
+ * @returns {{ code: 0 | 1 | 2, status: 'FRESH' | 'STALE' | 'MISSING' | 'SKIPPED', indexPath: string, sha256: string | null }}
86
+ */
87
+ export function checkIndex(filePath, options = {}) {
88
+ const baseCwd = path.resolve(options.cwd || process.cwd());
89
+ const absFile = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(baseCwd, filePath);
90
+ const indexPath = resolveIndexPath(absFile, options);
91
+
92
+ if (isBlockedTargetPath(absFile, baseCwd)) {
93
+ return { code: 2, status: 'SKIPPED', indexPath, sha256: null };
94
+ }
95
+ if (!fs.existsSync(absFile) || !fs.statSync(absFile).isFile()) {
96
+ return { code: 2, status: 'MISSING', indexPath, sha256: null };
97
+ }
98
+
99
+ const rawText = fs.readFileSync(absFile, 'utf8');
100
+ const liveSha = computeFileContentSha256(rawText);
101
+ if (!fs.existsSync(indexPath)) {
102
+ return { code: 2, status: 'MISSING', indexPath, sha256: liveSha };
103
+ }
104
+ const indexMd = fs.readFileSync(indexPath, 'utf8');
105
+ const cmp = compareIndexFreshness(liveSha, indexMd);
106
+ return {
107
+ code: cmp.code,
108
+ status: cmp.status,
109
+ indexPath,
110
+ sha256: liveSha
111
+ };
112
+ }
113
+
114
+ /**
115
+ * Builds or refreshes the zero-token `.index.md` structural map for `<file>`.
116
+ *
117
+ * @param {string} filePath
118
+ * @param {object} [options={}]
119
+ * @returns {{
120
+ * ok: boolean,
121
+ * skipped: boolean,
122
+ * reason?: string,
123
+ * refreshed?: boolean,
124
+ * indexPath: string,
125
+ * relIndexPath: string,
126
+ * sha256: string | null,
127
+ * totalLines: number,
128
+ * spanCount: number,
129
+ * usedFallback: boolean,
130
+ * indexTokens: number,
131
+ * markdown: string
132
+ * }}
133
+ */
134
+ export function buildIndex(filePath, options = {}) {
135
+ const baseCwd = path.resolve(options.cwd || process.cwd());
136
+ const absFile = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(baseCwd, filePath);
137
+ const indexPath = resolveIndexPath(absFile, options);
138
+ const relIndexPath = path.relative(baseCwd, indexPath).replace(/\\/g, '/');
139
+
140
+ if (isBlockedTargetPath(absFile, baseCwd)) {
141
+ return {
142
+ ok: false,
143
+ skipped: true,
144
+ reason: 'SKU boundary: isolated directory excluded from ctxtop indexing',
145
+ indexPath,
146
+ relIndexPath,
147
+ sha256: null,
148
+ totalLines: 0,
149
+ spanCount: 0,
150
+ usedFallback: false,
151
+ indexTokens: 0,
152
+ markdown: ''
153
+ };
154
+ }
155
+
156
+ if (!fs.existsSync(absFile) || !fs.statSync(absFile).isFile()) {
157
+ return {
158
+ ok: false,
159
+ skipped: true,
160
+ reason: `Target file not found: ${absFile}`,
161
+ indexPath,
162
+ relIndexPath,
163
+ sha256: null,
164
+ totalLines: 0,
165
+ spanCount: 0,
166
+ usedFallback: false,
167
+ indexTokens: 0,
168
+ markdown: ''
169
+ };
170
+ }
171
+
172
+ const rawText = fs.readFileSync(absFile, 'utf8');
173
+ const liveSha = computeFileContentSha256(rawText);
174
+
175
+ if (!options.force && fs.existsSync(indexPath)) {
176
+ try {
177
+ const existingMd = fs.readFileSync(indexPath, 'utf8');
178
+ const cmp = compareIndexFreshness(liveSha, existingMd);
179
+ if (cmp.code === 0) {
180
+ const lineCount = rawText.length === 0 ? 0 : rawText.replace(/\r\n/g, '\n').split('\n').length;
181
+ return {
182
+ ok: true,
183
+ skipped: false,
184
+ refreshed: false,
185
+ indexPath,
186
+ relIndexPath,
187
+ sha256: liveSha,
188
+ totalLines: lineCount,
189
+ spanCount: Math.max(0, existingMd.split('\n').filter((l) => l.startsWith('| L')).length),
190
+ usedFallback: existingMd.includes('| Unstructured Span L'),
191
+ indexTokens: Math.max(1, Math.ceil(existingMd.length / 4)),
192
+ markdown: existingMd
193
+ };
194
+ }
195
+ } catch {
196
+ // Rebuild below
197
+ }
198
+ }
199
+
200
+ const relDisplay = path.relative(baseCwd, absFile).replace(/\\/g, '/');
201
+ const displayPath = !relDisplay.startsWith('..') && !path.isAbsolute(relDisplay)
202
+ ? relDisplay
203
+ : path.basename(absFile);
204
+
205
+ const built = buildStructuralIndexMarkdown({
206
+ filePath: absFile,
207
+ displayPath,
208
+ rawText,
209
+ sha256: liveSha
210
+ });
211
+
212
+ fs.mkdirSync(path.dirname(indexPath), { recursive: true });
213
+ atomicWriteFileSync(indexPath, built.markdown);
214
+
215
+ return {
216
+ ok: true,
217
+ skipped: false,
218
+ refreshed: true,
219
+ indexPath,
220
+ relIndexPath,
221
+ sha256: built.sha256,
222
+ totalLines: built.totalLines,
223
+ spanCount: built.spanCount,
224
+ usedFallback: built.usedFallback,
225
+ indexTokens: built.indexTokens,
226
+ markdown: built.markdown
227
+ };
228
+ }
229
+
230
+ /**
231
+ * Slices `<file>` between 1-indexed `startLine` and `endLine` inclusive across CRLF/LF.
232
+ *
233
+ * @param {string} filePath
234
+ * @param {number} startLine
235
+ * @param {number} endLine
236
+ * @param {object} [options={}]
237
+ * @returns {{ ok: boolean, skipped?: boolean, reason?: string, text: string, startLine: number, endLine: number, totalLines: number }}
238
+ */
239
+ export function sliceFile(filePath, startLine, endLine, options = {}) {
240
+ const baseCwd = path.resolve(options.cwd || process.cwd());
241
+ const absFile = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(baseCwd, filePath);
242
+ if (isBlockedTargetPath(absFile, baseCwd)) {
243
+ return {
244
+ ok: false,
245
+ skipped: true,
246
+ reason: 'SKU boundary: isolated directory excluded from ctxtop slicing',
247
+ text: '',
248
+ startLine: 0,
249
+ endLine: 0,
250
+ totalLines: 0
251
+ };
252
+ }
253
+ if (!fs.existsSync(absFile) || !fs.statSync(absFile).isFile()) {
254
+ return {
255
+ ok: false,
256
+ reason: `File not found: ${absFile}`,
257
+ text: '',
258
+ startLine: 0,
259
+ endLine: 0,
260
+ totalLines: 0
261
+ };
262
+ }
263
+ const rawText = fs.readFileSync(absFile, 'utf8');
264
+ const sliced = formatSlicedLines(rawText, startLine, endLine);
265
+ return {
266
+ ok: true,
267
+ ...sliced
268
+ };
269
+ }
270
+
271
+ /**
272
+ * CLI runner for `node src/core/doc_indexer.mjs <--check|--build|--slice> ...`.
273
+ *
274
+ * @param {string[]} [args=[]]
275
+ * @returns {{ exitCode: number, output: string }}
276
+ */
277
+ export function runDocIndexerCli(args = process.argv.slice(2)) {
278
+ const cwdIdx = args.indexOf('--cwd');
279
+ const cwd = cwdIdx !== -1 && args[cwdIdx + 1] ? path.resolve(args[cwdIdx + 1]) : process.cwd();
280
+ const outIdx = args.indexOf('--index-path');
281
+ const indexPath = outIdx !== -1 && args[outIdx + 1] ? path.resolve(args[outIdx + 1]) : undefined;
282
+ const opts = { cwd, ...(indexPath ? { indexPath } : {}) };
283
+
284
+ const checkIdx = args.indexOf('--check');
285
+ if (checkIdx !== -1 && args[checkIdx + 1]) {
286
+ const res = checkIndex(args[checkIdx + 1], opts);
287
+ return {
288
+ exitCode: res.code,
289
+ output: `${res.status} (${res.indexPath})`
290
+ };
291
+ }
292
+
293
+ const buildIdx = args.indexOf('--build');
294
+ if (buildIdx !== -1 && args[buildIdx + 1]) {
295
+ const res = buildIndex(args[buildIdx + 1], opts);
296
+ if (!res.ok) {
297
+ return {
298
+ exitCode: res.skipped ? 0 : 1,
299
+ output: res.reason || 'Skipped'
300
+ };
301
+ }
302
+ return {
303
+ exitCode: 0,
304
+ output: `${res.indexPath} (${res.totalLines} lines, ${res.spanCount} spans)`
305
+ };
306
+ }
307
+
308
+ const sliceIdx = args.indexOf('--slice');
309
+ if (sliceIdx !== -1 && args[sliceIdx + 1]) {
310
+ const target = args[sliceIdx + 1];
311
+ const start = Number(args[sliceIdx + 2] || 1);
312
+ const end = Number(args[sliceIdx + 3] || start + 149);
313
+ const res = sliceFile(target, start, end, opts);
314
+ if (!res.ok) {
315
+ return { exitCode: 1, output: res.reason || 'Slice failed' };
316
+ }
317
+ return { exitCode: 0, output: res.text };
318
+ }
319
+
320
+ return {
321
+ exitCode: 1,
322
+ output: 'Usage: doc_indexer.mjs <--check <file> | --build <file> | --slice <file> <start_line> <end_line>> [--cwd <dir>]'
323
+ };
324
+ }
325
+
326
+ const isMain = (() => {
327
+ try {
328
+ return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
329
+ } catch {
330
+ return false;
331
+ }
332
+ })();
333
+
334
+ if (isMain) {
335
+ const res = runDocIndexerCli();
336
+ if (res.output) process.stdout.write(`${res.output}\n`);
337
+ process.exit(res.exitCode);
338
+ }
@@ -0,0 +1,135 @@
1
+ import fs from 'node:fs';
2
+ import { openLocalHorizonDb } from './sqlite_client.mjs';
3
+
4
+ /**
5
+ * SQLite FTS5 Episodic Memory Bridge & `[▶ RESUME HERE]` Context Synthesizer.
6
+ *
7
+ * Maintains a local zero-network SQLite FTS5 index (`~/.gemini/flightcheck/episodic_memory.db`)
8
+ * storing compact session summaries, architectural decisions, modified files, and resolved errors,
9
+ * and synthesizes a `<1,000 token` (`<=4,000 chars`) `[▶ RESUME HERE]` context pack.
10
+ */
11
+
12
+ export async function upsertEpisodicMemory(dbPath, record = {}, { DatabaseSync } = {}) {
13
+ if (!dbPath) {
14
+ return { success: false, error: 'dbPath is required' };
15
+ }
16
+ const db = openLocalHorizonDb(dbPath, { readOnly: false, DatabaseSync });
17
+ try {
18
+ db.exec(`
19
+ CREATE TABLE IF NOT EXISTS episodic_sessions (
20
+ session_id TEXT PRIMARY KEY,
21
+ workspace_path TEXT,
22
+ title TEXT,
23
+ summary TEXT,
24
+ decisions TEXT,
25
+ modified_files TEXT,
26
+ updated_at TEXT
27
+ );
28
+ CREATE VIRTUAL TABLE IF NOT EXISTS episodic_fts USING fts5(
29
+ session_id UNINDEXED,
30
+ workspace_path,
31
+ title,
32
+ summary,
33
+ decisions,
34
+ modified_files
35
+ );
36
+ `);
37
+
38
+ const sessionId = String(record.sessionId || `sess-${Date.now()}`);
39
+ const workspacePath = String(record.workspacePath || '');
40
+ const title = String(record.title || 'Session');
41
+ const summary = String(record.summary || '');
42
+ const decisions = Array.isArray(record.decisions) ? record.decisions.join('\n') : String(record.decisions || '');
43
+ const modifiedFiles = Array.isArray(record.modifiedFiles) ? record.modifiedFiles.join(', ') : String(record.modifiedFiles || '');
44
+ const updatedAt = record.updatedAt || new Date().toISOString();
45
+
46
+ db.prepare(`
47
+ INSERT OR REPLACE INTO episodic_sessions (session_id, workspace_path, title, summary, decisions, modified_files, updated_at)
48
+ VALUES (?, ?, ?, ?, ?, ?, ?)
49
+ `).run(sessionId, workspacePath, title, summary, decisions, modifiedFiles, updatedAt);
50
+
51
+ db.prepare('DELETE FROM episodic_fts WHERE session_id = ?').run(sessionId);
52
+ db.prepare(`
53
+ INSERT INTO episodic_fts (session_id, workspace_path, title, summary, decisions, modified_files)
54
+ VALUES (?, ?, ?, ?, ?, ?)
55
+ `).run(sessionId, workspacePath, title, summary, decisions, modifiedFiles);
56
+
57
+ return { success: true, sessionId };
58
+ } finally {
59
+ try { db.close(); } catch {}
60
+ }
61
+ }
62
+
63
+ export async function queryEpisodicMemoryBm25(dbPath, { query = '', workspacePath = '', limit = 8, DatabaseSync } = {}) {
64
+ if (!dbPath || !fs.existsSync(dbPath)) {
65
+ return { hits: [] };
66
+ }
67
+ const db = openLocalHorizonDb(dbPath, { readOnly: true, DatabaseSync });
68
+ try {
69
+ const cleanQuery = String(query || '')
70
+ .replace(/[^A-Za-z0-9_\s]/g, ' ')
71
+ .trim()
72
+ .split(/\s+/)
73
+ .filter(Boolean)
74
+ .join(' OR ');
75
+
76
+ let rows = [];
77
+ if (cleanQuery) {
78
+ rows = db.prepare(`
79
+ SELECT session_id AS sessionId, workspace_path AS workspacePath, title, summary, decisions, modified_files AS modifiedFiles, bm25(episodic_fts) AS rank
80
+ FROM episodic_fts
81
+ WHERE episodic_fts MATCH ?
82
+ ORDER BY rank ASC
83
+ LIMIT ?
84
+ `).all(cleanQuery, Math.max(1, limit));
85
+ } else {
86
+ rows = db.prepare(`
87
+ SELECT session_id AS sessionId, workspace_path AS workspacePath, title, summary, decisions, modified_files AS modifiedFiles, 0.0 AS rank
88
+ FROM episodic_sessions
89
+ ORDER BY updated_at DESC
90
+ LIMIT ?
91
+ `).all(Math.max(1, limit));
92
+ }
93
+
94
+ if (workspacePath) {
95
+ const normWs = workspacePath.toLowerCase().replace(/\\/g, '/');
96
+ const filtered = rows.filter(r => String(r.workspacePath || '').toLowerCase().replace(/\\/g, '/').includes(normWs));
97
+ if (filtered.length > 0) rows = filtered;
98
+ }
99
+
100
+ return { hits: rows };
101
+ } catch {
102
+ return { hits: [] };
103
+ } finally {
104
+ try { db.close(); } catch {}
105
+ }
106
+ }
107
+
108
+ export async function synthesizeResumeHerePack(dbPath, { workspacePath = '', query = '', maxChars = 4000, DatabaseSync } = {}) {
109
+ const { hits } = await queryEpisodicMemoryBm25(dbPath, { query, workspacePath, limit: 5, DatabaseSync });
110
+ const lines = [
111
+ `# [▶ RESUME HERE] Episodic Context Pack`,
112
+ `- **Workspace**: \`${workspacePath || 'active'}\``,
113
+ `- **Matched Prior Sessions**: ${hits.length}`,
114
+ ``
115
+ ];
116
+
117
+ for (let i = 0; i < hits.length; i++) {
118
+ const h = hits[i];
119
+ lines.push(`## ${i + 1}. ${h.title} (\`${h.sessionId}\`)`);
120
+ if (h.summary) lines.push(`- **Summary**: ${String(h.summary).slice(0, 300)}`);
121
+ if (h.decisions) lines.push(`- **Decisions**: ${String(h.decisions).slice(0, 260)}`);
122
+ if (h.modifiedFiles) lines.push(`- **Files**: \`${String(h.modifiedFiles).slice(0, 240)}\``);
123
+ lines.push('');
124
+ }
125
+
126
+ const rawMarkdown = lines.join('\n').slice(0, maxChars);
127
+ const estimatedTokens = Math.ceil(rawMarkdown.length / 4);
128
+ return {
129
+ header: '[▶ RESUME HERE]',
130
+ hitCount: hits.length,
131
+ estimatedTokens,
132
+ withinTokenBudget: estimatedTokens <= 1000,
133
+ markdown: rawMarkdown
134
+ };
135
+ }