akm-cli 0.10.261126 → 0.10.261127

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 (34) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/commands/health/improve-metrics.js +23 -3
  3. package/dist/commands/health/md-report.js +4 -3
  4. package/dist/commands/improve/consolidate/pair-pass.js +52 -27
  5. package/dist/commands/improve/loop-stages.js +3 -2
  6. package/dist/commands/lint/base-linter.js +23 -20
  7. package/dist/commands/lint/index.js +26 -4
  8. package/dist/commands/sources/plugin-upgrade.js +23 -3
  9. package/dist/core/adapter/adapters/akm-lint.js +35 -12
  10. package/dist/core/adapter/adapters/shared.js +11 -22
  11. package/dist/core/asset/asset-ref.js +3 -2
  12. package/dist/core/asset/frontmatter-lint.js +17 -22
  13. package/dist/core/asset/lint-text.js +50 -0
  14. package/dist/indexer/indexer.js +5 -0
  15. package/dist/output/text/command-format.js +2 -1
  16. package/dist/scripts/akm-migrate-node.js +86 -37
  17. package/dist/scripts/akm-migrate.js +86 -37
  18. package/dist/storage/repositories/index-layout-repository.js +81 -0
  19. package/dist/storage/repositories/index-schema.js +18 -0
  20. package/dist/storage/repositories/task-history-repository.js +28 -0
  21. package/dist/storage/repositories/workflow-runs-repository.js +25 -0
  22. package/dist/tasks/run/attempt-lifecycle.js +8 -1
  23. package/dist/tasks/run/reconcile-abandoned.js +75 -0
  24. package/dist/tasks/run/run-task.js +9 -1
  25. package/dist/tasks/run/task-result.js +2 -0
  26. package/dist/workspace/graph-duplicates.js +124 -28
  27. package/dist/workspace/graph.js +39 -7
  28. package/docs/architecture/internals/health-advisories.md +1 -1
  29. package/docs/architecture/internals/improve-workflow.md +1 -1
  30. package/docs/architecture/internals/indexing.md +2 -2
  31. package/docs/architecture/internals/storage-locations.md +23 -4
  32. package/docs/reference/cli.md +7 -2
  33. package/docs/reference/workspace.md +11 -8
  34. package/package.json +1 -1
@@ -48,8 +48,10 @@
48
48
  * module needs the strip for.
49
49
  */
50
50
  import { createHash } from "node:crypto";
51
+ import { BUNDLE_REF_RE } from "../../asset/asset-ref.js";
51
52
  import { parseFrontmatter } from "../../asset/frontmatter.js";
52
53
  import { checkUnquotedDescriptionColon } from "../../asset/frontmatter-lint.js";
54
+ import { findCurrentPathReferences, homeRootOf } from "../../asset/lint-text.js";
53
55
  import { toPosix } from "../../common.js";
54
56
  // ── Small pure helpers, reused across the concrete adapters ──────────────────
55
57
  /** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
@@ -76,15 +78,6 @@ export const RESERVED_FILES = new Set(["index.md", "log.md"]);
76
78
  function checkMissingUpdated(data, frontmatterText) {
77
79
  return frontmatterText !== null && !("updated" in data);
78
80
  }
79
- function findStalePathCandidates(body) {
80
- const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
81
- const out = [];
82
- let match;
83
- // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
84
- while ((match = pathRe.exec(body)) !== null)
85
- out.push(match[0]);
86
- return out;
87
- }
88
81
  /** See file header: same intent as `markdown-insertion.ts#findFenceRegions`, not byte-identical. */
89
82
  function stripFencedBlocksSimple(body) {
90
83
  const lines = body.split(/\r?\n/);
@@ -99,16 +92,9 @@ function stripFencedBlocksSimple(body) {
99
92
  });
100
93
  return out.join("\n");
101
94
  }
102
- // Ref-token grammar — copied from `base-linter.ts`'s `BUNDLE_REF_RE`
103
- // (`core/asset/asset-ref.ts`) as a VALUE,
104
- // not an import (same cycle-avoidance rationale as the file header — the source
105
- // string is duplicated so no new `core/adapter` -> `core/asset` edge is added for
106
- // this scan). Recognizes the 0.9.0 FULLY-QUALIFIED `<bundle>//<concept-id>
107
- // [#fragment]` prose body-ref anchored form ONLY. A bare short
108
- // conceptId in prose is NOT a ref, so it is never flagged here (it is a ref only
109
- // in the ref-LIST channels — {@link refTokenFromListValue}). The pre-0.9.0
110
- // `<type>:<slug>` colon grammar is gone from every recognition surface.
111
- const BUNDLE_BODY_REF_RE_SRC = "(?:^|[\\s`\"'(,[])([^\\s:.#/`\"'()[\\],<>]+\\/\\/[^\\s\"'`)\\]>,\\n]+)";
95
+ // Prose refs use the canonical `BUNDLE_REF_RE` (`core/asset/asset-ref.ts`): the 0.9.0 FULLY-QUALIFIED
96
+ // `<bundle>//<concept-id>[#fragment]` form ONLY. A bare short conceptId in prose is NOT a ref, so it is never flagged
97
+ // here (it is a ref only in the ref-LIST channels — {@link refTokenFromListValue}).
112
98
  /**
113
99
  * A conceptId that is a lint false positive rather than a real ref — mirrors the
114
100
  * `isNonRefName` guards `base-linter.ts` applies deep in its existence check:
@@ -130,7 +116,7 @@ function isNonRefConceptId(conceptId) {
130
116
  * ACP (`::`) false positives are dropped.
131
117
  */
