akm-cli 0.10.261129 → 0.10.261130-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/STABILITY.md +11 -0
  3. package/dist/assets/hints/cli-hints-full.md +1 -1
  4. package/dist/assets/hints/cli-hints-short.md +1 -0
  5. package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
  6. package/dist/cli/usage-report.js +184 -0
  7. package/dist/cli/usage.js +24 -7
  8. package/dist/cli.js +8 -2
  9. package/dist/commands/completions.js +5 -4
  10. package/dist/commands/health/checks.js +18 -4
  11. package/dist/commands/health/connections-and-harnesses-check.js +1 -0
  12. package/dist/commands/health/egress.js +1 -2
  13. package/dist/commands/health/plugin-staleness.js +75 -159
  14. package/dist/commands/health/scheduler-binary.js +7 -2
  15. package/dist/commands/health/semantic-search-check.js +7 -6
  16. package/dist/commands/health/version-drift.js +2 -0
  17. package/dist/commands/improve/extract.js +2 -2
  18. package/dist/commands/improve/preparation.js +6 -1
  19. package/dist/commands/lint/base-linter.js +90 -48
  20. package/dist/commands/lint/index.js +128 -185
  21. package/dist/commands/lint/moved-refs.js +69 -0
  22. package/dist/commands/lint/scope.js +41 -0
  23. package/dist/commands/metrics/collect.js +25 -2
  24. package/dist/commands/metrics/report-view.js +11 -2
  25. package/dist/commands/proposal/proposal.js +7 -2
  26. package/dist/commands/proposal/repository.js +16 -11
  27. package/dist/commands/read/rules.js +142 -0
  28. package/dist/commands/read/search-cli.js +5 -5
  29. package/dist/commands/read/search.js +1 -1
  30. package/dist/commands/sources/plugin-upgrade.js +139 -71
  31. package/dist/commands/sources/source-clone.js +4 -4
  32. package/dist/commands/sources/sources-cli.js +3 -20
  33. package/dist/commands/sources/sync.js +24 -0
  34. package/dist/commands/tasks/tasks.js +1 -1
  35. package/dist/core/adapter/adapters/akm-adapter.js +32 -23
  36. package/dist/core/adapter/adapters/akm-lint.js +55 -61
  37. package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
  38. package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
  39. package/dist/core/adapter/adapters/okf-adapter.js +5 -9
  40. package/dist/core/adapter/adapters/shared.js +52 -200
  41. package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
  42. package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
  43. package/dist/core/adapter/validate-context.js +7 -11
  44. package/dist/core/asset/asset-placement.js +29 -0
  45. package/dist/core/asset/frontmatter-edit.js +124 -0
  46. package/dist/core/asset/lint-text.js +18 -2
  47. package/dist/core/asset/llm-wiki-root.js +30 -0
  48. package/dist/core/asset/ref-rewrite.js +39 -0
  49. package/dist/core/asset/type-keys.js +59 -0
  50. package/dist/core/config/schema/local-state.js +5 -1
  51. package/dist/core/config/schema/output.js +4 -4
  52. package/dist/core/config/schema/search.js +4 -0
  53. package/dist/core/write-source.js +75 -25
  54. package/dist/indexer/index-written-assets.js +16 -8
  55. package/dist/indexer/indexer.js +68 -19
  56. package/dist/indexer/legacy-refs.js +1 -26
  57. package/dist/indexer/links/declared-links.js +13 -11
  58. package/dist/indexer/ref-moves.js +75 -0
  59. package/dist/indexer/search/db-search.js +3 -2
  60. package/dist/indexer/walk/place-rules.js +25 -0
  61. package/dist/indexer/walk/walker.js +5 -1
  62. package/dist/integrations/session-logs/pre-filter.js +1 -0
  63. package/dist/output/context.js +6 -2
  64. package/dist/output/shapes/passthrough.js +1 -0
  65. package/dist/output/text/rules.js +14 -0
  66. package/dist/output/text.js +2 -0
  67. package/dist/scripts/akm-migrate-node.js +4651 -3584
  68. package/dist/scripts/akm-migrate.js +4650 -3584
  69. package/dist/setup/registry-stash-loader.js +4 -2
  70. package/dist/sources/providers/git-stash.js +13 -5
  71. package/dist/storage/repositories/index-entries-repository.js +8 -3
  72. package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
  73. package/dist/workspace/activity.js +69 -8
  74. package/dist/workspace/asset-improve.js +9 -5
  75. package/dist/workspace/assets.js +33 -19
  76. package/dist/workspace/bundle-files.js +39 -2
  77. package/dist/workspace/bundles.js +53 -3
  78. package/dist/workspace/check-text.js +121 -0
  79. package/dist/workspace/config.js +3 -0
  80. package/dist/workspace/copy-entry.js +129 -0
  81. package/dist/workspace/derive.js +13 -4
  82. package/dist/workspace/documents.js +11 -16
  83. package/dist/workspace/file-actions.js +130 -0
  84. package/dist/workspace/frontmatter.js +41 -0
  85. package/dist/workspace/git-read.js +42 -27
  86. package/dist/workspace/graph.js +11 -2
  87. package/dist/workspace/impact.js +14 -5
  88. package/dist/workspace/metrics.js +1 -1
  89. package/dist/workspace/misses.js +8 -3
  90. package/dist/workspace/moved-links.js +57 -0
  91. package/dist/workspace/new-file.js +141 -0
  92. package/dist/workspace/proposals.js +12 -38
  93. package/dist/workspace/pulse.js +16 -9
  94. package/dist/workspace/readers.js +14 -0
  95. package/dist/workspace/sensitive.js +12 -6
  96. package/dist/workspace/setup.js +2 -1
  97. package/dist/workspace/stats.js +4 -0
  98. package/dist/workspace.d.ts +100 -1
  99. package/docs/architecture/adapters.md +15 -0
  100. package/docs/architecture/internals/health-advisories.md +13 -8
  101. package/docs/architecture/internals/indexing.md +1 -0
  102. package/docs/architecture/internals/storage-locations.md +3 -3
  103. package/docs/architecture/persisted-data-compat.md +2 -0
  104. package/docs/architecture/specs/ref.md +27 -13
  105. package/docs/guides/author-bundles.md +13 -12
  106. package/docs/integration/bundling-akm.md +3 -0
  107. package/docs/maintainers/implementation-details.md +1 -1
  108. package/docs/reference/api.md +3 -3
  109. package/docs/reference/cli.md +143 -35
  110. package/docs/reference/configuration.md +2 -1
  111. package/docs/reference/data-and-telemetry.md +49 -10
  112. package/docs/reference/workspace.md +122 -36
  113. package/package.json +1 -1
  114. package/schemas/akm-config.json +6 -0
