akm-cli 0.10.261129 → 0.10.261130-beta.2

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 (114) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/STABILITY.md +11 -0
  3. package/dist/assets/hints/cli-hints-full.md +1 -1
  4. package/dist/assets/hints/cli-hints-short.md +1 -0
  5. package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
  6. package/dist/cli/usage-report.js +184 -0
  7. package/dist/cli/usage.js +24 -7
  8. package/dist/cli.js +8 -2
  9. package/dist/commands/completions.js +5 -4
  10. package/dist/commands/health/checks.js +18 -4
  11. package/dist/commands/health/connections-and-harnesses-check.js +1 -0
  12. package/dist/commands/health/egress.js +1 -2
  13. package/dist/commands/health/plugin-staleness.js +75 -159
  14. package/dist/commands/health/scheduler-binary.js +7 -2
  15. package/dist/commands/health/semantic-search-check.js +7 -6
  16. package/dist/commands/health/version-drift.js +2 -0
  17. package/dist/commands/improve/extract.js +2 -2
  18. package/dist/commands/improve/preparation.js +6 -1
  19. package/dist/commands/lint/base-linter.js +90 -48
  20. package/dist/commands/lint/index.js +128 -185
  21. package/dist/commands/lint/moved-refs.js +69 -0
  22. package/dist/commands/lint/scope.js +41 -0
  23. package/dist/commands/metrics/collect.js +25 -2
  24. package/dist/commands/metrics/report-view.js +11 -2
  25. package/dist/commands/proposal/proposal.js +7 -2
  26. package/dist/commands/proposal/repository.js +16 -11
  27. package/dist/commands/read/rules.js +142 -0
  28. package/dist/commands/read/search-cli.js +5 -5
  29. package/dist/commands/read/search.js +1 -1
  30. package/dist/commands/sources/plugin-upgrade.js +139 -71
  31. package/dist/commands/sources/source-clone.js +4 -4
  32. package/dist/commands/sources/sources-cli.js +3 -20
  33. package/dist/commands/sources/sync.js +24 -0
  34. package/dist/commands/tasks/tasks.js +1 -1
  35. package/dist/core/adapter/adapters/akm-adapter.js +32 -23
  36. package/dist/core/adapter/adapters/akm-lint.js +55 -61
  37. package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
  38. package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
  39. package/dist/core/adapter/adapters/okf-adapter.js +5 -9
  40. package/dist/core/adapter/adapters/shared.js +52 -200
  41. package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
  42. package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
  43. package/dist/core/adapter/validate-context.js +7 -11
  44. package/dist/core/asset/asset-placement.js +29 -0
  45. package/dist/core/asset/frontmatter-edit.js +124 -0
  46. package/dist/core/asset/lint-text.js +18 -2
  47. package/dist/core/asset/llm-wiki-root.js +30 -0
  48. package/dist/core/asset/ref-rewrite.js +39 -0
  49. package/dist/core/asset/type-keys.js +59 -0
  50. package/dist/core/config/schema/local-state.js +5 -1
  51. package/dist/core/config/schema/output.js +4 -4
  52. package/dist/core/config/schema/search.js +4 -0
  53. package/dist/core/write-source.js +75 -25
  54. package/dist/indexer/index-written-assets.js +16 -8
  55. package/dist/indexer/indexer.js +68 -19
  56. package/dist/indexer/legacy-refs.js +1 -26
  57. package/dist/indexer/links/declared-links.js +13 -11
  58. package/dist/indexer/ref-moves.js +75 -0
  59. package/dist/indexer/search/db-search.js +3 -2
  60. package/dist/indexer/walk/place-rules.js +25 -0
  61. package/dist/indexer/walk/walker.js +5 -1
  62. package/dist/integrations/session-logs/pre-filter.js +1 -0
  63. package/dist/output/context.js +6 -2
  64. package/dist/output/shapes/passthrough.js +1 -0
  65. package/dist/output/text/rules.js +14 -0
  66. package/dist/output/text.js +2 -0
  67. package/dist/scripts/akm-migrate-node.js +4651 -3584
  68. package/dist/scripts/akm-migrate.js +4650 -3584
  69. package/dist/setup/registry-stash-loader.js +4 -2
  70. package/dist/sources/providers/git-stash.js +13 -5
  71. package/dist/storage/repositories/index-entries-repository.js +8 -3
  72. package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
  73. package/dist/workspace/activity.js +69 -8
  74. package/dist/workspace/asset-improve.js +9 -5
  75. package/dist/workspace/assets.js +33 -19
  76. package/dist/workspace/bundle-files.js +39 -2
  77. package/dist/workspace/bundles.js +53 -3
  78. package/dist/workspace/check-text.js +121 -0
  79. package/dist/workspace/config.js +3 -0
  80. package/dist/workspace/copy-entry.js +129 -0
  81. package/dist/workspace/derive.js +13 -4
  82. package/dist/workspace/documents.js +11 -16
  83. package/dist/workspace/file-actions.js +130 -0
  84. package/dist/workspace/frontmatter.js +41 -0
  85. package/dist/workspace/git-read.js +42 -27
  86. package/dist/workspace/graph.js +11 -2
  87. package/dist/workspace/impact.js +14 -5
  88. package/dist/workspace/metrics.js +1 -1
  89. package/dist/workspace/misses.js +8 -3
  90. package/dist/workspace/moved-links.js +57 -0
  91. package/dist/workspace/new-file.js +141 -0
  92. package/dist/workspace/proposals.js +12 -38
  93. package/dist/workspace/pulse.js +16 -9
  94. package/dist/workspace/readers.js +14 -0
  95. package/dist/workspace/sensitive.js +12 -6
  96. package/dist/workspace/setup.js +2 -1
  97. package/dist/workspace/stats.js +4 -0
  98. package/dist/workspace.d.ts +100 -1
  99. package/docs/architecture/adapters.md +15 -0
  100. package/docs/architecture/internals/health-advisories.md +13 -8
  101. package/docs/architecture/internals/indexing.md +1 -0
  102. package/docs/architecture/internals/storage-locations.md +3 -3
  103. package/docs/architecture/persisted-data-compat.md +2 -0
  104. package/docs/architecture/specs/ref.md +27 -13
  105. package/docs/guides/author-bundles.md +13 -12
  106. package/docs/integration/bundling-akm.md +3 -0
  107. package/docs/maintainers/implementation-details.md +1 -1
  108. package/docs/reference/api.md +3 -3
  109. package/docs/reference/cli.md +143 -35
  110. package/docs/reference/configuration.md +2 -1
  111. package/docs/reference/data-and-telemetry.md +49 -10
  112. package/docs/reference/workspace.md +122 -36
  113. package/package.json +1 -1
  114. package/schemas/akm-config.json +6 -0