132
118
  function extractProseRefTokens(text) {
133
- const re = new RegExp(BUNDLE_BODY_REF_RE_SRC, "gm");
119
+ const re = new RegExp(BUNDLE_REF_RE.source, BUNDLE_REF_RE.flags);
134
120
  const scanBody = stripFencedBlocksSimple(text);
135
121
  const refs = [];
136
122
  let match;
@@ -207,10 +193,13 @@ export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx)
207
193
  });
208
194
  }
209
195
  const staleCandidates = [
210
- ...findStalePathCandidates(body),
211
- ...(frontmatter ? findStalePathCandidates(frontmatter) : []),
196
+ ...findCurrentPathReferences(body),
197
+ ...(frontmatter ? findCurrentPathReferences(frontmatter) : []),
212
198
  ];
213
199
  for (const candidate of staleCandidates) {
200
+ const home = homeRootOf(candidate);
201
+ if (home !== undefined && (await ctx.list(home)).length === 0)
202
+ continue; // another host's or user's path
214
203
  const found = await ctx.readFile(candidate);
215
204
  if (found !== null)
216
205
  continue;
@@ -57,9 +57,10 @@ export function isBundleSlug(s) {
57
57
  * leading boundary char (e.g. the `[` of a markdown link) is not absorbed into
58
58
  * the slug. The concept segment reuses the same terminator charset as the
59
59
  * body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
60
- * `.`, and a trailing `#fragment`.
60
+ * `.`, and a trailing `#fragment`. Its last character is never sentence
61
+ * punctuation (`.;:!?`), so a ref that ends a sentence stops before the period.
61
62
  */
62
- export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]+)/gm;
63
+ export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]*[^\s"'`)\]>,\n.;:!?])/gm;
63
64
  /** NFC-normalize + traversal/null-byte/drive-letter guard + path-normalize a concept id. */
64
65
  function normalizeConceptId(raw) {
65
66
  const nfc = raw.normalize("NFC");
@@ -1,30 +1,25 @@
1
1
  // This Source Code Form is subject to the terms of the Mozilla Public
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
- import { isScalar, parseDocument } from "yaml";
4
+ import { parseDocument } from "yaml";
5
5
  /**
6
- * Report a colon-bearing description only when YAML parsed it as a plain
7
- * scalar. Quoted and block scalars may span physical lines and remain valid.
6
+ * Report a colon-bearing description only when its YAML does not parse. A
7
+ * plain scalar such as a URL or `admin:snapshot` is valid YAML and stays clean;
8
+ * `a: b` in a plain scalar is a nested mapping YAML rejects.
8
9
  */
9
10
  export function checkUnquotedDescriptionColon(frontmatterText) {
10
- if (!frontmatterText)
11
+ if (!frontmatterText || parseDocument(frontmatterText).errors.length === 0)
11
12
  return null;
12
- const document = parseDocument(frontmatterText);
13
- const description = document.get("description", true);
14
- if (document.errors.length === 0 &&
15
- isScalar(description) &&
16
- description.type === "PLAIN" &&
17
- typeof description.value === "string" &&
18
- description.value.includes(":")) {
19
- return `description value contains unquoted colon: ${description.value}`;
20
- }
21
- // Preserve the existing finding for malformed plain scalars that YAML cannot
22
- // construct, while letting valid multiline quoted/block scalars pass above.
23
- if (document.errors.length > 0) {
24
- const line = frontmatterText.split(/\r?\n/).find((candidate) => candidate.startsWith("description:"));
25
- const value = line?.slice("description:".length).trim();
26
- if (value?.includes(":"))
27
- return `description value contains unquoted colon: ${value}`;
28
- }
29
- return null;
13
+ const lines = frontmatterText.split(/\r?\n/);
14
+ const start = lines.findIndex((candidate) => candidate.startsWith("description:"));
15
+ if (start === -1)
16
+ return null;
17
+ let end = start + 1;
18
+ while (end < lines.length && /^[ \t]/.test(lines[end]))
19
+ end++;
20
+ const region = lines.slice(start, end).join("\n");
21
+ const value = lines[start]?.slice("description:".length).trim();
22
+ if (!region.includes(":") || parseDocument(region).errors.length === 0)
23
+ return null;
24
+ return `description value contains unquoted colon: ${value}`;
30
25
  }
@@ -0,0 +1,50 @@
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
+ /**
5
+ * Pure text rules shared by every lint surface (`akm lint` sweep and adapter
6
+ * `validate`): which absolute paths count as current guidance, and how
7
+ * sentence punctuation is kept out of paths and ref tokens. No filesystem
8
+ * access here; callers decide how existence is probed.
9
+ */
10
+ /**
11
+ * A path segment shaped like a run-time filename template rather than a
12
+ * literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
13
+ * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, or a glob
14
+ * character. Such a path never exists under its literal spelling.
15
+ */
16
+ const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
17
+ /** A line that presents a path as a record of the past or as an illustration, not as guidance to follow. */
18
+ const NON_CURRENT_LINE_PATTERN = /\b(?:historical(?:ly)?|previously|formerly|for example|for instance)\b|\be\.g\./i;
19
+ /** A heading whose section holds records or illustrations rather than current guidance. */
20
+ const NON_CURRENT_HEADING_PATTERN = /^#{1,6}\s.*\b(?:history|changelog|archive|examples?)\b/i;
21
+ /** Drop sentence punctuation absorbed at the end of a path or ref token. */
22
+ function stripTrailingSentencePunctuation(token) {
23
+ return token.replace(/[.;:!?]+$/, "");
24
+ }
25
+ /** The `/home/<user>` directory a path lives under, or `undefined` for any other path. */
26
+ export function homeRootOf(candidate) {
27
+ return candidate.match(/^\/home\/[^/]+/)?.[0];
28
+ }
29
+ /**
30
+ * Absolute paths in `text` presented as current guidance. Paths on lines or in
31
+ * sections that frame them as history or examples, run-time filename
32
+ * templates, and trailing sentence punctuation are all excluded.
33
+ */
34
+ export function findCurrentPathReferences(text) {
35
+ const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
36
+ const out = [];
37
+ let inNonCurrentSection = false;
38
+ for (const line of text.split(/\r?\n/)) {
39
+ if (/^#{1,6}\s/.test(line))
40
+ inNonCurrentSection = NON_CURRENT_HEADING_PATTERN.test(line);
41
+ if (inNonCurrentSection || NON_CURRENT_LINE_PATTERN.test(line))
42
+ continue;
43
+ for (const match of line.matchAll(pathRe)) {
44
+ const candidate = stripTrailingSentencePunctuation(match[0]);
45
+ if (!PATH_PLACEHOLDER_PATTERN.test(candidate))
46
+ out.push(candidate);
47
+ }
48
+ }
49
+ return out;
50
+ }
@@ -17,6 +17,7 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
17
17
  import { closeDatabase, deleteIndexDatabase, indexDbIsDamaged, isCorruptionError, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
18
18
  import { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteEntriesOutsideLibrary, deleteUsageEventsForEntries, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
19
19
  import { rebuildFtsIfTotalsStale } from "../storage/repositories/index-fts-repository.js";
20
+ import { storeLayout } from "../storage/repositories/index-layout-repository.js";
20
21
  import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
21
22
  import { deleteIndexDirState, deleteMeta, getIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
22
23
  import { VACUUM_PENDING_META } from "../storage/repositories/index-schema.js";
@@ -524,6 +525,10 @@ async function akmIndexReal(options) {
524
525
  reembed: options.reembed === true,
525
526
  importVectorsFile: options.importVectors,
526
527
  });
528
+ // The library's layout by meaning and its near-duplicates, from the vectors, when they changed.
529
+ throwIfAborted(signal);
530
+ onProgress({ phase: "finalize", message: "Grouping assets by meaning." });
531
+ await storeLayout(db);
527
532
  const tEmbedEnd = Date.now();
528
533
  // ── Finalize ──────────────────────────────────────────────────────────
529
534
  const tFinalizeStart = Date.now();
@@ -683,7 +683,8 @@ function formatUpgradePluginLines(r) {
683
683
  const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
684
684
  const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
685
685
  const note = p.message ? ` (${p.message})` : "";
686
- lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
686
+ const outcome = p.outcome === "current" && p.channel ? "current within its configured channel" : p.outcome;
687
+ lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${outcome}${versions}${channel}${note}`);
687
688
  }
688
689
  return lines;
689
690
  }
@@ -7234,10 +7234,11 @@ function parseBundleRef(ref) {
7234
7234
  const conceptId = normalizeConceptId(body);
7235
7235
  return { bundle: bundle || undefined, conceptId, fragment };
7236
7236
  }
7237
- var REF_FORM_HINT = "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.", BUNDLE_SLUG_RE;
7237
+ var REF_FORM_HINT = "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.", BUNDLE_SLUG_RE, BUNDLE_REF_RE;
7238
7238
  var init_asset_ref = __esm(() => {
7239
7239
  init_errors();
7240
7240
  BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
7241
+ BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]*[^\s"'`)\]>,\n.;:!?])/gm;
7241
7242
  });
