akm-cli 0.7.5 → 0.8.0-rc.10

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 (300) hide show
  1. package/{.github/CHANGELOG.md → CHANGELOG.md} +192 -2
  2. package/README.md +22 -6
  3. package/SECURITY.md +93 -0
  4. package/dist/cli/config-migrate.js +144 -0
  5. package/dist/cli/config-validate.js +39 -0
  6. package/dist/cli/confirm.js +73 -0
  7. package/dist/cli/parse-args.js +133 -0
  8. package/dist/cli/shared.js +129 -0
  9. package/dist/cli.js +2569 -1449
  10. package/dist/commands/add-cli.js +279 -0
  11. package/dist/commands/agent-dispatch.js +110 -0
  12. package/dist/commands/agent-support.js +68 -0
  13. package/dist/commands/completions.js +3 -0
  14. package/dist/commands/config-cli.js +130 -534
  15. package/dist/commands/consolidate.js +2122 -0
  16. package/dist/commands/curate.js +44 -3
  17. package/dist/commands/db-cli.js +23 -0
  18. package/dist/commands/distill-promotion-policy.js +660 -0
  19. package/dist/commands/distill.js +1075 -77
  20. package/dist/commands/env.js +213 -0
  21. package/dist/commands/eval-cases.js +43 -0
  22. package/dist/commands/events.js +5 -23
  23. package/dist/commands/extract-cli.js +127 -0
  24. package/dist/commands/extract-prompt.js +204 -0
  25. package/dist/commands/extract.js +477 -0
  26. package/dist/commands/feedback-cli.js +331 -0
  27. package/dist/commands/graph.js +477 -0
  28. package/dist/commands/health.js +1302 -0
  29. package/dist/commands/help/help-accept.md +12 -0
  30. package/dist/commands/help/help-improve.md +69 -0
  31. package/dist/commands/help/help-proposals.md +18 -0
  32. package/dist/commands/help/help-propose.md +17 -0
  33. package/dist/commands/help/help-reject.md +11 -0
  34. package/dist/commands/history.js +54 -46
  35. package/dist/commands/improve-auto-accept.js +97 -0
  36. package/dist/commands/improve-cli.js +217 -0
  37. package/dist/commands/improve-profiles.js +166 -0
  38. package/dist/commands/improve-result-file.js +167 -0
  39. package/dist/commands/improve.js +2373 -0
  40. package/dist/commands/info.js +5 -2
  41. package/dist/commands/init.js +50 -2
  42. package/dist/commands/installed-stashes.js +102 -139
  43. package/dist/commands/knowledge.js +136 -0
  44. package/dist/commands/lint/agent-linter.js +49 -0
  45. package/dist/commands/lint/base-linter.js +479 -0
  46. package/dist/commands/lint/command-linter.js +49 -0
  47. package/dist/commands/lint/default-linter.js +16 -0
  48. package/dist/commands/lint/env-key-rules.js +154 -0
  49. package/dist/commands/lint/index.js +196 -0
  50. package/dist/commands/lint/knowledge-linter.js +16 -0
  51. package/dist/commands/lint/markdown-insertion.js +343 -0
  52. package/dist/commands/lint/memory-linter.js +61 -0
  53. package/dist/commands/lint/registry.js +36 -0
  54. package/dist/commands/lint/skill-linter.js +45 -0
  55. package/dist/commands/lint/task-linter.js +50 -0
  56. package/dist/commands/lint/types.js +4 -0
  57. package/dist/commands/lint/workflow-linter.js +56 -0
  58. package/dist/commands/lint.js +4 -0
  59. package/dist/commands/migration-help.js +5 -2
  60. package/dist/commands/proposal.js +67 -12
  61. package/dist/commands/propose.js +86 -31
  62. package/dist/commands/reflect.js +1091 -73
  63. package/dist/commands/registry-cli.js +150 -0
  64. package/dist/commands/registry-search.js +5 -2
  65. package/dist/commands/remember-cli.js +257 -0
  66. package/dist/commands/remember.js +69 -6
  67. package/dist/commands/schema-repair.js +203 -0
  68. package/dist/commands/search.js +115 -14
  69. package/dist/commands/secret.js +173 -0
  70. package/dist/commands/self-update.js +3 -0
  71. package/dist/commands/show.js +148 -25
  72. package/dist/commands/source-add.js +17 -45
  73. package/dist/commands/source-clone.js +3 -0
  74. package/dist/commands/source-manage.js +14 -19
  75. package/dist/commands/tasks.js +437 -0
  76. package/dist/commands/url-checker.js +42 -0
  77. package/dist/core/action-contributors.js +28 -0
  78. package/dist/core/asset-ref.js +17 -2
  79. package/dist/core/asset-registry.js +12 -17
  80. package/dist/core/asset-serialize.js +88 -0
  81. package/dist/core/asset-spec.js +67 -1
  82. package/dist/core/common.js +182 -0
  83. package/dist/core/concurrent.js +25 -0
  84. package/dist/core/config-io.js +347 -0
  85. package/dist/core/config-migration.js +622 -0
  86. package/dist/core/config-schema.js +534 -0
  87. package/dist/core/config-sources.js +108 -0
  88. package/dist/core/config-types.js +4 -0
  89. package/dist/core/config-walker.js +337 -0
  90. package/dist/core/config.js +364 -981
  91. package/dist/core/errors.js +42 -20
  92. package/dist/core/events.js +91 -138
  93. package/dist/core/file-lock.js +104 -0
  94. package/dist/core/frontmatter.js +75 -8
  95. package/dist/core/lesson-lint.js +3 -0
  96. package/dist/core/markdown.js +20 -0
  97. package/dist/core/memory-belief.js +62 -0
  98. package/dist/core/memory-contradiction-detect.js +274 -0
  99. package/dist/core/memory-improve.js +806 -0
  100. package/dist/core/parse.js +158 -0
  101. package/dist/core/paths.js +280 -14
  102. package/dist/core/proposal-quality-validators.js +380 -0
  103. package/dist/core/proposal-validators.js +69 -0
  104. package/dist/core/proposals.js +512 -42
  105. package/dist/core/state-db.js +1068 -0
  106. package/dist/core/text-truncation.js +107 -0
  107. package/dist/core/time.js +54 -0
  108. package/dist/core/tty.js +59 -0
  109. package/dist/core/warn.js +64 -1
  110. package/dist/core/write-source.js +3 -0
  111. package/dist/indexer/db-backup.js +391 -0
  112. package/dist/indexer/db-search.js +163 -254
  113. package/dist/indexer/db.js +975 -103
  114. package/dist/indexer/ensure-index.js +64 -0
  115. package/dist/indexer/file-context.js +3 -0
  116. package/dist/indexer/graph-boost.js +376 -101
  117. package/dist/indexer/graph-db.js +391 -0
  118. package/dist/indexer/graph-dedup.js +95 -0
  119. package/dist/indexer/graph-extraction.js +550 -124
  120. package/dist/indexer/index-context.js +4 -0
  121. package/dist/indexer/indexer.js +523 -301
  122. package/dist/indexer/llm-cache.js +52 -0
  123. package/dist/indexer/manifest.js +3 -0
  124. package/dist/indexer/matchers.js +167 -160
  125. package/dist/indexer/memory-inference.js +152 -74
  126. package/dist/indexer/metadata-contributors.js +29 -0
  127. package/dist/indexer/metadata.js +275 -196
  128. package/dist/indexer/path-resolver.js +92 -0
  129. package/dist/indexer/project-context.js +192 -0
  130. package/dist/indexer/ranking-contributors.js +331 -0
  131. package/dist/indexer/ranking.js +81 -0
  132. package/dist/indexer/search-fields.js +5 -9
  133. package/dist/indexer/search-hit-enrichers.js +111 -0
  134. package/dist/indexer/search-source.js +44 -10
  135. package/dist/indexer/semantic-status.js +6 -17
  136. package/dist/indexer/staleness-detect.js +447 -0
  137. package/dist/indexer/usage-events.js +12 -9
  138. package/dist/indexer/walker.js +28 -0
  139. package/dist/integrations/agent/builders.js +135 -0
  140. package/dist/integrations/agent/config.js +122 -230
  141. package/dist/integrations/agent/detect.js +3 -0
  142. package/dist/integrations/agent/index.js +7 -13
  143. package/dist/integrations/agent/model-aliases.js +55 -0
  144. package/dist/integrations/agent/profiles.js +70 -5
  145. package/dist/integrations/agent/prompts.js +214 -80
  146. package/dist/integrations/agent/runner.js +151 -0
  147. package/dist/integrations/agent/sdk-runner.js +126 -0
  148. package/dist/integrations/agent/spawn.js +118 -23
  149. package/dist/integrations/github.js +3 -0
  150. package/dist/integrations/lockfile.js +32 -69
  151. package/dist/integrations/session-logs/index.js +69 -0
  152. package/dist/integrations/session-logs/inline-refs.js +35 -0
  153. package/dist/integrations/session-logs/pre-filter.js +152 -0
  154. package/dist/integrations/session-logs/providers/claude-code.js +282 -0
  155. package/dist/integrations/session-logs/providers/opencode.js +258 -0
  156. package/dist/integrations/session-logs/types.js +4 -0
  157. package/dist/llm/call-ai.js +62 -0
  158. package/dist/llm/client.js +77 -124
  159. package/dist/llm/embedder.js +20 -29
  160. package/dist/llm/embedders/cache.js +3 -7
  161. package/dist/llm/embedders/local.js +42 -1
  162. package/dist/llm/embedders/remote.js +20 -8
  163. package/dist/llm/embedders/types.js +3 -7
  164. package/dist/llm/feature-gate.js +95 -48
  165. package/dist/llm/graph-extract.js +676 -70
  166. package/dist/llm/index-passes.js +44 -29
  167. package/dist/llm/memory-infer.js +77 -71
  168. package/dist/llm/metadata-enhance.js +42 -29
  169. package/dist/llm/prompts/extract-session.md +80 -0
  170. package/dist/llm/prompts/graph-extract-user-prompt.md +35 -0
  171. package/dist/output/cli-hints-full.md +292 -0
  172. package/dist/output/cli-hints-short.md +66 -0
  173. package/dist/output/cli-hints.js +7 -320
  174. package/dist/output/context.js +60 -8
  175. package/dist/output/renderers.js +300 -257
  176. package/dist/output/shapes/curate.js +56 -0
  177. package/dist/output/shapes/distill.js +10 -0
  178. package/dist/output/shapes/env-list.js +19 -0
  179. package/dist/output/shapes/events.js +11 -0
  180. package/dist/output/shapes/helpers.js +424 -0
  181. package/dist/output/shapes/history.js +7 -0
  182. package/dist/output/shapes/passthrough.js +102 -0
  183. package/dist/output/shapes/proposal-accept.js +7 -0
  184. package/dist/output/shapes/proposal-diff.js +7 -0
  185. package/dist/output/shapes/proposal-list.js +7 -0
  186. package/dist/output/shapes/proposal-producer.js +11 -0
  187. package/dist/output/shapes/proposal-reject.js +7 -0
  188. package/dist/output/shapes/proposal-show.js +7 -0
  189. package/dist/output/shapes/registry-search.js +6 -0
  190. package/dist/output/shapes/registry.js +30 -0
  191. package/dist/output/shapes/search.js +6 -0
  192. package/dist/output/shapes/secret-list.js +19 -0
  193. package/dist/output/shapes/show.js +6 -0
  194. package/dist/output/shapes/vault-list.js +19 -0
  195. package/dist/output/shapes.js +51 -516
  196. package/dist/output/text/add.js +6 -0
  197. package/dist/output/text/clone.js +6 -0
  198. package/dist/output/text/config.js +6 -0
  199. package/dist/output/text/curate.js +6 -0
  200. package/dist/output/text/distill.js +7 -0
  201. package/dist/output/text/enable-disable.js +7 -0
  202. package/dist/output/text/events.js +10 -0
  203. package/dist/output/text/feedback.js +6 -0
  204. package/dist/output/text/helpers.js +1039 -0
  205. package/dist/output/text/history.js +7 -0
  206. package/dist/output/text/import.js +6 -0
  207. package/dist/output/text/index.js +6 -0
  208. package/dist/output/text/info.js +6 -0
  209. package/dist/output/text/init.js +6 -0
  210. package/dist/output/text/list.js +6 -0
  211. package/dist/output/text/proposal-producer.js +8 -0
  212. package/dist/output/text/proposal.js +11 -0
  213. package/dist/output/text/registry-commands.js +11 -0
  214. package/dist/output/text/registry.js +30 -0
  215. package/dist/output/text/remember.js +6 -0
  216. package/dist/output/text/remove.js +6 -0
  217. package/dist/output/text/save.js +6 -0
  218. package/dist/output/text/search.js +6 -0
  219. package/dist/output/text/show.js +6 -0
  220. package/dist/output/text/update.js +6 -0
  221. package/dist/output/text/upgrade.js +6 -0
  222. package/dist/output/text/vault.js +16 -0
  223. package/dist/output/text/wiki.js +15 -0
  224. package/dist/output/text/workflow.js +14 -0
  225. package/dist/output/text.js +44 -1092
  226. package/dist/registry/build-index.js +3 -0
  227. package/dist/registry/create-provider-registry.js +3 -0
  228. package/dist/registry/factory.js +4 -1
  229. package/dist/registry/origin-resolve.js +3 -0
  230. package/dist/registry/providers/index.js +3 -0
  231. package/dist/registry/providers/skills-sh.js +71 -50
  232. package/dist/registry/providers/static-index.js +53 -48
  233. package/dist/registry/providers/types.js +3 -24
  234. package/dist/registry/resolve.js +11 -16
  235. package/dist/registry/types.js +3 -0
  236. package/dist/scripts/migrate-storage.js +17750 -0
  237. package/dist/scripts/migrations/import-fs-improve-runs-to-db.js +9031 -0
  238. package/dist/scripts/migrations/v16-to-v17.js +141 -0
  239. package/dist/setup/detect.js +3 -0
  240. package/dist/setup/ripgrep-install.js +3 -0
  241. package/dist/setup/ripgrep-resolve.js +3 -0
  242. package/dist/setup/setup.js +775 -37
  243. package/dist/setup/steps.js +3 -15
  244. package/dist/sources/include.js +3 -0
  245. package/dist/sources/provider-factory.js +5 -12
  246. package/dist/sources/provider.js +3 -20
  247. package/dist/sources/providers/filesystem.js +19 -23
  248. package/dist/sources/providers/git.js +138 -21
  249. package/dist/sources/providers/index.js +3 -0
  250. package/dist/sources/providers/install-types.js +3 -13
  251. package/dist/sources/providers/npm.js +3 -4
  252. package/dist/sources/providers/provider-utils.js +3 -0
  253. package/dist/sources/providers/sync-from-ref.js +3 -11
  254. package/dist/sources/providers/tar-utils.js +3 -0
  255. package/dist/sources/providers/website.js +18 -22
  256. package/dist/sources/resolve.js +3 -0
  257. package/dist/sources/types.js +3 -0
  258. package/dist/sources/website-ingest.js +7 -0
  259. package/dist/tasks/backends/cron.js +203 -0
  260. package/dist/tasks/backends/exec-utils.js +28 -0
  261. package/dist/tasks/backends/index.js +24 -0
  262. package/dist/tasks/backends/launchd-template.xml +19 -0
  263. package/dist/tasks/backends/launchd.js +187 -0
  264. package/dist/tasks/backends/schtasks-template.xml +29 -0
  265. package/dist/tasks/backends/schtasks.js +215 -0
  266. package/dist/tasks/parser.js +211 -0
  267. package/dist/tasks/resolveAkmBin.js +87 -0
  268. package/dist/tasks/runner.js +458 -0
  269. package/dist/tasks/schedule.js +227 -0
  270. package/dist/tasks/schema.js +15 -0
  271. package/dist/tasks/validator.js +62 -0
  272. package/dist/version.js +3 -0
  273. package/dist/wiki/index-template.md +12 -0
  274. package/dist/wiki/ingest-workflow-template.md +54 -0
  275. package/dist/wiki/log-template.md +8 -0
  276. package/dist/wiki/schema-template.md +61 -0
  277. package/dist/wiki/wiki-templates.js +15 -0
  278. package/dist/wiki/wiki.js +13 -61
  279. package/dist/workflows/authoring.js +8 -25
  280. package/dist/workflows/cli.js +3 -0
  281. package/dist/workflows/db.js +140 -10
  282. package/dist/workflows/document-cache.js +3 -10
  283. package/dist/workflows/parser.js +3 -0
  284. package/dist/workflows/renderer.js +11 -3
  285. package/dist/workflows/runs.js +77 -92
  286. package/dist/workflows/schema.js +3 -0
  287. package/dist/workflows/scope-key.js +3 -0
  288. package/dist/workflows/validator.js +4 -8
  289. package/dist/workflows/workflow-template.md +24 -0
  290. package/docs/README.md +10 -2
  291. package/docs/data-and-telemetry.md +225 -0
  292. package/docs/migration/release-notes/0.7.0.md +1 -1
  293. package/docs/migration/release-notes/0.7.5.md +2 -2
  294. package/docs/migration/release-notes/0.8.0.md +48 -0
  295. package/docs/migration/v0.7-to-v0.8.md +1307 -0
  296. package/package.json +30 -12
  297. package/.github/LICENSE +0 -374
  298. package/dist/commands/install-audit.js +0 -381
  299. package/dist/commands/vault.js +0 -328
  300. package/dist/templates/wiki-templates.js +0 -100
