akm-cli 0.10.261128 → 0.10.261129

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/dist/cli.js +2 -0
  3. package/dist/commands/agent/contribute-cli.js +7 -1
  4. package/dist/commands/backups-cli.js +103 -0
  5. package/dist/commands/health.js +1 -34
  6. package/dist/commands/improve/reflect-noise.js +0 -1
  7. package/dist/commands/lint/base-linter.js +24 -48
  8. package/dist/commands/lint/bundle-skip.js +27 -0
  9. package/dist/commands/lint/index.js +83 -45
  10. package/dist/commands/lint/tracked-secrets.js +43 -0
  11. package/dist/commands/lint/types.js +58 -0
  12. package/dist/commands/proposal/repository.js +5 -1
  13. package/dist/commands/sources/stash-skeleton.js +7 -26
  14. package/dist/core/adapter/adapters/akm-adapter.js +2 -2
  15. package/dist/core/adapter/adapters/akm-workflow-adapter.js +6 -1
  16. package/dist/core/adapter/adapters/shared.js +13 -25
  17. package/dist/core/asset/lint-text.js +14 -13
  18. package/dist/core/asset/stale-path.js +63 -0
  19. package/dist/core/config/schema/sources-bundles.js +3 -0
  20. package/dist/output/shapes/passthrough.js +1 -0
  21. package/dist/output/text/lint-format.js +90 -1
  22. package/dist/output/text/migrate.js +5 -0
  23. package/dist/scripts/akm-migrate-node.js +1149 -791
  24. package/dist/scripts/akm-migrate.js +1149 -791
  25. package/dist/sources/include.js +1 -1
  26. package/dist/sources/snapshot-fetchers/website-ingest.js +0 -2
  27. package/dist/workspace/backups.js +21 -0
  28. package/dist/workspace/cli-child.js +5 -1
  29. package/dist/workspace-node.mjs +2 -0
  30. package/dist/workspace.d.ts +4 -0
  31. package/dist/workspace.js +1 -0
  32. package/docs/architecture/internals/health-advisories.md +1 -2
  33. package/docs/guides/bundles.md +5 -4
  34. package/docs/integration/bundling-akm.md +9 -1
  35. package/docs/reference/asset-types.md +1 -2
  36. package/docs/reference/cli.md +83 -3
  37. package/docs/reference/configuration.md +8 -2
  38. package/docs/reference/data-and-telemetry.md +1 -0
  39. package/docs/reference/env-and-secrets.md +9 -4
  40. package/docs/reference/website-sources.md +2 -2
  41. package/docs/reference/workspace.md +1 -0
  42. package/package.json +1 -1
  43. package/schemas/akm-config.json +34 -0
  44. package/dist/commands/health/stash-exposure.js +0 -64
@@ -7,20 +7,24 @@ import { factDiagnostics, MAX_SKILL_GROUP_DEPTH, matchWorkflowPlaceholder, memor
7
7
  import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
8
8
  import { adapterForId } from "../../core/adapter/registry.js";
9
9
  import { createValidateContext } from "../../core/adapter/validate-context.js";
10
- import { stashDirFor } from "../../core/asset/asset-placement.js";
10
+ import { refForFile, stashDirFor, typeForStashDir } from "../../core/asset/asset-placement.js";
11
11
  import { parseFrontmatter } from "../../core/asset/frontmatter.js";
12
12
  import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
13
+ import { stalePathRoots } from "../../core/asset/stale-path.js";
13
14
  import { deriveBundleIds } from "../../core/bundle-id.js";
14
15
  import { compareCodePoints, isAkmRegistryCachePath, resolveStashDir, safeRealpath, samePath } from "../../core/common.js";
15
16
  import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
17
+ import { bundleKeyForContentRoot } from "../../core/config/config-sources.js";
16
18
  import { UsageError } from "../../core/errors.js";
17
19
  import { warn } from "../../core/warn.js";
18
20
  import { resolveSourceEntries } from "../../indexer/search/search-source.js";
19
21
  import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
20
22
  import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
21
23
  import { runBaseChecks } from "./base-linter.js";
24
+ import { bundleLintSkip } from "./bundle-skip.js";
22
25
  import { checkEnvForDangerousKeys } from "./env-key-rules.js";
23
- import { isAdvisoryLintIssue } from "./types.js";
26
+ import { trackedSecretIssues } from "./tracked-secrets.js";
27
+ import { isAdvisoryLintIssue, LINT_RULES } from "./types.js";
24
28
  // ── Constants ─────────────────────────────────────────────────────────────────
25
29
  const STASH_SUBDIRS = [
26
30
  "agents",
@@ -222,19 +226,9 @@ const KNOWN_ADAPTER_ISSUE_TYPES = new Set([
222
226
  ]);
223
227
  /** Map one adapter {@link Diagnostic} onto a {@link LintIssue} — see `types.ts`'s `"adapter-diagnostic"` doc comment for the open→closed reconciliation. */
224
228
  export function diagnosticToLintIssue(diag) {
225
- // `line` is optional on both shapes: carry it only when the adapter set one,
226
- // so whole-file findings keep their exact existing serialization.
227
- const location = typeof diag.line === "number" ? { line: diag.line } : {};
228
- if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue)) {
229
- return { file: diag.file, issue: diag.issue, detail: diag.detail, fixed: diag.fixed, ...location };
230
- }
231
- return {
232
- file: diag.file,
233
- issue: "adapter-diagnostic",
234
- detail: `[${diag.issue}] ${diag.detail}`,
235
- fixed: diag.fixed,
236
- ...location,
237
- };
229
+ if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue))
230
+ return { ...diag, issue: diag.issue };
231
+ return { ...diag, issue: "adapter-diagnostic", detail: `[${diag.issue}] ${diag.detail}` };
238
232
  }