@@ -15,9 +15,10 @@ import path from "node:path";
15
15
  import { tryParseJson } from "../../core/common.js";
16
16
  import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
17
17
  import { opencodeCacheDir } from "../../integrations/harnesses/opencode/roots.js";
18
- import { highestVersion, isExactSemver, isPrerelease } from "../../registry/semver.js";
18
+ import { highestVersion, isExactSemver } from "../../registry/semver.js";
19
+ import { semverOrder } from "../../runtime.js";
19
20
  import { codexMarketplace } from "../sources/plugin-channels.js";
20
- import { codexConfigFile, codexMarketplaceRef, codexPluginVersion, openCodeConfigSpec, } from "../sources/plugin-upgrade.js";
21
+ import { claudeMarketplace, codexConfigFile, codexMarketplaceRef, codexPluginVersion, marketplaceTargetVersion, openCodeConfigSpec, refChannel, } from "../sources/plugin-upgrade.js";
21
22
  /**
22
23
  * Root directory holding Claude Code's plugin cache + marketplace clones.
23
24
  * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
@@ -207,123 +208,47 @@ function readPinnedCli(pluginDir) {
207
208
  const pin = manifest?.dependencies?.["akm-cli"];
208
209
  return typeof pin === "string" && isExactSemver(pin) ? pin : undefined;
209
210
  }
210
- const LS_REMOTE_TIMEOUT_MS = 5_000;
211
- /**
212
- * `git ls-remote --symref origin` against the marketplace clone's configured remote (lists refs only, fetches no
213
- * objects, writes no local refs), read for the channel the clone follows:
214
- *
215
- * - **The remote's default branch** (stable): every stable release tag; the newest is the highest of them.
216
- * - **Any other branch** (a channel such as `next`): the release tags on that branch's head. A channel branch is
217
- * reset to each build it publishes, so its head IS the newest build of the channel, whatever semver order says
218
- * about other tags (retired build schemes can sort above current builds).
219
- * - **No branch** (a marketplace added at a tag ref, which Claude Code clones detached): the release tag the clone
220
- * is pinned to. A pinned marketplace never offers anything newer, so `claude plugin update` could not act on a
221
- * newer tag elsewhere. A detached clone at an untagged commit reads like the default branch.
222
- *
223
- * Returns `undefined` (never throws) when the directory is not a git checkout, has no `origin` remote, or the
224
- * command fails/times out (e.g. offline): all "cannot determine availability", not "up to date". A channel head
225
- * with no release tag returns `[]`, which reads the same way.
226
- */
227
- const splitRefs = (lsRemote) => lsRemote
228
- .split("\n")
229
- .map((line) => line.trim())
230
- .filter(Boolean)
231
- .map((line) => line.split("\t"));
232
- /**
233
- * The release versions one channel offers, from `git ls-remote --symref` output: the tags at `branch`'s head when it
234
- * is not the remote's default branch, the tags at `pinnedSha` when given and tagged, else every stable tag.
235
- */
236
- function channelVersions(lsRemote, branch, pinnedSha) {
237
- const refs = splitRefs(lsRemote);
238
- const defaultBranch = refs
239
- .find(([value, name]) => name === "HEAD" && value?.startsWith("ref: refs/heads/"))?.[0]
240
- ?.replace(/^ref: refs\/heads\//, "");
241
- const tags = refs
242
- .filter(([, name]) => typeof name === "string" && name.startsWith("refs/tags/"))
243
- .map(([sha, name]) => ({
244
- sha: sha,
245
- version: name
246
- .replace(/^refs\/tags\//, "")
247
- .replace(/\^\{\}$/, "")
248
- .replace(/^v/, ""),
249
- }))
250
- .filter((tag) => isExactSemver(tag.version));
251
- const tagsAt = (sha) => [
252
- ...new Set(tags.filter((tag) => tag.sha === sha).map((tag) => tag.version)),
253
- ];
254
- const onChannelBranch = branch !== "" && defaultBranch !== undefined && branch !== defaultBranch;
255
- if (onChannelBranch)
256
- return tagsAt(refs.find(([, name]) => name === `refs/heads/${branch}`)?.[0]);
257
- if (branch === "" && pinnedSha !== undefined) {
258
- const pinned = tagsAt(pinnedSha);
259
- if (pinned.length > 0)
260
- return pinned;
261
- }
262
- return [...new Set(tags.map((tag) => tag.version).filter((version) => !isPrerelease(version)))];
263
- }
264
- const realListRemoteTags = (marketplaceDir) => {
265
- let result;
266
- let branch;
211
+ function readOffered(harness, registered, readChannelVersion) {
267
212
  try {
268
- branch =
269
- spawnSync("git", ["-C", marketplaceDir, "branch", "--show-current"], {
270
- encoding: "utf8",
271
- timeout: LS_REMOTE_TIMEOUT_MS,
272
- }).stdout?.trim() ?? "";
273
- result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--symref", "origin"], {
274
- encoding: "utf8",
275
- timeout: LS_REMOTE_TIMEOUT_MS,
276
- });
213
+ const { source, ref } = registered();
214
+ if (source === undefined)
215
+ return { error: "the registered marketplace has no Git source" };
216
+ const channel = refChannel(ref);
217
+ // A marketplace pinned to one tag never offers anything newer.
218
+ if (channel === "pinned")
219
+ return { pinned: ref };
220
+ return { version: readChannelVersion(source, channel, harness) };
277
221
  }
278
- catch {
279
- return undefined;
222
+ catch (error) {
223
+ return { error: error instanceof Error ? error.message : String(error) };
280
224
  }
281
- if (result.status !== 0 || !result.stdout)
282
- return undefined;
283
- const pinnedSha = branch === ""
284
- ? spawnSync("git", ["-C", marketplaceDir, "rev-parse", "HEAD"], {
285
- encoding: "utf8",
286
- timeout: LS_REMOTE_TIMEOUT_MS,
287
- }).stdout?.trim()
288
- : undefined;
289
- return channelVersions(result.stdout, branch, pinnedSha);
290
- };
291
- const realListRemoteTagsAt = (remote, ref) => {
292
- let result;
293
- try {
294
- result = spawnSync("git", ["ls-remote", "--symref", remote], { encoding: "utf8", timeout: LS_REMOTE_TIMEOUT_MS });
295
- }
296
- catch {
297
- return undefined;
298
- }
299
- if (result.status !== 0 || !result.stdout)
300
- return undefined;
301
- if (ref !== undefined && splitRefs(result.stdout).some(([, name]) => name === `refs/tags/${ref}`)) {
302
- const version = ref.replace(/^v/, "");
303
- return isExactSemver(version) ? [version] : [];
304
- }
305
- return channelVersions(result.stdout, ref ?? "", undefined);
306
- };
307
- /** The marketplace every akm Codex install registers (`codex plugin marketplace add itlackey/akm-plugins`). */
308
- const CODEX_MARKETPLACE_REMOTE = "https://github.com/itlackey/akm-plugins";
225
+ }
309
226
  /** Codex is checked only when its config registers the akm-plugins marketplace, so a host without Codex runs nothing. */
310
227
  function readCodexPlugin() {
228
+ let source;
311
229
  try {
312
- if (codexMarketplace(codexConfigFile()) === undefined)
230
+ const marketplace = codexMarketplace(codexConfigFile());
231
+ if (marketplace === undefined)
313
232
  return undefined;
233
+ source = marketplace.source;
314
234
  }
315
235
  catch {
316
236
  return undefined;
317
237
  }
318
- return { ref: codexMarketplaceRef(), listed: codexPluginVersion() };
238
+ return {
239
+ ref: codexMarketplaceRef(),
240
+ source: typeof source === "string" ? source : undefined,
241
+ listed: codexPluginVersion(),
242
+ };
319
243
  }
320
244
  /** One `codex-plugin-version` advisory, or none when the marketplace is registered but the plugin is not installed. */
321
- function buildCodexAdvisory(codex, cliVersion, probe, listRemoteTagsAt) {
245
+ function buildCodexAdvisory(codex, cliVersion, probe, readChannelVersion) {
322
246
  const base = { name: "codex-plugin-version", kind: "deterministic", confidence: "high" };
323
247
  if ("error" in codex.listed) {
324
248
  return {
325
249
  ...base,
326
250
  status: "unknown",
251
+ reason: "blocked",
327
252
  message: codex.listed.error.missing
328
253
  ? "Codex's config registers the akm-plugins marketplace, but `codex` is not on PATH, so its akm plugin was not checked."
329
254
  : `Codex's akm plugin could not be listed: ${codex.listed.error.error}`,
@@ -335,36 +260,25 @@ function buildCodexAdvisory(codex, cliVersion, probe, listRemoteTagsAt) {
335
260
  return undefined;
336
261
  const { ref } = codex;
337
262
  const channel = ref === undefined || ref === "main" || ref === "master" ? "stable" : ref === "next" ? "next" : `pinned to ${ref}`;
338
- let availableVersion;
339
- let remoteUnavailable = false;
340
- if (probe) {
341
- const tags = listRemoteTagsAt(CODEX_MARKETPLACE_REMOTE, ref);
342
- if (tags === undefined)
343
- remoteUnavailable = true;
344
- else
345
- availableVersion = highestVersion(tags);
346
- }
347
- const stale = availableVersion !== undefined &&
348
- installed !== availableVersion &&
349
- highestVersion([installed, availableVersion]) === availableVersion;
263
+ const offered = probe ? readOffered("codex", () => ({ source: codex.source, ref }), readChannelVersion) : undefined;
264
+ const availableVersion = offered && "version" in offered ? offered.version : undefined;
265
+ const stale = availableVersion !== undefined && semverOrder(availableVersion, installed) > 0;
350
266
  // The akm-cli Codex's plugin cache holds for the installed plugin version: read, never executed.
351
267
  const bundledCli = readPackageVersion(path.join(path.dirname(codexConfigFile()), "plugins", "cache", "akm-plugins", "akm", installed, "node_modules", "akm-cli", "package.json"));
352
268
  const cliMatches = bundledCli === undefined ? undefined : bundledCli === cliVersion;
353
269
  const messageParts = [`akm@akm-plugins (Codex): installed ${installed} (${channel} channel)`];
354
- if (!probe)
355
- messageParts.push("newest tag was not probed");
356
- else if (remoteUnavailable)
357
- messageParts.push(REMOTE_UNAVAILABLE_NOTE);
358
- if (availableVersion !== undefined) {
359
- messageParts.push(stale ? `available ${availableVersion} (STALE)` : `available ${availableVersion} (up to date)`);
360
- }
270
+ messageParts.push(...offeredNotes(offered, stale));
361
271
  if (stale)
362
272
  messageParts.push("-> codex plugin marketplace upgrade akm-plugins");
363
273
  if (bundledCli !== undefined && cliMatches === false)
364
274
  messageParts.push(bundledCliNote(bundledCli, cliVersion));
365
275
  return {
366
276
  ...base,
367
- status: stale || cliMatches === false ? "warn" : probe && availableVersion !== undefined ? "pass" : "unknown",
277
+ ...(stale || cliMatches === false
278
+ ? { status: "warn" }
279
+ : offered && !("error" in offered)
280
+ ? { status: "pass" }
281
+ : unreadOffer(offered)),
368
282
  message: messageParts.join(" — "),
369
283
  evidence: {
370
284
  harness: "codex",
@@ -372,7 +286,7 @@ function buildCodexAdvisory(codex, cliVersion, probe, listRemoteTagsAt) {
372
286
  ref: ref ?? null,
373
287
  availableVersion: availableVersion ?? null,
374
288
  ...(probe ? {} : { probed: false }),
375
- ...(remoteUnavailable ? { remoteUnavailable: true } : {}),
289
+ ...(offered && "error" in offered ? { remoteUnavailable: true } : {}),
376
290
  stale,
377
291
  bundledCliVersion: bundledCli ?? null,
378
292
  cliVersion,
@@ -380,8 +294,20 @@ function buildCodexAdvisory(codex, cliVersion, probe, listRemoteTagsAt) {
380
294
  },
381
295
  };
382
296
  }
383
- /** Said when a probe asked the marketplace remote and got no answer, so "unknown" is not mistaken for "no newer release". */
384
- const REMOTE_UNAVAILABLE_NOTE = "the newest release could not be read from the marketplace remote (offline?)";
297
+ /** The `unknown` verdict of a check whose marketplace was not asked (`not-probed`) or could not be read (`blocked`). */
298
+ function unreadOffer(offered) {
299
+ return { status: "unknown", reason: offered === undefined ? "not-probed" : "blocked" };
300
+ }
301
+ /** What the read of the marketplace says in a message: that it was not made, why it failed, or what the channel offers. */
302
+ function offeredNotes(offered, stale) {
303
+ if (offered === undefined)
304
+ return ["newest release was not probed"];
305
+ if ("error" in offered)
306
+ return [`the newest release could not be read from the marketplace (${offered.error})`];
307
+ if ("pinned" in offered)
308
+ return [`the marketplace is pinned to ${offered.pinned}, which offers nothing newer`];
309
+ return [stale ? `available ${offered.version} (STALE)` : `available ${offered.version} (up to date)`];
310
+ }
385
311
  /**
386
312
  * Build one `plugin-version` advisory per detected `akm` Claude Code plugin, a `codex-plugin-version` advisory when
387
313
  * Codex has the plugin installed from the akm-plugins marketplace, plus one `opencode-plugin-version` /
@@ -391,15 +317,16 @@ const REMOTE_UNAVAILABLE_NOTE = "the newest release could not be read from the m
391
317
  */
392
318
  export function collectPluginStalenessAdvisories(options) {
393
319
  const pluginsRoot = options.pluginsRoot ?? claudePluginsDir();
394
- const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
320
+ const readChannelVersion = options.readChannelVersion ?? marketplaceTargetVersion;
395
321
  const plugins = detectInstalledPlugins(pluginsRoot);
396
322
  const probe = options.probe ?? true;
397
- const results = (plugins ?? []).map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags, probe));
323
+ const results = (plugins ?? []).map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, readChannelVersion, probe));
398
324
  if (plugins === undefined && fs.existsSync(pluginsRoot)) {
399
325
  results.push({
400
326
  name: "plugin-version",
401
327
  kind: "deterministic",
402
328
  status: "unknown",
329
+ reason: "blocked",
403
330
  confidence: "high",
404
331
  message: "Claude plugin installation and enabled state could not be resolved with `claude plugin list --json`; cached versions do not establish the selected installation.",
405
332
  evidence: { harness: "claude", installedVersion: null, enabled: null, cliMatches: null },
@@ -407,7 +334,7 @@ export function collectPluginStalenessAdvisories(options) {
407
334
  }
408
335
  const codex = (options.readCodex ?? readCodexPlugin)();
409
336
  if (codex) {
410
- const advisory = buildCodexAdvisory(codex, options.cliVersion, probe, options.listRemoteTagsAt ?? realListRemoteTagsAt);
337
+ const advisory = buildCodexAdvisory(codex, options.cliVersion, probe, readChannelVersion);
411
338
  if (advisory)
412
339
  results.push(advisory);
413
340
  }
@@ -425,25 +352,15 @@ function bundledCliNote(bundled, cliVersion, olderSuffix = "") {
425
352
  ? `bundles akm-cli ${bundled}, newer than the running CLI ${cliVersion}; both share the same databases -> akm upgrade`
426
353
  : `bundles akm-cli ${bundled}, older than the running CLI ${cliVersion}; both share the same databases${olderSuffix}`;
427
354
  }
428
- function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
355
+ function buildAdvisory(plugin, cliVersion, pluginsRoot, readChannelVersion, probe) {
429
356
  const pluginRef = `${plugin.pluginName}@${plugin.marketplace}`;
430
- // Point 2: newest available vs. installed, via the marketplace clone's remote.
431
- const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
432
- const asked = probe && plugin.selectionKnown && plugin.enabled !== false && fs.existsSync(marketplaceDir);
433
- let availableVersion;
434
- let remoteUnavailable = false;
435
- try {
436
- const tags = asked ? listRemoteTags(marketplaceDir) : undefined;
437
- remoteUnavailable = asked && tags === undefined;
438
- availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
439
- }
440
- catch {
441
- availableVersion = undefined;
442
- remoteUnavailable = asked;
443
- }
444
- const stale = availableVersion !== undefined &&
445
- plugin.version !== availableVersion &&
446
- highestVersion([plugin.version, availableVersion]) === availableVersion;
357
+ // Point 2: newest available vs. installed, from the channel of the marketplace Claude registered.
358
+ const asked = probe && plugin.selectionKnown && plugin.enabled !== false;
359
+ const offered = asked
360
+ ? readOffered("claude", () => claudeMarketplace(pluginsRoot, plugin.marketplace), readChannelVersion)
361
+ : undefined;
362
+ const availableVersion = offered && "version" in offered ? offered.version : undefined;
363
+ const stale = availableVersion !== undefined && semverOrder(availableVersion, plugin.version) > 0;
447
364
  // Point 3: does the akm-cli the plugin runs match the running CLI? Both read and write the same databases.
448
365
  const pinnedCliVersion = readPinnedCli(plugin.pluginDir);
449
366
  const cliMatches = pinnedCliVersion === undefined ? undefined : pinnedCliVersion === cliVersion;
@@ -461,12 +378,9 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
461
378
  if (cliMatches === undefined)
462
379
  messageParts.push("bundled akm-cli unknown (no exact akm-cli pin in package.json)");
463
380
  if (!probe)
464
- messageParts.push("newest tag was not probed");
465
- else if (remoteUnavailable)
466
- messageParts.push(REMOTE_UNAVAILABLE_NOTE);
467
- if (availableVersion !== undefined) {
468
- messageParts.push(stale ? `available ${availableVersion} (STALE)` : `available ${availableVersion} (up to date)`);
469
- }
381
+ messageParts.push("newest release was not probed");
382
+ else if (offered)
383
+ messageParts.push(...offeredNotes(offered, stale));
470
384
  if (stale)
471
385
  messageParts.push(`-> claude plugin update ${pluginRef}`);
472
386
  if (plugin.selectionKnown && plugin.enabled === true && cliMatches === false) {
@@ -477,15 +391,17 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
477
391
  kind: "deterministic",
478
392
  // Not probed => staleness is unknown, not "up to date"; only the local
479
393
  // pin comparison can still warn.
480
- status: plugin.enabled === false || !plugin.applicable
481
- ? "pass"
394
+ ...(plugin.enabled === false || !plugin.applicable
395
+ ? { status: "pass" }
482
396
  : !plugin.selectionKnown || plugin.enabled === undefined
483
- ? "unknown"
397
+ ? { status: "unknown", reason: "blocked" }
484
398
  : stale || cliMatches === false
485
- ? "warn"
486
- : probe && availableVersion !== undefined && cliMatches !== undefined && plugin.enabled === true
487
- ? "pass"
488
- : "unknown",
399
+ ? { status: "warn" }
400
+ : offered && !("error" in offered) && cliMatches !== undefined && plugin.enabled === true
401
+ ? { status: "pass" }
402
+ : cliMatches === undefined && offered !== undefined && !("error" in offered)
403
+ ? { status: "unknown", reason: "blocked" }
404
+ : unreadOffer(offered)),
489
405
  confidence: "high",
490
406
  message: messageParts.join(" — "),
491
407
  evidence: {
@@ -501,7 +417,7 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
501
417
  installPath: plugin.pluginDir,
502
418
  availableVersion: availableVersion ?? null,
503
419
  ...(probe ? {} : { probed: false }),
504
- ...(remoteUnavailable ? { remoteUnavailable: true } : {}),
420
+ ...(offered && "error" in offered ? { remoteUnavailable: true } : {}),
505
421
  stale,
506
422
  pinnedCliVersion: pinnedCliVersion ?? null,
507
423
  cliVersion,
@@ -44,6 +44,7 @@ export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
44
44
  name: "scheduler-binary",
45
45
  kind: "deterministic",
46
46
  status: "unknown",
47
+ reason: "not-probed",
47
48
  confidence: "high",
48
49
  message: "Scheduler binary version drift was not probed.",
49
50
  };
@@ -54,13 +55,15 @@ export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
54
55
  }
55
56
  catch (error) {
56
57
  const detail = error instanceof Error ? error.message : String(error);
58
+ // A host without the scheduler's own binary (no crontab) runs no scheduled task: nothing is drifting there.
59
+ const noScheduler = /not found on PATH/.test(detail);
57
60
  return {
58
61
  name: "scheduler-binary",
59
62
  kind: "deterministic",
60
63
  status: "unknown",
64
+ reason: noScheduler ? "off" : "blocked",
61
65
  confidence: "high",
62
- // A host without the scheduler's own binary (no crontab) runs no scheduled task: nothing is drifting there.
63
- message: /not found on PATH/.test(detail)
66
+ message: noScheduler
64
67
  ? `No scheduler is available on this host (${detail}), so no scheduled task is installed or runs here.`
65
68
  : `Installed scheduled tasks could not be inspected: ${detail}`,
66
69
  };
@@ -75,6 +78,7 @@ export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
75
78
  name: "scheduler-binary",
76
79
  kind: "deterministic",
77
80
  status: "unknown",
81
+ reason: "off",
78
82
  confidence: "high",
79
83
  message: "No scheduled task is installed.",
80
84
  };
@@ -98,6 +102,7 @@ export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
98
102
  name: "scheduler-binary",
99
103
  kind: "deterministic",
100
104
  status: "unknown",
105
+ reason: "blocked",
101
106
  confidence: "high",
102
107
  message: "The scheduler's recorded akm binary could not be executed.",
103
108
  evidence: { binding },
@@ -50,24 +50,25 @@ export function readSemanticSearchState(mode) {
50
50
  }
51
51
  }
52
52
  export function semanticSearchCheck(state) {
53
- const result = (status, message, evidence) => ({
53
+ const base = (message, evidence) => ({
54
54
  name: "semantic-search",
55
55
  kind: "deterministic",
56
- status,
57
56
  confidence: "high",
58
57
  message,
59
58
  ...(evidence ? { evidence } : {}),
60
59
  });
60
+ const result = (status, message, evidence) => ({ ...base(message, evidence), status });
61
+ const unknown = (reason, message, evidence) => ({ ...base(message, evidence), status: "unknown", reason });
61
62
  // Keyword search needs a readable index too, even when embeddings are off.
62
63
  if (state.error)
63
64
  return result("fail", `Could not read the index: ${state.error}. Run \`akm index\`; it rebuilds a damaged index.db.`);
64
65
  if (state.building)
65
- return result("unknown", "The search index is being built; check again when the build finishes.");
66
+ return unknown("idle", "The search index is being built; check again when the build finishes.");
66
67
  if (state.mode === "off")
67
68
  return result("pass", "Semantic search is off (semanticSearchMode: off).", { mode: "off" });
68
69
  const index = state.index;
69
70
  if (!index?.record)
70
- return result("unknown", "No semantic-search state recorded yet; run `akm index`.");
71
+ return unknown("idle", "No semantic-search state recorded yet; run `akm index`.");
71
72
  const { record, builtAt, entryCount, embeddingCount } = index;
72
73
  const evidence = { ...record, ...(builtAt ? { builtAt } : {}), entryCount, embeddingCount };
73
74
  const asOf = builtAt ? ` at the last index (${builtAt})` : " at the last index";
@@ -89,8 +90,8 @@ export function semanticSearchCheck(state) {
89
90
  }
90
91
  return result("pass", `Semantic search ready (${embeddingCount}/${entryCount} embeddings${record.runtime ? ` on ${record.runtime}` : ""}).`, evidence);
91
92
  case "disabled":
92
- return result("unknown", `Semantic search was off${asOf}; run \`akm index\` to build it.`, evidence);
93
+ return unknown("off", `Semantic search was off${asOf}; run \`akm index\` to build it.`, evidence);
93
94
  default:
94
- return result("unknown", `No entries were indexed${asOf}.`, evidence);
95
+ return unknown("idle", `No entries were indexed${asOf}.`, evidence);
95
96
  }
96
97
  }
@@ -55,6 +55,7 @@ export async function collectVersionDriftAdvisory(probe, deps = {}) {
55
55
  name: "cli-version",
56
56
  kind: "deterministic",
57
57
  status: "unknown",
58
+ reason: "not-probed",
58
59
  confidence: "high",
59
60
  message: `akm v${cliVersion} is installed. Version-drift was not probed.`,
60
61
  evidence: { installedVersion: cliVersion },
@@ -83,6 +84,7 @@ export async function collectVersionDriftAdvisory(probe, deps = {}) {
83
84
  name: "cli-version",
84
85
  kind: "deterministic",
85
86
  status: "unknown",
87
+ reason: "blocked",
86
88
  confidence: "high",
87
89
  message: `akm v${cliVersion} is installed; the update check could not reach the release source.`,
88
90
  evidence: {
@@ -258,9 +258,9 @@ export function deriveExtractCandidateRef(candidate, sourceRef, projectName) {
258
258
  if (candidate.type === "memory" || candidate.type === "lesson") {
259
259
  const folder = projectName ?? sourceRef.projectHint?.split(/[\\/]/).filter(Boolean).at(-1);
260
260
  const scope = folder ? canonicalSegment(folder) : "";
261
- return `${candidate.type === "memory" ? "memories" : "lessons"}/${scope ? `${scope}/` : ""}${leaf}`;
261
+ return conceptIdFromTypeName(candidate.type, `${scope ? `${scope}/` : ""}${leaf}`);
262
262
  }
263
- return `knowledge/${leaf}`;
263
+ return conceptIdFromTypeName("knowledge", leaf);
264
264
  }
265
265
  function resolveExtractStandards(stashDir) {
266
266
  const sections = [];
@@ -445,7 +445,12 @@ export async function runImprovePreparationStage(args) {
445
445
  let lintSummary;
446
446
  if (primaryStashDir) {
447
447
  try {
448
- const lintResult = await akmLint({ fix: false, dir: primaryStashDir });
448
+ const lintResult = await akmLint({
449
+ fix: false,
450
+ dir: primaryStashDir,
451
+ // The moves are read through the run's own connection: a dry run's is its private snapshot of state.db.
452
+ readMoves: () => readEvents({ type: "moved" }, eventsCtx).events,
453
+ });
449
454
  lintSummary = { fixed: lintResult.summary.fixed, flagged: lintResult.summary.flagged };
450
455
  }
451
456
  catch {