7242
7243
 
7243
7244
  // src/core/bundle-id.ts
@@ -35403,25 +35404,57 @@ var init_scratch = __esm(() => {
35403
35404
 
35404
35405
  // src/core/asset/frontmatter-lint.ts
35405
35406
  function checkUnquotedDescriptionColon(frontmatterText) {
35406
- if (!frontmatterText)
35407
+ if (!frontmatterText || $parseDocument(frontmatterText).errors.length === 0)
35407
35408
  return null;
35408
- const document = $parseDocument(frontmatterText);
35409
- const description = document.get("description", true);
35410
- if (document.errors.length === 0 && $isScalar(description) && description.type === "PLAIN" && typeof description.value === "string" && description.value.includes(":")) {
35411
- return `description value contains unquoted colon: ${description.value}`;
35412
- }
35413
- if (document.errors.length > 0) {
35414
- const line = frontmatterText.split(/\r?\n/).find((candidate) => candidate.startsWith("description:"));
35415
- const value = line?.slice("description:".length).trim();
35416
- if (value?.includes(":"))
35417
- return `description value contains unquoted colon: ${value}`;
35418
- }
35419
- return null;
35409
+ const lines = frontmatterText.split(/\r?\n/);
35410
+ const start = lines.findIndex((candidate) => candidate.startsWith("description:"));
35411
+ if (start === -1)
35412
+ return null;
35413
+ let end = start + 1;
35414
+ while (end < lines.length && /^[ \t]/.test(lines[end]))
35415
+ end++;
35416
+ const region = lines.slice(start, end).join(`
35417
+ `);
35418
+ const value = lines[start]?.slice("description:".length).trim();
35419
+ if (!region.includes(":") || $parseDocument(region).errors.length === 0)
35420
+ return null;
35421
+ return `description value contains unquoted colon: ${value}`;
35420
35422
  }
35421
35423
  var init_frontmatter_lint = __esm(() => {
35422
35424
  init_dist();
35423
35425
  });
35424
35426
 
35427
+ // src/core/asset/lint-text.ts
35428
+ function stripTrailingSentencePunctuation(token) {
35429
+ return token.replace(/[.;:!?]+$/, "");
35430
+ }
35431
+ function homeRootOf(candidate) {
35432
+ return candidate.match(/^\/home\/[^/]+/)?.[0];
35433
+ }
35434
+ function findCurrentPathReferences(text2) {
35435
+ const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
35436
+ const out = [];
35437
+ let inNonCurrentSection = false;
35438
+ for (const line of text2.split(/\r?\n/)) {
35439
+ if (/^#{1,6}\s/.test(line))
35440
+ inNonCurrentSection = NON_CURRENT_HEADING_PATTERN.test(line);
35441
+ if (inNonCurrentSection || NON_CURRENT_LINE_PATTERN.test(line))
35442
+ continue;
35443
+ for (const match of line.matchAll(pathRe)) {
35444
+ const candidate = stripTrailingSentencePunctuation(match[0]);
35445
+ if (!PATH_PLACEHOLDER_PATTERN.test(candidate))
35446
+ out.push(candidate);
35447
+ }
35448
+ }
35449
+ return out;
35450
+ }
35451
+ var PATH_PLACEHOLDER_PATTERN, NON_CURRENT_LINE_PATTERN, NON_CURRENT_HEADING_PATTERN;
35452
+ var init_lint_text = __esm(() => {
35453
+ PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
35454
+ NON_CURRENT_LINE_PATTERN = /\b(?:historical(?:ly)?|previously|formerly|for example|for instance)\b|\be\.g\./i;
35455
+ NON_CURRENT_HEADING_PATTERN = /^#{1,6}\s.*\b(?:history|changelog|archive|examples?)\b/i;
35456
+ });
35457
+
35425
35458
  // src/core/adapter/adapters/shared.ts
35426
35459
  import { createHash } from "node:crypto";
35427
35460
  function hashContent(content) {
@@ -35442,14 +35475,6 @@ function readTags(value) {
35442
35475
  function checkMissingUpdated(data, frontmatterText) {
35443
35476
  return frontmatterText !== null && !("updated" in data);
35444
35477
  }
35445
- function findStalePathCandidates(body) {
35446
- const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
35447
- const out = [];
35448
- let match;
35449
- while ((match = pathRe.exec(body)) !== null)
35450
- out.push(match[0]);
35451
- return out;
35452
- }
35453
35478
  function stripFencedBlocksSimple(body) {
35454
35479
  const lines = body.split(/\r?\n/);
35455
35480
  let inFence = false;
@@ -35473,7 +35498,7 @@ function isNonRefConceptId(conceptId) {
35473
35498
  return false;
35474
35499
  }
35475
35500
  function extractProseRefTokens(text2) {
35476
- const re = new RegExp(BUNDLE_BODY_REF_RE_SRC, "gm");
35501
+ const re = new RegExp(BUNDLE_REF_RE.source, BUNDLE_REF_RE.flags);
35477
35502
  const scanBody = stripFencedBlocksSimple(text2);
35478
35503
  const refs = [];
35479
35504
  let match;
@@ -35523,10 +35548,13 @@ async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
35523
35548
  });
35524
35549
  }
35525
35550
  const staleCandidates = [
35526
- ...findStalePathCandidates(body),
35527
- ...frontmatter ? findStalePathCandidates(frontmatter) : []
35551
+ ...findCurrentPathReferences(body),
35552
+ ...frontmatter ? findCurrentPathReferences(frontmatter) : []
35528
35553
  ];
35529
35554
  for (const candidate of staleCandidates) {
35555
+ const home = homeRootOf(candidate);
35556
+ if (home !== undefined && (await ctx.list(home)).length === 0)
35557
+ continue;
35530
35558
  const found = await ctx.readFile(candidate);
35531
35559
  if (found !== null)
35532
35560
  continue;
@@ -35579,10 +35607,12 @@ async function validateChangesWithBaseChecks(c, changes, ctx) {
35579
35607
  }
35580
35608
  return diagnostics;
35581
35609
  }
35582
- var RESERVED_FILES, BUNDLE_BODY_REF_RE_SRC = "(?:^|[\\s`\"'(,[])([^\\s:.#/`\"'()[\\],<>]+\\/\\/[^\\s\"'`)\\]>,\\n]+)", XREF_FRONTMATTER_KEYS;
35610
+ var RESERVED_FILES, XREF_FRONTMATTER_KEYS;
35583
35611
  var init_shared = __esm(() => {
35612
+ init_asset_ref();
35584
35613
  init_frontmatter();
35585
35614
  init_frontmatter_lint();
35615
+ init_lint_text();
35586
35616
  init_common();
35587
35617
  RESERVED_FILES = new Set(["index.md", "log.md"]);
35588
35618
  XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
@@ -40900,18 +40930,36 @@ function dangerousEnvKeyDiagnostics(type, relPath, raw) {
40900
40930
  }
40901
40931
  return diagnostics;
40902
40932
  }
40933
+ async function hasSkillBelow(dir, depth, ctx) {
40934
+ if (depth >= MAX_SKILL_GROUP_DEPTH)
40935
+ return false;
40936
+ for (const entry of await ctx.list(dir)) {
40937
+ if (entry.startsWith("."))
40938
+ continue;
40939
+ const child = `${dir}/${entry}`;
40940
+ if (await ctx.readFile(`${child}/SKILL.md`) !== null)
40941
+ return true;
40942
+ if (await hasSkillBelow(child, depth + 1, ctx))
40943
+ return true;
40944
+ }
40945
+ return false;
40946
+ }
40903
40947
  async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs = AKM_SKILL_DIRS) {
40904
40948
  const segments = relPath.replace(/\\/g, "/").split("/").filter((s) => s.length > 0);
40905
40949
  if (segments.length < 3 || !skillDirs.has(segments[0]))
40906
40950
  return [];
40907
- const skillDir = `${segments[0]}/${segments[1]}`;
40908
- if (seen.has(skillDir))
40909
- return [];
40910
- seen.add(skillDir);
40911
- const skillMd = await ctx.readFile(`${skillDir}/SKILL.md`);
40912
- if (skillMd !== null)
40913
- return [];
40914
- return [{ file: skillDir, issue: "missing-skill-md", detail: `no SKILL.md in ${skillDir}/`, fixed: false }];
40951
+ for (let depth = 2;depth < segments.length; depth++) {
40952
+ const dir = segments.slice(0, depth).join("/");
40953
+ if (await ctx.readFile(`${dir}/SKILL.md`) !== null)
40954
+ return [];
40955
+ if (await hasSkillBelow(dir, depth - 1, ctx))
40956
+ continue;
40957
+ if (seen.has(dir))
40958
+ return [];
40959
+ seen.add(dir);
40960
+ return [{ file: dir, issue: "missing-skill-md", detail: `no SKILL.md in ${dir}/`, fixed: false }];
40961
+ }
40962
+ return [];
40915
40963
  }
40916
40964
  async function perTypeValidateChecks(args) {
40917
40965
  const { type, relPath, raw, data, frontmatter, body, ext, ctx } = args;
@@ -41066,7 +41114,7 @@ async function memoryDiagnostics(relPath, data, body, ctx) {
41066
41114
  return [];
41067
41115
  return [{ file: relPath, issue: "orphaned-stub", detail: ORPHANED_STUB_DETAIL, fixed: false }];
41068
41116
  }
41069
- var KNOWN_CATEGORIES, PLACEHOLDER_STRINGS, SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key", AKM_SKILL_DIRS, ORPHANED_STUB_DETAIL = "inferenceProcessed stub with no derived sibling";
41117
+ var KNOWN_CATEGORIES, PLACEHOLDER_STRINGS, SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key", AKM_SKILL_DIRS, MAX_SKILL_GROUP_DEPTH = 3, ORPHANED_STUB_DETAIL = "inferenceProcessed stub with no derived sibling";
41070
41118
  var init_akm_lint = __esm(() => {
41071
41119
  init_env_key_rules();
41072
41120
  init_backends();
@@ -71176,7 +71224,8 @@ function formatUpgradePluginLines(r) {
71176
71224
  const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
71177
71225
  const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
71178
71226
  const note = p.message ? ` (${p.message})` : "";
71179
- lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
71227
+ const outcome = p.outcome === "current" && p.channel ? "current within its configured channel" : p.outcome;
71228
+ lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${outcome}${versions}${channel}${note}`);
71180
71229
  }
71181
71230
  return lines;
71182
71231
  }
@@ -74808,7 +74857,7 @@ function contentRefRewriter(bundles) {
74808
74857
  }
74809
74858
 
74810
74859
  // scripts/akm-migrate/content-ref-migrate.ts
74811
- var TEXT_EXTENSIONS = new Set([".md", ".yml", ".yaml", ".sh", ".ts", ".js", ".json", ".txt", ".py", ".mjs", ".jsonc", ".toml", ""]);
74860
+ var TEXT_EXTENSIONS = new Set([".md", ".yml", ".yaml"]);
74812
74861
  function textFiles(root) {
74813
74862
  return walkStashFlat(root).filter((file2) => TEXT_EXTENSIONS.has(file2.ext) && fs52.lstatSync(file2.absPath).isFile()).map((file2) => file2.absPath);
74814
74863
  }
@@ -7233,10 +7233,11 @@ function parseBundleRef(ref) {
7233
7233
  const conceptId = normalizeConceptId(body);
7234
7234
  return { bundle: bundle || undefined, conceptId, fragment };
7235
7235
  }
7236
- var REF_FORM_HINT = "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.", BUNDLE_SLUG_RE;
7236
+ var REF_FORM_HINT = "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.", BUNDLE_SLUG_RE, BUNDLE_REF_RE;
7237
7237
  var init_asset_ref = __esm(() => {
7238
7238
  init_errors();
7239
7239
  BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
7240
+ BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]*[^\s"'`)\]>,\n.;:!?])/gm;
7240
7241
  });
7241
7242
 
7242
7243
  // src/core/bundle-id.ts
@@ -35402,25 +35403,57 @@ var init_scratch = __esm(() => {
35402
35403
 
35403
35404
  // src/core/asset/frontmatter-lint.ts
35404
35405
  function checkUnquotedDescriptionColon(frontmatterText) {
35405
- if (!frontmatterText)
35406
+ if (!frontmatterText || $parseDocument(frontmatterText).errors.length === 0)
35406
35407
  return null;
35407
- const document = $parseDocument(frontmatterText);
35408
- const description = document.get("description", true);
35409
- if (document.errors.length === 0 && $isScalar(description) && description.type === "PLAIN" && typeof description.value === "string" && description.value.includes(":")) {
35410
- return `description value contains unquoted colon: ${description.value}`;
35411
- }
35412
- if (document.errors.length > 0) {
35413
- const line = frontmatterText.split(/\r?\n/).find((candidate) => candidate.startsWith("description:"));
35414
- const value = line?.slice("description:".length).trim();
35415
- if (value?.includes(":"))
35416
- return `description value contains unquoted colon: ${value}`;
35417
- }
35418
- return null;
35408
+ const lines = frontmatterText.split(/\r?\n/);
35409
+ const start = lines.findIndex((candidate) => candidate.startsWith("description:"));
35410
+ if (start === -1)
35411
+ return null;
35412
+ let end = start + 1;
35413
+ while (end < lines.length && /^[ \t]/.test(lines[end]))
35414
+ end++;
35415
+ const region = lines.slice(start, end).join(`
35416
+ `);
35417
+ const value = lines[start]?.slice("description:".length).trim();
35418
+ if (!region.includes(":") || $parseDocument(region).errors.length === 0)
35419
+ return null;
35420
+ return `description value contains unquoted colon: ${value}`;
35419
35421
  }
35420
35422
  var init_frontmatter_lint = __esm(() => {
35421
35423
  init_dist();
35422
35424
  });
35423
35425
 
35426
+ // src/core/asset/lint-text.ts
35427
+ function stripTrailingSentencePunctuation(token) {
35428
+ return token.replace(/[.;:!?]+$/, "");
35429
+ }
35430
+ function homeRootOf(candidate) {
35431
+ return candidate.match(/^\/home\/[^/]+/)?.[0];
35432
+ }
35433
+ function findCurrentPathReferences(text2) {
35434
+ const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
35435
+ const out = [];
35436
+ let inNonCurrentSection = false;
35437
+ for (const line of text2.split(/\r?\n/)) {
35438
+ if (/^#{1,6}\s/.test(line))
35439
+ inNonCurrentSection = NON_CURRENT_HEADING_PATTERN.test(line);
35440
+ if (inNonCurrentSection || NON_CURRENT_LINE_PATTERN.test(line))
35441
+ continue;
35442
+ for (const match of line.matchAll(pathRe)) {
35443
+ const candidate = stripTrailingSentencePunctuation(match[0]);
35444
+ if (!PATH_PLACEHOLDER_PATTERN.test(candidate))
35445
+ out.push(candidate);
35446
+ }
35447
+ }
35448
+ return out;
35449
+ }
35450
+ var PATH_PLACEHOLDER_PATTERN, NON_CURRENT_LINE_PATTERN, NON_CURRENT_HEADING_PATTERN;
35451
+ var init_lint_text = __esm(() => {
35452
+ PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
35453
+ NON_CURRENT_LINE_PATTERN = /\b(?:historical(?:ly)?|previously|formerly|for example|for instance)\b|\be\.g\./i;
35454
+ NON_CURRENT_HEADING_PATTERN = /^#{1,6}\s.*\b(?:history|changelog|archive|examples?)\b/i;
35455
+ });
35456
+
35424
35457
  // src/core/adapter/adapters/shared.ts
35425
35458
  import { createHash } from "crypto";
35426
35459
  function hashContent(content) {
@@ -35441,14 +35474,6 @@ function readTags(value) {
35441
35474
  function checkMissingUpdated(data, frontmatterText) {
35442
35475
  return frontmatterText !== null && !("updated" in data);
35443
35476
  }
35444
- function findStalePathCandidates(body) {
35445
- const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
35446
- const out = [];
35447
- let match;
35448
- while ((match = pathRe.exec(body)) !== null)
35449
- out.push(match[0]);
35450
- return out;
35451
- }
35452
35477
  function stripFencedBlocksSimple(body) {
35453
35478
  const lines = body.split(/\r?\n/);
35454
35479
  let inFence = false;
@@ -35472,7 +35497,7 @@ function isNonRefConceptId(conceptId) {
35472
35497
  return false;
35473
35498
  }
35474
35499
  function extractProseRefTokens(text2) {
35475
- const re = new RegExp(BUNDLE_BODY_REF_RE_SRC, "gm");
35500
+ const re = new RegExp(BUNDLE_REF_RE.source, BUNDLE_REF_RE.flags);
35476
35501
  const scanBody = stripFencedBlocksSimple(text2);
35477
35502
  const refs = [];
35478
35503
  let match;
@@ -35522,10 +35547,13 @@ async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
35522
35547
  });
35523
35548
  }
35524
35549
  const staleCandidates = [
35525
- ...findStalePathCandidates(body),
35526
- ...frontmatter ? findStalePathCandidates(frontmatter) : []
35550
+ ...findCurrentPathReferences(body),
35551
+ ...frontmatter ? findCurrentPathReferences(frontmatter) : []
35527
35552
  ];
35528
35553
  for (const candidate of staleCandidates) {
35554
+ const home = homeRootOf(candidate);
35555
+ if (home !== undefined && (await ctx.list(home)).length === 0)
35556
+ continue;
35529
35557
  const found = await ctx.readFile(candidate);
35530
35558
  if (found !== null)
35531
35559
  continue;
@@ -35578,10 +35606,12 @@ async function validateChangesWithBaseChecks(c, changes, ctx) {
35578
35606
  }
35579
35607
  return diagnostics;
35580
35608
  }
35581
- var RESERVED_FILES, BUNDLE_BODY_REF_RE_SRC = "(?:^|[\\s`\"'(,[])([^\\s:.#/`\"'()[\\],<>]+\\/\\/[^\\s\"'`)\\]>,\\n]+)", XREF_FRONTMATTER_KEYS;
35609
+ var RESERVED_FILES, XREF_FRONTMATTER_KEYS;
35582
35610
  var init_shared = __esm(() => {
35611
+ init_asset_ref();
35583
35612
  init_frontmatter();
35584
35613
  init_frontmatter_lint();
35614
+ init_lint_text();
35585
35615
  init_common();
35586
35616
  RESERVED_FILES = new Set(["index.md", "log.md"]);
35587
35617
  XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
@@ -40899,18 +40929,36 @@ function dangerousEnvKeyDiagnostics(type, relPath, raw) {
40899
40929
  }
40900
40930
  return diagnostics;
40901
40931
  }
40932
+ async function hasSkillBelow(dir, depth, ctx) {
40933
+ if (depth >= MAX_SKILL_GROUP_DEPTH)
40934
+ return false;
40935
+ for (const entry of await ctx.list(dir)) {
40936
+ if (entry.startsWith("."))
40937
+ continue;
40938
+ const child = `${dir}/${entry}`;
40939
+ if (await ctx.readFile(`${child}/SKILL.md`) !== null)
40940
+ return true;
40941
+ if (await hasSkillBelow(child, depth + 1, ctx))
40942
+ return true;
40943
+ }
40944
+ return false;
40945
+ }
40902
40946
  async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs = AKM_SKILL_DIRS) {
40903
40947
  const segments = relPath.replace(/\\/g, "/").split("/").filter((s) => s.length > 0);
40904
40948
  if (segments.length < 3 || !skillDirs.has(segments[0]))
40905
40949
  return [];
40906
- const skillDir = `${segments[0]}/${segments[1]}`;
40907
- if (seen.has(skillDir))
40908
- return [];
40909
- seen.add(skillDir);
40910
- const skillMd = await ctx.readFile(`${skillDir}/SKILL.md`);
40911
- if (skillMd !== null)
40912
- return [];
40913
- return [{ file: skillDir, issue: "missing-skill-md", detail: `no SKILL.md in ${skillDir}/`, fixed: false }];
40950
+ for (let depth = 2;depth < segments.length; depth++) {
40951
+ const dir = segments.slice(0, depth).join("/");
40952
+ if (await ctx.readFile(`${dir}/SKILL.md`) !== null)
40953
+ return [];
40954
+ if (await hasSkillBelow(dir, depth - 1, ctx))
40955
+ continue;
40956
+ if (seen.has(dir))
40957
+ return [];
40958
+ seen.add(dir);
40959
+ return [{ file: dir, issue: "missing-skill-md", detail: `no SKILL.md in ${dir}/`, fixed: false }];
40960
+ }
40961
+ return [];
40914
40962
  }
40915
40963
  async function perTypeValidateChecks(args) {
40916
40964
  const { type, relPath, raw, data, frontmatter, body, ext, ctx } = args;
@@ -41065,7 +41113,7 @@ async function memoryDiagnostics(relPath, data, body, ctx) {
41065
41113
  return [];
41066
41114
  return [{ file: relPath, issue: "orphaned-stub", detail: ORPHANED_STUB_DETAIL, fixed: false }];
41067
41115
  }
41068
- var KNOWN_CATEGORIES, PLACEHOLDER_STRINGS, SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key", AKM_SKILL_DIRS, ORPHANED_STUB_DETAIL = "inferenceProcessed stub with no derived sibling";
41116
+ var KNOWN_CATEGORIES, PLACEHOLDER_STRINGS, SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key", AKM_SKILL_DIRS, MAX_SKILL_GROUP_DEPTH = 3, ORPHANED_STUB_DETAIL = "inferenceProcessed stub with no derived sibling";
41069
41117
  var init_akm_lint = __esm(() => {
41070
41118
  init_env_key_rules();
41071
41119
  init_backends();
@@ -71174,7 +71222,8 @@ function formatUpgradePluginLines(r) {
71174
71222
  const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} \u2192 v${p.to}` : "";
71175
71223
  const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
71176
71224
  const note = p.message ? ` (${p.message})` : "";
71177
- lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
71225
+ const outcome = p.outcome === "current" && p.channel ? "current within its configured channel" : p.outcome;
71226
+ lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${outcome}${versions}${channel}${note}`);
71178
71227
  }
71179
71228
  return lines;
71180
71229
  }
@@ -74793,7 +74842,7 @@ function contentRefRewriter(bundles) {
74793
74842
  }
74794
74843
 
74795
74844
  // scripts/akm-migrate/content-ref-migrate.ts
74796
- var TEXT_EXTENSIONS = new Set([".md", ".yml", ".yaml", ".sh", ".ts", ".js", ".json", ".txt", ".py", ".mjs", ".jsonc", ".toml", ""]);
74845
+ var TEXT_EXTENSIONS = new Set([".md", ".yml", ".yaml"]);
74797
74846
  function textFiles(root2) {
74798
74847
  return walkStashFlat(root2).filter((file2) => TEXT_EXTENSIONS.has(file2.ext) && fs52.lstatSync(file2.absPath).isFile()).map((file2) => file2.absPath);
74799
74848
  }