239
233
  /**
240
234
  * Lint a bundle through its OWN adapter's `validate()`: the
@@ -298,13 +292,7 @@ async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cf
298
292
  flagged.push(issue);
299
293
  }
300
294
  }
301
- return {
302
- ok: true,
303
- fixed: [],
304
- flagged,
305
- warnings,
306
- summary: { fixed: 0, flagged: flagged.length, warnings: warnings.length },
307
- };
295
+ return { fixed: [], flagged, warnings };
308
296
  }
309
297
  function lintIssueDedupeKey(issue) {
310
298
  return `${issue.file} ${issue.issue} ${issue.detail}`;
@@ -466,6 +454,8 @@ function appendMemoryStubIssue(ctx, issues) {
466
454
  * both halves.
467
455
  */
468
456
  function appendWorkflowStubIssue(ctx, issues) {
457
+ if (ctx.lintSkip?.includes("placeholder-stub"))
458
+ return;
469
459
  const placeholder = matchWorkflowPlaceholder(ctx.body);
470
460
  if (!placeholder)
471
461
  return;
@@ -534,7 +524,8 @@ export function lintAssetFile(ctx, subdir) {
534
524
  }
535
525
  /** Lint one asset file of `subdir` and file its findings into `sinks` (the sweep loop body, shared with {@link lintFile}). */
536
526
  function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warnings }) {
537
- const { stashRoot, extraStashRoots, fix, pruneDanglingEdges, lintSkip } = scope;
527
+ const { stashRoot, extraStashRoots, fix, pruneDanglingEdges, stalePathRoots } = scope;
528
+ const lintSkip = [...(scope.lintSkip ?? []), ...(scope.bundleSkip?.(relPath) ?? [])];
538
529
  let raw;
539
530
  try {
540
531
  raw = fs.readFileSync(filePath, "utf8");
@@ -545,6 +536,7 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
545
536
  let data;
546
537
  let body;
547
538
  let frontmatter;
539
+ let bodyStartLine = 1;
548
540
  // File-identity findings the per-type rules cannot produce: they describe
549
541
  // the FILE (its extension, whether it parsed at all), not its fields.
550
542
  const fileIssues = [];
@@ -564,7 +556,7 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
564
556
  frontmatter = null;
565
557
  }
566
558
  else {
567
- ({ data, content: body, frontmatter } = parseFrontmatter(raw));
559
+ ({ data, content: body, frontmatter, bodyStartLine } = parseFrontmatter(raw));
568
560
  }
569
561
  // One file's checks — including its `--fix` mutations — must never abort
570
562
  // the sweep: an uncaught throw here left the caller with an exception and
@@ -582,9 +574,11 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
582
574
  data,
583
575
  body,
584
576
  frontmatter,
577
+ bodyStartLine,
585
578
  fix,
586
579
  pruneDanglingEdges,
587
580
  stashRoot,
581
+ stalePathRoots,
588
582
  extraStashRoots,
589
583
  lintSkip,
590
584
  }, subdir),
@@ -662,6 +656,8 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
662
656
  const fixed = [];
663
657
  const flagged = [];
664
658
  const warnings = [];
