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
@@ -16,10 +16,12 @@ import { hasRegistryUrlCredentials } from "../core/registry-url.js";
16
16
  import { fetchRegistryJson } from "../registry/network.js";
17
17
  import { parseRegistryRef } from "../registry/resolve.js";
18
18
  // ── Default selections ──────────────────────────────────────────────────────
19
+ /** The AKM starter bundle's Git address, as `bundle add` takes it: what setup offers, and what Desktop recognises by its `identity`. */
20
+ export const STARTER_SOURCE = "https://github.com/itlackey/akm-stash";
19
21
  const AUTHENTICATED_DEFAULT_TARGETS = {
20
22
  "itlackey/akm-stash": {
21
23
  installType: "git",
22
- url: "https://github.com/itlackey/akm-stash",
24
+ url: STARTER_SOURCE,
23
25
  },
24
26
  };
25
27
  // ── Fallback list ───────────────────────────────────────────────────────────
@@ -32,7 +34,7 @@ const FALLBACK_STASHES = [
32
34
  id: "itlackey/akm-stash",
33
35
  name: "itlackey/akm-stash",
34
36
  description: "Official AKM onboarding bundle",
35
- url: "https://github.com/itlackey/akm-stash",
37
+ url: STARTER_SOURCE,
36
38
  installType: "git",
37
39
  source: "fallback",
38
40
  defaultSelected: true,
@@ -301,11 +301,7 @@ export function saveGitStash(name, message, writableOverride, options) {
301
301
  const managedRelativeRoot = managedContentRoot
302
302
  ? path.relative(repoDir, managedContentRoot).replaceAll(path.sep, "/")
303
303
  : "";
304
- const changedPaths = listGitChangedPaths(repoDir);
305
- const requestedPaths = normalizeExactPaths(repoDir, options?.paths ??
306
- withoutIgnoredPaths(repoDir, withoutDirectories(repoDir, managedRelativeRoot && managedRelativeRoot !== ".." && !managedRelativeRoot.startsWith("../")
307
- ? changedPaths.filter((changedPath) => changedPath === managedRelativeRoot || changedPath.startsWith(`${managedRelativeRoot}/`))
308
- : changedPaths)));
304
+ const requestedPaths = normalizeExactPaths(repoDir, options?.paths ?? pathsSyncWouldCommit(repoDir, managedRelativeRoot).paths);
309
305
  if (requestedPaths.length === 0) {
310
306
  return report(nothingToCommit(repoDir, "nothing to commit", syncWithRemote, remoteEnv));
311
307
  }
@@ -464,6 +460,18 @@ function integrateUpstream(repoDir, env) {
464
460
  };
465
461
  }
466
462
  /** Git lists a nested repository as a bare directory; it is not a file sync can publish, so it is left out. */
463
+ /**
464
+ * The paths an explicit sync of the bundle at `managedRelativeRoot` of the repository would commit: every changed path inside
465
+ * the bundle that is not a directory (a nested repository) or ignored. `ok` is false when git could not list the changes, and
466
+ * the paths are then not to be trusted.
467
+ */
468
+ export function pathsSyncWouldCommit(repoDir, managedRelativeRoot = "") {
469
+ const changed = tryListGitChangedPaths(repoDir);
470
+ const inside = managedRelativeRoot && managedRelativeRoot !== ".." && !managedRelativeRoot.startsWith("../")
471
+ ? changed.paths.filter((changedPath) => changedPath === managedRelativeRoot || changedPath.startsWith(`${managedRelativeRoot}/`))
472
+ : changed.paths;
473
+ return { paths: withoutIgnoredPaths(repoDir, withoutDirectories(repoDir, inside)), ok: changed.ok };
474
+ }
467
475
  function withoutDirectories(repoDir, paths) {
468
476
  return paths.filter((candidate) => {
469
477
  try {
@@ -53,9 +53,10 @@ function embeddedInput(entry, maxInputTokens) {
53
53
  * The entry's vector is deleted when the text it is embedded from changes,
54
54
  * that is when the search text cut to `maxInputTokens` (the embedding cap,
55
55
  * `embedding.maxInputTokens`) differs from the cut of the stored document. A
56
- * change past the cut rewrites the keyword rows and keeps the vector.
56
+ * change past the cut rewrites the keyword rows and keeps the vector. A caller that knows the content is the
57
+ * same file (a moved file) passes `keepVector`: the vector stays whatever the search text now says.
57
58
  */
58
- export function upsertEntry(db, filePath, entry, provenance, contentHash, maxInputTokens = DEFAULT_MAX_INPUT_TOKENS) {
59
+ export function upsertEntry(db, filePath, entry, provenance, contentHash, maxInputTokens = DEFAULT_MAX_INPUT_TOKENS, keepVector = false) {
59
60
  // Hot path during indexing — cache prepared statements per database
60
61
  // connection so we don't pay the SQL parse/compile cost on every call.
61
62
  const stmts = getUpsertStmts(db);
@@ -75,7 +76,7 @@ export function upsertEntry(db, filePath, entry, provenance, contentHash, maxInp
75
76
  const result = stmts.upsert.get(provenance.itemRef, provenance.bundleId, provenance.componentId, provenance.conceptId, provenance.adapterId, entry.type, filePath, contentHash ?? null, JSON.stringify(entry), derivedFrom, hash);
76
77
  if (!result)
77
78
  throw new Error("upsertEntry: item_ref not found after upsert");
78
- if (previous?.id === result.id && vectorStale)
79
+ if (previous?.id === result.id && vectorStale && !keepVector)
79
80
  deleteEntryVectors(db, result.id);
80
81
  replaceFtsEntry(db, result.id, entry, hasMarkdownFragmentContent(entry) ? (getMarkdownFragmentContent(entry) ?? null) : undefined);
81
82
  replaceEntryLinks(db, result.id, entry, provenance);
@@ -364,6 +365,10 @@ function selectRowsInDirectory(db, dirPath, columns, bundleId) {
364
365
  const rows = db.prepare(sql).all(...params);
365
366
  return rows.filter((row) => path.dirname(row.file_path) === resolvedDir);
366
367
  }
368
+ /** The entries stored for the files directly in one directory of a bundle, with each file's content hash. */
369
+ export function getStoredEntriesInDirectory(db, dirPath, bundleId) {
370
+ return selectRowsInDirectory(db, dirPath, "id, item_ref, file_path, content_hash", bundleId).map((row) => ({ id: row.id, itemRef: row.item_ref, filePath: row.file_path, contentHash: row.content_hash }));
371
+ }
367
372
  function rowsInDirectory(db, dirPath, bundleId) {
368
373
  return selectRowsInDirectory(db, dirPath, "id, item_ref, file_path", bundleId);
369
374
  }
@@ -99,3 +99,7 @@ export function clearStaleCacheEntries(db) {
99
99
  export function computeBodyHash(body) {
100
100
  return sha256Hex(body);
101
101
  }
102
+ /** Move a file's cached results to its new path, so a moved file is not enriched again. */
103
+ export function rekeyLlmCache(db, oldPath, newPath) {
104
+ db.prepare("UPDATE OR REPLACE llm_enrichment_cache SET asset_ref = ? WHERE asset_ref = ?").run(newPath, oldPath);
105
+ }
@@ -2,19 +2,26 @@
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
4
  /** Observability read models: the overview, the week's pulse, health, retrieval and impact trends, task history. */
5
+ import fs from "node:fs";
5
6
  import os from "node:os";
7
+ import { reportUsageIfDue } from "../cli/usage-report.js";
6
8
  import { akmHealth, parseHealthSince } from "../commands/health.js";
7
9
  import { buildTasks } from "../commands/metrics/collect.js";
8
10
  import { akmMetrics, metricsWindow, readUsageRows } from "../commands/metrics/metrics-cli.js";
9
11
  import { NotFoundError, UsageError } from "../core/errors.js";
12
+ import { buildTaskRunId, getLogsDbPath, queryTaskLogs } from "../core/logs-db.js";
13
+ import { openDatabase } from "../storage/database.js";
10
14
  import { getImproveRunById, listRecentImproveRuns, } from "../storage/repositories/improve-runs-repository.js";
11
15
  import { decodeTaskHistoryMetadata, queryTaskHistory, } from "../storage/repositories/task-history-repository.js";
12
16
  import { WorkflowRunsRepository } from "../storage/repositories/workflow-runs-repository.js";
17
+ import { applyReadonlyPragmas } from "../storage/sqlite-pragmas.js";
13
18
  import { pkgVersion } from "../version.js";
14
19
  import { listWorkflowRunSummaries, readWorkflowStatus } from "../workflows/runtime/runs.js";
15
- import { pChart, weekOf, weekRange } from "./derive.js";
20
+ import { pChart, weekRange } from "./derive.js";
16
21
  import { filledActivity, retrievalSeries } from "./metrics.js";
17
- import { clampLimit, section, withReadonlyStateDb } from "./readers.js";
22
+ import { isUserEvent } from "./misses.js";
23
+ import { clampLimit, section, stateDbUnavailable, withReadonlyStateDb } from "./readers.js";
24
+ import { weekDays } from "./stats.js";
18
25
  export { improveImpact } from "./impact.js";
19
26
  export { overviewPulse as pulse } from "./pulse.js";
20
27
  const IMPROVE_RUNS_SHOWN = 10;
@@ -29,6 +36,10 @@ export function meta() {
29
36
  runtime: process.versions.bun ? "bun" : "node",
30
37
  };
31
38
  }
39
+ /** The Desktop daily usage report, once at server start: sent at most once a UTC day, never throws, `true` when sent. */
40
+ export function reportUsage() {
41
+ return reportUsageIfDue({ surface: "desktop" });
42
+ }
32
43
  const IMPROVE_ERRORS_SHOWN = 20;
33
44
  /** One persisted improve run, projected to what the overview shows. Tolerant: a row from an older release just has fewer fields. */
34
45
  function summarizeImproveRun(row) {
@@ -135,6 +146,8 @@ export async function overview(input = {}) {
135
146
  // Rank the complete window in the order of the bars (failed runs over runs), not the metrics top-20 by volume.
136
147
  taskFailures: metrics ? failingTasks(queryTaskHistory(db, metrics.window)) : null,
137
148
  }), null));
149
+ if (stateReads === null && !errors.state)
150
+ errors.state = `The state database is ${stateDbUnavailable().reason === "absent" ? "absent" : "behind on migrations"}.`;
138
151
  return {
139
152
  health,
140
153
  metrics: metrics
@@ -184,6 +197,9 @@ export function taskHistory(input) {
184
197
  startedAt: row.started_at,
185
198
  durationMs: metadata?.durationMs ?? null,
186
199
  trigger: metadata?.trigger ?? null,
200
+ targetKind: row.target_kind ?? null,
201
+ targetRef: row.target_ref ?? null,
202
+ engine: metadata?.engine ?? null,
187
203
  detail: metadata?.detail ?? null,
188
204
  // A steps task (Experimental): each step without its stored result, which can be large.
189
205
  steps: metadata?.steps?.map(({ result: _result, ...step }) => step) ?? null,
@@ -192,23 +208,63 @@ export function taskHistory(input) {
192
208
  return { available: true, totalCount: rows.length, count: runs.length, runs };
193
209
  }, { available: false, totalCount: 0, count: 0, runs: [] });
194
210
  }
211
+ /** Most log lines one run's output returns; a longer log says it was cut. */
212
+ const LOG_LINES_MAX = 500;
213
+ /**
214
+ * One task run's recorded output, as `logs.db` holds it (`taskId` and `startedAt` as `taskHistory` lists them), oldest
215
+ * line first. Read-only: a missing `logs.db` is `available: false`, and nothing is created or migrated.
216
+ */
217
+ export function taskRunLog(input) {
218
+ const taskId = (input.taskId ?? "").trim();
219
+ const startedAt = (input.startedAt ?? "").trim();
220
+ if (!taskId || !startedAt)
221
+ throw new UsageError("A taskId and the run's startedAt are required.", "MISSING_REQUIRED_ARGUMENT");
222
+ const dbPath = getLogsDbPath();
223
+ if (!fs.existsSync(dbPath))
224
+ return { available: false, reason: "absent" };
225
+ const db = openDatabase(dbPath, { readonly: true, create: false });
226
+ try {
227
+ applyReadonlyPragmas(db);
228
+ const rows = queryTaskLogs(db, { runId: buildTaskRunId(taskId, startedAt), limit: LOG_LINES_MAX + 1 });
229
+ return {
230
+ available: true,
231
+ truncated: rows.length > LOG_LINES_MAX,
232
+ lines: rows.slice(0, LOG_LINES_MAX).map(({ stream, level, line }) => ({ stream, level, line })),
233
+ };
234
+ }
235
+ finally {
236
+ db.close();
237
+ }
238
+ }
195
239
  /** The per-day search series over a longer window than the Overview's, for the Improve impact trend. */
196
240
  export function retrievalTrend(input = {}) {
197
241
  const window = metricsWindow(input.since || "90d");
198
- const series = retrievalSeries(withReadonlyStateDb((db) => readUsageRows(db, window), []), window);
242
+ const rows = withReadonlyStateDb((db) => readUsageRows(db, window), null);
243
+ if (!rows)
244
+ return stateDbUnavailable();
245
+ const series = retrievalSeries(rows, window);
199
246
  // The same days by ISO week, for a p-chart of the share that found nothing.
200
247
  const first = series.daily[0]?.date;
201
248
  const weeks = first ? weekRange(first, window.until.slice(0, 10)) : [];
249
+ const byDate = new Map(series.daily.map((d) => [d.date, d]));
202
250
  const perWeek = weeks.map((week) => {
203
- const days = series.daily.filter((d) => weekOf(d.date) === week);
251
+ const days = weekDays(week).map((date) => byDate.get(date));
204
252
  return {
205
253
  week,
206
- x: days.reduce((sum, d) => sum + d.zeroResults, 0),
207
- n: days.reduce((sum, d) => sum + d.searches, 0),
254
+ x: days.reduce((sum, d) => sum + (d?.zeroResults ?? 0), 0),
255
+ n: days.reduce((sum, d) => sum + (d?.searches ?? 0), 0),
256
+ // A day akm has no row for (before the first recorded day) or marks partial makes the week partial.
257
+ partial: days.some((d) => d === undefined || d.partial === true),
208
258
  };
209
259
  });
210
260
  const chart = pChart(perWeek);
211
- return { ...series, weekly: chart.points, centre: chart.centre };
261
+ return {
262
+ available: true,
263
+ ...series,
264
+ weekly: chart.points,
265
+ centre: chart.centre,
266
+ enoughHistory: chart.enough,
267
+ };
212
268
  }
213
269
  /** Most runs or events one window read returns; a longer window says it was cut. */
214
270
  const WINDOW_ROWS_MAX = 20000;
@@ -350,6 +406,11 @@ export function events(input = {}) {
350
406
  // One row past the cap says "truncated"; the cut keeps the newest rows, listed oldest first.
351
407
  const rows = readUsageRows(db, window, { allSources: true, newest: WINDOW_ROWS_MAX + 1 });
352
408
  const kept = rows.length > WINDOW_ROWS_MAX ? rows.slice(1) : rows;
353
- return { available: true, window, truncated: rows.length > WINDOW_ROWS_MAX, events: kept };
409
+ return {
410
+ available: true,
411
+ window,
412
+ truncated: rows.length > WINDOW_ROWS_MAX,
413
+ events: kept.map((row) => ({ ...row, byPerson: isUserEvent(row) })),
414
+ };
354
415
  }, { available: false, window, truncated: false, events: [] });
355
416
  }
@@ -3,21 +3,24 @@
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /** What improve proposed for one asset, how it was decided, and how the asset has been used since. */
5
5
  import { metricsWindow, readUsageRows } from "../commands/metrics/metrics-cli.js";
6
+ import { resolveStashDir } from "../core/common.js";
6
7
  import { UsageError } from "../core/errors.js";
7
8
  import { listStateProposals } from "../storage/repositories/proposals-repository.js";
8
9
  import { classifyOutcome, decidedAt, weekOf, weekRange } from "./derive.js";
9
- import { tryStashDir, withReadonlyStateDb } from "./readers.js";
10
+ import { stateDbUnavailable, withReadonlyStateDb } from "./readers.js";
10
11
  const DAY = 86_400_000;
11
12
  export function assetImprove(input) {
12
13
  const ref = input.ref?.trim();
13
14
  if (!ref)
14
15
  throw new UsageError("Give the asset's ref: <bundle>//<type>/<name>.", "MISSING_REQUIRED_ARGUMENT");
15
- const stashDir = tryStashDir();
16
16
  const window = metricsWindow("90d");
17
- const { proposals, mine } = withReadonlyStateDb((db) => ({
18
- proposals: stashDir ? listStateProposals(db, { stashDir, ref, withContent: false }) : [],
17
+ const state = withReadonlyStateDb((db) => ({
18
+ proposals: listStateProposals(db, { stashDir: resolveStashDir(), ref, withContent: false }),
19
19
  mine: readUsageRows(db, window).filter((row) => row.ref === ref),
20
- }), { proposals: [], mine: [] });
20
+ }), null);
21
+ if (!state)
22
+ return stateDbUnavailable();
23
+ const { proposals, mine } = state;
21
24
  const now = Date.now();
22
25
  const weeks = weekRange(new Date(now - 90 * DAY).toISOString().slice(0, 10), new Date(now).toISOString().slice(0, 10));
23
26
  const usageByWeek = weeks.map((week) => {
@@ -30,6 +33,7 @@ export function assetImprove(input) {
30
33
  };
31
34
  });
32
35
  return {
36
+ available: true,
33
37
  proposals: proposals
34
38
  .map((p) => ({
35
39
  id: p.id,
@@ -7,25 +7,32 @@ import { akmRelated } from "../commands/read/related.js";
7
7
  import { akmSearch, narrowSourcesToName, normalizeScopeFilters, parseBeliefFilterMode } from "../commands/read/search.js";
8
8
  import { akmShowUnified } from "../commands/read/show.js";
9
9
  import { parseBundleRef } from "../core/asset/asset-ref.js";
10
+ import { readFrontmatter } from "../core/asset/frontmatter-edit.js";
10
11
  import { parseMarkdownToc, uniqueHeadingSlugs } from "../core/asset/markdown.js";
11
12
  import { markdownLinkTargets } from "../core/asset/markdown-link-targets.js";
12
13
  import { loadConfig } from "../core/config/config.js";
14
+ import { defaultExcludedTypes } from "../core/config/schema/search.js";
13
15
  import { resolveRefOwner } from "../core/env-secret-ref.js";
14
16
  import { UsageError } from "../core/errors.js";
15
17
  import { includedTypes, includesProposed } from "../core/include.js";
16
18
  import { projectView, resolveProject } from "../core/projects.js";
19
+ import { inspectWriteTarget } from "../core/write-source.js";
17
20
  import { readUsableIndex } from "../indexer/index-readiness.js";
18
21
  import { resolveReadSources } from "../indexer/read-preflight.js";
19
22
  import { countBrowseEntries } from "../indexer/search/db-search.js";
20
23
  import { findSourceForPath, resolveSourceEntries } from "../indexer/search/search-source.js";
24
+ import { protectedTypeOf } from "../indexer/walk/place-rules.js";
21
25
  import { getEntryIdByFilePath, getItemRefById } from "../storage/repositories/index-entries-repository.js";
22
26
  import { countFeedbackBySignal, listFeedbackEventRows } from "../storage/repositories/metrics-repository.js";
23
27
  import { assetImprove } from "./asset-improve.js";
24
28
  import { bundleFileLocation, listBundleFiles } from "./bundle-files.js";
29
+ import { bundleWriteBlockers, fileActions } from "./file-actions.js";
25
30
  import { readFileRevision, readRecentCommits } from "./git-read.js";
26
- import { automaticWriteTarget, capSide, clampLimit, DIFF_SIDE_MAX_CHARS, withReadonlyStateDb } from "./readers.js";
31
+ import { capSide, clampLimit, DIFF_SIDE_MAX_CHARS, durableRefForPath, withReadonlyStateDb } from "./readers.js";
32
+ export { copyEntry } from "./copy-entry.js";
27
33
  export { graph } from "./graph.js";
28
34
  export { searchMisses } from "./misses.js";
35
+ export { movedLinks, updateMovedLinks } from "./moved-links.js";
29
36
  /** Browse keeps its contract that blank scope values are omitted (an empty filter value would mean "without the key"). */
30
37
  function blanksOmitted(scope) {
31
38
  if (!scope)
@@ -81,20 +88,17 @@ export function projectOverview(input) {
81
88
  : [project.from].flat().map((from) => ({ name: from, source: narrowSourcesToName(local, [from])[0] }));
82
89
  const readable = selected.flatMap((bundle) => (bundle.source ? [bundle.source] : []));
83
90
  const counts = readable.length > 0
84
- ? readUsableIndex((db) => countBrowseEntries(db, readable, project.filters, (config.search?.defaultExcludeTypes ?? ["session"]).filter((type) => !includedTypes(project.include).includes(type)), includesProposed(project.include)), undefined)
91
+ ? readUsableIndex((db) => countBrowseEntries(db, readable, project.filters, defaultExcludedTypes(config).filter((type) => !includedTypes(project.include).includes(type)), includesProposed(project.include)), undefined)
85
92
  : undefined;
86
- const writeName = project.write.bundle ?? config.defaultWriteTarget ?? automaticWriteTarget(config)?.name ?? null;
87
- const writeSource = writeName === null ? undefined : local.find((source) => source.registryId === writeName);
93
+ // Where akm would write for this project, and the sentence its write path refuses with (null when it would accept a
94
+ // write); a write bundle that does not resolve is shown by the name it was given.
95
+ const write = inspectWriteTarget(config, project.write.bundle);
96
+ const writeName = write.name ?? project.write.bundle ?? null;
88
97
  return {
89
98
  project: { ...projectView(project), write: project.write },
90
99
  fromImplicit: project.from === undefined,
91
100
  preferImplicit: config.projects?.[name]?.prefer === undefined,
92
- // `usable`: the bundle is enabled and accepts writes. Null when no write bundle resolves.
93
- writeBundle: {
94
- name: writeName,
95
- implicit: project.write.bundle === undefined,
96
- usable: writeName === null ? null : writeSource?.writable === true,
97
- },
101
+ writeBundle: { name: writeName, implicit: project.write.bundle === undefined, writeBlocker: write.blocker },
98
102
  bundles: selected.map(({ name: bundle, source }) => {
99
103
  const entry = Object.hasOwn(config.bundles ?? {}, bundle) ? config.bundles?.[bundle] : undefined;
100
104
  const found = source ? counts?.[readable.indexOf(source)] : undefined;
@@ -111,13 +115,6 @@ export function projectOverview(input) {
111
115
  }),
112
116
  };
113
117
  }
114
- /** The durable `bundle//conceptId` of the indexed asset at `filePath`, the key feedback rows use. */
115
- function durableRefForPath(filePath) {
116
- return readUsableIndex((db) => {
117
- const id = getEntryIdByFilePath(db, filePath);
118
- return id === undefined ? null : getItemRefById(db, id);
119
- }, null);
120
- }
121
118
  function feedbackFor(durableRef) {
122
119
  const empty = { counts: {}, history: [] };
123
120
  if (!durableRef)
@@ -155,6 +152,8 @@ export async function show(input) {
155
152
  const shown = await akmShowUnified({ ref, readOnly: true });
156
153
  const durableRef = shown.path ? durableRefForPath(shown.path) : null;
157
154
  const content = shown.content ?? "";
155
+ // Where the body starts in the text an asset is read from (content, a command's template, an agent's prompt).
156
+ const bodyStart = readFrontmatter(shown.content || shown.template || shown.prompt || "").bodyStart;
158
157
  const headings = parseMarkdownToc(content).headings;
159
158
  const slugs = uniqueHeadingSlugs(headings);
160
159
  const links = {};
@@ -181,12 +180,25 @@ export async function show(input) {
181
180
  }
182
181
  }, undefined);
183
182
  }
183
+ const location = shown.path ? bundleFileLocation(shown.path) : null;
184
184
  return {
185
185
  redacted: false,
186
186
  durableRef,
187
187
  bundle: durableRef ? parseBundleRef(durableRef).bundle : null,
188
188
  asset: shown,
189
- location: shown.path ? bundleFileLocation(shown.path) : null,
189
+ location,
190
+ bodyStart,
191
+ // What akm accepts doing to this asset's file, and why not: the verdicts the file listing gives the same entry.
192
+ actions: location && shown.path
193
+ ? fileActions({
194
+ bundle: location.bundle,
195
+ relative: location.path,
196
+ kind: "file",
197
+ absolute: shown.path,
198
+ protected: protectedTypeOf(location.path) !== undefined,
199
+ assets: durableRef ? [{ ref: durableRef, type: shown.type }] : [],
200
+ }, bundleWriteBlockers(loadConfig(), location.bundle))
201
+ : null,
190
202
  feedback: feedbackFor(durableRef),
191
203
  feedbackRequireReason: loadConfig().feedback?.requireReason !== false,
192
204
  links,
@@ -203,7 +215,8 @@ export async function history(input) {
203
215
  const file = path.relative(source.path, selected.asset.path).split(path.sep).join("/");
204
216
  if (file.startsWith("../") || path.isAbsolute(file))
205
217
  throw new UsageError("Asset path is outside its bundle.");
206
- const commits = await readRecentCommits(source.path, clampLimit(input.limit, 30), file);
218
+ const read = await readRecentCommits(source.path, clampLimit(input.limit, 30), file);
219
+ const commits = read?.commits ?? null;
207
220
  const revision = input.revision;
208
221
  if (revision && !commits?.some((commit) => commit.sha === revision))
209
222
  throw new UsageError("Choose a revision from this asset's history.");
@@ -213,6 +226,7 @@ export async function history(input) {
213
226
  return {
214
227
  available: commits !== null,
215
228
  commits: commits ?? [],
229
+ ...(read?.error ? { error: read.error } : {}),
216
230
  ...(diff
217
231
  ? {
218
232
  diff: {
@@ -4,10 +4,14 @@
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
6
  import { isWithin, relativeToRoot, safeRealpath } from "../core/common.js";
7
+ import { loadConfig } from "../core/config/config.js";
7
8
  import { NotFoundError, UsageError } from "../core/errors.js";
8
9
  import { findSourceForPath, resolveSourceEntries } from "../indexer/search/search-source.js";
10
+ import { protectedTypeOf } from "../indexer/walk/place-rules.js";
9
11
  import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
10
12
  import { getAssetRefsForFiles } from "../storage/repositories/index-entries-repository.js";
13
+ import { bundleWriteBlockers, fileActions, placeVerdict } from "./file-actions.js";
14
+ import { newFileVerdict } from "./new-file.js";
11
15
  const portable = (value) => value.split(path.sep).join("/");
12
16
  /** Source roots and identities come from the same resolver as search, never from a ref's spelling. */
13
17
  export function bundleFileLocation(filePath) {
@@ -21,7 +25,11 @@ export function bundleFileLocation(filePath) {
21
25
  parent: portable(path.dirname(relative)).replace(/^\.$/, ""),
22
26
  };
23
27
  }
24
- /** One directory, not a recursive walk or an index refresh. File contents are never read here. */
28
+ /**
29
+ * One directory, not a recursive walk or an index refresh. Each entry says what akm accepts doing to it (`actions`) and
30
+ * why not. A file's contents are not listed; the first bytes of a file that is neither protected nor managed are probed
31
+ * to tell text from binary, and a protected file is never opened.
32
+ */
25
33
  export function listBundleFiles(bundle, relative = "", showHidden = false) {
26
34
  if (!bundle)
27
35
  throw new UsageError("Choose a registered bundle.", "MISSING_REQUIRED_ARGUMENT");
@@ -62,10 +70,19 @@ export function listBundleFiles(bundle, relative = "", showHidden = false) {
62
70
  unavailable = "Link target is unavailable.";
63
71
  }
64
72
  }
73
+ // Size (a file's) and modified time, from the file the entry resolves to; absent when it cannot be read.
74
+ let stat;
75
+ try {
76
+ stat = fs.statSync(absolute);
77
+ }
78
+ catch {
79
+ stat = undefined;
80
+ }
65
81
  return {
66
82
  name: entry.name,
67
83
  path: portable(path.relative(source.path, absolute)),
68
84
  kind,
85
+ ...(stat ? { modified: stat.mtime.toISOString(), ...(stat.isFile() ? { size: stat.size } : {}) } : {}),
69
86
  // Keep the displayed alias, but look up the file under this bundle's indexed root.
70
87
  absolute: path.join(source.path, path.relative(physicalRoot, safeRealpath(absolute))),
71
88
  ...(entry.isSymbolicLink() ? { symlink: true } : {}),
@@ -93,14 +110,34 @@ export function listBundleFiles(bundle, relative = "", showHidden = false) {
93
110
  /* Files remain browsable when the derived index needs repair. */
94
111
  }
95
112
  const current = portable(path.relative(source.path, target));
113
+ const writeBlockers = bundleWriteBlockers(loadConfig(), bundle);
96
114
  return {
97
115
  bundle,
98
116
  path: current,
99
117
  parent: current ? portable(path.dirname(current)).replace(/^\.$/, "") : null,
100
118
  indexAvailable,
119
+ // Whether a new file may be made in this folder, and the type its place gives it (null: none).
120
+ newFile: newFileVerdict(current, writeBlockers),
121
+ // Whether a folder may be made here, or a file or folder moved in: plain file operations, which need only a place akm
122
+ // does not manage or protect and a bundle that is not read-only.
123
+ place: placeVerdict(current, writeBlockers),
101
124
  entries: rows.map(({ absolute, ...row }) => {
102
125
  const assets = refs.get(absolute) ?? [];
103
- return { ...row, assets };
126
+ const isProtected = row.kind === "file" && protectedTypeOf(portable(path.relative(source.path, absolute))) !== undefined;
127
+ return {
128
+ ...row,
129
+ assets,
130
+ protected: isProtected,
131
+ actions: fileActions({
132
+ bundle,
133
+ relative: row.path,
134
+ kind: row.kind,
135
+ absolute: row.unavailable ? undefined : path.join(target, row.name),
136
+ unavailable: row.unavailable,
137
+ protected: isProtected,
138
+ assets,
139
+ }, writeBlockers),
140
+ };
104
141
  }),
105
142
  };
106
143
  }
@@ -5,14 +5,36 @@
5
5
  import { setConfigValue } from "../commands/config-cli.js";
6
6
  import { assembleInfo } from "../commands/sources/info.js";
7
7
  import { akmListSources } from "../commands/sources/installed-stashes.js";
8
+ import { akmSync } from "../commands/sources/sync.js";
8
9
  import { loadConfig, mutateConfig } from "../core/config/config.js";
9
10
  import { UsageError } from "../core/errors.js";
10
11
  import { getDbPath } from "../core/paths.js";
12
+ import { inspectWriteTarget } from "../core/write-source.js";
13
+ import { deriveSemanticProviderFingerprint } from "../indexer/materialize-embeddings.js";
14
+ import { effectiveEmbedding } from "../llm/embedders/connection.js";
15
+ import { parseRegistryRef } from "../registry/resolve.js";
16
+ import { STARTER_SOURCE } from "../setup/registry-stash-loader.js";
11
17
  import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
18
+ import { getEmbeddableEntryCount } from "../storage/repositories/index-entries-repository.js";
12
19
  import { getEmbeddingCount } from "../storage/repositories/index-vec-repository.js";
13
20
  import { runCli } from "./cli-child.js";
14
21
  import { readBundleGitStatus } from "./git-read.js";
22
+ import { interactive } from "./lease.js";
15
23
  import { configSource, preserveUnrelatedConfig, tryStashDir, workingStashDir } from "./readers.js";
24
+ /**
25
+ * One name for where a bundle comes from, parsed by the code `bundle add` uses: the same repository or package gives
26
+ * the same identity however its address is written. Null for a folder, a website, or an address that does not parse.
27
+ */
28
+ function sourceIdentity(source) {
29
+ if (source.kind !== "git" && source.kind !== "npm")
30
+ return null;
31
+ try {
32
+ return parseRegistryRef(source.locator).id;
33
+ }
34
+ catch {
35
+ return null;
36
+ }
37
+ }
16
38
  export async function list() {
17
39
  const config = loadConfig();
18
40
  const listing = await akmListSources({ stashDir: tryStashDir() ?? "" });
@@ -21,8 +43,11 @@ export async function list() {
21
43
  kind: source.kind,
22
44
  default: source.default,
23
45
  source: source.source,
46
+ identity: sourceIdentity(source.source),
24
47
  path: source.path ?? null,
25
48
  writable: source.writable,
49
+ // Whether akm would accept a write to this bundle now, and the sentence why not: the write path's own checks.
50
+ writeBlocker: inspectWriteTarget(config, source.name).blocker,
26
51
  enabled: config.bundles?.[source.name]?.enabled !== false,
27
52
  writableSetting: config.bundles?.[source.name]?.writable,
28
53
  components: source.components.map((component) => ({
@@ -42,11 +67,14 @@ export async function list() {
42
67
  cards.sort((a, b) => Number(b.default) - Number(a.default));
43
68
  const info = assembleInfo();
44
69
  let embeddingCount = null;
70
+ let embeddableCount = 0;
45
71
  try {
46
72
  const db = openReadonlyExistingDatabase(getDbPath());
47
73
  if (db) {
48
74
  try {
49
- embeddingCount = getEmbeddingCount(db);
75
+ // The same two counts akm's own readiness test compares: the current model's vectors, the embeddable entries.
76
+ embeddingCount = getEmbeddingCount(db, deriveSemanticProviderFingerprint(effectiveEmbedding(config)));
77
+ embeddableCount = getEmbeddableEntryCount(db);
50
78
  }
51
79
  finally {
52
80
  closeDatabase(db);
@@ -56,10 +84,13 @@ export async function list() {
56
84
  catch {
57
85
  // An index without an embeddings table (older layout) has none.
58
86
  }
59
- const entryCount = info.indexStats.entryCount;
87
+ const { entryCount } = info.indexStats;
60
88
  return {
61
89
  defaultBundle: config.defaultBundle ?? null,
62
90
  defaultWriteTarget: config.defaultWriteTarget ?? null,
91
+ // Where a write goes when no bundle is named, and why none does (`name: null`) or why it would be refused.
92
+ writeTarget: inspectWriteTarget(config),
93
+ starter: { source: STARTER_SOURCE, identity: sourceIdentity({ kind: "git", locator: STARTER_SOURCE }) },
63
94
  bundles: cards,
64
95
  workingStash,
65
96
  index: {
@@ -68,7 +99,7 @@ export async function list() {
68
99
  lastBuiltAt: info.indexStats.lastBuiltAt,
69
100
  hasEmbeddings: info.indexStats.hasEmbeddings,
70
101
  embeddingCount,
71
- embeddingCoverage: embeddingCount !== null && entryCount > 0 ? Math.min(1, embeddingCount / entryCount) : null,
102
+ embeddingCoverage: embeddingCount !== null && embeddableCount > 0 ? Math.min(1, embeddingCount / embeddableCount) : null,
72
103
  semanticSearch: info.semanticSearch,
73
104
  ...(info.indexStats.unavailable ? { unavailable: info.indexStats.unavailable } : {}),
74
105
  ...(info.indexStats.unreadable ? { unreadable: info.indexStats.unreadable } : {}),
@@ -111,6 +142,13 @@ export async function remove(input) {
111
142
  export async function update(input) {
112
143
  return runCli(["bundle", "update", "--", configured(name(input.bundle, "bundle"))]);
113
144
  }
145
+ /**
146
+ * `akm index`: the incremental build. It pairs a file renamed or moved on disk with the asset it was and carries the
147
+ * asset's history to the new ref (`moves` in the result), which the write-path index refresh does not do.
148
+ */
149
+ export async function index() {
150
+ return (await runCli(["index"]));
151
+ }
114
152
  /** A dry run returns the plan and writes nothing. */
115
153
  export async function rename(input) {
116
154
  if (input.dryRun !== true)
@@ -156,3 +194,15 @@ export function setSettings(input) {
156
194
  });
157
195
  return { saved: result.written };
158
196
  }
197
+ /**
198
+ * `akm sync` for one bundle: commit every unignored change inside it, and push when it is writable with a remote. Says what it
199
+ * did: the commit, whether it was pushed, or why nothing was committed (`reason`).
200
+ */
201
+ export async function commit(input) {
202
+ const bundle = configured(name(input.bundle, "bundle"));
203
+ const message = typeof input.message === "string" && input.message.trim() ? input.message.trim() : undefined;
204
+ return interactive("ui-bundle-commit", async () => ({
205
+ bundle,
206
+ ...akmSync({ name: bundle, message, push: input.push }),
207
+ }));
208
+ }