akm-cli 0.10.261124 → 0.10.261125

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 (44) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/dist/cli/usage.js +4 -0
  3. package/dist/cli.js +10 -0
  4. package/dist/commands/feedback-cli.js +12 -3
  5. package/dist/commands/health/semantic-search-check.js +12 -2
  6. package/dist/commands/health.js +8 -15
  7. package/dist/commands/lint/index.js +6 -6
  8. package/dist/commands/read/knowledge.js +8 -8
  9. package/dist/commands/read/related.js +3 -9
  10. package/dist/commands/read/show.js +17 -9
  11. package/dist/commands/sources/bundle-cli.js +1 -0
  12. package/dist/commands/sources/installed-stashes.js +36 -27
  13. package/dist/core/asset/resolve-ref.js +8 -0
  14. package/dist/core/common.js +21 -0
  15. package/dist/core/endpoint-url.js +4 -4
  16. package/dist/core/events.js +8 -2
  17. package/dist/core/file-lock.js +52 -1
  18. package/dist/core/state-db.js +47 -15
  19. package/dist/core/stdio-reader-gone.js +19 -0
  20. package/dist/core/write-source.js +2 -2
  21. package/dist/indexer/index-build.js +6 -3
  22. package/dist/indexer/index-readiness.js +30 -4
  23. package/dist/indexer/indexer.js +56 -8
  24. package/dist/indexer/search/db-search.js +7 -1
  25. package/dist/indexer/search/search-source.js +23 -25
  26. package/dist/indexer/usage/usage-events.js +13 -4
  27. package/dist/indexer/vector-file.js +3 -3
  28. package/dist/registry/origin-resolve.js +2 -3
  29. package/dist/scripts/akm-migrate-node.js +136 -88
  30. package/dist/scripts/akm-migrate.js +136 -88
  31. package/dist/setup/endpoint.js +1 -1
  32. package/dist/storage/database.js +29 -36
  33. package/dist/storage/repositories/index-connection.js +44 -41
  34. package/dist/storage/repositories/index-entries-repository.js +14 -7
  35. package/dist/storage/repositories/index-entry-schema.js +7 -5
  36. package/dist/storage/repositories/index-schema.js +23 -0
  37. package/dist/storage/sqlite-read-snapshot.js +2 -2
  38. package/dist/workspace/assets.js +24 -44
  39. package/dist/workspace/bundle-files.js +2 -2
  40. package/dist/workspace/documents.js +7 -12
  41. package/dist/workspace/graph-topics.js +249 -0
  42. package/dist/workspace/graph.js +68 -4
  43. package/docs/reference/workspace.md +21 -4
  44. package/package.json +1 -1
@@ -2,29 +2,50 @@
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
  /** The whole library as a graph: every indexed asset, every declared link between them, and how each is used. */
5
+ import { createHash } from "node:crypto";
6
+ import fs from "node:fs";
5
7
  import { loadConfig } from "../core/config/config.js";
8
+ import { ConfigError } from "../core/errors.js";
6
9
  import { getDbPath } from "../core/paths.js";
7
10
  import { applyEntryFilters } from "../indexer/search/db-search.js";
8
11
  import { resolveSourceEntries } from "../indexer/search/search-source.js";
9
- import { countUseByRef, usageRetentionSince } from "../indexer/usage/usage-events.js";
12
+ import { countFeedbackSignalsByRef, countUseByRef, usageRetentionSince } from "../indexer/usage/usage-events.js";
10
13
  import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
11
14
  import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
12
15
  import { listDeclaredLinks } from "../storage/repositories/index-links-repository.js";
13
16
  import { getMeta } from "../storage/repositories/index-meta-repository.js";
14
17
  import { listCurrentEmbeddings } from "../storage/repositories/index-vec-repository.js";
18
+ import { findTopics } from "./graph-topics.js";
15
19
  import { withReadonlyStateDb } from "./readers.js";
16
20
  /** Types never drawn: protected files and session logs, as `assets.related` leaves them out. */
17
21
  const HIDDEN_TYPES = ["secret", "env", "session"];
18
22
  /**
19
23
  * Every asset of the enabled bundles and the declared links between them, in column form: node `i` is `nodes.ref[i]`,
20
24
  * and its type, bundle and belief state are indexes into `types`, `bundles` (largest first) and `beliefs` (-1: no state
21
- * recorded). `shows` and `searches` are read live from the user-attributed usage events within retention (`use`). A link joins two nodes by index and names its kind
22
- * by index into `kinds`. `meaning` places each node with a stored embedding in three dimensions (see
25
+ * recorded). `shows`, `searches`, `lastShownAt` and the feedback counts `positive` and `negative` are read live from the
26
+ * user-attributed usage events within retention (`use`); `modifiedAt` is the file's modification time. A link joins two
27
+ * nodes by index and names its kind by index into `kinds`. `topic` indexes `topics` (see {@link findTopics}), -1 for
28
+ * an asset with no stored embedding, and `duplicates` pairs assets of one topic whose embeddings are nearly the same. `meaning` places each node with a stored embedding in three dimensions (see
23
29
  * {@link projectEmbeddings}); it is `null` when the index has no embeddings. Nothing is written. The projection yields
24
30
  * to the event loop as it goes, so a host serving other requests keeps answering them.
25
31
  */