659
+ const bundleSkip = bundleLintSkip(cfg, stashRoot);
660
+ const roots = stalePathRoots(cfg, stashRoot);
665
661
  const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
666
662
  for (const subdir of dirsToScan) {
667
663
  const dirPath = path.join(stashRoot, subdir);
@@ -705,7 +701,14 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
705
701
  // rewrote files inside the registry cache.
706
702
  if (isAkmRegistryCachePath(filePath))
707
703
  continue;
708
- lintSweepFile(filePath, path.relative(stashRoot, filePath), subdir, { stashRoot, extraStashRoots, fix, pruneDanglingEdges: options.pruneDanglingEdges === true }, { fixed, flagged, warnings });
704
+ lintSweepFile(filePath, path.relative(stashRoot, filePath), subdir, {
705
+ stashRoot,
706
+ extraStashRoots,
707
+ fix,
708
+ pruneDanglingEdges: options.pruneDanglingEdges === true,
709
+ stalePathRoots: roots,
710
+ bundleSkip,
711
+ }, { fixed, flagged, warnings });
709
712
  }
710
713
  }
711
714
  // ── Env dangerous-key pass ─────────────────────────────────────────────────
@@ -722,13 +725,7 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
722
725
  // 2. `ok` is the shared `{ok, error, code}` failure indicator across the
723
726
  // whole CLI; reusing it for "found stuff" forced callers to disambiguate
724
727
  // a successful-but-flagged run from a hard error by inspecting fields.
725
- return {
726
- ok: true,
727
- fixed,
728
- flagged,
729
- warnings,
730
- summary: { fixed: fixed.length, flagged: flagged.length, warnings: warnings.length },
731
- };
728
+ return { fixed, flagged, warnings };
732
729
  }
733
730
  /** The configured bundle root (or `--dir`) that contains `file`, deepest first; undefined when `file` is outside every bundle. */
734
731
  function containingBundleRoot(file, roots) {
@@ -785,15 +782,7 @@ async function lintFile(file, options, cfg) {
785
782
  if (adapterId !== "akm") {
786
783
  const result = await lintViaAdapter(adapterId, root, sources.map((s) => s.path).filter((p) => p !== root && fs.existsSync(p)), sources, cfg, { ...options, typeFilter: undefined });
787
784
  const only = (issues) => issues.filter((i) => path.resolve(realRoot, i.file) === absFile);
788
- const flagged = only(result.flagged);
789
- const warnings = only(result.warnings);
790
- return {
791
- ok: true,
792
- fixed: [],
793
- flagged,
794
- warnings,
795
- summary: { fixed: 0, flagged: flagged.length, warnings: warnings.length },
796
- };
785
+ return finishLint({ fixed: [], flagged: only(result.flagged), warnings: only(result.warnings) }, cfg, options, root);
797
786
  }
798
787
  // The type comes from where the file sits, as the bundle sweep decides it.
799
788
  const located = STASH_SUBDIRS.find((d) => relPath.split(path.sep)[0] === d);
@@ -831,16 +820,57 @@ async function lintFile(file, options, cfg) {
831
820
  : [],
832
821
  fix: options.fix === true,
833
822
  pruneDanglingEdges: false,
823
+ stalePathRoots: stalePathRoots(cfg, root ?? path.dirname(absFile)),
824
+ bundleSkip: root ? bundleLintSkip(cfg, root) : undefined,
834
825
  // Outside a bundle there are no other assets to resolve refs or a derived stub against.
835
826
  lintSkip: root ? undefined : ["missing-ref", "orphaned-stub"],
836
827
  }, sinks);
837
- const { fixed, flagged, warnings } = sinks;
828
+ return finishLint(sinks, cfg, options, root);
829
+ }
830
+ /** The ref of an asset of the bundle at `root` by its bundle-relative `file`; undefined when `file` is not an asset path. */
831
+ function refOfFile(root, file, cfg) {
832
+ const type = typeForStashDir(file.split(/[\\/]/)[0] ?? "");
833
+ const conceptId = type ? refForFile(type, root, path.join(root, file)) : undefined;
834
+ if (conceptId === undefined)
835
+ return undefined;
836
+ const bundleId = bundleKeyForContentRoot(cfg, root);
837
+ return displayRefForConceptId(conceptId, bundleId, cfg.defaultBundle);
838
+ }
839
+ /**
840
+ * Turn what a pass found into the result: drop what the bundle's `lint.skip`
841
+ * names, give each finding its asset ref, narrow to `--rule`, and count the
842
+ * flagged findings per rule.
843
+ */
844
+ function finishLint(found, cfg, options, root) {
845
+ const skippedRules = root ? bundleLintSkip(cfg, root) : () => [];
846
+ let rule = options.rule;
847
+ if (rule !== undefined && !LINT_RULES.includes(rule)) {
848
+ warn(`Warning: lint --rule "${rule}" is not a lint rule — valid rules: ${LINT_RULES.join(", ")}. Showing every rule.`);
849
+ rule = undefined;
850
+ }
851
+ const keep = (issue) => (rule === undefined || issue.issue === rule) && !skippedRules(issue.file).includes(issue.issue);
852
+ const fixed = found.fixed.filter((issue) => rule === undefined || issue.issue === rule);
853
+ const flagged = found.flagged.filter(keep);
854
+ const warnings = found.warnings.filter(keep);
855
+ if (root) {
856
+ for (const issue of [...fixed, ...flagged, ...warnings])
857
+ issue.ref ??= refOfFile(root, issue.file, cfg);
858
+ }
859
+ const byRule = {};
860
+ const assetsByRule = new Map();
861
+ for (const issue of flagged) {
862
+ const assets = (assetsByRule.get(issue.issue) ?? new Set()).add(issue.file);
863
+ assetsByRule.set(issue.issue, assets);
864
+ byRule[issue.issue] = { findings: (byRule[issue.issue]?.findings ?? 0) + 1, assets: assets.size };
865
+ }
838
866
  return {
839
867
  ok: true,
840
868
  fixed,
841
869
  flagged,
842
870
  warnings,
843
871
  summary: { fixed: fixed.length, flagged: flagged.length, warnings: warnings.length },
872
+ byRule,
873
+ ...(rule === undefined ? {} : { rule }),
844
874
  };
845
875
  }