@@ -15,7 +15,7 @@
15
15
  * cache remain full-index responsibilities.
16
16
  */
17
17
  import fs from "node:fs";
18
- import { akmAdapter } from "../core/adapter/adapters/akm-adapter.js";
18
+ import { adapterForId } from "../core/adapter/registry.js";
19
19
  import { loadConfig } from "../core/config/config.js";
20
20
  import { isDataDirUnreadableError, TransientError } from "../core/errors.js";
21
21
  import { isPathAbsent } from "../core/path-access.js";
@@ -29,6 +29,7 @@ import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
29
29
  import { embeddingInputCap, generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
30
30
  import { withFileSize } from "./passes/metadata.js";
31
31
  import { drainDirDocuments } from "./scan/drain-dir.js";
32
+ import { resolveSourceEntries } from "./search/search-source.js";
32
33
  import { buildFileContext } from "./walk/file-context.js";
33
34
  import { walkedFiles } from "./walk/walker.js";
34
35
  /**
@@ -75,8 +76,17 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
75
76
  // short. One drain call per file keeps the entry↔path pairing exact and
76
77
  // reuses the full-index recognize engine (F4a M-core-2 item 5): broken
77
78
  // workflows drop, valid workflow docs are cached for the side-table upsert.
79
+ // The bundle's own adapter recognizes what was written: a named bundle's configured one, the akm adapter otherwise.
80
+ const adapterId = options.bundleId
81
+ ? resolveSourceEntries(undefined, loadConfig()).find((entry) => entry.registryId === options.bundleId)?.adapterId
82
+ : undefined;
78
83
  const component = deriveInstallations([
79
- { path: stashDir, writable: true, ...(options.bundleId ? { registryId: options.bundleId } : {}) },
84
+ {
85
+ path: stashDir,
86
+ writable: true,
87
+ ...(options.bundleId ? { registryId: options.bundleId } : {}),
88
+ ...(adapterId ? { adapterId } : {}),
89
+ },
80
90
  ])[0]?.components[0];
81
91
  if (!component)
82
92
  throw new Error(`Could not derive bundle provenance for ${stashDir}`);
@@ -98,12 +108,10 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
98
108
  }
99
109
  }
100
110
  const ctx = buildFileContext(stashDir, file);
101
- // Hardcoded `akmAdapter` on purpose (owner ruling 2026-07-21): this
102
- // write-path fast path only ever runs for assets a first-class akm
103
- // mutation command just wrote into a managed akm source, so the akm
104
- // adapter is always the right recognizer here — no per-component
105
- // dispatch needed.
106
- const drained = drainDirDocuments(akmAdapter, component, [ctx]);
111
+ const adapter = adapterForId(component.adapter);
112
+ if (!adapter)
113
+ throw new Error(`Unknown adapter "${component.adapter}" for ${stashDir}`);
114
+ const drained = drainDirDocuments(adapter, component, [ctx]);
107
115
  for (const rejectedPath of drained.rejectedPaths)
108
116
  unindexable.add(rejectedPath);
109
117
  for (const conceptId of drained.rejectedConceptIds)
@@ -15,10 +15,10 @@ import { localEmbeddingRuntime } from "../llm/embedder.js";
15
15
  import { effectiveEmbedding } from "../llm/embedders/connection.js";
16
16
  import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
17
17
  import { closeDatabase, deleteIndexDatabase, indexDbIsDamaged, isCorruptionError, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
18
- import { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteEntriesOutsideLibrary, deleteUsageEventsForEntries, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
18
+ import { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteEntriesOutsideLibrary, deleteUsageEventsForEntries, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, getStoredEntriesInDirectory, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
19
19
  import { rebuildFtsIfTotalsStale } from "../storage/repositories/index-fts-repository.js";
20
20
  import { storeLayout } from "../storage/repositories/index-layout-repository.js";
21
- import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
21
+ import { clearStaleCacheEntries, rekeyLlmCache } from "../storage/repositories/index-llm-cache-repository.js";
22
22
  import { deleteIndexDirState, deleteMeta, getIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
23
23
  import { VACUUM_PENDING_META } from "../storage/repositories/index-schema.js";
24
24
  import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
@@ -28,11 +28,12 @@ import { INDEX_DB_VACUUMED_EVENT, readFreelistInfo, vacuumIfReclaimable } from "
28
28
  import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
29
29
  import { reclassifyIndexDbContention } from "./index-db-contention.js";
30
30
  import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
31
- import { legacyRefMove, rekeyLegacyEntry, rewriteLegacyStateRefs } from "./legacy-refs.js";
31
+ import { legacyRefMove, rekeyLegacyEntry } from "./legacy-refs.js";
32
32
  import { entryFromFiles, indexedPathMatchesOwner, resolveConceptOwner, } from "./lookup/adapter-concept-owner.js";
33
33
  import { embeddingInputCap, generateEmbeddingsForDb } from "./materialize-embeddings.js";
34
34
  import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
35
35
  import { CONTENT_PROJECTION_VERSION, isWorkflowSkipWarning, withFileSize, } from "./passes/metadata.js";
36
+ import { pairMovedFiles, rekeyStateRefs, repointEntry, } from "./ref-moves.js";
36
37
  import { drainDirDocuments } from "./scan/drain-dir.js";
37
38
  import { purgeOldUsageEvents, USAGE_EVENT_RETENTION_DAYS } from "./usage/usage-events.js";
38
39
  import { SEMANTIC_SEARCH_META_KEY, } from "./walk/index-context.js";
@@ -470,7 +471,7 @@ async function akmIndexReal(options) {
470
471
  const bundleByRoot = buildIndexedSourceOwners(sources);
471
472
  // A source that did not resolve this run keeps its last-known-good rows through a library switch.
472
473
  const unresolvedBundleIds = new Set(sources.flatMap((source) => (source.unresolved ? [bundleByRoot.get(path.resolve(source.path))?.bundleId] : [])));
473
- persistDirRecords(db, dirRecords, warnings, bundleByRoot, embeddingInputCap(config), {
474
+ const moves = persistDirRecords(db, dirRecords, warnings, bundleByRoot, embeddingInputCap(config), {
474
475
  stashDir,
475
476
  sourceDirs,
476
477
  unresolvedBundleIds,
@@ -583,6 +584,7 @@ async function akmIndexReal(options) {
583
584
  verification,
584
585
  timing,
585
586
  ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
587
+ ...(moves ? { moves } : {}),
586
588
  };
587
589
  }
588
590
  finally {
@@ -1014,6 +1016,30 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1014
1016
  const deletedEntries = new Map();
1015
1017
  const legacyMoves = [];
1016
1018
  const findPersisted = db.prepare("SELECT id, content_hash, file_path, adapter_id FROM entries WHERE item_ref = ?");
1019
+ // Files renamed or moved on disk since the last run: each vanished entry whose content is now at another path.
1020
+ let pairing = { pairs: [], unpaired: [] };
1021
+ const movedRefs = new Set();
1022
+ const pairMoves = () => {
1023
+ const stored = [];
1024
+ const fresh = [];
1025
+ for (const record of dirRecords) {
1026
+ const bundle = bundleByRoot.get(path.resolve(record.currentStashDir));
1027
+ if (record.skip || !bundle)
1028
+ continue;
1029
+ const kept = new Set();
1030
+ for (const entry of record.remove ? [] : (record.stash?.entries ?? [])) {
1031
+ const found = identifyEntry(record.dirPath, bundle, entry, record.conceptIdByFile);
1032
+ if ("problem" in found)
1033
+ continue;
1034
+ kept.add(found.provenance.itemRef);
1035
+ const contentHash = record.hashByFile?.get(found.entryPath);
1036
+ if (contentHash !== undefined && !findPersisted.get(found.provenance.itemRef))
1037
+ fresh.push({ filePath: found.entryPath, provenance: found.provenance, contentHash });
1038
+ }
1039
+ stored.push(...getStoredEntriesInDirectory(db, record.dirPath, bundle.bundleId).filter((row) => !kept.has(row.itemRef)));
1040
+ }
1041
+ return pairMovedFiles(stored, fresh);
1042
+ };
1017
1043
  const persist = () => {
1018
1044
  // Entries are about to describe another library: the old watermark is not theirs, and neither are rows outside
1019
1045
  // its directories. They go in this transaction, so the marker never names a library whose index serves another's.
@@ -1023,6 +1049,12 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1023
1049
  }
1024
1050
  setMeta(db, "stashDir", safeRealpath(library.stashDir));
1025
1051
  setMeta(db, "stashDirs", JSON.stringify(library.sourceDirs));
1052
+ pairing = pairMoves();
1053
+ for (const pair of pairing.pairs) {
1054
+ repointEntry(db, pair.id, pair.entry);
1055
+ rekeyLlmCache(db, pair.oldFilePath, pair.entry.filePath);
1056
+ movedRefs.add(pair.entry.provenance.itemRef);
1057
+ }
1026
1058
  for (const { dirPath, currentStashDir, files, fingerprint, stash, skip, reason, persistedRowCount, hashByFile, conceptIdByFile, indexVariant, remove, } of dirRecords) {
1027
1059
  const bundle = bundleByRoot.get(path.resolve(currentStashDir));
1028
1060
  if (!bundle)
@@ -1071,22 +1103,15 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1071
1103
  if (stash) {
1072
1104
  const sourceRoot = `${path.resolve(currentStashDir)}${path.sep}`;
1073
1105
  for (const entry of stash.entries) {
1074
- const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
1075
- if (!entryPath) {
1076
- warn(`Skipping entry with no resolvable path in ${dirPath}`);
1077
- continue;
1078
- }
1079
- const adapterConceptId = conceptIdByFile?.get(entryPath);
1080
- if (!adapterConceptId) {
1081
- warn(`Skipping entry without adapter-owned concept identity: ${entryPath}`);
1106
+ const found = identifyEntry(dirPath, bundle, entry, conceptIdByFile);
1107
+ if ("problem" in found) {
1108
+ warn(found.problem);
1082
1109
  continue;
1083
1110
  }
1111
+ const { entryPath, provenance } = found;
1084
1112
  // content_hash = doc.hash from the drain, keyed by the recognized
1085
1113
  // file's path. A missing hash preserves the existing value on upsert.
1086
1114
  const contentHash = hashByFile?.get(entryPath);
1087
- // Adapter-owned concept identity is path-based and cannot be replaced
1088
- // by presentation fields such as type/title.
1089
- const provenance = deriveEntryProvenance(bundle, entry.type, entry.name, adapterConceptId);
1090
1115
  // Two files of one source can claim one ref (a skill's references/a.md and
1091
1116
  // knowledge/skills/x/references/a.md are both knowledge/skills/x/references/a). The file with
1092
1117
  // the smaller path holds it, whichever directories this run drains and in whatever order the
@@ -1111,7 +1136,9 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1111
1136
  keptItemRefs.add(provenance.itemRef);
1112
1137
  persistedRows++;
1113
1138
  const previous = sameVariant ? holder : undefined;
1114
- const unchanged = previous !== undefined &&
1139
+ const moved = movedRefs.has(provenance.itemRef);
1140
+ const unchanged = !moved &&
1141
+ previous !== undefined &&
1115
1142
  contentHash !== undefined &&
1116
1143
  previous.content_hash === contentHash &&
1117
1144
  previous.file_path === entryPath &&
@@ -1124,7 +1151,7 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1124
1151
  rekeyLegacyEntry(db, legacy, provenance.conceptId, entryPath);
1125
1152
  legacyMoves.push(legacy);
1126
1153
  }
1127
- upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance, contentHash, maxInputTokens);
1154
+ upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance, contentHash, maxInputTokens, moved);
1128
1155
  }
1129
1156
  }
1130
1157
  // Prune the departed rows: everything under this dir NOT re-upserted above
@@ -1162,12 +1189,34 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputToken
1162
1189
  // this same run: only refs that no longer exist lose their events.
1163
1190
  const refStillIndexed = db.prepare("SELECT 1 FROM entries WHERE item_ref = ?");
1164
1191
  deleteUsageEventsForEntries([...deletedEntries.values()].filter((entry) => refStillIndexed.get(entry.itemRef) == null));
1192
+ const movedAssets = pairing.pairs.map((pair) => ({ from: pair.oldItemRef, to: pair.entry.provenance.itemRef }));
1165
1193
  try {
1166
- rewriteLegacyStateRefs(legacyMoves);
1194
+ rekeyStateRefs([...legacyMoves, ...movedAssets.map(({ from, to }) => ({ oldItemRef: from, newItemRef: to }))]);
1167
1195
  }
1168
1196
  catch (error) {
1169
- warn(`[index] could not carry over the history of ${legacyMoves.length} re-keyed asset(s): ${String(error)}`);
1197
+ warnings.push(`[index] could not carry over the history of ${legacyMoves.length + movedAssets.length} re-keyed asset(s): ${String(error)}`);
1198
+ }
1199
+ // Each move is recorded on the asset's new ref, which later moves re-key with the rest of its history.
1200
+ for (const { from, to } of movedAssets)
1201
+ appendEvent({ eventType: "moved", ref: to, metadata: { from } });
1202
+ if (pairing.unpaired.length > 0) {
1203
+ warnings.push(`[index] ${pairing.unpaired.length} moved file(s) not paired: other files with identical content appeared, so ` +
1204
+ `each is indexed as a new asset and its history stays with the old ref (${pairing.unpaired.map((entry) => entry.itemRef).join(", ")}).`);
1170
1205
  }
1206
+ return movedAssets.length > 0 || pairing.unpaired.length > 0
1207
+ ? { moved: movedAssets, unpaired: pairing.unpaired.length }
1208
+ : undefined;
1209
+ }
1210
+ /** The path and durable identity of a drained entry, or why it has none. */
1211
+ function identifyEntry(dirPath, bundle, entry, conceptIdByFile) {
1212
+ const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
1213
+ if (!entryPath)
1214
+ return { problem: `Skipping entry with no resolvable path in ${dirPath}` };
1215
+ const adapterConceptId = conceptIdByFile?.get(entryPath);
1216
+ if (!adapterConceptId)
1217
+ return { problem: `Skipping entry without adapter-owned concept identity: ${entryPath}` };
1218
+ // Adapter-owned concept identity is path-based and cannot be replaced by presentation fields such as type/title.
1219
+ return { entryPath, provenance: deriveEntryProvenance(bundle, entry.type, entry.name, adapterConceptId) };
1171
1220
  }
1172
1221
  // ── Helpers ─────────────────────────────────────────────────────────────────
1173
1222
  function buildIndexSummaryMessage(options) {
@@ -9,21 +9,10 @@
9
9
  * (`reports/x`). The mapping is closed-form, so each indexed entry names the old
10
10
  * ref its history is stored under, and the rows keyed by it are re-keyed in
11
11
  * place: the `entries` row (keeping its id, which keeps its usage events and
12
- * scores attached) and the ref-keyed state.db rows. Idempotent: once the rows
12
+ * scores attached) and the ref-keyed state.db rows (`rekeyStateRefs`). Idempotent: once the rows
13
13
  * carry the new ref there is nothing under the old one.
14
14
  */
15
15
  import { stashDirFor } from "../core/asset/asset-placement.js";
16
- import { withStateDb } from "../core/state-db.js";
17
- /** state.db tables that store a full `bundle//conceptId` ref, with the column that holds it. */
18
- const STATE_REF_COLUMNS = [
19
- ["usage_events", "entry_ref"],
20
- ["proposals", "ref"],
21
- ["events", "ref"],
22
- ["task_history", "target_ref"],
23
- ["improve_ledger", "ref"],
24
- ["asset_salience", "asset_ref"],
25
- ["asset_outcome", "asset_ref"],
26
- ];
27
16
  /** The ref releases before path refs gave this entry, or `undefined` when its ref never changed. */
28
17
  export function legacyRefMove(bundleId, type, conceptId) {
29
18
  const dir = stashDirFor(type);
@@ -44,17 +33,3 @@ export function rekeyLegacyEntry(db, move, conceptId, filePath) {
44
33
  db.prepare("UPDATE entries SET item_ref = ?, concept_id = ? WHERE id = ?").run(move.newItemRef, conceptId, old.id);
45
34
  return true;
46
35
  }
47
- /** Re-key the state.db rows stored under the old refs. A row already at the new ref is an orphan and gives way. */
48
- export function rewriteLegacyStateRefs(moves) {
49
- if (moves.length === 0)
50
- return;
51
- withStateDb((db) => {
52
- db.transaction(() => {
53
- for (const [table, column] of STATE_REF_COLUMNS) {
54
- const update = db.prepare(`UPDATE OR REPLACE ${table} SET ${column} = ? WHERE ${column} = ?`);
55
- for (const move of moves)
56
- update.run(move.newItemRef, move.oldItemRef);
57
- }
58
- })();
59
- });
60
- }
@@ -5,22 +5,24 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
5
5
  import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
6
6
  /** Channel order is the order links are stored and shown in. */
7
7
  const CHANNELS = [
8
- ["xref", (doc) => doc.xrefs],
9
- ["superseded_by", (doc) => doc.supersededBy],
10
- ["contradicted_by", (doc) => doc.contradictedBy],
11
- ["belief_peer", (doc) => doc.currentBeliefRefs],
12
- ["derived_from", (doc) => doc.derivedFrom],
13
- ["cites", (doc) => doc.sources],
14
- ["links_to", (doc) => doc.links],
15
- ["uses", (doc) => doc.uses],
8
+ { kind: "xref", read: (doc) => doc.xrefs, key: "xrefs" },
9
+ { kind: "superseded_by", read: (doc) => doc.supersededBy, key: "supersededBy" },
10
+ { kind: "contradicted_by", read: (doc) => doc.contradictedBy, key: "contradictedBy" },
11
+ { kind: "belief_peer", read: (doc) => doc.currentBeliefRefs, key: "currentBeliefRefs" },
12
+ { kind: "derived_from", read: (doc) => doc.derivedFrom },
13
+ { kind: "cites", read: (doc) => doc.sources, key: "sources" },
14
+ { kind: "links_to", read: (doc) => doc.links },
15
+ { kind: "uses", read: (doc) => doc.uses },
16
16
  ];
17
+ /** The frontmatter keys whose entries are refs to assets: what an asset declares, whatever folder the target is in. */
18
+ export const DECLARED_REF_FRONTMATTER_KEYS = CHANNELS.flatMap((channel) => channel.key === undefined ? [] : [channel.key]);
17
19
  /** The links an indexed document declares, in channel then authored order; one per (kind, target). */
18
20
  export function declaredLinks(doc, owner) {
19
21
  const links = [];
20
22
  const seen = new Set();
21
- for (const [kind, read] of CHANNELS) {
23
+ for (const { kind, read } of CHANNELS) {
22
24
  for (const raw of stringValues(read(doc))) {
23
- const target = linkTarget(raw, owner.conceptId);
25
+ const target = declaredLinkTarget(raw, owner.conceptId);
24
26
  if (!target)
25
27
  continue;
26
28
  const bundle = target.bundle ?? owner.bundleId;
@@ -47,7 +49,7 @@ function stringValues(value) {
47
49
  * wikis, now knowledge under `wikis/`), a `.md` suffix, and a `#fragment`.
48
50
  * Inside a wiki page, `raw/…` and `pages/…` are relative to the wiki root.
49
51
  */
50
- function linkTarget(raw, ownerConceptId) {
52
+ export function declaredLinkTarget(raw, ownerConceptId) {
51
53
  const token = raw.trim();
52
54
  if (!token || /[\s<*]/.test(token) || token.includes("$(") || token.includes("${"))
53
55
  return;
@@ -0,0 +1,75 @@
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
+ * An asset that changed ref and kept its identity: its history is re-keyed to the new ref.
6
+ *
7
+ * Two things move an asset's ref without making it a new asset: a file that was renamed or moved on disk
8
+ * (`pairMovedFiles`, which pairs the vanished entry with the new file of the same content), and the one-time carry-over
9
+ * of refs that gained a different spelling (`legacy-refs.ts`). Both end in the same re-key of the rows
10
+ * state.db keeps by ref, which is {@link rekeyStateRefs}.
11
+ */
12
+ import fs from "node:fs";
13
+ import path from "node:path";
14
+ import { groupBy } from "../core/common.js";
15
+ import { withStateDb } from "../core/state-db.js";
16
+ /** state.db tables that store a full `bundle//conceptId` ref, with the column that holds it. */
17
+ const STATE_REF_COLUMNS = [
18
+ ["usage_events", "entry_ref"],
19
+ ["proposals", "ref"],
20
+ ["events", "ref"],
21
+ ["task_history", "target_ref"],
22
+ ["improve_ledger", "ref"],
23
+ ["asset_salience", "asset_ref"],
24
+ ["asset_outcome", "asset_ref"],
25
+ ["workflow_runs", "workflow_ref"],
26
+ ];
27
+ /** Re-key the state.db rows stored under the old refs. A row already at the new ref is an orphan and gives way. */
28
+ export function rekeyStateRefs(moves) {
29
+ if (moves.length === 0)
30
+ return;
31
+ withStateDb((db) => {
32
+ db.transaction(() => {
33
+ for (const [table, column] of STATE_REF_COLUMNS) {
34
+ const update = db.prepare(`UPDATE OR REPLACE ${table} SET ${column} = ? WHERE ${column} = ?`);
35
+ for (const move of moves)
36
+ update.run(move.newItemRef, move.oldItemRef);
37
+ }
38
+ })();
39
+ });
40
+ }
41
+ const sameName = (entries, filePath) => entries.filter((entry) => path.basename(entry.filePath) === path.basename(filePath));
42
+ /**
43
+ * Pair each stored entry whose file is gone with the new file of the same content. A hash held by one vanished and one
44
+ * new file pairs them; a hash held by several pairs the ones whose file names match one to one, and anything still
45
+ * ambiguous is left unpaired (indexed as new). An entry whose file still exists is not a move.
46
+ */
47
+ export function pairMovedFiles(stored, fresh) {
48
+ const vanished = stored.filter((entry) => entry.contentHash !== null && !fs.existsSync(entry.filePath));
49
+ const freshByHash = groupBy([...fresh], (entry) => entry.contentHash);
50
+ const pairs = [];
51
+ const unpaired = [];
52
+ for (const [hash, candidates] of groupBy(vanished, (entry) => entry.contentHash)) {
53
+ const targets = freshByHash.get(hash);
54
+ if (!targets)
55
+ continue;
56
+ for (const from of candidates) {
57
+ const named = sameName(targets, from.filePath);
58
+ const matched = candidates.length === 1 && targets.length === 1
59
+ ? targets[0]
60
+ : named.length === 1 && sameName(candidates, from.filePath).length === 1
61
+ ? named[0]
62
+ : undefined;
63
+ if (matched)
64
+ pairs.push({ id: from.id, oldItemRef: from.itemRef, oldFilePath: from.filePath, entry: matched });
65
+ else
66
+ unpaired.push(from);
67
+ }
68
+ }
69
+ return { pairs, unpaired };
70
+ }
71
+ /** An entry row moved to its new file in place: its id keeps its vector, links and scores. */
72
+ export function repointEntry(db, id, entry) {
73
+ const { provenance } = entry;
74
+ db.prepare("UPDATE entries SET item_ref = ?, bundle_id = ?, component_id = ?, concept_id = ?, adapter_id = ?, file_path = ? WHERE id = ?").run(provenance.itemRef, provenance.bundleId, provenance.componentId, provenance.conceptId, provenance.adapterId, entry.filePath, id);
75
+ }
@@ -13,6 +13,7 @@
13
13
  import path from "node:path";
14
14
  import { displayRef } from "../../core/asset/resolve-ref.js";
15
15
  import { compareCodePoints } from "../../core/common.js";
16
+ import { defaultExcludedTypes } from "../../core/config/schema/search.js";
16
17
  import { withStateDbTelemetry } from "../../core/state-db.js";
17
18
  import { systemErrorCode } from "../../core/system-error.js";
18
19
  import { isoDay } from "../../core/time.js";
@@ -157,7 +158,7 @@ async function searchDatabase(db, input) {
157
158
  // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
158
159
  // ['session'] is applied; an explicit empty list disables exclusion.
159
160
  const defaultExcludes = searchType === "any" && !input.includeExcludedTypes
160
- ? (config.search?.defaultExcludeTypes ?? ["session"]).filter((type) => !input.includeTypes?.includes(type))
161
+ ? defaultExcludedTypes(config).filter((type) => !input.includeTypes?.includes(type))
161
162
  : [];
162
163
  // D4 — conceptId-prefix queries (`memories/projecta/`, `bundle//`,
163
164
  // `bundle//skills/`) translate to a deterministic enumeration narrowed by
@@ -441,7 +442,7 @@ function rankByUsage(items, project) {
441
442
  .sort((a, b) => (shown.get(b.itemRef) ?? 0) - (shown.get(a.itemRef) ?? 0) || a.itemRef.localeCompare(b.itemRef));
442
443
  }
443
444
  /** Whether an asset applies under the project: it names it or no project, unless the selection's filter decided. */
444
- function appliesUnder(entry, project) {
445
+ export function appliesUnder(entry, project) {
445
446
  return project.byFilter === true || appliesToProject(entry, project.name);
446
447
  }
447
448
  /** The day an entry is dated by: when it was observed, else when it was last updated. */
@@ -0,0 +1,25 @@
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
+ * What akm says about a place in a bundle by its path alone: whether it holds env or secret files (the directory rules that
6
+ * type a file `env` or `secret`) and whether it is a folder akm and Git manage. Nothing is read.
7
+ */
8
+ import path from "node:path";
9
+ import { buildFileContext } from "./file-context.js";
10
+ import { declaredTypeForPath } from "./matchers.js";
11
+ import { MANAGED_DIRS } from "./walker.js";
12
+ /** akm's own directory rules on a bundle-relative path: `env` or `secret` when any env/ or secrets/ ancestor makes it a protected file. */
13
+ export function protectedTypeOf(relative) {
14
+ const type = declaredTypeForPath(buildFileContext("/", path.posix.join("/", relative)));
15
+ return type === "env" || type === "secret" ? type : undefined;
16
+ }
17
+ /** Whether a file made in `folder` would be an env or secret file: the folder is, or is inside, a protected place. */
18
+ export function isProtectedPlace(folder) {
19
+ return (protectedTypeOf(path.posix.join(folder, "probe.env")) !== undefined ||
20
+ protectedTypeOf(path.posix.join(folder, "probe")) !== undefined);
21
+ }
22
+ /** The managed folder (`.git`, `.akm`) a bundle-relative path is in, if any. */
23
+ export function managedFolderOf(relative) {
24
+ return relative.split("/").find((segment) => MANAGED_DIRS.includes(segment));
25
+ }
@@ -15,7 +15,11 @@ import { isRelevantAssetFile } from "../../core/asset/asset-placement.js";
15
15
  import { isScratchPath } from "../../core/asset/scratch.js";
16
16
  import { spawnSync } from "../../runtime.js";
17
17
  import { buildFileContext } from "./file-context.js";
18
- const ALWAYS_SKIP_DIRS = new Set([".git", "node_modules"]);
18
+ /** Directories akm and Git manage inside a bundle: never content, whatever a person or an adapter lists. */
19
+ export const GIT_DIR = ".git";
20
+ export const AKM_DIR = ".akm";
21
+ export const MANAGED_DIRS = [GIT_DIR, AKM_DIR];
22
+ const ALWAYS_SKIP_DIRS = new Set([GIT_DIR, "node_modules"]);
19
23
  const AKM_SKIP_DIRS = new Set(["bin", ".cache"]);
20
24
  /** Sidecar and git dot-files the walk never lists. */
21
25
  const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
@@ -19,6 +19,7 @@ export const DEFAULT_AKM_READONLY_OPS = new Set([
19
19
  "show",
20
20
  "search",
21
21
  "curate",
22
+ "rules",
22
23
  "history",
23
24
  "info",
24
25
  "hints",
@@ -15,8 +15,12 @@
15
15
  * top-level driver comment there).
16
16
  */
17
17
  import { UsageError } from "../core/errors.js";
18
- const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
19
- const DETAIL_VALUES = ["brief", "normal", "full", "agent"];
18
+ /** Every `--format` value, and every value `output.format` accepts as a default. */
19
+ export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
20
+ /** Verbosity axis. */
21
+ export const DETAIL_LEVELS = ["brief", "normal", "full"];
22
+ /** What `--detail` accepts: a verbosity level, or `agent` for the agent projection. */
23
+ export const DETAIL_VALUES = [...DETAIL_LEVELS, "agent"];
20
24
  function parseOutputFormat(value) {
21
25
  if (!value)
22
26
  return undefined;
@@ -69,6 +69,7 @@ const PASSTHROUGH_COMMANDS = [
69
69
  "registry-remove",
70
70
  "remember",
71
71
  "remove",
72
+ "rules",
72
73
  "secret-remove",
73
74
  "secret-set",
74
75
  "setup",
@@ -0,0 +1,14 @@
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
+ import { withProjectLine } from "../../core/projects.js";
5
+ /** The project line when one applies, then each rule under its ref. */
6
+ export function formatRulesText(result) {
7
+ const body = result.rules.length === 0
8
+ ? "No rules apply here."
9
+ : result.rules.map((rule) => `## ${rule.ref}\n\n${rule.content}`).join("\n\n");
10
+ return withProjectLine(body, result.project);
11
+ }
12
+ export const rulesFormatters = [
13
+ { command: "rules", handler: (r) => formatRulesText(r) },
14
+ ];
@@ -28,6 +28,7 @@ import { getTextFormatterHandler, registerTextFormatters } from "./text/registry
28
28
  import { registryCommandFormatters } from "./text/registry-commands.js";
29
29
  import { rememberFormatters } from "./text/remember.js";
30
30
  import { removeFormatters } from "./text/remove.js";
31
+ import { rulesFormatters } from "./text/rules.js";
31
32
  import { searchFormatters } from "./text/search.js";
32
33
  import { showFormatters } from "./text/show.js";
33
34
  import { syncFormatters } from "./text/sync.js";
@@ -48,6 +49,7 @@ const BUILT_IN_TEXT_FORMATTERS = [
48
49
  ...showFormatters,
49
50
  ...searchFormatters,
50
51
  ...curateFormatters,
52
+ ...rulesFormatters,
51
53
  ...workflowFormatters,
52
54
  ...listFormatters,
53
55
  ...addFormatters,