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
@@ -38,14 +38,16 @@ import { assetPathCandidatesForName, assetPathForName, filesForRef, stashDirFor,
38
38
  import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
39
39
  import { removeFrontmatterListValues, rewriteFrontmatterListValue, spliceFrontmatterLine, } from "../../core/asset/frontmatter.js";
40
40
  import { checkUnquotedDescriptionColon } from "../../core/asset/frontmatter-lint.js";
41
- import { isSkillPath } from "../../core/asset/lint-text.js";
41
+ import { ruleApplies } from "../../core/asset/lint-text.js";
42
42
  import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
43
43
  import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
44
44
  import { findStalePaths } from "../../core/asset/stale-path.js";
45
45
  import { localDateStamp } from "../../core/common.js";
46
46
  import { containsRedactedContent, REDACTED_CONTENT_MARKER } from "../../core/content-safety.js";
47
47
  import { DERIVED_SUFFIX } from "../../core/recognition-util.js";
48
+ import { DECLARED_REF_FRONTMATTER_KEYS, declaredLinkTarget } from "../../indexer/links/declared-links.js";
48
49
  import { findFenceRegions } from "./markdown-insertion.js";
50
+ import { rewriteMovedLinks } from "./moved-refs.js";
49
51
  // ── Helpers ───────────────────────────────────────────────────────────────────
50
52
  /** Fold physically wrapped prose the same way a YAML plain scalar does. */
51
53
  function foldDescriptionLines(lines) {
@@ -129,9 +131,6 @@ function fixUnquotedColon(raw) {
129
131
  }
130
132
  return null;
131
133
  }
132
- function checkMissingUpdated(relPath, data, frontmatterText) {
133
- return frontmatterText !== null && !("updated" in data) && !isSkillPath(relPath);
134
- }
135
134
  function fixMissingUpdated(raw, mtime) {
136
135
  return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
137
136
  }
@@ -319,7 +318,7 @@ function localRefMissingRelPath(refType, refName, allRoots) {
319
318
  * is checked on disk by {@link classifyConceptRef}; a conceptId whose leading
320
319
  * segment names no known stash-subdir is not a local asset ref and is skipped (foreign-adapter / cross-bundle prose).
321
320
  */
322
- function scanBundleRefs(scanBody, allRoots) {
321
+ function scanBundleRefs(scanBody, allRoots, movedConcepts, bundleRoots) {
323
322
  const missing = [];
324
323
  const re = new RegExp(BUNDLE_REF_RE.source, BUNDLE_REF_RE.flags);
325
324
  let match;
@@ -331,12 +330,19 @@ function scanBundleRefs(scanBody, allRoots) {
331
330
  const boundary = token.indexOf("//");
332
331
  if (boundary < 0)
333
332
  continue;
334
- const found = classifyConceptRef(token.slice(boundary + 2), allRoots);
333
+ const found = classifyConceptRef(token.slice(boundary + 2), rootsOfBundle(token.slice(0, boundary), allRoots, bundleRoots), movedConcepts);
335
334
  if (found !== null)
336
335
  missing.push({ ref: token, resolvedRelPath: found });
337
336
  }
338
337
  return missing;
339
338
  }
339
+ const NO_CONCEPTS = new Set();
340
+ const NO_BUNDLES = new Map();
341
+ /** A qualified ref is checked in the bundle it names; a bundle the config does not name is checked as an unqualified ref is. */
342
+ function rootsOfBundle(bundle, allRoots, bundleRoots) {
343
+ const root = bundleRoots.get(bundle);
344
+ return root === undefined ? allRoots : [root];
345
+ }
340
346
  /**
341
347
  * Run the existence check for a bare conceptId. Returns the missing relPath, or
342
348
  * `null` when it resolves or does not read as a local asset ref. A ref is the
@@ -346,14 +352,23 @@ function scanBundleRefs(scanBody, allRoots) {
346
352
  * stash folder is foreign-adapter / cross-bundle prose and is skipped. Drops a
347
353
  * trailing `#fragment` (export selector) before mapping.
348
354
  */
349
- function classifyConceptRef(rawConceptId, allRoots) {
355
+ function classifyConceptRef(rawConceptId, allRoots, movedConcepts = NO_CONCEPTS, declared = false) {
350
356
  const conceptId = rawConceptId.split("#", 1)[0];
351
357
  const legacy = legacyTypeSlugParts(conceptId);
352
358
  if (legacy !== undefined)
353
359
  return localRefMissingRelPath(legacy.type, legacy.name, allRoots);
354
360
  const slash = conceptId.indexOf("/");
355
- if (slash <= 0 || !stashDirNames().includes(conceptId.slice(0, slash)))
356
- return null;
361
+ if (slash <= 0 || !stashDirNames().includes(conceptId.slice(0, slash))) {
362
+ // What an asset declares as a ref is one wherever it points: it must exist as a file of that concept id.
363
+ if (declared) {
364
+ const files = [`${conceptId}.md`, ...filesForRef("", conceptId)];
365
+ const found = allRoots.some((root) => files.some((file) => fs.existsSync(path.join(root, file)) || isArchivedRelPath(file, root)));
366
+ return found ? null : `${conceptId}.md`;
367
+ }
368
+ // A path ref outside the type folders is checked only when the index recorded a move away from it.
369
+ const gone = !allRoots.some((root) => fs.existsSync(path.join(root, `${conceptId}.md`))) && movedConcepts.has(conceptId);
370
+ return gone ? `${conceptId}.md` : null;
371
+ }
357
372
  if (isNonRefName(conceptId.slice(slash + 1)))
358
373
  return null;
359
374
  const spellings = [conceptId, conceptId.slice(slash + 1)];
@@ -398,11 +413,11 @@ function legacyTypeSlugParts(rawConceptId) {
398
413
  * those are recognized only in the ref-list channels
399
414
  * ({@link checkMissingRefsInList}).
400
415
  */
401
- function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
416
+ function checkMissingRefs(body, stashRoot, extraStashRoots = [], movedConcepts = NO_CONCEPTS, bundleRoots = NO_BUNDLES) {
402
417
  const allRoots = [stashRoot, ...extraStashRoots];
403
418
  // C1: Strip fenced code blocks so example refs inside ``` are not flagged.
404
419
  const scanBody = stripFencedBlocks(body);
405
- return dedupeMissing(scanBundleRefs(scanBody, allRoots));
420
+ return dedupeMissing(scanBundleRefs(scanBody, allRoots, movedConcepts, bundleRoots));
406
421
  }
407
422
  /**
408
423
  * Missing-ref check for the REF-LIST channels (frontmatter `refs:` /
@@ -414,7 +429,7 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
414
429
  * - fully-qualified `bundle//conceptId`;
415
430
  * - bare short `conceptId` (`<stash-subdir>/<name>`).
416
431
  */
417
- function checkMissingRefsInList(values, stashRoot, extraStashRoots = []) {
432
+ function checkMissingRefsInList(values, ownerRelPath, stashRoot, extraStashRoots = [], movedConcepts = NO_CONCEPTS, bundleRoots = NO_BUNDLES) {
418
433
  const allRoots = [stashRoot, ...extraStashRoots];
419
434
  const missing = [];
420
435
  for (const raw of values) {
@@ -422,21 +437,16 @@ function checkMissingRefsInList(values, stashRoot, extraStashRoots = []) {
422
437
  if (!value || value.includes("$(") || value.includes("${") || value.includes("::"))
423
438
  continue;
424
439
  const boundary = value.indexOf("//");
425
- if (boundary >= 0) {
426
- // Qualified: `bundle//conceptId` (0.9.0). A colon in the tail marks a
427
- // legacy/remote `origin//type:name` — not the new grammar, so skip it.
428
- const tail = value.slice(boundary + 2);
429
- if (tail.includes(":"))
430
- continue;
431
- const rel = classifyConceptRef(tail, allRoots);
432
- if (rel !== null)
433
- missing.push({ ref: value, resolvedRelPath: rel });
440
+ // A colon in the tail of a qualified value marks a legacy/remote `origin//type:name`, not the 0.9.0 grammar.
441
+ if (boundary >= 0 && value.slice(boundary + 2).includes(":"))
434
442
  continue;
435
- }
436
- // Un-prefixed: a 0.9.0 short `conceptId`. (Post-Chunk-8 the durable
437
- // frontmatter xref channel is conceptId-spelled — the legacy `type:name`
438
- // ref-list arm is retired.)
439
- const rel = classifyConceptRef(value, allRoots);
443
+ // The retired `type:slug` spelling is read as it always was; every other value is a ref as the index reads it.
444
+ const target = boundary < 0 && legacyTypeSlugParts(value) !== undefined
445
+ ? { conceptId: value }
446
+ : declaredLinkTarget(value, ownerRelPath.replace(/\\/g, "/").replace(/\.md$/i, ""));
447
+ if (target === undefined)
448
+ continue;
449
+ const rel = classifyConceptRef(target.conceptId, target.bundle === undefined ? allRoots : rootsOfBundle(target.bundle, allRoots, bundleRoots), movedConcepts, true);
440
450
  if (rel !== null)
441
451
  missing.push({ ref: value, resolvedRelPath: rel });
442
452
  }
@@ -456,20 +466,7 @@ function dedupeMissing(rows) {
456
466
  }
457
467
  // ── frontmatter refs ─────────────────────────────────────────────────────────
458
468
  /**
459
- * Frontmatter keys that carry cross-reference lists per the stash
460
- * organization conventions: `xrefs:` (provenance / associative links),
461
- * `supersededBy:` and `contradictedBy:` (belief-state correction links).
462
- * The missing-ref check validates each of these in ADDITION to the body /
463
- * `refs:` scan — they are the channel the conventions mandate, and a rename
464
- * would otherwise dangle them silently.
465
- *
466
- * `sources:` is deliberately excluded (non-wiki `sources:` was rejected as a
467
- * typed channel; wiki `sources:` is checked by lintWiki). `evidenceSources:` is
468
- * excluded because it can point at merged-away or pruned assets.
469
- */
470
- const XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
471
- /**
472
- * The belief-graph subset of {@link XREF_FRONTMATTER_KEYS} — the only channels
469
+ * The belief-graph subset of {@link DECLARED_REF_FRONTMATTER_KEYS} — the only channels
473
470
  * `--prune-dangling-edges` will repair (#884). Typed as `readonly string[]` so
474
471
  * `.includes` accepts any xref key without a cast.
475
472
  */
@@ -631,8 +628,7 @@ export function runBaseChecks(ctx) {
631
628
  let modified = false;
632
629
  /** Findings whose `fixed: true` is only true once the flush below succeeds. */
633
630
  const pendingFixes = [];
634
- const lintSkip = ctx.lintSkip ?? [];
635
- const shouldRun = (issueType) => !lintSkip.includes(issueType);
631
+ const shouldRun = (rule) => ruleApplies(rule, { relPath: ctx.relPath, llmWiki: ctx.llmWiki, skip: ctx.lintSkip });
636
632
  if (shouldRun("redacted-content") && containsRedactedContent(stripQuotedExamples(currentRaw))) {
637
633
  issues.push({
638
634
  file: ctx.relPath,
@@ -679,7 +675,7 @@ export function runBaseChecks(ctx) {
679
675
  }
680
676
  } // end shouldRun("unquoted-colon")
681
677
  // ── 2. missing-updated ─────────────────────────────────────────────────
682
- if (shouldRun("missing-updated") && checkMissingUpdated(ctx.relPath, ctx.data, ctx.frontmatter)) {
678
+ if (shouldRun("missing-updated") && ctx.frontmatter !== null && !("updated" in ctx.data)) {
683
679
  if (ctx.fix) {
684
680
  let mtime;
685
681
  try {
@@ -786,15 +782,44 @@ function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
786
782
  // stash.
787
783
  if (!shouldRun("missing-ref"))
788
784
  return { issues, raw, modified };
785
+ const allRoots = [ctx.stashRoot, ...(ctx.extraStashRoots ?? [])];
786
+ const moves = ctx.moves;
787
+ const movedConcepts = moves ? { has: (concept) => moves.concepts.has(concept) } : NO_CONCEPTS;
788
+ const bundleRoots = ctx.bundleRoots ?? NO_BUNDLES;
789
+ // Links to an asset the index recorded as moved: reported with the new ref, and rewritten under `--fix`.
790
+ const movedLinks = new Map();
791
+ const movedFinding = (ref, where) => {
792
+ const moved = ctx.moves?.target(ref);
793
+ const concept = moved?.to.slice(moved.to.indexOf("//") + 2);
794
+ if (!moved ||
795
+ concept === undefined ||
796
+ classifyConceptRef(concept, rootsOfBundle(moved.to.slice(0, moved.to.indexOf("//")), allRoots, bundleRoots), new Set([concept])) !== null)
797
+ return undefined;
798
+ const issue = {
799
+ file: ctx.relPath,
800
+ issue: "missing-ref",
801
+ detail: `missing ref: ${ref} (${where}moved to ${moved.to})`,
802
+ fixed: false,
803
+ movedFrom: ref,
804
+ movedTo: moved.to,
805
+ };
806
+ if (ctx.fix || ctx.fixMovedRefs) {
807
+ movedLinks.set(ref.split("#", 1)[0], moved.spelled);
808
+ issue.fixed = true;
809
+ issue.detail = `moved ref updated: ${ref} -> ${moved.spelled}`;
810
+ pendingFixes.push(issue);
811
+ }
812
+ return issue;
813
+ };
789
814
  {
790
815
  const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
791
816
  // An explicit `refs:` array is a REF LIST (each value is a whole ref —
792
817
  // short conceptIds included); a bare body is PROSE (anchored refs only).
793
818
  const missingRefs = explicitRefs !== null
794
- ? checkMissingRefsInList(explicitRefs, ctx.stashRoot, ctx.extraStashRoots)
795
- : checkMissingRefs(ctx.body, ctx.stashRoot, ctx.extraStashRoots);
819
+ ? checkMissingRefsInList(explicitRefs, ctx.relPath, ctx.stashRoot, ctx.extraStashRoots, movedConcepts, bundleRoots)
820
+ : checkMissingRefs(ctx.body, ctx.stashRoot, ctx.extraStashRoots, movedConcepts, bundleRoots);
796
821
  for (const { ref, resolvedRelPath } of missingRefs) {
797
- issues.push({
822
+ issues.push(movedFinding(ref, "") ?? {
798
823
  file: ctx.relPath,
799
824
  issue: "missing-ref",
800
825
  detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
@@ -822,7 +847,7 @@ function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
822
847
  // without `refs:` land in the skip branch with empty ctx.data, so
823
848
  // nothing is lost for them either.
824
849
  if (ctx.frontmatter !== null || explicitRefs !== null) {
825
- for (const key of XREF_FRONTMATTER_KEYS) {
850
+ for (const key of DECLARED_REF_FRONTMATTER_KEYS) {
826
851
  const values = readRefStringOrArray(ctx.data?.[key]);
827
852
  if (values === null)
828
853
  continue;
@@ -866,7 +891,11 @@ function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
866
891
  }
867
892
  }
868
893
  }
869
- const missingXrefs = checkMissingRefsInList(values, ctx.stashRoot, ctx.extraStashRoots);
894
+ const allMissingXrefs = checkMissingRefsInList(values, ctx.relPath, ctx.stashRoot, ctx.extraStashRoots, movedConcepts, bundleRoots);
895
+ // A moved ref is a link to update, never a dangling edge to drop.
896
+ const movedXrefs = allMissingXrefs.flatMap(({ ref }) => movedFinding(ref, `frontmatter ${key}; `) ?? []);
897
+ issues.push(...movedXrefs);
898
+ const missingXrefs = allMissingXrefs.filter(({ ref }) => !movedXrefs.some((issue) => issue.movedFrom === ref));
870
899
  // #884 opt-in repair. Scoped to the BELIEF channels only: an edge whose
871
900
  // target has neither a file nor a prune tombstone asserts a
872
901
  // relationship to a memory that no longer exists in any form, and
@@ -905,5 +934,18 @@ function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
905
934
  }
906
935
  }
907
936
  }
937
+ if (movedLinks.size > 0) {
938
+ const rewritten = rewriteMovedLinks(currentRaw, movedLinks);
939
+ if (rewritten !== currentRaw) {
940
+ currentRaw = rewritten;
941
+ modified = true;
942
+ }
943
+ else {
944
+ for (const issue of issues.filter((found) => found.movedTo !== undefined && found.fixed === true)) {
945
+ issue.fixed = "failed";
946
+ issue.detail = `${issue.detail} — could not find the link in the file to rewrite`;
947
+ }
948
+ }
949
+ }
908
950
  return { issues, raw: currentRaw, modified };
909
951
  }