846
876
  /**
@@ -855,6 +885,9 @@ async function lintFile(file, options, cfg) {
855
885
  * `commands/improve/preparation.ts`) or is a test that can `await` it.
856
886
  */
857
887
  export async function akmLint(options = {}) {
888
+ if (options.rule !== undefined && (options.fix || options.pruneDanglingEdges)) {
889
+ throw new UsageError("lint: --rule lists findings; run it without --fix or --prune-dangling-edges.", "INVALID_FLAG_VALUE");
890
+ }
858
891
  // Fail closed on a mistyped invocation (§24.2 "Lint" release gate): a
859
892
  // nonexistent --dir used to walk nothing and report a clean
860
893
  // `ok:true, flagged:0`, silently passing scripted --fail-on-flagged gates.
@@ -873,8 +906,11 @@ export async function akmLint(options = {}) {
873
906
  const configuredAdapter = sources.find((source) => samePath(source.path, stashRoot))?.adapterId;
874
907
  const adapterId = configuredAdapter ?? detectAdapterId(stashRoot);
875
908
  const extraStashRoots = sources.map((s) => s.path).filter((p) => p !== stashRoot && fs.existsSync(p));
876
- if (adapterId !== "akm")
877
- return lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cfg, options);
909
+ if (adapterId !== "akm") {
910
+ const found = await lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cfg, options);
911
+ found.flagged.push(...trackedSecretIssues(stashRoot));
912
+ return finishLint(found, cfg, options, stashRoot);
913
+ }
878
914
  // Same fail-closed rule for --type on the akm sweep: an unknown value used
879
915
  // to filter the walk to ZERO directories — a false-clean result on the
880
916
  // classic singular/plural typo ("workflow" for "workflows"). Non-akm
@@ -884,5 +920,7 @@ export async function akmLint(options = {}) {
884
920
  `valid types: ${STASH_SUBDIRS.join(", ")}. The whole bundle was validated.`);
885
921
  options = { ...options, typeFilter: undefined };
886
922
  }
887
- return lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
923
+ const found = lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
924
+ found.flagged.push(...trackedSecretIssues(stashRoot));
925
+ return finishLint(found, cfg, options, stashRoot);
888
926
  }
