akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

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 (587) hide show
  1. package/CHANGELOG.md +1190 -52
  2. package/README.md +62 -37
  3. package/SECURITY.md +46 -31
  4. package/dist/akm +162 -38
  5. package/dist/akm-migrate +44 -0
  6. package/dist/assets/backends/schtasks-template.xml +2 -1
  7. package/dist/assets/hints/cli-hints-full.md +268 -118
  8. package/dist/assets/hints/cli-hints-short.md +87 -24
  9. package/dist/assets/{profiles → improve-strategies}/catchup.json +3 -1
  10. package/dist/assets/{profiles → improve-strategies}/consolidate.json +3 -1
  11. package/dist/assets/{profiles → improve-strategies}/default.json +6 -7
  12. package/dist/assets/improve-strategies/frequent.json +15 -0
  13. package/dist/assets/{profiles → improve-strategies}/graph-refresh.json +4 -2
  14. package/dist/assets/{profiles → improve-strategies}/memory-focus.json +4 -1
  15. package/dist/assets/{profiles → improve-strategies}/proactive-maintenance.json +5 -5
  16. package/dist/assets/{profiles → improve-strategies}/quick.json +4 -2
  17. package/dist/assets/improve-strategies/reflect-distill.json +30 -0
  18. package/dist/assets/{profiles → improve-strategies}/thorough.json +1 -1
  19. package/dist/assets/prompts/consolidate-system.md +5 -5
  20. package/dist/assets/prompts/extract-session.md +2 -6
  21. package/dist/assets/prompts/memory-infer-user.md +2 -3
  22. package/dist/assets/prompts/reflect-llm-framed-contract.md +11 -0
  23. package/dist/assets/prompts/reflect-llm-schema-contract.md +3 -0
  24. package/dist/assets/prompts/reflect-output-repair.md +3 -0
  25. package/dist/assets/stash-skeleton/README.md +38 -10
  26. package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md +8 -0
  27. package/dist/assets/stash-skeleton/facts/conventions/assets/command.md +8 -0
  28. package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md +14 -1
  29. package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md +13 -1
  30. package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md +9 -1
  31. package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md +11 -0
  32. package/dist/assets/stash-skeleton/facts/conventions/assets/script.md +9 -0
  33. package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md +9 -0
  34. package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md +8 -0
  35. package/dist/assets/stash-skeleton/facts/conventions/backlinks.md +100 -0
  36. package/dist/assets/stash-skeleton/facts/conventions/domains.md +64 -0
  37. package/dist/assets/stash-skeleton/facts/conventions/organization.md +136 -0
  38. package/dist/assets/tasks/core/extract.yml +3 -2
  39. package/dist/assets/tasks/core/improve.yml +2 -1
  40. package/dist/assets/tasks/core/index-refresh.yml +1 -0
  41. package/dist/assets/tasks/core/sync.yml +1 -0
  42. package/dist/assets/tasks/core/version-check.yml +2 -1
  43. package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml +5 -0
  44. package/dist/assets/tasks/improve/akm-improve-catchup.yml +8 -0
  45. package/dist/assets/tasks/improve/akm-improve-consolidate.yml +5 -0
  46. package/dist/assets/tasks/improve/akm-improve-frequent.yml +5 -0
  47. package/dist/assets/tasks/improve/akm-improve-nightly.yml +5 -0
  48. package/dist/assets/templates/html/health.html +5 -4
  49. package/dist/assets/workflows/workflow-template.md +31 -15
  50. package/dist/cli/invocation.js +279 -0
  51. package/dist/cli/parse-args.js +5 -90
  52. package/dist/cli/retired-commands.js +78 -0
  53. package/dist/cli/shared.js +158 -48
  54. package/dist/cli-node.mjs +2 -1
  55. package/dist/cli.js +747 -293
  56. package/dist/commands/agent/agent-dispatch.js +19 -18
  57. package/dist/commands/agent/agent-support.js +0 -24
  58. package/dist/commands/agent/contribute-cli.js +43 -97
  59. package/dist/commands/completions.js +80 -23
  60. package/dist/commands/config-cli.js +44 -281
  61. package/dist/commands/env/env-binding.js +13 -9
  62. package/dist/commands/env/env-cli.js +76 -159
  63. package/dist/commands/env/env.js +12 -163
  64. package/dist/commands/env/marker-path.js +6 -0
  65. package/dist/commands/env/secret-cli.js +45 -61
  66. package/dist/commands/env/secret.js +32 -62
  67. package/dist/commands/feedback-cli.js +179 -85
  68. package/dist/commands/health/accept-rate.js +58 -0
  69. package/dist/commands/health/advisories.js +7 -8
  70. package/dist/commands/health/checks.js +279 -94
  71. package/dist/commands/health/html-report.js +197 -578
  72. package/dist/commands/health/improve-metrics.js +277 -246
  73. package/dist/commands/health/llm-usage.js +19 -19
  74. package/dist/commands/health/md-report.js +16 -7
  75. package/dist/commands/health/metrics.js +67 -32
  76. package/dist/commands/health/renderers.js +47 -0
  77. package/dist/commands/health/report-view-model.js +508 -0
  78. package/dist/commands/health/stash-exposure.js +1 -1
  79. package/dist/commands/health/surfaces.js +16 -56
  80. package/dist/commands/health/task-runs.js +3 -67
  81. package/dist/{migrate-storage-node.mjs → commands/health/types-checks.js} +1 -5
  82. package/dist/commands/health/types-improve.js +29 -0
  83. package/dist/{output/text/save.js → commands/health/types-metrics.js} +1 -2
  84. package/dist/commands/health/types-result.js +7 -0
  85. package/dist/commands/health/types-runs.js +4 -0
  86. package/dist/commands/health/types-session-log.js +4 -0
  87. package/dist/commands/health/types-windows.js +4 -0
  88. package/dist/commands/health/types.js +26 -21
  89. package/dist/commands/health/windows.js +2 -3
  90. package/dist/commands/health.js +296 -167
  91. package/dist/commands/improve/anti-collapse.js +5 -5
  92. package/dist/commands/improve/autonomy-gate.js +68 -0
  93. package/dist/commands/improve/collapse-detector.js +65 -52
  94. package/dist/commands/improve/consolidate/chunking.js +9 -7
  95. package/dist/commands/improve/consolidate/eligibility.js +1 -23
  96. package/dist/commands/improve/consolidate/merge.js +4 -0
  97. package/dist/commands/improve/consolidate.js +454 -1354
  98. package/dist/commands/improve/content-hash.js +39 -0
  99. package/dist/commands/improve/distill/content-repair.js +4 -10
  100. package/dist/commands/improve/distill/promote-memory.js +89 -64
  101. package/dist/commands/improve/distill/quality-gate.js +118 -42
  102. package/dist/commands/improve/distill-guards.js +1 -1
  103. package/dist/commands/improve/distill-promotion-policy.js +33 -888
  104. package/dist/commands/improve/distill.js +607 -363
  105. package/dist/commands/improve/eligibility.js +165 -79
  106. package/dist/commands/improve/extract-cli.js +35 -126
  107. package/dist/commands/improve/extract-prompt.js +6 -35
  108. package/dist/commands/improve/extract.js +640 -391
  109. package/dist/commands/improve/feedback-valence.js +2 -12
  110. package/dist/commands/improve/improve-cli.js +134 -135
  111. package/dist/commands/improve/improve-result-file.js +30 -50
  112. package/dist/commands/improve/improve-run-types.js +4 -0
  113. package/dist/commands/improve/improve-strategies.js +135 -0
  114. package/dist/commands/improve/improve.js +904 -701
  115. package/dist/commands/improve/locks.js +64 -111
  116. package/dist/commands/improve/loop-stages.js +1110 -923
  117. package/dist/commands/improve/memory/derived-ref.js +124 -0
  118. package/dist/commands/improve/memory/memory-belief.js +79 -7
  119. package/dist/commands/improve/memory/memory-contradiction-detect.js +49 -52
  120. package/dist/commands/improve/memory/memory-improve.js +25 -37
  121. package/dist/commands/improve/outcome-loop.js +25 -88
  122. package/dist/commands/improve/preparation.js +1034 -813
  123. package/dist/commands/improve/proactive-maintenance.js +34 -9
  124. package/dist/commands/improve/proposal-envelope.js +31 -0
  125. package/dist/commands/improve/reflect.js +983 -794
  126. package/dist/commands/improve/run-context.js +119 -0
  127. package/dist/commands/improve/salience.js +24 -127
  128. package/dist/commands/improve/session-asset.js +7 -3
  129. package/dist/commands/improve/shared.js +14 -34
  130. package/dist/commands/improve/source-identity.js +28 -0
  131. package/dist/commands/improve/triage.js +20 -17
  132. package/dist/commands/lint/base-linter.js +340 -313
  133. package/dist/commands/lint/env-key-rules.js +31 -47
  134. package/dist/commands/lint/index.js +185 -30
  135. package/dist/commands/{events.js → log.js} +28 -38
  136. package/dist/commands/migrate-cli.js +54 -0
  137. package/dist/commands/migration-tool.js +55 -0
  138. package/dist/commands/observability-cli.js +70 -208
  139. package/dist/commands/proposal/diff-format.js +50 -0
  140. package/dist/commands/proposal/drain-policies.js +0 -6
  141. package/dist/commands/proposal/drain.js +91 -40
  142. package/dist/commands/proposal/proposal-cli.js +134 -132
  143. package/dist/commands/proposal/proposal-types.js +56 -0
  144. package/dist/commands/proposal/proposal.js +83 -65
  145. package/dist/commands/proposal/propose-cli.js +88 -0
  146. package/dist/commands/proposal/propose.js +105 -88
  147. package/dist/commands/proposal/repository.js +1303 -278
  148. package/dist/commands/proposal/validators/proposal-quality-validators.js +16 -6
  149. package/dist/commands/proposal/validators/proposal-validators.js +61 -12
  150. package/dist/commands/proposal/validators/proposals.js +6 -8
  151. package/dist/commands/read/curate.js +78 -73
  152. package/dist/commands/read/knowledge.js +510 -13
  153. package/dist/commands/read/registry-search.js +2 -2
  154. package/dist/commands/read/remember-cli.js +84 -15
  155. package/dist/commands/read/search-cli.js +203 -96
  156. package/dist/commands/read/search.js +126 -94
  157. package/dist/commands/read/show.js +226 -250
  158. package/dist/commands/registry-cli.js +34 -60
  159. package/dist/commands/remember.js +18 -57
  160. package/dist/commands/sources/add-cli.js +104 -49
  161. package/dist/commands/sources/bundle-cli.js +166 -0
  162. package/dist/commands/sources/bundle-config-ops.js +63 -0
  163. package/dist/commands/sources/info.js +27 -15
  164. package/dist/commands/sources/init.js +30 -40
  165. package/dist/commands/sources/installed-stashes.js +469 -172
  166. package/dist/commands/sources/schema-repair.js +10 -9
  167. package/dist/commands/sources/self-update.js +182 -121
  168. package/dist/commands/sources/source-add.js +169 -178
  169. package/dist/commands/sources/source-clone.js +144 -41
  170. package/dist/commands/sources/source-manage.js +94 -59
  171. package/dist/commands/sources/sources-cli.js +64 -205
  172. package/dist/commands/sources/stash-cli.js +91 -54
  173. package/dist/commands/sources/stash-skeleton.js +1 -1
  174. package/dist/commands/tasks/tasks-cli.js +106 -104
  175. package/dist/commands/tasks/tasks.js +445 -262
  176. package/dist/commands/workflow-cli.js +75 -228
  177. package/dist/core/action-contributors.js +1 -1
  178. package/dist/core/activation-policy.js +49 -0
  179. package/dist/core/adapter/adapters/agent-skills-adapter.js +181 -0
  180. package/dist/core/adapter/adapters/akm-adapter.js +528 -0
  181. package/dist/core/adapter/adapters/akm-lint.js +392 -0
  182. package/dist/core/adapter/adapters/akm-metadata.js +387 -0
  183. package/dist/core/adapter/adapters/akm-task-adapter.js +149 -0
  184. package/dist/core/adapter/adapters/akm-workflow-adapter.js +180 -0
  185. package/dist/core/adapter/adapters/claude-adapter.js +61 -0
  186. package/dist/core/adapter/adapters/dotenv-adapter.js +187 -0
  187. package/dist/core/adapter/adapters/generic-files-adapter.js +119 -0
  188. package/dist/core/adapter/adapters/index.js +80 -0
  189. package/dist/core/adapter/adapters/llm-wiki-adapter.js +419 -0
  190. package/dist/core/adapter/adapters/okf-adapter.js +391 -0
  191. package/dist/core/adapter/adapters/opencode-adapter.js +68 -0
  192. package/dist/core/adapter/adapters/shared.js +286 -0
  193. package/dist/core/adapter/adapters/tool-dir-shared.js +217 -0
  194. package/dist/core/adapter/adapters/website-snapshot-adapter.js +155 -0
  195. package/dist/core/adapter/bundle-adapter.js +4 -0
  196. package/dist/core/adapter/detect-adapter.js +17 -0
  197. package/dist/core/adapter/recognize-match.js +44 -0
  198. package/dist/core/adapter/registry.js +56 -0
  199. package/dist/core/adapter/types.js +4 -0
  200. package/dist/core/asset/akm-markdown.js +30 -0
  201. package/dist/core/asset/asset-placement.js +243 -0
  202. package/dist/core/asset/asset-ref.js +110 -79
  203. package/dist/core/asset/asset-serialize.js +20 -0
  204. package/dist/core/asset/frontmatter.js +28 -12
  205. package/dist/core/asset/markdown.js +40 -51
  206. package/dist/core/asset/resolve-ref.js +274 -0
  207. package/dist/core/asset/stash-meta.js +2 -2
  208. package/dist/core/bundle-id.js +51 -0
  209. package/dist/core/common.js +281 -86
  210. package/dist/core/config/config-io.js +42 -128
  211. package/dist/core/config/config-schema.js +233 -855
  212. package/dist/core/config/config-sources.js +162 -39
  213. package/dist/core/config/config-types.js +16 -11
  214. package/dist/core/config/config-version.js +29 -0
  215. package/dist/core/config/config-walker.js +126 -37
  216. package/dist/core/config/config.js +154 -331
  217. package/dist/core/config/deep-merge.js +41 -0
  218. package/dist/core/config/engine-semantics.js +28 -0
  219. package/dist/core/config/experimental.js +21 -0
  220. package/dist/core/config/schema/embedding.js +38 -0
  221. package/dist/core/config/schema/engines.js +116 -0
  222. package/dist/core/config/schema/experimental.js +47 -0
  223. package/dist/core/config/schema/feedback.js +31 -0
  224. package/dist/core/config/schema/improve-processes.js +389 -0
  225. package/dist/core/config/schema/improve.js +94 -0
  226. package/dist/core/config/schema/index-config.js +176 -0
  227. package/dist/core/config/schema/output.js +18 -0
  228. package/dist/core/config/schema/primitives.js +94 -0
  229. package/dist/core/config/schema/search.js +30 -0
  230. package/dist/core/config/schema/setup.js +18 -0
  231. package/dist/core/config/schema/sources-bundles.js +169 -0
  232. package/dist/core/config/schema/workflow.js +29 -0
  233. package/dist/core/env-secret-ref.js +155 -20
  234. package/dist/core/errors.js +17 -15
  235. package/dist/core/events-types.js +4 -0
  236. package/dist/core/events.js +46 -128
  237. package/dist/core/extra-params.js +62 -0
  238. package/dist/core/file-change.js +17 -0
  239. package/dist/core/file-lock.js +202 -57
  240. package/dist/core/fs-txn.js +392 -0
  241. package/dist/core/git-message.js +59 -0
  242. package/dist/core/improve-result.js +167 -0
  243. package/dist/core/lesson-lint.js +1 -17
  244. package/dist/core/logs-db.js +1 -1
  245. package/dist/core/maintenance-barrier.js +135 -0
  246. package/dist/core/migration-operation.js +44 -0
  247. package/dist/core/mutation-target.js +78 -0
  248. package/dist/core/paths.js +22 -25
  249. package/dist/core/platform.js +10 -0
  250. package/dist/core/recognition-util.js +128 -0
  251. package/dist/core/redaction.js +392 -0
  252. package/dist/core/standards/resolve-standards-context.js +36 -65
  253. package/dist/core/standards/resolve-stash-standards.js +2 -2
  254. package/dist/core/standards/resolve-type-conventions.js +5 -5
  255. package/dist/core/state/migrations.js +242 -11
  256. package/dist/core/state-db.js +98 -10
  257. package/dist/core/structured.js +1 -1
  258. package/dist/core/subprocess.js +303 -0
  259. package/dist/core/text-truncation.js +9 -5
  260. package/dist/core/time.js +20 -0
  261. package/dist/core/type-presentation.js +130 -0
  262. package/dist/core/warn.js +0 -3
  263. package/dist/core/write-source.js +834 -118
  264. package/dist/indexer/bundle-identity-guard.js +92 -0
  265. package/dist/indexer/db/graph-db.js +1 -25
  266. package/dist/indexer/db/llm-cache.js +1 -1
  267. package/dist/indexer/ensure-index.js +30 -9
  268. package/dist/indexer/graph/graph-boost.js +9 -30
  269. package/dist/indexer/graph/graph-extraction.js +41 -27
  270. package/dist/indexer/graph/graph-types.js +4 -0
  271. package/dist/indexer/index-writer-lock.js +93 -49
  272. package/dist/indexer/index-written-assets.js +100 -53
  273. package/dist/indexer/indexer.js +746 -329
  274. package/dist/indexer/init.js +18 -25
  275. package/dist/indexer/installations.js +142 -0
  276. package/dist/indexer/passes/dir-staleness.js +18 -10
  277. package/dist/indexer/passes/memory-inference.js +25 -15
  278. package/dist/indexer/passes/metadata.js +412 -243
  279. package/dist/indexer/scan/doc-to-entry.js +160 -0
  280. package/dist/indexer/scan/drain-dir.js +134 -0
  281. package/dist/indexer/search/db-search.js +292 -108
  282. package/dist/indexer/search/fts-query.js +64 -0
  283. package/dist/indexer/search/ranking-contributors.js +145 -25
  284. package/dist/indexer/search/ranking-types.js +4 -0
  285. package/dist/indexer/search/ranking.js +28 -71
  286. package/dist/indexer/search/search-attribution.js +67 -0
  287. package/dist/indexer/search/search-fields.js +18 -3
  288. package/dist/indexer/search/search-hit-enrichers.js +30 -40
  289. package/dist/indexer/search/search-source.js +157 -111
  290. package/dist/indexer/search/semantic-status.js +4 -1
  291. package/dist/indexer/usage/usage-events.js +10 -30
  292. package/dist/indexer/walk/file-context.js +3 -45
  293. package/dist/indexer/walk/matchers.js +42 -73
  294. package/dist/indexer/walk/path-resolver.js +11 -5
  295. package/dist/indexer/walk/walker.js +42 -14
  296. package/dist/integrations/agent/builder-shared.js +7 -0
  297. package/dist/integrations/agent/builders.js +5 -58
  298. package/dist/integrations/agent/config.js +3 -143
  299. package/dist/integrations/agent/detect.js +17 -2
  300. package/dist/integrations/agent/engine-resolution.js +231 -0
  301. package/dist/integrations/agent/index.js +1 -2
  302. package/dist/integrations/agent/model-aliases.js +8 -3
  303. package/dist/integrations/agent/profiles.js +6 -99
  304. package/dist/integrations/agent/prompts.js +46 -18
  305. package/dist/integrations/agent/runner-dispatch.js +78 -13
  306. package/dist/integrations/agent/runner.js +76 -208
  307. package/dist/integrations/agent/spawn.js +48 -279
  308. package/dist/integrations/harnesses/aider/agent-builder.js +9 -8
  309. package/dist/integrations/harnesses/aider/index.js +2 -12
  310. package/dist/integrations/harnesses/amazonq/agent-builder.js +10 -16
  311. package/dist/integrations/harnesses/amazonq/index.js +3 -17
  312. package/dist/integrations/harnesses/claude/agent-builder.js +2 -3
  313. package/dist/integrations/harnesses/claude/config-import.js +1 -3
  314. package/dist/integrations/harnesses/claude/index.js +1 -14
  315. package/dist/integrations/harnesses/claude/session-log.js +27 -75
  316. package/dist/integrations/harnesses/codex/agent-builder.js +8 -7
  317. package/dist/integrations/harnesses/codex/index.js +2 -13
  318. package/dist/integrations/harnesses/copilot/agent-builder.js +9 -9
  319. package/dist/integrations/harnesses/copilot/index.js +1 -13
  320. package/dist/integrations/harnesses/gemini/agent-builder.js +8 -9
  321. package/dist/integrations/harnesses/gemini/index.js +1 -13
  322. package/dist/integrations/harnesses/ids.js +24 -0
  323. package/dist/integrations/harnesses/index.js +31 -33
  324. package/dist/integrations/harnesses/opencode/agent-builder.js +23 -5
  325. package/dist/integrations/harnesses/opencode/config-import.js +1 -3
  326. package/dist/integrations/harnesses/opencode/index.js +1 -18
  327. package/dist/integrations/harnesses/opencode/session-log.js +67 -125
  328. package/dist/integrations/harnesses/opencode-sdk/harness.js +3 -17
  329. package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +274 -191
  330. package/dist/integrations/harnesses/openhands/agent-builder.js +12 -10
  331. package/dist/integrations/harnesses/openhands/index.js +2 -12
  332. package/dist/integrations/harnesses/pi/agent-builder.js +11 -18
  333. package/dist/integrations/harnesses/pi/index.js +3 -16
  334. package/dist/integrations/harnesses/shared.js +17 -0
  335. package/dist/integrations/harnesses/types.js +38 -34
  336. package/dist/integrations/lockfile.js +211 -24
  337. package/dist/integrations/session-logs/index.js +24 -40
  338. package/dist/integrations/session-logs/provider-base.js +113 -0
  339. package/dist/llm/client.js +182 -110
  340. package/dist/llm/embedders/deterministic.js +2 -2
  341. package/dist/llm/embedders/remote.js +21 -9
  342. package/dist/llm/feature-gate.js +17 -57
  343. package/dist/llm/graph-extract.js +12 -13
  344. package/dist/llm/index-passes.js +8 -42
  345. package/dist/llm/memory-infer.js +144 -1
  346. package/dist/llm/metadata-enhance.js +45 -30
  347. package/dist/llm/structured-call.js +16 -8
  348. package/dist/llm/usage-persist.js +30 -5
  349. package/dist/llm/usage-telemetry.js +59 -6
  350. package/dist/output/cli-hints.js +1 -2
  351. package/dist/output/command-registry.js +27 -0
  352. package/dist/output/context.js +22 -7
  353. package/dist/output/format-exempt.js +80 -0
  354. package/dist/output/generic-render.js +251 -0
  355. package/dist/output/html-render.js +11 -16
  356. package/dist/output/render-registry.js +57 -0
  357. package/dist/output/renderers.js +15 -281
  358. package/dist/output/shapes/curate.js +10 -1
  359. package/dist/output/shapes/events.js +12 -7
  360. package/dist/output/shapes/helpers.js +58 -84
  361. package/dist/output/shapes/passthrough.js +8 -40
  362. package/dist/output/shapes/proposal/producer.js +15 -7
  363. package/dist/output/shapes/registry.js +12 -6
  364. package/dist/output/shapes.js +0 -9
  365. package/dist/output/text/{init.js → bundle-create.js} +3 -1
  366. package/dist/output/text/bundle-show.js +7 -0
  367. package/dist/output/text/command-format.js +562 -0
  368. package/dist/output/text/env.js +1 -3
  369. package/dist/output/text/events.js +8 -7
  370. package/dist/output/text/helpers.js +15 -1375
  371. package/dist/output/text/proposal/producer.js +4 -2
  372. package/dist/output/text/proposal-format.js +202 -0
  373. package/dist/output/text/registry-commands.js +1 -2
  374. package/dist/output/text/registry.js +12 -6
  375. package/dist/output/text/show-directives.js +117 -0
  376. package/dist/output/text/show-format.js +103 -0
  377. package/dist/output/text/sync.js +5 -0
  378. package/dist/output/text/workflow-format.js +332 -0
  379. package/dist/output/text/workflow.js +1 -2
  380. package/dist/output/text.js +10 -19
  381. package/dist/registry/factory.js +4 -6
  382. package/dist/registry/origin-resolve.js +16 -27
  383. package/dist/registry/providers/skills-sh.js +3 -3
  384. package/dist/registry/providers/static-index.js +15 -25
  385. package/dist/registry/resolve.js +43 -94
  386. package/dist/registry/semver.js +43 -0
  387. package/dist/runtime.js +81 -12
  388. package/dist/scripts/akm-migrate.js +35529 -0
  389. package/dist/setup/detect.js +5 -7
  390. package/dist/setup/detected-engines.js +136 -0
  391. package/dist/setup/engine-config.js +100 -0
  392. package/dist/setup/registry-stash-loader.js +3 -3
  393. package/dist/setup/semantic-assets.js +12 -9
  394. package/dist/setup/setup.js +444 -208
  395. package/dist/setup/steps/connection-shared.js +120 -0
  396. package/dist/setup/steps/connection.js +108 -305
  397. package/dist/setup/steps/platforms.js +13 -12
  398. package/dist/setup/steps/semantic.js +15 -3
  399. package/dist/setup/steps/sources.js +21 -15
  400. package/dist/setup/steps/stashdir.js +6 -4
  401. package/dist/setup/steps/tasks.js +236 -119
  402. package/dist/setup/steps.js +3 -2
  403. package/dist/sources/freshness.js +39 -0
  404. package/dist/sources/provider-factory.js +11 -17
  405. package/dist/sources/providers/filesystem.js +2 -3
  406. package/dist/sources/providers/git-install.js +278 -34
  407. package/dist/sources/providers/git-provider.js +54 -56
  408. package/dist/sources/providers/git-stash.js +420 -91
  409. package/dist/sources/providers/git.js +2 -2
  410. package/dist/sources/providers/npm.js +16 -19
  411. package/dist/sources/providers/provider-utils.js +47 -22
  412. package/dist/sources/providers/sync-from-ref.js +3 -9
  413. package/dist/sources/providers/website.js +2 -2
  414. package/dist/sources/resolve.js +11 -10
  415. package/dist/sources/snapshot-fetchers/types.js +4 -0
  416. package/dist/sources/{website-ingest.js → snapshot-fetchers/website-ingest.js} +110 -41
  417. package/dist/storage/database.js +60 -4
  418. package/dist/storage/engines/sqlite-migrations.js +156 -5
  419. package/dist/storage/locations.js +1 -2
  420. package/dist/storage/repositories/canaries-repository.js +1 -1
  421. package/dist/storage/repositories/events-repository.js +51 -11
  422. package/dist/storage/repositories/improve-runs-repository.js +6 -32
  423. package/dist/storage/repositories/index-connection.js +79 -0
  424. package/dist/storage/repositories/index-db.js +4 -3
  425. package/dist/storage/repositories/index-entries-repository.js +863 -0
  426. package/dist/{indexer/db/entry-mapper.js → storage/repositories/index-entry-mapper.js} +19 -2
  427. package/dist/storage/repositories/index-entry-types.js +4 -0
  428. package/dist/storage/repositories/index-fts-repository.js +167 -0
  429. package/dist/storage/repositories/index-llm-cache-repository.js +108 -0
  430. package/dist/storage/repositories/index-meta-repository.js +49 -0
  431. package/dist/{indexer/db/schema.js → storage/repositories/index-schema.js} +226 -100
  432. package/dist/storage/repositories/index-sql.js +12 -0
  433. package/dist/storage/repositories/index-utility-repository.js +356 -0
  434. package/dist/storage/repositories/index-vec-repository.js +250 -0
  435. package/dist/storage/repositories/outcome-repository.js +119 -0
  436. package/dist/storage/repositories/proposals-repository.js +317 -75
  437. package/dist/storage/repositories/registry-cache.js +1 -1
  438. package/dist/storage/repositories/salience-repository.js +172 -0
  439. package/dist/storage/repositories/task-history-repository.js +110 -3
  440. package/dist/storage/repositories/workflow-runs-repository.js +68 -35
  441. package/dist/tasks/backends/cron.js +169 -46
  442. package/dist/tasks/backends/exec-utils.js +76 -3
  443. package/dist/tasks/backends/index.js +6 -9
  444. package/dist/tasks/backends/launchd.js +292 -55
  445. package/dist/tasks/backends/schtasks.js +557 -70
  446. package/dist/tasks/backends/types.js +4 -0
  447. package/dist/tasks/command-executable.js +93 -0
  448. package/dist/tasks/embedded.js +56 -38
  449. package/dist/tasks/parser.js +156 -64
  450. package/dist/tasks/resolve-akm-bin.js +144 -51
  451. package/dist/tasks/runner.js +377 -209
  452. package/dist/tasks/schedule.js +108 -19
  453. package/dist/tasks/scheduler-invocation.js +296 -0
  454. package/dist/tasks/schema.js +1 -1
  455. package/dist/tasks/task-id.js +35 -0
  456. package/dist/tasks/validator.js +30 -16
  457. package/dist/workflows/authoring/authoring.js +96 -148
  458. package/dist/workflows/authoring/scope-key.js +1 -1
  459. package/dist/workflows/cli.js +0 -20
  460. package/dist/workflows/concurrency-policy.js +15 -0
  461. package/dist/workflows/exec/brief.js +25 -59
  462. package/dist/workflows/exec/frozen-judge.js +47 -0
  463. package/dist/workflows/exec/native-executor.js +157 -94
  464. package/dist/workflows/exec/report.js +365 -200
  465. package/dist/workflows/exec/run-workflow.js +46 -40
  466. package/dist/workflows/exec/scheduler.js +12 -41
  467. package/dist/workflows/exec/step-work.js +239 -205
  468. package/dist/workflows/exec/workflow-engine-gate.js +67 -0
  469. package/dist/workflows/ir/compile.js +141 -283
  470. package/dist/workflows/ir/freeze.js +233 -0
  471. package/dist/workflows/ir/plan-hash.js +40 -5
  472. package/dist/workflows/ir/schema.js +537 -1
  473. package/dist/workflows/parser.js +878 -306
  474. package/dist/workflows/program/expressions.js +20 -208
  475. package/dist/workflows/program/schema.js +7 -10
  476. package/dist/workflows/renderer.js +99 -121
  477. package/dist/workflows/resource-limits.js +22 -0
  478. package/dist/workflows/runtime/checkin.js +1 -1
  479. package/dist/workflows/runtime/plan-classifier.js +131 -0
  480. package/dist/workflows/runtime/runs.js +200 -113
  481. package/dist/workflows/runtime/unit-checkin.js +1 -1
  482. package/dist/workflows/runtime/unit-phases.js +20 -0
  483. package/dist/workflows/runtime/workflow-asset-loader.js +235 -97
  484. package/dist/workflows/schema.js +1 -11
  485. package/dist/workflows/validate-summary.js +4 -26
  486. package/dist/workflows/validator.js +52 -30
  487. package/docs/README.md +42 -78
  488. package/docs/migration/README.md +8 -0
  489. package/docs/migration/release-notes/0.6.0.md +1 -1
  490. package/docs/migration/release-notes/0.7.0.md +9 -8
  491. package/docs/migration/release-notes/0.9.0.md +158 -14
  492. package/docs/migration/v0.7-to-v0.8.md +46 -47
  493. package/docs/migration/v0.8-to-v0.9.md +844 -0
  494. package/docs/reference/README.md +12 -0
  495. package/docs/reference/data-and-telemetry.md +333 -0
  496. package/package.json +21 -17
  497. package/schemas/akm-asset-envelope.json +93 -0
  498. package/schemas/akm-config.json +4636 -0
  499. package/schemas/akm-task.json +87 -0
  500. package/{dist/schemas → schemas}/akm-workflow.json +127 -82
  501. package/dist/akm-migrate-storage +0 -38
  502. package/dist/assets/help/help-accept.md +0 -12
  503. package/dist/assets/help/help-improve.md +0 -84
  504. package/dist/assets/help/help-proposals.md +0 -17
  505. package/dist/assets/help/help-propose.md +0 -17
  506. package/dist/assets/help/help-reject.md +0 -11
  507. package/dist/assets/profiles/frequent.json +0 -13
  508. package/dist/assets/profiles/recombine-only.json +0 -21
  509. package/dist/assets/profiles/reflect-distill.json +0 -30
  510. package/dist/assets/profiles/synthesize.json +0 -15
  511. package/dist/assets/prompts/procedural-system.md +0 -44
  512. package/dist/assets/prompts/recombine-system.md +0 -40
  513. package/dist/assets/prompts/staleness-detect-system.md +0 -6
  514. package/dist/assets/tasks/core/backup.yml +0 -4
  515. package/dist/assets/tasks/graph-refresh-weekly.yml +0 -10
  516. package/dist/assets/templates/html/default.html +0 -78
  517. package/dist/assets/templates/html/vendor/echarts.min.js +0 -45
  518. package/dist/assets/wiki/index-template.md +0 -12
  519. package/dist/assets/wiki/ingest-workflow-template.md +0 -83
  520. package/dist/assets/wiki/log-template.md +0 -8
  521. package/dist/assets/wiki/schema-template.md +0 -61
  522. package/dist/cli/config-migrate.js +0 -150
  523. package/dist/cli/config-validate.js +0 -39
  524. package/dist/commands/graph/graph-cli.js +0 -124
  525. package/dist/commands/graph/graph.js +0 -487
  526. package/dist/commands/improve/calibration.js +0 -161
  527. package/dist/commands/improve/dedup.js +0 -482
  528. package/dist/commands/improve/extract-watch.js +0 -140
  529. package/dist/commands/improve/hot-probation.js +0 -45
  530. package/dist/commands/improve/improve-auto-accept.js +0 -276
  531. package/dist/commands/improve/improve-profiles.js +0 -168
  532. package/dist/commands/improve/procedural.js +0 -398
  533. package/dist/commands/improve/recombine.js +0 -818
  534. package/dist/commands/improve/schema-similarity-gate.js +0 -168
  535. package/dist/commands/lint/agent-linter.js +0 -44
  536. package/dist/commands/lint/command-linter.js +0 -44
  537. package/dist/commands/lint/default-linter.js +0 -16
  538. package/dist/commands/lint/fact-linter.js +0 -39
  539. package/dist/commands/lint/knowledge-linter.js +0 -16
  540. package/dist/commands/lint/memory-linter.js +0 -61
  541. package/dist/commands/lint/registry.js +0 -41
  542. package/dist/commands/lint/skill-linter.js +0 -45
  543. package/dist/commands/lint/task-linter.js +0 -50
  544. package/dist/commands/lint/workflow-linter.js +0 -81
  545. package/dist/commands/proposal/legacy-import.js +0 -115
  546. package/dist/commands/sources/history.js +0 -196
  547. package/dist/commands/tasks/default-tasks.js +0 -186
  548. package/dist/commands/wiki-cli.js +0 -292
  549. package/dist/core/asset/asset-registry.js +0 -76
  550. package/dist/core/asset/asset-spec.js +0 -316
  551. package/dist/core/config/config-migration.js +0 -602
  552. package/dist/core/deep-merge.js +0 -38
  553. package/dist/core/eval/rank-metrics.js +0 -113
  554. package/dist/core/ripgrep/install.js +0 -163
  555. package/dist/core/ripgrep/resolve.js +0 -81
  556. package/dist/indexer/db/db.js +0 -1414
  557. package/dist/indexer/manifest.js +0 -170
  558. package/dist/indexer/passes/metadata-contributors.js +0 -31
  559. package/dist/indexer/usage/unmigrated-vaults-guard.js +0 -94
  560. package/dist/integrations/harnesses/opencode-sdk/index.js +0 -25
  561. package/dist/llm/call-ai.js +0 -62
  562. package/dist/llm/memory-infer-impl.js +0 -138
  563. package/dist/output/shapes/distill.js +0 -14
  564. package/dist/output/shapes/history.js +0 -11
  565. package/dist/output/text/distill.js +0 -6
  566. package/dist/output/text/enable-disable.js +0 -8
  567. package/dist/output/text/history.js +0 -6
  568. package/dist/output/text/wiki.js +0 -16
  569. package/dist/registry/build-index.js +0 -386
  570. package/dist/schemas/akm-config.json +0 -14225
  571. package/dist/scripts/migrate-storage.js +0 -13169
  572. package/dist/scripts/migrations/import-fs-improve-runs-to-db.js +0 -10169
  573. package/dist/scripts/migrations/v16-to-v17.js +0 -141
  574. package/dist/setup/legacy-config.js +0 -106
  575. package/dist/storage/repositories/consolidation-repository.js +0 -38
  576. package/dist/storage/repositories/recombine-repository.js +0 -213
  577. package/dist/wiki/wiki-templates.js +0 -15
  578. package/dist/wiki/wiki.js +0 -1012
  579. package/dist/workflows/authoring/workflow-program-template.yaml +0 -31
  580. package/dist/workflows/db.js +0 -350
  581. package/dist/workflows/exec/watch.js +0 -116
  582. package/dist/workflows/program/parser.js +0 -760
  583. package/dist/workflows/program/project.js +0 -105
  584. package/docs/data-and-telemetry.md +0 -227
  585. package/docs/migration/release-notes/0.9.0-beta.60.md +0 -19
  586. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/registry.js +0 -0
  587. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/youtube.js +0 -0