@@ -1,528 +1,63 @@
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/.
1
4
  /**
2
5
  * Pure shaping functions that select and trim fields from command result
3
6
  * objects according to the active detail level / agent mode.
4
7
  *
5
8
  * Every function in this module is side-effect free and operates on plain
6
9
  * `Record<string, unknown>` shapes, which makes them trivial to unit test.
10
+ *
11
+ * Output shapes are registered via `registerOutputShape` — see the per-command
12
+ * modules in `src/output/shapes/` for individual registrations. The central
13
+ * `shapeForCommand` dispatcher looks up the registry and throws for unknown
14
+ * commands (v1 spec §9 — exhaustive registry, no silent fallback).
7
15
  */
8
- const NORMAL_DESCRIPTION_LIMIT = 250;
9
- export function shapeForCommand(command, result, detail, forAgent = false) {
10
- switch (command) {
11
- case "search":
12
- return shapeSearchOutput(result, detail, forAgent);
13
- case "registry-search":
14
- return shapeRegistrySearchOutput(result, detail);
15
- case "show":
16
- return shapeShowOutput(result, detail, forAgent);
17
- // Output shape registration for `akm history` paired with the textRenderer in text.ts.
18
- case "history":
19
- return shapeHistoryOutput(result, detail);
20
- // Output shape registration for `akm events list` and `akm events tail`
21
- // (#204). Both share the same envelope; the renderer in text.ts uses
22
- // distinct command names so it can format streaming differently.
23
- case "events-list":
24
- case "events-tail":
25
- return shapeEventsOutput(result, detail);
26
- // Output shape registration for `akm proposal {list,show,accept,reject,diff}`
27
- // (#225). Each verb gets its own arm so the registry stays exhaustive (no
28
- // silent JSON.stringify fallback). The proposal payload is reshaped per
29
- // detail level — `brief` omits the full content body, while some proposal
30
- // shapers still retain normal-level metadata such as review details;
31
- // `full`/`agent` includes everything.
32
- case "proposal-list":
33
- return shapeProposalListOutput(result, detail);
34
- case "proposal-show":
35
- return shapeProposalShowOutput(result, detail);
36
- case "proposal-accept":
37
- return shapeProposalAcceptOutput(result, detail);
38
- case "proposal-reject":
39
- return shapeProposalRejectOutput(result, detail);
40
- case "proposal-diff":
41
- return shapeProposalDiffOutput(result, detail);
42
- // Output shape registration for `akm reflect` and `akm propose` (#226).
43
- // Both share the proposal-producer envelope shape (success carries a
44
- // proposal entry; failure carries an AgentFailureReason discriminant).
45
- case "reflect":
46
- case "propose":
47
- return shapeProposalProducerOutput(result, detail);
48
- // Output shape registration for `akm distill <ref>` (#228). The shape is
49
- // simple — outcome + ids + optional payload — so `brief` strips the full
50
- // proposal blob, `normal` keeps the headline fields, and `full` projects
51
- // everything for downstream automation.
52
- case "distill":
53
- return shapeDistillOutput(result, detail);
54
- // Identity-passthrough commands — registered here so the registry stays
55
- // exhaustive (v1 spec §9). Each result object is already shaped at the
56
- // command boundary; the registry just confirms there's no surprise
57
- // command name slipping through.
58
- case "add":
59
- case "clone":
60
- case "config":
61
- case "curate":
62
- case "disable":
63
- case "enable":
64
- case "feedback":
65
- case "import":
66
- case "index":
67
- case "info":
68
- case "init":
69
- case "list":
70
- case "registry-add":
71
- case "registry-build-index":
72
- case "registry-list":
73
- case "registry-remove":
74
- case "remember":
75
- case "remove":
76
- case "save":
77
- case "update":
78
- case "upgrade":
79
- case "vault-create":
80
- case "vault-list":
81
- case "vault-set":
82
- case "vault-unset":
83
- case "wiki-create":
84
- case "wiki-ingest":
85
- case "wiki-lint":
86
- case "wiki-list":
87
- case "wiki-pages":
88
- case "wiki-register":
89
- case "wiki-remove":
90
- case "wiki-show":
91
- case "wiki-stash":
92
- case "workflow-complete":
93
- case "workflow-create":
94
- case "workflow-list":
95
- case "workflow-next":
96
- case "workflow-resume":
97
- case "workflow-start":
98
- case "workflow-status":
99
- case "workflow-validate":
100
- return result;
101
- default:
102
- // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
103
- // fallback. A missing case here is a registration bug — fail loudly so
104
- // the caller (or its tests) sees the missing command name.
105
- throw new Error(`output shape not registered for command: ${command}`);
106
- }
107
- }
16
+ import { UsageError } from "../core/errors";
17
+ import { getOutputShapeHandler } from "./shapes/registry";
18
+ // Re-export helpers so existing imports from `shapes.ts` keep working.
19
+ export { capDescription, NORMAL_DESCRIPTION_LIMIT, pickFields, shapeAssetHit, shapeDistillOutput, shapeEventEntry, shapeEventsOutput, shapeHistoryEntry, shapeHistoryOutput, shapeProposalAcceptOutput, shapeProposalDiffOutput, shapeProposalEntry, shapeProposalListOutput, shapeProposalProducerOutput, shapeProposalRejectOutput, shapeProposalShowOutput, shapeRegistrySearchOutput, shapeSearchHit, shapeSearchHitForAgent, shapeSearchOutput, shapeShowOutput, truncateDescription, } from "./shapes/helpers";
20
+ // Re-export registry API so callers can use this module as the single entry
21
+ // point (backward compat).
22
+ export { deregisterOutputShape, registerOutputShape } from "./shapes/registry";
23
+ // ── Per-command shape modules (self-register at import time) ──────────────────
24
+ // Importing these modules triggers their `registerOutputShape(...)` calls.
25
+ // These imports must come AFTER the registry module has been loaded (guaranteed
26
+ // by the import order above).
27
+ import "./shapes/search";
28
+ import "./shapes/curate";
29
+ import "./shapes/registry-search";
30
+ import "./shapes/show";
31
+ import "./shapes/history";
32
+ import "./shapes/events";
33
+ import "./shapes/proposal-list";
34
+ import "./shapes/proposal-show";
35
+ import "./shapes/proposal-accept";
36
+ import "./shapes/proposal-reject";
37
+ import "./shapes/proposal-diff";
38
+ import "./shapes/proposal-producer";
39
+ import "./shapes/distill";
40
+ import "./shapes/env-list";
41
+ import "./shapes/vault-list";
42
+ import "./shapes/secret-list";
43
+ import "./shapes/passthrough";
44
+ // ── Dispatcher ────────────────────────────────────────────────────────────────
108
45
  /**
109
- * Shape the result of `akm reflect` / `akm propose`. On success we surface
110
- * the queued proposal entry (using the standard proposal-entry shaper so
111
- * detail levels behave uniformly with `akm proposal show`). On failure we
112
- * surface the structured failure-reason envelope as-is — the failure
113
- * surface is small and the reason / error text is always load-bearing.
46
+ * Commands whose shape handler implements the `summary` projection. For every
47
+ * other command, `--shape summary` is a usage error (v1 §5 honest rejection
48
+ * for a soon-frozen contract, not a silent fallback to `human`).
114
49
  */