@@ -0,0 +1,43 @@
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
+ * The `tracked-secrets` rule. Versioning a bundle is supported, so a tracked
6
+ * `env/` or `secrets/` file is not wrong by itself. The leak moment is a
7
+ * tracked file in a bundle that has a remote: only then can a `git push`
8
+ * send tokens or keys away. Lint flags exactly that, one finding per tracked
9
+ * file so each can be untracked or skipped (`lint.skip`) on its own.
10
+ */
11
+ import { spawnSync } from "node:child_process";
12
+ import fs from "node:fs";
13
+ import path from "node:path";
14
+ const realGit = (bundleRoot, args) => {
15
+ const result = spawnSync("git", ["-C", bundleRoot, ...args], { encoding: "utf8", timeout: 5_000 });
16
+ return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
17
+ };
18
+ /**
19
+ * One finding per `env/` or `secrets/` file the git repository at `bundleRoot`
20
+ * tracks, when the repository has a remote. Empty for a bundle without its own
21
+ * `.git` (unless a `git` seam is given), without a remote, or with nothing tracked.
22
+ */
23
+ export function trackedSecretIssues(bundleRoot, git = realGit) {
24
+ if (git === realGit && !fs.existsSync(path.join(bundleRoot, ".git")))
25
+ return [];
26
+ if (!git(bundleRoot, ["rev-parse", "--is-inside-work-tree"]).ok)
27
+ return [];
28
+ const tracked = git(bundleRoot, ["ls-files", "--", "env", "secrets"]);
29
+ if (!tracked.ok || tracked.stdout.length === 0)
30
+ return [];
31
+ const remotes = git(bundleRoot, ["remote"]);
32
+ if (!remotes.ok || remotes.stdout.length === 0)
33
+ return [];
34
+ return tracked.stdout
35
+ .split("\n")
36
+ .filter(Boolean)
37
+ .map((file) => ({
38
+ file,
39
+ issue: "tracked-secrets",
40
+ detail: "tracked by git in a bundle with a remote, so a push can leak it",
41
+ fixed: false,
42
+ }));
43
+ }
@@ -1,6 +1,64 @@
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
+ /** Every rule `akm lint` reports; a rule name in `lint.skip` or `--rule` is one of these. */
5
+ export const LINT_RULES = [
6
+ "unquoted-colon",
7
+ "missing-updated",
8
+ "orphaned-stub",
9
+ "placeholder-stub",
10
+ "missing-name-or-type",
11
+ "missing-type",
12
+ "stale-path",
13
+ "missing-skill-md",
14
+ "invalid-task-yaml",
15
+ "missing-ref",
16
+ "redacted-content",
17
+ "dangerous-env-key",
18
+ "tracked-secrets",
19
+ "invalid-workflow-structure",
20
+ "missing-category",
21
+ /**
22
+ * A file the sweep reached but could not finish checking — the per-file
23
+ * dispatch threw (unreadable mid-run, a `--fix` write that failed in a way
24
+ * the fixer could not absorb). Reported in-band so a partial sweep is
25
+ * VISIBLE: before this code existed the throw escaped `akmLint()` entirely
26
+ * and the caller learned neither which file failed nor which fixes had
27
+ * already landed on disk (issue #761).
28
+ */
29
+ "lint-failed",
30
+ // ── non-akm adapter `validate()` codes (akm 0.9.0 lint/adapter-dispatch wiring) ──
31
+ //
32
+ // These four are `llm-wiki`'s native structural checks
33
+ // (`core/adapter/adapters/llm-wiki-adapter.ts`), reachable now that `akm lint`
34
+ // dispatches every non-akm bundle through its OWN adapter's `validate()`
35
+ // instead of the akm-shaped per-file sweep. `missing-type` / `missing-ref`
36
+ // above are shared with `okf` (already closed members of this union).
37
+ "uncited-raw",
38
+ "missing-description",
39
+ "broken-xref",
40
+ "broken-source",
41
+ /**
42
+ * Non-fatal workflow compile ADVISORY (`compileWorkflowPlan().warnings` —
43
+ * e.g. a step with no `output:` schema, or a `params.<name>` reference to an
44
+ * undeclared param). Routed into `AkmLintResult.warnings`, never `flagged`,
45
+ * so `--fail-on-flagged` ignores it (see
46
+ * `core/adapter/adapters/akm-lint.ts#workflowFrontendDiagnostics`).
47
+ */
48
+ "workflow-warning",
49
+ /**
50
+ * Fallback for a `Diagnostic.issue` code this union does not (yet) name.
51
+ * `Diagnostic.issue` (`core/adapter/types.ts`) is deliberately an OPEN
52
+ * `string` — any current or future `BundleAdapter.validate()` may emit a
53
+ * code this closed lint-command union has never heard of. Rather than
54
+ * silently dropping that finding (or throwing at the CLI boundary), the
55
+ * lint→adapter mapping (`commands/lint/index.ts#diagnosticToLintIssue`)
56
+ * folds an unrecognized code onto this member and preserves the ORIGINAL
57
+ * code in `detail` (prefixed `[<issue>] `) so nothing an adapter reports is
58
+ * ever lost, even though the closed union can't type it precisely.
59
+ */
60
+ "adapter-diagnostic",
61
+ ];
4
62
  /**
5
63
  * The issue codes that are ADVISORY: surfaced in lint output but never routed
6
64
  * into `flagged`, so `--fail-on-flagged` cannot fail a run over one.
@@ -22,6 +22,7 @@ import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-seri
22
22
  import { carryForwardBookkeepingFrontmatter, parseFrontmatter, replaceFrontmatterBlocks, } from "../../core/asset/frontmatter.js";
23
23
  import { MEMORY_ARCHIVE_REL } from "../../core/asset/memory-archive.js";
24
24
  import { parsePlacementRef } from "../../core/asset/resolve-ref.js";
25
+ import { stalePathRoots } from "../../core/asset/stale-path.js";
25
26
  import { loadConfig } from "../../core/config/config.js";
26
27
  import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
27
28
  import { appendEvent } from "../../core/events.js";
@@ -987,6 +988,7 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
987
988
  let data;
988
989
  let body;
989
990
  let frontmatter;
991
+ let bodyStartLine = 1;
990
992
  if (refType === "task") {
991
993
  try {
992
994
  const parsed = parseYaml(raw);
@@ -999,7 +1001,7 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
999
1001
  frontmatter = null;
1000
1002
  }
1001
1003
  else {
1002
- ({ data, content: body, frontmatter } = parseFrontmatter(raw));
1004
+ ({ data, content: body, frontmatter, bodyStartLine } = parseFrontmatter(raw));
1003
1005
  }
1004
1006
  const resolvedRoot = path.resolve(targetRoot);
1005
1007
  return runBaseChecks({
@@ -1009,8 +1011,10 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
1009
1011
  data,
1010
1012
  body,
1011
1013
  frontmatter,
1014
+ bodyStartLine,
1012
1015
  fix: false,
1013
1016
  stashRoot: targetRoot,
1017
+ stalePathRoots: stalePathRoots(config, targetRoot),
1014
1018
  extraStashRoots: resolveSourceEntries(targetRoot, config)
1015
1019
  .map((source) => source.path)
1016
1020
  .filter((sourcePath) => path.resolve(sourcePath) !== resolvedRoot),
@@ -90,7 +90,7 @@ export function scaffoldScratch(stashDir) {
90
90
  // Non-fatal — the bundle is usable without the scratch scaffold.
91
91
  }
92
92
  }
93
- /** Add the root-scoped scratch ignore rule unless present. Independent of the secret-ignore block and its opt-out. */
93
+ /** Add the root-scoped scratch ignore rule unless present. */
94
94
  export function ensureScratchGitignore(stashDir) {
95
95
  try {
96
96
  const gitignorePath = path.join(stashDir, ".gitignore");
@@ -106,38 +106,19 @@ export function ensureScratchGitignore(stashDir) {
106
106
  }
107
107
  }
108
108
  const SCRATCH_GITIGNORE_RULE = `/${SCRATCH_DIR}/`;
109
- /** Marks the akm-authored block in a stash `.gitignore` (idempotency anchor). */
110
- const STASH_GITIGNORE_MARKER = "# akm: keep secret material out of git by default";
111
- /** Documented opt-out for private bundles that deliberately version env/ and secrets/. */
112
- export const STASH_GITIGNORE_TRACK_SECRETS_MARKER = "# akm: intentionally track env and secrets";
113
- const STASH_GITIGNORE_BLOCK = [
114
- STASH_GITIGNORE_MARKER,
115
- "# env/ and secrets/ assets hold tokens and keys. They are ignored by default",
116
- "# so `git push` can never leak them. To version a specific one (e.g. for a",
117
- "# private-remote backup), un-ignore its path below once you accept the risk.",
118
- "env/",
119
- "secrets/",
120
- "",
121
- ].join("\n");
122
109
  /**
123
- * Ensure the stash `.gitignore` keeps `env/` and `secrets/` out of git by
124
- * default (08-F1: the v0.8.0 `vaults/` → `env/`+`secrets/` migration never
125
- * carried the ignore rules forward, and init scaffolded none).
126
- *
127
- * Idempotent + non-clobbering: creates the file when absent, appends the akm
128
- * block when the file exists but lacks it (preserving the user's own rules),
129
- * and no-ops once the marker is present. A private bundle that deliberately
130
- * versions all secret material can add `# akm: intentionally track env and
131
- * secrets`; that explicit marker suppresses this helper entirely (#981).
110
+ * Add `env/` and `secrets/` to the bundle `.gitignore` when it mentions neither, so a
111
+ * new bundle does not commit its tokens and keys. A `.gitignore` that already names
112
+ * either one is the owner's choice and is left as written.
132
113
  */
133
114
  export function ensureStashGitignore(stashDir) {
134
115
  try {
135
116
  const gitignorePath = path.join(stashDir, ".gitignore");
136
117
  const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
137
- if (existing.includes(STASH_GITIGNORE_MARKER) || existing.includes(STASH_GITIGNORE_TRACK_SECRETS_MARKER))
118
+ if (existing.includes("env/") || existing.includes("secrets/"))
138
119
  return;
139
- const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
140
- fs.writeFileSync(gitignorePath, `${existing}${gap}${STASH_GITIGNORE_BLOCK}`);
120
+ const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "" : "\n";
121
+ fs.writeFileSync(gitignorePath, `${existing}${gap}env/\nsecrets/\n`);
141
122
  }
142
123
  catch {
143
124
  // Non-fatal — the stash is usable without the ignore scaffold.
@@ -424,11 +424,11 @@ async function validate(c, changes, ctx) {
424
424
  // checks need only a frontmatter-free placeholder here.
425
425
  let parsed;
426
426
  if (type === "task") {
427
- parsed = { data: {}, content: raw, frontmatter: null };
427
+ parsed = { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 };
428
428
  }
429
429
  else {
430
430
  const p = parseFrontmatter(raw);
431
- parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
431
+ parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter, bodyStartLine: p.bodyStartLine };
432
432
  }
433
433
  diagnostics.push(...(await runBaseValidateChecks(change.path, parsed, c.root, ctx)));
434
434
  diagnostics.push(...(await perTypeValidateChecks({
@@ -94,7 +94,12 @@ async function validate(c, changes, ctx) {
94
94
  if (!isWorkflowFile(raw))
95
95
  continue;
96
96
  const p = parseFrontmatter(raw);
97
- const parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
97
+ const parsed = {
98
+ data: p.data,
99
+ content: p.content,
100
+ frontmatter: p.frontmatter,
101
+ bodyStartLine: p.bodyStartLine,
102
+ };
98
103
  diagnostics.push(...(await runBaseValidateChecks(relPath, parsed, c.root, ctx)));
99
104
  diagnostics.push(...(await perTypeValidateChecks({
100
105
  type: "workflow",
@@ -51,8 +51,10 @@ import { createHash } from "node:crypto";
51
51
  import { BUNDLE_REF_RE } from "../../asset/asset-ref.js";
52
52
  import { parseFrontmatter } from "../../asset/frontmatter.js";
53
53
  import { checkUnquotedDescriptionColon } from "../../asset/frontmatter-lint.js";
54
- import { findCurrentPathReferences, homeRootOf } from "../../asset/lint-text.js";
54
+ import { isSkillPath } from "../../asset/lint-text.js";
55
+ import { findStalePaths, stalePathRoots } from "../../asset/stale-path.js";
55
56
  import { toPosix } from "../../common.js";
57
+ import { loadConfig } from "../../config/config.js";
56
58
  // ── Small pure helpers, reused across the concrete adapters ──────────────────
57
59
  /** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
58
60
  export function hashContent(content) {
@@ -75,8 +77,8 @@ export function readTags(value) {
75
77
  /** Reserved files (case-insensitive) every concrete adapter recognizes but never indexes as a concept. */
76
78
  export const RESERVED_FILES = new Set(["index.md", "log.md"]);
77
79
  // ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
78
- function checkMissingUpdated(data, frontmatterText) {
79
- return frontmatterText !== null && !("updated" in data);
80
+ function checkMissingUpdated(relPath, data, frontmatterText) {
81
+ return frontmatterText !== null && !("updated" in data) && !isSkillPath(relPath);
80
82
  }
81
83
  /** See file header: same intent as `markdown-insertion.ts#findFenceRegions`, not byte-identical. */
82
84
  function stripFencedBlocksSimple(body) {
@@ -179,12 +181,12 @@ function readRefStringOrArray(value) {
179
181
  */
180
182
  export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
181
183
  const diagnostics = [];
182
- const { data, content: body, frontmatter } = parsed;
184
+ const { data, content: body, frontmatter, bodyStartLine } = parsed;
183
185
  const unquotedColonDetail = checkUnquotedDescriptionColon(frontmatter);
184
186
  if (unquotedColonDetail) {
185
187
  diagnostics.push({ file: relPath, issue: "unquoted-colon", detail: unquotedColonDetail, fixed: false });
186
188
  }
187
- if (checkMissingUpdated(data, frontmatter)) {
189
+ if (checkMissingUpdated(relPath, data, frontmatter)) {
188
190
  diagnostics.push({
189
191
  file: relPath,
190
192
  issue: "missing-updated",
@@ -192,27 +194,13 @@ export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx)
192
194
  fixed: false,
193
195
  });
194
196
  }
195
- const staleCandidates = [
196
- ...findCurrentPathReferences(body),
197
- ...(frontmatter ? findCurrentPathReferences(frontmatter) : []),
197
+ const roots = stalePathRoots(loadConfig(), componentRoot);
198
+ const stale = [
199
+ ...(frontmatter ? findStalePaths(frontmatter, 2, roots, componentRoot) : []),
200
+ ...findStalePaths(body, bodyStartLine, roots, componentRoot),
198
201
  ];
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
203
- const found = await ctx.readFile(candidate);
204
- if (found !== null)
205
- continue;
206
- const portableHint = candidate.startsWith(componentRoot)
207
- ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(componentRoot.length)})`
208
- : "";
209
- diagnostics.push({
210
- file: relPath,
211
- issue: "stale-path",
212
- detail: `nonexistent path: ${candidate}${portableHint}`,
213
- fixed: false,
214
- });
215
- }
202
+ for (const finding of stale)
203
+ diagnostics.push({ file: relPath, issue: "stale-path", fixed: false, ...finding });
216
204
  for (const ref of extractProseRefTokens(body)) {
217
205
  const { exists } = await ctx.resolveRef(ref);
218
206
  if (!exists)
@@ -10,10 +10,10 @@
10
10
  /**
11
11
  * A path segment shaped like a run-time filename template rather than a
12
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.
13
+ * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, a glob
14
+ * character, or an elided `...` segment. Such a path never exists under its literal spelling.
15
15
  */
16
- const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
16
+ const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}|\.\.\./;
17
17
  /** A line that presents a path as a record of the past or as an illustration, not as guidance to follow. */
18
18
  const NON_CURRENT_LINE_PATTERN = /\b(?:historical(?:ly)?|previously|formerly|for example|for instance)\b|\be\.g\./i;
19
19
  /** A heading whose section holds records or illustrations rather than current guidance. */
@@ -22,29 +22,30 @@ const NON_CURRENT_HEADING_PATTERN = /^#{1,6}\s.*\b(?:history|changelog|archive|e
22
22
  function stripTrailingSentencePunctuation(token) {
23
23
  return token.replace(/[.;:!?]+$/, "");
24
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];
25
+ /** True for a file under a bundle's `skills/` directory: a skill carries no `updated` field. */
26
+ export function isSkillPath(relPath) {
27
+ return relPath.split(/[\\/]/)[0] === "skills";
28
28
  }
29
29
  /**
30
30
  * Absolute paths in `text` presented as current guidance. Paths on lines or in
31
31
  * sections that frame them as history or examples, run-time filename
32
32
  * templates, and trailing sentence punctuation are all excluded.
33
33
  */
34
- export function findCurrentPathReferences(text) {
35
- const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
34
+ export function findCurrentPathReferences(text, firstLine = 1) {
35
+ const pathRe = /(?<=^|[\s"'`([=])\/[^\s"'`)\]>,:\[\n]+/g;
36
36
  const out = [];
37
37
  let inNonCurrentSection = false;
38
- for (const line of text.split(/\r?\n/)) {
38
+ text.split(/\r?\n/).forEach((line, index) => {
39
39
  if (/^#{1,6}\s/.test(line))
40
40
  inNonCurrentSection = NON_CURRENT_HEADING_PATTERN.test(line);
41
41
  if (inNonCurrentSection || NON_CURRENT_LINE_PATTERN.test(line))
42
- continue;
42
+ return;
43
43
  for (const match of line.matchAll(pathRe)) {
44
44
  const candidate = stripTrailingSentencePunctuation(match[0]);
45
- if (!PATH_PLACEHOLDER_PATTERN.test(candidate))
46
- out.push(candidate);
45
+ if (candidate.length > 1 && !PATH_PLACEHOLDER_PATTERN.test(candidate)) {
46
+ out.push({ path: candidate, line: firstLine + index, lineText: line.trim() });
47
+ }
47
48
  }
48
- }
49
+ });
49
50
  return out;
50
51
  }