26
32
  export async function graph() {
27
- const empty = {
33
+ try {
34
+ return await readGraph();
35
+ }
36
+ catch (error) {
37
+ // A damaged or unreadable index file is "no usable index" to the map, not a raw SQLite error.
38
+ if (error instanceof Error && error.name === "SQLiteError")
39
+ return {
40
+ available: false,
41
+ note: `The index could not be read (${error.message}). Rebuild it with 'akm index --full'.`,
42
+ ...emptyGraph(),
43
+ };
44
+ throw error;
45
+ }
46
+ }
47
+ function emptyGraph() {
48
+ return {
28
49
  types: [],
29
50
  bundles: [],
30
51
  beliefs: [],
@@ -42,15 +63,28 @@ export async function graph() {
42
63
  belief: [],
43
64
  shows: [],
44
65
  searches: [],
66
+ lastShownAt: [],
67
+ modifiedAt: [],
68
+ positive: [],
69
+ negative: [],
70
+ topic: [],
45
71
  },
46
72
  links: { from: [], to: [], kind: [] },
47
73
  meaning: null,
74
+ topics: [],
75
+ duplicates: null,
48
76
  };
77
+ }
78
+ async function readGraph() {
79
+ const empty = emptyGraph();
49
80
  const db = openReadonlyExistingDatabase();
50
81
  if (!db)
51
82
  return { available: false, note: "No index is available. Build the AKM index first.", ...empty };
52
83
  let closed = false;
53
84
  try {
85
+ // An index still being built for the first time has its meta table but not yet its entries.
86
+ if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'entries'").get())
87
+ return { available: false, note: "The index is still being built. Try again when it finishes.", ...empty };
54
88
  const sources = resolveSourceEntries(undefined, loadConfig()).filter((source) => !source.unresolved);
55
89
  const rows = applyEntryFilters(getAllEntries(db, undefined, HIDDEN_TYPES), {
56
90
  db,
@@ -84,6 +118,7 @@ export async function graph() {
84
118
  result.emptyBundles = sources.flatMap((source) => source.registryId && !perBundle.has(source.registryId) ? [source.registryId] : []);
85
119
  const since = usageRetentionSince();
86
120
  const use = withReadonlyStateDb((state) => countUseByRef(state, since), null);
121
+ const feedback = withReadonlyStateDb((state) => countFeedbackSignalsByRef(state, rows.map((row) => row.itemRef)), null);
87
122
  result.use = { since, source: "user" };
88
123
  for (const row of rows) {
89
124
  const counts = use?.get(row.itemRef);
@@ -94,6 +129,11 @@ export async function graph() {
94
129
  result.nodes.belief.push(row.entry.beliefState ? beliefCode(row.entry.beliefState) : -1);
95
130
  result.nodes.shows.push(counts?.shows ?? 0);
96
131
  result.nodes.searches.push(counts?.searches ?? 0);
132
+ result.nodes.lastShownAt.push(counts?.lastShownAt ?? null);
133
+ result.nodes.modifiedAt.push(modifiedAt(row.filePath));
134
+ const signals = feedback?.get(row.itemRef);
135
+ result.nodes.positive.push(signals?.pos ?? 0);
136
+ result.nodes.negative.push(signals?.neg ?? 0);
97
137
  }
98
138
  for (const link of listDeclaredLinks(db)) {
99
139
  const from = index.get(link.from);
@@ -114,6 +154,15 @@ export async function graph() {
114
154
  closed = true;
115
155
  const placed = await projectEmbeddings(rows.map((row) => vectors.get(row.id)), build);
116
156
  result.meaning = placed.embedded ? placed : null;
157
+ const libraryKey = createHash("sha1")
158
+ .update(rows.map((row) => row.id).join(","))
159
+ .digest("hex");
160
+ const found = await findTopics(rows.map((row) => vectors.get(row.id)), rows.map((row, i) => `${row.conceptId} ${result.nodes.title[i]}`),
161
+ // Topics are per asset: the same build read through a different set of enabled bundles is a different library.
162
+ `${build}|${libraryKey}`);
163
+ result.topics = found.topics;
164
+ result.nodes.topic = found.topic;
165
+ result.duplicates = found.topics.length ? found.duplicates : null;
117
166
  const noted = [`${rows.length} assets and ${result.links.from.length} links of the enabled bundles.`];
118
167
  if (result.unresolvedLinks)
119
168
  noted.push(`${result.unresolvedLinks} declared links are not drawn (target missing, hidden or in a bundle that is not enabled).`);
@@ -129,11 +178,26 @@ export async function graph() {
129
178
  ...result,
130
179
  };
131
180
  }
181
+ catch (error) {
182
+ // A query that fails on a damaged index is no index; permission and newer-layout errors still raise.
183
+ if (closed || error instanceof ConfigError)
184
+ throw error;
185
+ return { available: false, note: "The index could not be read. Rebuild it with `akm index`.", ...empty };
186
+ }
132
187
  finally {
133
188
  if (!closed)
134
189
  closeDatabase(db);
135
190
  }
136
191
  }
192
+ /** A file's modification time as an ISO timestamp, or null when it cannot be read. */
193
+ function modifiedAt(file) {
194
+ try {
195
+ return fs.statSync(file).mtime.toISOString();
196
+ }
197
+ catch {
198
+ return null;
199
+ }
200
+ }
137
201
  /** Fewest vectors the principal components can be found from. */
138
202
  const MIN_VECTORS = 4;
139
203
  /** The note's sentence on how many assets have a position by meaning. */
@@ -200,9 +200,13 @@ them, in column form, so 30,000 assets stay a few megabytes:
200
200
  "unresolvedLinks": 2,
201
201
  "kinds": ["xref", "links_to"],
202
202
  "nodes": { "ref": ["team-wiki//knowledge/a"], "title": ["A"], "type": [0], "bundle": [0], "belief": [-1],
203
- "shows": [12], "searches": [40] },
203
+ "shows": [12], "searches": [40], "lastShownAt": ["2026-11-02T09:14:03Z"],
204
+ "modifiedAt": ["2026-03-30T17:02:11.000Z"], "positive": [2], "negative": [0], "topic": [4] },
204
205
  "links": { "from": [0], "to": [3], "kind": [1] },
205
- "meaning": { "embedded": 29840, "xyz": [12.5, -40.1, 3.2] }
206
+ "meaning": { "embedded": 29840, "xyz": [12.5, -40.1, 3.2] },
207
+ "topics": [{ "label": "deploy · canary", "terms": ["deploy", "canary", "rollout"], "size": 812,
208
+ "related": [{ "topic": 7, "cosine": 0.81 }] }],
209
+ "duplicates": { "threshold": 0.96, "a": [0], "b": [9], "cosine": [0.9871], "truncated": false }
206
210
  }
207
211
  ```
208
212
 
@@ -213,13 +217,26 @@ the asset that declares it to its target; `unresolvedLinks` counts the declared
213
217
  target is missing, of a type that is not returned, or in a bundle that is not enabled. `shows` and `searches` are
214
218
  counted from the usage events when the operation is called: events of source `user` (people and their agent
215
219
  sessions, not scheduled tasks or Improve) at or after `use.since`, the start of the usage retention window. They are
216
- zero, and the note says so, when no usage history is available. `meaning` places each asset with a stored embedding
220
+ zero, and the note says so, when no usage history is available. `lastShownAt` is the latest of those shows (UTC), `null`
221
+ when there is none in the window. `positive` and `negative` count feedback from people inside the retention window, as
222
+ search ranks by it (a negative answered by an accepted fix does not count). `modifiedAt` is the file's modification
223
+ time, `null` when it cannot be read; in a Git checkout it is when the file was last written there, not its last commit. `meaning` places each asset with a stored embedding
217
224
  of the index's current model in three dimensions (three coordinates per node, `null` for one with no embedding): its
218
225
  projection on the three principal components of the vectors, so assets with similar content land near each other. The
219
226
  components are found from an evenly spaced sample of at most 4,000 vectors and kept for the life of the process until
220
227
  the index's embedding model or full build changes; an asset embedded since is projected onto them. The work yields to
221
228
  the event loop as it goes, so a host's other requests are served meanwhile. `meaning` is `null` when the index has no
222
- embeddings. `available` is `false`, with a `note`,
229
+ embeddings.
230
+
231
+ `topics` groups the embedded assets by meaning: spherical k-means on their stored vectors, about √(n/2) topics (2 to 36),
232
+ largest first, the centres found from an evenly spaced sample of at most 4,000 vectors from a fixed start, so the same
233
+ index gives the same topics. A topic's `terms` are the words of its assets' paths and titles most particular to it
234
+ (frequent in the topic, rare in the library), and its `label` the first two; `related` names the three topics whose
235
+ centres are nearest, with the cosine between them. `nodes.topic` indexes `topics`, `-1` for an asset with no embedding.
236
+ `duplicates` lists pairs of assets of one topic whose vectors have a cosine of at least `threshold` (0.96), most alike
237
+ first, at most 2,000 (`truncated` says there were more); pairs across topics are not compared. Both are `[]` and `null`
238
+ without at least eight embedded assets. They are found once per index build and kept, like the projection: the first
239
+ read of a 20,000-asset index takes several seconds. `available` is `false`, with a `note`,
223
240
  when there is no index.
224
241
 
225
242
  ## `bundles.list`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261124",
3
+ "version": "0.10.261125",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [