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.
- package/CHANGELOG.md +25 -0
- package/dist/cli/usage.js +4 -0
- package/dist/cli.js +10 -0
- package/dist/commands/feedback-cli.js +12 -3
- package/dist/commands/health/semantic-search-check.js +12 -2
- package/dist/commands/health.js +8 -15
- package/dist/commands/lint/index.js +6 -6
- package/dist/commands/read/knowledge.js +8 -8
- package/dist/commands/read/related.js +3 -9
- package/dist/commands/read/show.js +17 -9
- package/dist/commands/sources/bundle-cli.js +1 -0
- package/dist/commands/sources/installed-stashes.js +36 -27
- package/dist/core/asset/resolve-ref.js +8 -0
- package/dist/core/common.js +21 -0
- package/dist/core/endpoint-url.js +4 -4
- package/dist/core/events.js +8 -2
- package/dist/core/file-lock.js +52 -1
- package/dist/core/state-db.js +47 -15
- package/dist/core/stdio-reader-gone.js +19 -0
- package/dist/core/write-source.js +2 -2
- package/dist/indexer/index-build.js +6 -3
- package/dist/indexer/index-readiness.js +30 -4
- package/dist/indexer/indexer.js +56 -8
- package/dist/indexer/search/db-search.js +7 -1
- package/dist/indexer/search/search-source.js +23 -25
- package/dist/indexer/usage/usage-events.js +13 -4
- package/dist/indexer/vector-file.js +3 -3
- package/dist/registry/origin-resolve.js +2 -3
- package/dist/scripts/akm-migrate-node.js +136 -88
- package/dist/scripts/akm-migrate.js +136 -88
- package/dist/setup/endpoint.js +1 -1
- package/dist/storage/database.js +29 -36
- package/dist/storage/repositories/index-connection.js +44 -41
- package/dist/storage/repositories/index-entries-repository.js +14 -7
- package/dist/storage/repositories/index-entry-schema.js +7 -5
- package/dist/storage/repositories/index-schema.js +23 -0
- package/dist/storage/sqlite-read-snapshot.js +2 -2
- package/dist/workspace/assets.js +24 -44
- package/dist/workspace/bundle-files.js +2 -2
- package/dist/workspace/documents.js +7 -12
- package/dist/workspace/graph-topics.js +249 -0
- package/dist/workspace/graph.js +68 -4
- package/docs/reference/workspace.md +21 -4
- package/package.json +1 -1
package/dist/workspace/graph.js
CHANGED
|
@@ -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
|
|
22
|
-
*
|
|
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
|
-
|
|
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. `
|
|
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.
|
|
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.
|
|
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": [
|