@@ -6,8 +6,8 @@
6
6
  *
7
7
  * `sync()` resolves the npm package tarball, downloads it, verifies its
8
8
  * integrity, extracts it securely (via `extractTarGzSecure`), detects the
9
- * stash root inside the package, and applies any nested `.akm-include`
10
- * configuration. Cache hits short-circuit the fetch.
9
+ * stash root inside the package, and applies any nested `akm.include`
10
+ * (package.json) configuration. Cache hits short-circuit the fetch.
11
11
  */
12
12
  import fs from "node:fs";
13
13
  import path from "node:path";
@@ -19,11 +19,10 @@ import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectSta
19
19
  import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils.js";
20
20
  /**
21
21
  * NPM source provider — fetches a tarball from the npm registry and extracts
22
- * it into a local cache. Implements the v1 {@link SourceProvider} interface
23
- * (spec §2.1): `{ name, kind, init, path, sync }`.
22
+ * it into a local cache. Implements the {@link SourceProvider} interface.
24
23
  *
25
24
  * The install-time pipeline (`syncNpmRef`) lives below as a standalone
26
- * function used by `akm add` / `akm update` — that path produces a
25
+ * function used by `akm add` / `akm update`; that path produces a
27
26
  * {@link SourceLockData} record for lockfile bookkeeping. The provider's own
28
27
  * `sync()` is a void refresh (delegates to the install pipeline but discards
29
28
  * the lock data, which is owned by `lockfile.ts`).
@@ -39,7 +38,7 @@ class NpmSourceProvider {
39
38
  path() {
40
39
  if (this.#config.path)
41
40
  return this.#config.path;
42
- throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm update\` to sync it before indexing.`);
41
+ throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm bundle update\` to sync it before indexing.`);
43
42
  }
44
43
  async sync(options) {
45
44
  const ref = npmRefFromConfig(this.#config);
@@ -48,22 +47,20 @@ class NpmSourceProvider {
48
47
  }
49
48
  registerSourceProvider("npm", (config) => new NpmSourceProvider(config));
50
49
  function npmRefFromConfig(config) {
51
- // Prefer an explicit ref-bearing field (set by akmAdd when persisting), else fall back
52
- // to options or url so the provider stays usable from a hand-rolled config.
53
- const candidate = config.options?.ref ?? config.url ?? config.options?.package ?? config.name;
50
+ const candidate = config.path;
54
51
  if (typeof candidate !== "string" || !candidate) {
55
- throw new UsageError('npm stash entry must include an `options.ref` (e.g. "npm:my-pkg@1.2.3")');
52
+ throw new UsageError('npm source entry must include a package ref (e.g. "npm:my-pkg@1.2.3")');
56
53
  }
57
54
  return candidate.startsWith("npm:") ? candidate : `npm:${candidate}`;
58
55
  }
59
56
  /**
60
57
  * Fetch and extract an npm tarball, returning a populated `SourceLockData`.
61
58
  *
62
- * Mirrors the historical `installRegistryRef()` path for npm sources:
63
- * - resolve artifact URL + integrity from the npm registry
59
+ * Materializes npm sources by:
60
+ * - resolving the artifact URL and integrity from the npm registry
64
61
  * - reuse cached extraction when present
65
62
  * - download, verify, extract securely, then detect the stash root
66
- * - honour `.akm-include` filters
63
+ * - honour `akm.include` (package.json) filters
67
64
  */