115
- export function shapeProposalProducerOutput(result, detail) {
116
- if (result.ok === false) {
117
- const base = {
118
- ok: false,
119
- reason: result.reason,
120
- error: result.error,
121
- ...(result.ref !== undefined ? { ref: result.ref } : {}),
122
- ...(result.type !== undefined ? { type: result.type } : {}),
123
- ...(result.name !== undefined ? { name: result.name } : {}),
124
- ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
125
- };
126
- if (detail === "full") {
127
- return {
128
- schemaVersion: result.schemaVersion ?? 1,
129
- ...base,
130
- ...(result.stdout !== undefined ? { stdout: result.stdout } : {}),
131
- ...(result.stderr !== undefined ? { stderr: result.stderr } : {}),
132
- };
133
- }
134
- return base;
135
- }
136
- const proposal = result.proposal ?? {};
137
- const base = {
138
- ok: true,
139
- ref: result.ref,
140
- ...(result.agentProfile !== undefined ? { agentProfile: result.agentProfile } : {}),
141
- ...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
142
- proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
143
- };
144
- if (detail === "full") {
145
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
146
- }
147
- return base;
148
- }
149
- export function shapeProposalEntry(entry, detail) {
150
- if (detail === "brief") {
151
- return pickFields(entry, ["id", "ref", "status", "source", "createdAt"]);
152
- }
153
- if (detail === "normal" || detail === "summary") {
154
- return pickFields(entry, ["id", "ref", "status", "source", "sourceRun", "createdAt", "updatedAt", "review"]);
155
- }
156
- // full / agent: project everything including the payload.
157
- return pickFields(entry, [
158
- "id",
159
- "ref",
160
- "status",
161
- "source",
162
- "sourceRun",
163
- "createdAt",
164
- "updatedAt",
165
- "payload",
166
- "review",
167
- ]);
168
- }
169
- export function shapeProposalListOutput(result, detail) {
170
- const proposals = Array.isArray(result.proposals) ? result.proposals : [];
171
- const shaped = proposals.map((p) => shapeProposalEntry(p, detail));
172
- const base = {
173
- totalCount: result.totalCount ?? shaped.length,
174
- proposals: shaped,
175
- };
176
- if (detail === "full") {
177
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
178
- }
179
- return base;
180
- }
181
- export function shapeProposalShowOutput(result, detail) {
182
- const proposal = result.proposal ?? {};
183
- const validation = result.validation;
184
- const base = {
185
- proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
186
- ...(validation ? { validation } : {}),
187
- };
188
- if (detail === "full") {
189
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
190
- }
191
- return base;
192
- }
193
- export function shapeProposalAcceptOutput(result, detail) {
194
- const proposal = result.proposal ?? {};
195
- const base = {
196
- ok: result.ok ?? true,
197
- id: result.id,
198
- ref: result.ref,
199
- assetPath: result.assetPath,
200
- proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
201
- };
202
- if (detail === "full") {
203
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
204
- }
205
- return base;
206
- }
207
- export function shapeProposalRejectOutput(result, detail) {
208
- const proposal = result.proposal ?? {};
209
- const base = {
210
- ok: result.ok ?? true,
211
- id: result.id,
212
- ref: result.ref,
213
- ...(result.reason !== undefined ? { reason: result.reason } : {}),
214
- proposal: shapeProposalEntry(proposal, detail === "brief" ? "normal" : detail),
215
- };
216
- if (detail === "full") {
217
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
218
- }
219
- return base;
220
- }
221
- export function shapeDistillOutput(result, detail) {
222
- const proposal = result.proposal;
223
- if (detail === "brief") {
224
- return pickFields(result, ["ok", "outcome", "inputRef", "lessonRef", "proposalId", "message"]);
225
- }
226
- const base = {
227
- ok: result.ok ?? true,
228
- outcome: result.outcome,
229
- inputRef: result.inputRef,
230
- lessonRef: result.lessonRef,
231
- ...(result.proposalId !== undefined ? { proposalId: result.proposalId } : {}),
232
- ...(result.message !== undefined ? { message: result.message } : {}),
233
- ...(Array.isArray(result.findings) && result.findings.length > 0 ? { findings: result.findings } : {}),
234
- ...(proposal ? { proposal: shapeProposalEntry(proposal, detail === "summary" ? "normal" : detail) } : {}),
235
- };
236
- if (detail === "full") {
237
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
238
- }
239
- return base;
240
- }
241
- export function shapeProposalDiffOutput(result, detail) {
242
- const base = {
243
- id: result.id,
244
- ref: result.ref,
245
- isNew: result.isNew,
246
- unified: result.unified,
247
- ...(result.targetPath !== undefined ? { targetPath: result.targetPath } : {}),
248
- };
249
- if (detail === "full") {
250
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
251
- }
252
- return base;
253
- }
254
- export function shapeEventsOutput(result, detail) {
255
- const events = Array.isArray(result.events) ? result.events : [];
256
- const shapedEvents = events.map((event) => shapeEventEntry(event, detail));
257
- const base = {
258
- ...(result.ref !== undefined ? { ref: result.ref } : {}),
259
- ...(result.type !== undefined ? { type: result.type } : {}),
260
- ...(result.since !== undefined ? { since: result.since } : {}),
261
- ...(typeof result.sinceOffset === "number" ? { sinceOffset: result.sinceOffset } : {}),
262
- totalCount: result.totalCount ?? shapedEvents.length,
263
- events: shapedEvents,
264
- };
265
- if (typeof result.nextOffset === "number") {
266
- base.nextOffset = result.nextOffset;
267
- }
268
- if (typeof result.reason === "string") {
269
- base.reason = result.reason;
270
- }
271
- if (detail === "full") {
272
- return { schemaVersion: result.schemaVersion ?? 1, ...base };
273
- }
274
- return base;
275
- }
276
- export function shapeEventEntry(entry, detail) {
277
- if (detail === "brief") {
278
- return pickFields(entry, ["eventType", "ref", "ts"]);
279
- }
280
- if (detail === "normal" || detail === "summary") {
281
- return pickFields(entry, ["eventType", "ref", "ts"]);
282
- }
283
- // full / agent: project everything the reader emits.
284
- return pickFields(entry, ["id", "schemaVersion", "eventType", "ref", "ts", "metadata"]);
285
- }
286
- export function shapeHistoryOutput(result, detail) {
287
- const entries = Array.isArray(result.entries) ? result.entries : [];
288
- const shapedEntries = entries.map((entry) => shapeHistoryEntry(entry, detail));
289
- if (detail === "full") {
290
- return {
291
- schemaVersion: result.schemaVersion ?? 1,
292
- ...(result.ref !== undefined ? { ref: result.ref } : {}),
293
- ...(result.since !== undefined ? { since: result.since } : {}),
294
- totalCount: result.totalCount ?? shapedEntries.length,
295
- entries: shapedEntries,
296
- // `sources` lists the event sources included in this response.
297
- // Always contains "usage_events"; also "events.jsonl" when
298
- // --include-proposals was specified.
299
- ...(Array.isArray(result.sources) ? { sources: result.sources } : {}),
300
- ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
301
- };
302
- }
303
- return {
304
- ...(result.ref !== undefined ? { ref: result.ref } : {}),
305
- ...(result.since !== undefined ? { since: result.since } : {}),
306
- totalCount: result.totalCount ?? shapedEntries.length,
307
- entries: shapedEntries,
308
- ...(Array.isArray(result.sources) ? { sources: result.sources } : {}),
309
- ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
310
- };
311
- }
312
- export function shapeHistoryEntry(entry, detail) {
313
- if (detail === "brief") {
314
- // signal is load-bearing for feedback rows (positive/negative) so we
315
- // project it even at brief — without it the entry is ambiguous.
316
- return pickFields(entry, ["eventType", "ref", "signal", "createdAt"]);
317
- }
318
- if (detail === "normal" || detail === "summary") {
319
- return pickFields(entry, ["eventType", "ref", "signal", "query", "createdAt"]);
50
+ const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
51
+ export function shapeForCommand(command, result, detail, shape = "human") {
52
+ if (shape === "summary" && !SHAPE_SUMMARY_COMMANDS.has(command)) {
53
+ throw new UsageError(`'--shape summary' is not supported for 'akm ${command}'. It is only available on 'akm show'.`, "INVALID_SHAPE_VALUE");
320
54
  }
321
- // full / agent: return everything the reader emits.
322
- return pickFields(entry, ["id", "eventType", "ref", "entryId", "query", "signal", "metadata", "createdAt"]);
323
- }
324
- export function shapeSearchOutput(result, detail, forAgent = false) {
325
- const hits = Array.isArray(result.hits) ? result.hits : [];
326
- const registryHits = Array.isArray(result.registryHits) ? result.registryHits : [];
327
- const shapedHits = forAgent
328
- ? hits.map((hit) => shapeSearchHitForAgent(hit))
329
- : hits.map((hit) => shapeSearchHit(hit, detail));
330
- const shapedRegistryHits = forAgent
331
- ? registryHits.map((hit) => shapeSearchHitForAgent(hit))
332
- : registryHits.map((hit) => shapeSearchHit(hit, detail));
333
- if (forAgent) {
334
- return {
335
- hits: shapedHits,
336
- ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
337
- ...(result.tip ? { tip: result.tip } : {}),
338
- };
339
- }
340
- if (detail === "full") {
341
- return {
342
- schemaVersion: result.schemaVersion,
343
- stashDir: result.stashDir,
344
- source: result.source,
345
- hits: shapedHits,
346
- ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
347
- ...(result.semanticSearch ? { semanticSearch: result.semanticSearch } : {}),
348
- ...(result.tip ? { tip: result.tip } : {}),
349
- ...(result.warnings ? { warnings: result.warnings } : {}),
350
- ...(result.timing ? { timing: result.timing } : {}),
351
- };
352
- }
353
- return {
354
- hits: shapedHits,
355
- ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
356
- ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
357
- ...(result.tip ? { tip: result.tip } : {}),
358
- };
359
- }
360
- export function shapeRegistrySearchOutput(result, detail) {
361
- const hits = Array.isArray(result.hits) ? result.hits : [];
362
- const assetHits = Array.isArray(result.assetHits) ? result.assetHits : [];
363
- // Shape stash hits as registry type
364
- const shapedKitHits = hits.map((hit) => shapeSearchHit({ ...hit, type: "registry" }, detail));
365
- // Shape asset hits by detail level
366
- const shapedAssetHits = assetHits.map((hit) => shapeAssetHit(hit, detail));
367
- const shaped = {
368
- hits: shapedKitHits,
369
- ...(shapedAssetHits.length > 0 ? { assetHits: shapedAssetHits } : {}),
370
- ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
371
- };
372
- if (detail === "full") {
373
- shaped.query = result.query;
374
- }
375
- return shaped;
376
- }
377
- export function shapeAssetHit(hit, detail) {
378
- if (detail === "brief")
379
- return pickFields(hit, ["assetName", "assetType", "action", "estimatedTokens"]);
380
- if (detail === "normal") {
381
- return capDescription(pickFields(hit, ["assetName", "assetType", "description", "stash", "action", "estimatedTokens"]), NORMAL_DESCRIPTION_LIMIT);
382
- }
383
- return hit;
384
- }
385
- export function shapeSearchHit(hit, detail) {
386
- if (hit.type === "registry") {
387
- if (detail === "brief") {
388
- // RegistrySearchHit uses `title` (not `name`); always project installRef
389
- // and score so callers can use the result without --detail full (QA #28).
390
- const out = pickFields(hit, ["title", "name", "installRef", "score"]);
391
- // Normalise: if only title exists, expose it as `name` for consistency
392
- if (out.title && !out.name)
393
- out.name = out.title;
394
- return out;
395
- }
396
- if (detail === "normal") {
397
- // `curated` was removed in v1 (spec §4.2). Renderers project optional
398
- // hit-level `warnings` instead so providers can surface non-fatal issues.
399
- const out = capDescription(pickFields(hit, ["title", "name", "description", "action", "installRef", "score", "warnings"]), NORMAL_DESCRIPTION_LIMIT);
400
- if (out.title && !out.name)
401
- out.name = out.title;
402
- return out;
403
- }
404
- return hit;
405
- }
406
- // Stash hit (local or remote)
407
- // `ref` is included at `brief` so agents can run `akm show <ref>` without
408
- // needing --detail full or --for-agent (REC-03).
409
- if (detail === "brief")
410
- return pickFields(hit, ["type", "name", "ref", "action", "estimatedTokens", "keys"]);
411
- if (detail === "normal") {
412
- // `warnings` is projected at `normal` so non-fatal hit-level issues are
413
- // visible without forcing callers up to `--detail full`. Optional
414
- // `quality` (v1 spec §4.2) is also surfaced when present so callers
415
- // can see why a `proposed` entry showed up under `--include-proposed`.
416
- const shaped = capDescription(pickFields(hit, ["type", "name", "description", "action", "score", "estimatedTokens", "warnings", "quality"]), NORMAL_DESCRIPTION_LIMIT);
417
- if (Array.isArray(hit.keys) && hit.keys.length > 0)
418
- shaped.keys = hit.keys;
419
- return shaped;
420
- }
421
- return hit;
422
- }
423
- /** Agent-optimized search hit: only fields an LLM agent needs to decide and act */
424
- export function shapeSearchHitForAgent(hit) {
425
- const picked = pickFields(hit, ["name", "ref", "type", "description", "action", "score", "estimatedTokens", "keys"]);
426
- return capDescription(picked, NORMAL_DESCRIPTION_LIMIT);
427
- }
428
- export function capDescription(hit, limit) {
429
- if (typeof hit.description !== "string")
430
- return hit;
431
- return { ...hit, description: truncateDescription(hit.description, limit) };
432
- }
433
- export function truncateDescription(description, limit) {
434
- const normalized = description.replace(/\s+/g, " ").trim();
435
- if (normalized.length <= limit)
436
- return normalized;
437
- const truncated = normalized.slice(0, limit - 1);
438
- const lastSpace = truncated.lastIndexOf(" ");
439
- const safe = lastSpace >= Math.floor(limit * 0.6) ? truncated.slice(0, lastSpace) : truncated;
440
- return `${safe.trimEnd()}...`;
441
- }
442
- export function shapeShowOutput(result, detail, forAgent = false) {
443
- if (forAgent) {
444
- return pickFields(result, [
445
- "type",
446
- "name",
447
- "description",
448
- "action",
449
- "content",
450
- "template",
451
- "prompt",
452
- "run",
453
- "setup",
454
- "cwd",
455
- "activeRun",
456
- "toolPolicy",
457
- "modelHint",
458
- "agent",
459
- "parameters",
460
- "workflowTitle",
461
- "workflowParameters",
462
- "steps",
463
- "keys",
464
- "comments",
465
- ]);
466
- }
467
- if (detail === "summary") {
468
- return pickFields(result, [
469
- "type",
470
- "name",
471
- "description",
472
- "tags",
473
- "parameters",
474
- "workflowTitle",
475
- "action",
476
- "run",
477
- "origin",
478
- "keys",
479
- "comments",
480
- ]);
481
- }
482
- const base = pickFields(result, [
483
- "type",
484
- "name",
485
- "origin",
486
- "action",
487
- "description",
488
- "tags",
489
- "content",
490
- "template",
491
- "prompt",
492
- "toolPolicy",
493
- "modelHint",
494
- "agent",
495
- "parameters",
496
- "workflowTitle",
497
- "workflowParameters",
498
- "steps",
499
- "run",
500
- "setup",
501
- "cwd",
502
- "activeRun",
503
- "keys",
504
- "comments",
505
- // path and editable are always projected so JSON consumers can locate and
506
- // edit the asset without needing --detail full (QA #7).
507
- "path",
508
- "editable",
509
- ]);
510
- if (detail !== "full") {
511
- return base;
512
- }
513
- return {
514
- schemaVersion: 1,
515
- ...base,
516
- ...pickFields(result, ["editHint"]),
517
- };
518
- }
519
- export function pickFields(source, fields) {
520
- const result = {};
521
- for (const field of fields) {
522
- if (source[field] !== undefined) {
523
- result[field] = source[field];
524
- }
55
+ const handler = getOutputShapeHandler(command);
56
+ if (handler) {
57
+ return handler(result, detail, shape);
525
58
  }
526
- return result;
59
+ // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
60
+ // fallback. A missing case here is a registration bug — fail loudly so
61
+ // the caller (or its tests) sees the missing command name.
62
+ throw new Error(`output shape not registered for command: ${command}`);
527
63
  }
528
- export { NORMAL_DESCRIPTION_LIMIT };
@@ -0,0 +1,6 @@
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
+ import { formatAddPlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("add", (r) => formatAddPlain(r));
@@ -0,0 +1,6 @@
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
+ import { formatClonePlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("clone", (r) => formatClonePlain(r));
@@ -0,0 +1,6 @@
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
+ import { formatConfigPlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("config", (r) => formatConfigPlain(r));
@@ -0,0 +1,6 @@
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
+ import { formatCuratePlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("curate", (r, detail) => formatCuratePlain(r, detail));
@@ -0,0 +1,7 @@
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
+ // Output text formatter for `akm distill <ref>` (#228).
5
+ import { formatDistillPlain } from "./helpers";
6
+ import { registerTextFormatter } from "./registry";
7
+ registerTextFormatter("distill", (r) => formatDistillPlain(r));
@@ -0,0 +1,7 @@
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
+ import { formatToggleComponentPlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("enable", (r) => formatToggleComponentPlain("enable", r));
7
+ registerTextFormatter("disable", (r) => formatToggleComponentPlain("disable", r));
@@ -0,0 +1,10 @@
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
+ // Output text formatters for `akm events list` / `akm events tail` (#204).
5
+ // Both share a renderer; `events-tail` is also called per-event by the streaming
6
+ // code path via `formatEventLine`.
7
+ import { formatEventsPlain } from "./helpers";
8
+ import { registerTextFormatter } from "./registry";
9
+ registerTextFormatter("events-list", (r) => formatEventsPlain(r));
10
+ registerTextFormatter("events-tail", (r) => formatEventsPlain(r));
@@ -0,0 +1,6 @@
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
+ import { formatFeedbackPlain } from "./helpers";
5
+ import { registerTextFormatter } from "./registry";
6
+ registerTextFormatter("feedback", (r) => formatFeedbackPlain(r));