68
65
  export async function syncNpmRef(ref, options) {
69
66
  const parsed = parseRegistryRef(ref);
@@ -107,7 +104,7 @@ async function doSyncNpm(parsed, options) {
107
104
  }
108
105
  fs.mkdirSync(cacheDir, { recursive: true });
109
106
  let integrity;
110
- let provisionalKitRoot;
107
+ let provisionalBundleRoot;
111
108
  let installRoot;
112
109
  let stashRoot;
113
110
  try {
@@ -115,15 +112,15 @@ async function doSyncNpm(parsed, options) {
115
112
  verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
116
113
  integrity = await computeFileHash(archivePath);
117
114
  extractTarGzSecure(archivePath, extractedDir);
118
- const detectedProvisionalKitRoot = detectStashRoot(extractedDir);
119
- if (!detectedProvisionalKitRoot) {
115
+ const detectedProvisionalBundleRoot = detectStashRoot(extractedDir);
116
+ if (!detectedProvisionalBundleRoot) {
120
117
  throw new UsageError(`Unable to detect a stash root in extracted npm package: ${resolved.ref}`);
121
118
  }
122
- provisionalKitRoot = detectedProvisionalKitRoot;
123
- installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
119
+ provisionalBundleRoot = detectedProvisionalBundleRoot;
120
+ installRoot = applyAkmIncludeConfig(provisionalBundleRoot, cacheDir, extractedDir) ?? provisionalBundleRoot;
124
121
  const detectedStashRoot = detectStashRoot(installRoot);
125
122
  if (!detectedStashRoot) {
126
- throw new UsageError(`Unable to detect a stash root after applying .akm-include configuration for npm package: ${resolved.ref}`);
123
+ throw new UsageError(`Unable to detect a stash root after applying akm.include (package.json) configuration for npm package: ${resolved.ref}`);
127
124
  }
128
125
  stashRoot = detectedStashRoot;
129
126
  }
@@ -4,11 +4,12 @@
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import fs from "node:fs";
6
6
  import path from "node:path";
7
- import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
7
+ import { getAdapters } from "../../core/adapter/registry.js";
8
+ import { stashDirNames } from "../../core/asset/asset-placement.js";
8
9
  import { fetchWithRetry } from "../../core/common.js";
9
- import { writeResponseToFile } from "../../runtime.js";
10
+ import { writeResponseToFileCapped } from "../../runtime.js";
10
11
  import { copyIncludedPaths, findNearestIncludeConfig } from "../include.js";
11
- const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
12
+ const REGISTRY_STASH_DIR_NAMES = new Set(stashDirNames());
12
13
  /** Strip terminal control characters from untrusted strings. */
13
14
  export function sanitizeString(value, maxLength = 255) {
14
15
  if (typeof value !== "string")
@@ -20,18 +21,43 @@ export function sanitizeString(value, maxLength = 255) {
20
21
  export function isExpired(mtimeMs, ttlMs) {
21
22
  return Date.now() - mtimeMs > ttlMs;
22
23
  }
24
+ /**
25
+ * True when ANY built-in adapter's install-time `looksLikeRoot` probe claims
26
+ * `root` — the spec §1.2 ordered probe reduced to "is this the root of a bundle
27
+ * of some format family?". A probe that throws (unreadable dir, race) does not
28
+ * claim the root.
29
+ */
30
+ function looksLikeAnyBundleRoot(root) {
31
+ for (const adapter of getAdapters()) {
32
+ try {
33
+ if (adapter.looksLikeRoot?.(root) === true)
34
+ return true;
35
+ }
36
+ catch {
37
+ // a throwing probe does not claim the root — try the next adapter
38
+ }
39
+ }
40
+ return false;
41
+ }
23
42
  /**
24
43
  * Find the directory inside `extractedDir` that should be treated as the
25
- * stash root. Looks for a `.stash` marker, then well-known type dirs, then
26
- * BFS for the shallowest such candidate.
44
+ * bundle/stash root. Probes the top-level dir via the ordered §1.2 registry
45
+ * probe; if nothing claims it, BFS for the shallowest nested candidate.
27
46
  */
28
47
  export function detectStashRoot(extractedDir) {
29
48
  const root = path.resolve(extractedDir);
30
- const rootDotStash = path.join(root, ".stash");
31
- if (isDirectory(rootDotStash)) {
32
- return root;
33
- }
34
- if (hasStashDirs(root)) {
49
+ // WI-3.1 → wired to the static registry: the top-level root check now routes
50
+ // through the ordered §1.2 `looksLikeRoot` probe over ALL built-in adapters
51
+ // (`registry.getAdapters()`), not the single hardcoded `akm` probe. This is
52
+ // BEHAVIOR-IDENTICAL for akm roots — `akm.looksLikeRoot` reproduces the former
53
+ // `.stash`-marker + immediate-stash-subdir (`hasStashDirs`) checks VERBATIM
54
+ // (akm-adapter.looksLikeRoot) and `akm` is in the probe set — so those two
55
+ // local checks are now subsumed and were removed. It additionally recognizes
56
+ // NON-akm bundle roots (okf root index / llm-wiki / `.claude` / …) at the top
57
+ // level, which the single-adapter probe missed but the old final `return root`
58
+ // fallback also happened to yield. The shallowest-BFS nested-layout discovery
59
+ // is unchanged.
60
+ if (looksLikeAnyBundleRoot(root)) {
35
61
  return root;
36
62
  }
37
63
  const shallowest = findShallowestStashRoot(root);
@@ -50,14 +76,17 @@ function uniqueSlug() {
50
76
  * `local` sources get a unique slug so each install is isolated.
51
77
  */
52
78
  export function buildInstallCacheDir(cacheRootDir, source, id, version) {
53
- const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`;
79
+ const safeId = id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
80
+ const identitySuffix = version === "writable" ? `-${createHash("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
81
+ const slug = `${source}-${safeId}${identitySuffix}`;
54
82
  const versionSlug = source === "local" ? uniqueSlug() : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug());
55
83
  return path.join(cacheRootDir, slug || source, versionSlug);
56
84
  }
57
85
  /**
58
- * Apply an `.akm-include` config (if any) by copying the selected paths
59
- * into a sibling `selected/` directory and returning that path. Returns
60
- * undefined when no include config is found.
86
+ * Apply an `akm.include` config (a `package.json` `akm.include` array — NOT
87
+ * a `.akm-include` dotfile) if any, by copying the selected paths into a
88
+ * sibling `selected/` directory and returning that path. Returns undefined
89
+ * when no include config is found.
61
90
  */
62
91
  export function applyAkmIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
63
92
  const includeConfig = findNearestIncludeConfig(sourceRoot, searchRoot);
@@ -75,8 +104,10 @@ export async function downloadArchive(url, destination) {
75
104
  if (!response.ok) {
76
105
  throw new Error(`Failed to download archive (${response.status}) from ${url}`);
77
106
  }
78
- // Stream response to disk instead of buffering the entire archive in memory.
79
- await writeResponseToFile(destination, response);
107
+ // Stream to disk with an explicit byte cap + body-read deadline: the fetch
108
+ // timeout above bounds only the connection/header phase, so an unbounded or
109
+ // dribbling body could otherwise fill the disk or hang the install forever.
110
+ await writeResponseToFileCapped(destination, response);
80
111
  }
81
112
  /** SHA-256 of a file, returned as `sha256:<hex>`. */
82
113
  export async function computeFileHash(filePath) {
@@ -114,12 +145,6 @@ export function isDirectory(target) {
114
145
  return false;
115
146
  }
116
147
  }
117
- function hasStashDirs(dirPath) {
118
- if (!isDirectory(dirPath))
119
- return false;
120
- const entries = fs.readdirSync(dirPath, { withFileTypes: true });
121
- return entries.some((entry) => entry.isDirectory() && REGISTRY_STASH_DIR_NAMES.has(entry.name));
122
- }
123
148
  function countStashDirs(dirPath) {
124
149
  if (!isDirectory(dirPath))
125
150
  return 0;
@@ -2,11 +2,7 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /**
5
- * Unified install-ref dispatcher.
6
- *
7
- * Replaces the historical `installRegistryRef()` entry point. Given an
8
- * unparsed install ref, this resolves the right syncable provider and
9
- * invokes its `sync()` method.
5
+ * Materialize an install ref through the matching source implementation.
10
6
  */
11
7
  import { UsageError } from "../../core/errors.js";
12
8
  import { parseRegistryRef } from "../../registry/resolve.js";
@@ -21,11 +17,9 @@ export async function syncFromRef(ref, options) {
21
17
  return syncNpmRef(ref, options);
22
18
  }
23
19
  if (parsed.source === "git" || parsed.source === "github") {
24
- const { syncRegistryGitRef } = await import("./git.js");
25
- return syncRegistryGitRef(ref, options);
20
+ const { syncGitRef } = await import("./git-install.js");
21
+ return syncGitRef(ref, options);
26
22
  }
27
- // Exhaustiveness — `parseRegistryRef` only emits the four sources above.
28
- const _exhaustive = parsed;
29
23
  throw new UsageError(`No syncable provider for ref: ${ref}`);
30
24
  }
31
25
  function syncLocalRef(parsed, options) {
@@ -2,7 +2,7 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  import { registerSourceProvider } from "../provider-factory.js";
5
- import { ensureWebsiteMirror, getWebsiteCachePaths, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteUrl, } from "../website-ingest.js";
5
+ import { ensureWebsiteMirror, getWebsiteCachePaths, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteUrl, } from "../snapshot-fetchers/website-ingest.js";
6
6
  /**
7
7
  * Website source provider — thin adapter over the shared website ingest module.
8
8
  */
@@ -14,7 +14,7 @@ registerSourceProvider("website", (config) => {
14
14
  kind: "website",
15
15
  name,
16
16
  path() {
17
- return getWebsiteCachePaths(url).stashDir;
17
+ return getWebsiteCachePaths(url).rootDir;
18
18
  },
19
19
  async sync(options) {
20
20
  await ensureWebsiteMirror(config, {
@@ -3,17 +3,18 @@
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
- import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "../core/asset/asset-spec.js";
6
+ import { recognizeMatch } from "../core/adapter/recognize-match.js";
7
+ import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, stashDirFor, } from "../core/asset/asset-placement.js";
8
+ import { conceptIdFromTypeName } from "../core/asset/resolve-ref.js";
7
9
  import { hasErrnoCode, isWithin } from "../core/common.js";
8
10
  import { NotFoundError, UsageError } from "../core/errors.js";
9
- import { runMatchers } from "../indexer/walk/file-context.js";
10
11
  import { walkStashFlat } from "../indexer/walk/walker.js";
11
12
  /**
12
13
  * Resolve an asset path from a stash directory, type, and name.
13
14
  */
14
15
  export async function resolveAssetPath(stashDir, type, name) {
15
16
  try {
16
- return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
17
+ return resolveInTypeDir(stashDir, stashDirFor(type), type, name);
17
18
  }
18
19
  catch (error) {
19
20
  if (!(error instanceof NotFoundError))
@@ -29,14 +30,14 @@ export async function resolveAssetPath(stashDir, type, name) {
29
30
  */
30
31
  function resolveInTypeDir(stashDir, typeDir, type, name) {
31
32
  const root = path.join(stashDir, typeDir);
32
- const target = resolveAssetPathFromName(type, root, name);
33
+ const target = assetPathForName(type, root, name);
33
34
  const resolvedRoot = resolveAndValidateTypeRoot(root, type, name);
34
35
  const resolvedTarget = path.resolve(target);
35
36
  if (!isWithin(resolvedTarget, resolvedRoot)) {
36
37
  throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
37
38
  }
38
39
  if (!fs.existsSync(resolvedTarget) || !fs.statSync(resolvedTarget).isFile()) {
39
- throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
40
+ throw new NotFoundError(`Stash asset not found for ref: ${conceptIdFromTypeName(type, name)}`, "ASSET_NOT_FOUND");
40
41
  }
41
42
  const realTarget = fs.realpathSync(resolvedTarget);
42
43
  if (!isWithin(realTarget, resolvedRoot)) {
@@ -46,15 +47,15 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
46
47
  if (type === "script") {
47
48
  throw new NotFoundError("Script ref must resolve to a file with a supported script extension. Refer to the akm documentation for the complete list of supported script extensions.");
48
49
  }
49
- throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
50
+ throw new NotFoundError(`Stash asset not found for ref: ${conceptIdFromTypeName(type, name)}`, "ASSET_NOT_FOUND");
50
51
  }
51
52
  return realTarget;
52
53
  }
53
54
  function resolveAndValidateTypeRoot(root, type, name) {
54
55
  const rootStat = readTypeRootStat(root, type, name);
55
56
  if (!rootStat.isDirectory()) {
56
- throw new NotFoundError(`Asset directory for ${type} assets is not accessible — got a file where a directory was expected for ref: ${type}:${name}. ` +
57
- "Run `akm index` to rebuild the index, or check your source configuration.", "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources and verify the source path exists.");
57
+ throw new NotFoundError(`Asset directory for ${type} assets is not accessible — got a file where a directory was expected for ref: ${conceptIdFromTypeName(type, name)}. ` +
58
+ "Run `akm index` to rebuild the index, or check your source configuration.", "ASSET_NOT_FOUND", "Run `akm bundle list` to see your configured sources and verify the source path exists.");
58
59
  }
59
60
  return fs.realpathSync(root);
60
61
  }
@@ -64,7 +65,7 @@ function readTypeRootStat(root, type, name) {
64
65
  }
65
66
  catch (error) {
66
67
  if (hasErrnoCode(error, "ENOENT")) {
67
- throw new NotFoundError(`Asset not found for ref: ${type}:${name}. No ${type} assets are present in the configured source.`, "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources, or `akm index` to rebuild the search index.");
68
+ throw new NotFoundError(`Asset not found for ref: ${conceptIdFromTypeName(type, name)}. No ${type} assets are present in the configured source.`, "ASSET_NOT_FOUND", "Run `akm bundle list` to see your configured sources, or `akm index` to rebuild the search index.");
68
69
  }
69
70
  throw error;
70
71
  }
@@ -72,7 +73,7 @@ function readTypeRootStat(root, type, name) {
72
73
  async function resolveByCanonicalName(stashDir, type, name) {
73
74
  const normalizedName = name.replace(/\\/g, "/");
74
75
  for (const ctx of walkStashFlat(stashDir)) {
75
- const match = await runMatchers(ctx);
76
+ const match = recognizeMatch(ctx);
76
77
  if (!match || match.type !== type)
77
78
  continue;
78
79
  const canonicalName = deriveCanonicalAssetNameFromStashRoot(type, stashDir, ctx.absPath);
@@ -0,0 +1,4 @@
1
+ // This Source Code Form is subject to the terms of the Mozilla Public
2
+ // License, v. 2.0. If a copy of the MPL was not distributed with this
3
+ // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
+ export {};
@@ -2,15 +2,17 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  import { createHash } from "node:crypto";
5
+ import { lookup as dnsLookup } from "node:dns/promises";
5
6
  import fs from "node:fs";
6
7
  import { isIP } from "node:net";
7
8
  import path from "node:path";
8
- import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap, resolveStashDir } from "../core/common.js";
9
- import { ConfigError, UsageError } from "../core/errors.js";
10
- import { getRegistryIndexCacheDir } from "../core/paths.js";
11
- import { warn } from "../core/warn.js";
12
- import { isExpired, sanitizeString } from "./providers/provider-utils.js";
13
- import { loadWikiSnapshotFetchers } from "./wiki-fetchers/registry.js";
9
+ import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap, resolveStashDir, todayIso, } from "../../core/common.js";
10
+ import { ConfigError, UsageError } from "../../core/errors.js";
11
+ import { getRegistryIndexCacheDir } from "../../core/paths.js";
12
+ import { warn } from "../../core/warn.js";
13
+ import { withFreshnessCache } from "../freshness.js";
14
+ import { sanitizeString } from "../providers/provider-utils.js";
15
+ import { loadWikiSnapshotFetchers } from "./registry.js";
14
16
  /** Refresh website snapshots every 12 hours to balance freshness with scraping load. */
15
17
  const CACHE_REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000;
16
18
  /** Allow up to 7 days of stale snapshots when refresh fails so search remains available during outages. */
@@ -33,6 +35,13 @@ const WEBSITE_PAGE_BYTE_CAP = 5 * 1024 * 1024;
33
35
  */
34
36
  const WEBSITE_CRAWL_WALL_CLOCK_MS = 10 * 60 * 1000;
35
37
  const WEBSITE_MAX_REDIRECTS = 8;
38
+ /**
39
+ * Body-read deadline for a single page (30s). The per-request fetch timeout
40
+ * (15s) bounds only the connection/header phase; without this a server that
41
+ * dribbles body bytes below the size cap could stall the crawl until the whole
42
+ * wall-clock cap elapses.
43
+ */
44
+ const WEBSITE_PAGE_BODY_TIMEOUT_MS = 30_000;
36
45
  export function shouldAllowPrivateWebsiteHostsForTests() {
37
46
  return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
38
47
  }
@@ -50,7 +59,7 @@ function resolveFetcherStashDir(explicitStashDir) {
50
59
  if (explicitStashDir)
51
60
  return explicitStashDir;
52
61
  try {
53
- return resolveStashDir({ readOnly: true });
62
+ return resolveStashDir();
54
63
  }
55
64
  catch {
56
65
  return null;
@@ -70,36 +79,23 @@ export async function ensureWebsiteMirror(config, options) {
70
79
  const normalizedUrl = validateWebsiteUrl(rawUrl, { allowPrivateHosts: options?.allowPrivateHosts });
71
80
  const cachePaths = getWebsiteCachePaths(normalizedUrl);
72
81
  const requireStashDir = options?.requireStashDir === true;
73
- const force = options?.force === true;
74
- let mtime = 0;
75
- try {
76
- mtime = fs.statSync(cachePaths.manifestPath).mtimeMs;
77
- }
78
- catch {
79
- /* no cached manifest */
80
- }
81
- if (!force &&
82
- mtime &&
83
- !isExpired(mtime, CACHE_REFRESH_INTERVAL_MS) &&
84
- (!requireStashDir || hasExtractedSite(cachePaths.stashDir))) {
85
- return cachePaths;
86
- }
87
- try {
88
- fs.mkdirSync(cachePaths.rootDir, { recursive: true });
89
- await scrapeWebsiteToStash(normalizedUrl, cachePaths.stashDir, {
90
- maxPages: coercePositiveInt(config.options?.maxPages, MAX_PAGES_DEFAULT),
91
- maxDepth: coercePositiveInt(config.options?.maxDepth, MAX_DEPTH_DEFAULT),
92
- allowPrivateHosts: options?.allowPrivateHosts,
93
- });
94
- fs.writeFileSync(cachePaths.manifestPath, `${JSON.stringify({ url: normalizedUrl, fetchedAt: new Date().toISOString() }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
95
- return cachePaths;
96
- }
97
- catch (err) {
98
- if (mtime && !isExpired(mtime, CACHE_STALE_MS) && (!requireStashDir || hasExtractedSite(cachePaths.stashDir))) {
99
- return cachePaths;
100
- }
101
- throw err;
102
- }
82
+ await withFreshnessCache({
83
+ markerPath: cachePaths.manifestPath,
84
+ ttlMs: CACHE_REFRESH_INTERVAL_MS,
85
+ staleMs: CACHE_STALE_MS,
86
+ force: options?.force === true,
87
+ isUsable: () => !requireStashDir || hasExtractedSite(cachePaths.stashDir),
88
+ refresh: async () => {
89
+ fs.mkdirSync(cachePaths.rootDir, { recursive: true });
90
+ await scrapeWebsiteToStash(normalizedUrl, cachePaths.stashDir, {
91
+ maxPages: coercePositiveInt(config.options?.maxPages, MAX_PAGES_DEFAULT),
92
+ maxDepth: coercePositiveInt(config.options?.maxDepth, MAX_DEPTH_DEFAULT),
93
+ allowPrivateHosts: options?.allowPrivateHosts,
94
+ });
95
+ fs.writeFileSync(cachePaths.manifestPath, `${JSON.stringify({ url: normalizedUrl, fetchedAt: new Date().toISOString() }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
96
+ },
97
+ });
98
+ return cachePaths;
103
99
  }
104
100
  function hasExtractedSite(stashDir) {
105
101
  try {
@@ -131,7 +127,7 @@ async function scrapeWebsiteToStash(startUrl, stashDir, options) {
131
127
  fs.mkdirSync(knowledgeDir, { recursive: true });
132
128
  const usedPaths = new Set();
133
129
  for (const page of pages) {
134
- const relPath = urlToRelativePath(page.url);
130
+ const relPath = avoidReservedBasename(urlToRelativePath(page.url));
135
131
  const uniquePath = uniqueSlug(relPath, usedPaths);
136
132
  const filePath = path.join(knowledgeDir, `${uniquePath}.md`);
137
133
  const dir = path.dirname(filePath);
@@ -237,7 +233,9 @@ async function fetchWebsitePage(pageUrl, options) {
237
233
  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
238
234
  let body;
239
235
  try {
240
- body = await readBodyWithByteCap(response, WEBSITE_PAGE_BYTE_CAP);
236
+ body = await readBodyWithByteCap(response, WEBSITE_PAGE_BYTE_CAP, {
237
+ bodyTimeoutMs: WEBSITE_PAGE_BODY_TIMEOUT_MS,
238
+ });
241
239
  }
242
240
  catch (err) {
243
241
  if (err instanceof ResponseTooLargeError)
@@ -268,6 +266,11 @@ async function fetchWebsitePage(pageUrl, options) {
268
266
  }
269
267
  async function fetchWebsiteResponse(pageUrl, redirectCount = 0, options) {
270
268
  assertWebsiteRequestUrl(pageUrl, Error, options);
269
+ // Resolve-then-validate BEFORE connecting: the hostname checks above only
270
+ // catch IP-literal / well-known-name hosts, so a public-looking DNS name that
271
+ // resolves into a private range would otherwise slip through. This runs on
272
+ // every hop because the redirect path re-enters this function recursively.
273
+ await assertResolvedHostAllowed(new URL(pageUrl).hostname, options);
271
274
  const response = await fetchWithRetry(pageUrl, {
272
275
  headers: {
273
276
  Accept: "text/html, text/markdown, text/plain;q=0.9, application/xhtml+xml;q=0.8",
@@ -291,8 +294,8 @@ async function fetchWebsiteResponse(pageUrl, redirectCount = 0, options) {
291
294
  }
292
295
  function buildMarkdownSnapshot(page, slug, tags) {
293
296
  const title = sanitizeString(page.title, 200) || slug;
294
- const description = sanitizeString(`Snapshot of ${page.url}`, 500);
295
297
  const host = sanitizeString(new URL(page.url).hostname, 120);
298
+ const description = sanitizeString(`Website snapshot from ${host}`, 500);
296
299
  const content = page.markdown.trim() || `Source: ${page.url}`;
297
300
  const normalizedTags = Array.from(new Set(["website", host, ...(tags ?? [])]));
298
301
  return [
@@ -301,6 +304,9 @@ function buildMarkdownSnapshot(page, slug, tags) {
301
304
  `description: ${JSON.stringify(description)}`,
302
305
  `sourceUrl: ${JSON.stringify(page.url)}`,
303
306
  `title: ${JSON.stringify(title)}`,
307
+ `updated: ${todayIso()}`,
308
+ "lint_skip:",
309
+ " - stale-path",
304
310
  "tags:",
305
311
  ...normalizedTags.map((tag) => ` - ${JSON.stringify(tag)}`),
306
312
  "---",
@@ -363,6 +369,20 @@ function normalizeCrawlUrl(rawUrl) {
363
369
  return null;
364
370
  }
365
371
  }
372
+ /**
373
+ * D-R6: `index.md`/`log.md` are OKF reserved structural filenames at every
374
+ * depth — no adapter indexes them, so a crawled page must never land on one.
375
+ * Same remap convention as the content migration (`index.md` →
376
+ * `index-content.md`). Segments are already lowercased by slugifySegment.
377
+ */
378
+ function avoidReservedBasename(relPath) {
379
+ const segments = relPath.split("/");
380
+ const last = segments[segments.length - 1] ?? "";
381
+ if (last === "index" || last === "log") {
382
+ segments[segments.length - 1] = `${last}-content`;
383
+ }
384
+ return segments.join("/");
385
+ }
366
386
  function urlToRelativePath(rawUrl) {
367
387
  const parsed = new URL(rawUrl);
368
388
  const segments = parsed.pathname
@@ -545,6 +565,54 @@ function assertWebsiteRequestUrl(rawUrl, ErrorType = Error, options) {
545
565
  throw new ErrorType(`Refusing to fetch non-public website host: ${parsedUrl.hostname}`);
546
566
  }
547
567
  }
568
+ async function defaultResolveHostname(hostname) {
569
+ const records = await dnsLookup(hostname, { all: true });
570
+ return records.map((record) => record.address);
571
+ }
572
+ /**
573
+ * Resolve-then-validate SSRF guard against DNS rebinding / private-range
574
+ * bypasses. {@link assertWebsiteRequestUrl} only rejects IP-literal and
575
+ * well-known-name hosts; a hostname like `private-host.example.com` that
576
+ * resolves to `10.0.0.1` passes those checks and then fetch connects to the
577
+ * private address. Here we resolve EVERY A/AAAA record and validate each
578
+ * against the same forbidden-range rules, failing CLOSED on an empty answer or
579
+ * resolver error.
580
+ *
581
+ * TOCTOU residual (documented, not fully closable here): Bun's `fetch` exposes
582
+ * no custom `lookup`/agent hook, so we cannot pin the socket to the exact IP we
583
+ * validated — a hostile resolver could return a public IP to this lookup and a
584
+ * private IP microseconds later at connect time (classic rebinding). This still
585
+ * removes the TRIVIAL `hostname A 10.0.0.1` bypass, which is the strongest
586
+ * guarantee available without a pinned-connection fetch API. Re-run on every
587
+ * redirect hop (the crawler recurses through `fetchWebsiteResponse`).
588
+ */
589
+ export async function assertResolvedHostAllowed(hostname, options) {
590
+ if (options?.allowPrivateHosts === true)
591
+ return;
592
+ const bare = stripIpv6Brackets(hostname.toLowerCase());
593
+ // IP-literal hosts are already fully validated by assertWebsiteRequestUrl's
594
+ // range checks; resolving them is a no-op (and dnsLookup would just echo it).
595
+ if (isIP(bare) !== 0)
596
+ return;
597
+ const resolve = options?.resolveHostname ?? defaultResolveHostname;
598
+ let addresses;
599
+ try {
600
+ addresses = await resolve(bare);
601
+ }
602
+ catch {
603
+ throw new Error(`Refusing to fetch ${hostname}: DNS resolution failed`);
604
+ }
605
+ if (addresses.length === 0) {
606
+ throw new Error(`Refusing to fetch ${hostname}: hostname resolved to no addresses`);
607
+ }
608
+ for (const address of addresses) {
609
+ const version = isIP(address);
610
+ const forbidden = version === 4 ? isForbiddenIpv4(address) : version === 6 ? isForbiddenIpv6(stripIpv6Brackets(address)) : true;
611
+ if (forbidden) {
612
+ throw new Error(`Refusing to fetch ${hostname}: resolves to non-public or unparseable address ${address}`);
613
+ }
614
+ }
615
+ }
548
616
  // WHATWG URL.hostname wraps IPv6 literals in brackets (e.g. "[::1]"), but
549
617
  // node:net's isIP() only recognizes the bare address form and returns 0 for
550
618
  // anything bracketed — silently skipping all IPv6 forbidden-host checks
@@ -582,7 +650,8 @@ function isForbiddenIpv4(hostname) {
582
650
  const parts = hostname.split(".").map((part) => Number.parseInt(part, 10));
583
651
  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
584
652
  return true;
585
- const [a, b] = parts;
653
+ const a = parts[0];
654
+ const b = parts[1];
586
655
  return (a === 0 ||
587
656
  a === 10 ||
588
657
  a === 127 ||