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
@@ -13,6 +13,7 @@
13
13
  import { execFile } from "node:child_process";
14
14
  import fs from "node:fs";
15
15
  import path from "node:path";
16
+ import { pathsSyncWouldCommit } from "../sources/providers/git-stash.js";
16
17
  const GIT_TIMEOUT_MS = 10_000;
17
18
  /** `git log` output for a large accept can be big; cap what we buffer. */
18
19
  const GIT_MAX_BUFFER = 16 * 1024 * 1024;
@@ -25,9 +26,26 @@ function git(repoDir, args) {
25
26
  timeout: GIT_TIMEOUT_MS,
26
27
  maxBuffer: GIT_MAX_BUFFER,
27
28
  env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
28
- }, (error, stdout) => resolve(error ? null : stdout));
29
+ }, (error, stdout, stderr) => {
30
+ if (!error)
31
+ return resolve({ ok: true, out: stdout });
32
+ if (error.code === "ENOENT")
33
+ return resolve({ ok: false, error: "git not found", quiet: false });
34
+ if (error.killed)
35
+ return resolve({ ok: false, error: "timed out", quiet: false });
36
+ const line = stderr
37
+ .split("\n")
38
+ .find((text) => text.trim() !== "")
39
+ ?.trim();
40
+ resolve({ ok: false, error: line ?? `git exited with ${error.code}`, quiet: !line });
41
+ });
29
42
  });
30
43
  }
44
+ /** Why a failed `git log` is not just an empty history: it is when HEAD resolves, or git cannot even say. */
45
+ async function logFailure(repoDir, failed) {
46
+ const head = await git(repoDir, ["rev-parse", "--verify", "-q", "HEAD"]);
47
+ return head.ok ? failed.error : head.quiet ? null : head.error;
48
+ }
31
49
  /** Whether `dir` is the root of its own git repository (a bundle inside a larger repo is not reported as git-backed). */
32
50
  export function isGitRoot(dir) {
33
51
  return fs.existsSync(path.join(dir, ".git"));
@@ -42,37 +60,35 @@ export async function readBundleGitStatus(repoDir) {
42
60
  git(repoDir, ["status", "--porcelain"]),
43
61
  git(repoDir, ["log", "-1", "--format=%H%x1f%cI%x1f%s"]),
44
62
  ]);
63
+ let error = !status.ok ? status.error : !branch.ok && !branch.quiet ? branch.error : null;
64
+ if (!last.ok)
65
+ error ??= await logFailure(repoDir, last);
45
66
  let ahead = null;
46
67
  let behind = null;
47
- if (upstream?.trim()) {
48
- const counts = (await git(repoDir, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]))?.trim().split(/\s+/);
49
- if (counts?.length === 2) {
68
+ if (upstream.ok && upstream.out.trim()) {
69
+ const counted = await git(repoDir, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]);
70
+ const counts = counted.ok ? counted.out.trim().split(/\s+/) : [];
71
+ if (counts.length === 2) {
50
72
  ahead = Number(counts[0]);
51
73
  behind = Number(counts[1]);
52
74
  }
53
75
  }
54
- const [sha, time, subject] = (last ?? "").trim().split("\x1f");
76
+ const [sha, time, subject] = (last.ok ? last.out : "").trim().split("\x1f");
77
+ const syncing = pathsSyncWouldCommit(repoDir);
55
78
  return {
56
- branch: branch?.trim() || null,
57
- upstream: upstream?.trim() || null,
79
+ error,
80
+ branch: (branch.ok && branch.out.trim()) || null,
81
+ upstream: (upstream.ok && upstream.out.trim()) || null,
58
82
  ahead,
59
83
  behind,
60
- dirtyPaths: status ? status.split("\n").filter((line) => line.trim() !== "").length : 0,
84
+ uncommitted: syncing.ok ? syncing.paths.length : null,
61
85
  lastCommit: sha && time ? { sha, time, subject: subject ?? "" } : null,
62
86
  };
63
87
  }
64
- export function classifyCommitOrigin(subject) {
65
- if (/^akm improve\b/i.test(subject))
66
- return "improve-sync";
67
- if (/^akm (accept|proposal)\b/i.test(subject))
68
- return "accept";
69
- if (/\bremember\b/i.test(subject))
70
- return "remember";
71
- if (/^akm (save|sync)\b/i.test(subject))
72
- return "sync";
73
- return "other";
74
- }
75
- /** The `limit` most recent commits of the repository at `repoDir`, newest first; `null` when it is not a git root. */
88
+ /**
89
+ * The `limit` most recent commits of the repository at `repoDir`, newest first; `null` when it is not a git root.
90
+ * `error` says why git could not be read, and then `commits` is empty because nothing was read.
91
+ */
76
92
  export async function readRecentCommits(repoDir, limit, file) {
77
93
  if (!isGitRoot(repoDir))
78
94
  return null;
@@ -84,10 +100,10 @@ export async function readRecentCommits(repoDir, limit, file) {
84
100
  "--format=%x1e%H%x1f%cI%x1f%an%x1f%s",
85
101
  ...(file ? ["--", file] : []),
86
102
  ]);
87
- if (out === null)
88
- return [];
103
+ if (!out.ok)
104
+ return { commits: [], error: await logFailure(repoDir, out) };
89
105
  const commits = [];
90
- for (const record of out.split("\x1e")) {
106
+ for (const record of out.out.split("\x1e")) {
91
107
  if (!record.trim())
92
108
  continue;
93
109
  const [header = "", ...pathLines] = record.split("\n");
@@ -99,19 +115,18 @@ export async function readRecentCommits(repoDir, limit, file) {
99
115
  time,
100
116
  author,
101
117
  subject,
102
- origin: classifyCommitOrigin(subject),
103
118
  paths: paths.slice(0, PATHS_PER_COMMIT),
104
119
  pathCount: paths.length,
105
120
  });
106
121
  }
107
- return commits;
122
+ return { commits, error: null };
108
123
  }
109
124
  /** Caller supplies an indexed asset path inside this bundle and a commit ID it took from {@link readRecentCommits}. */
110
125
  export async function readFileRevision(repoDir, file, sha) {
111
126
  const after = await git(repoDir, ["show", `${sha}:${file}`]);
112
- if (after === null)
127
+ if (!after.ok)
113
128
  return null;
114
129
  const before = await git(repoDir, ["show", `${sha}^:${file}`]);
115
130
  const unified = await git(repoDir, ["show", "--no-ext-diff", "--no-textconv", "--format=", sha, "--", file]);
116
- return { before, after, unified: unified ?? "" };
131
+ return { before: before.ok ? before.out : null, after: after.out, unified: unified.ok ? unified.out : "" };
117
132
  }
@@ -19,7 +19,7 @@ const HIDDEN_TYPES = ["secret", "env", "session"];
19
19
  * Every asset of the enabled bundles and the declared links between them, in column form: node `i` is `nodes.ref[i]`,
20
20
  * and its type, bundle and belief state are indexes into `types`, `bundles` (largest first) and `beliefs` (-1: no state
21
21
  * recorded). `shows`, `lastShownAt` and the feedback counts `positive` and `negative` are read live from the
22
- * user-attributed usage events within retention (`use`); `modifiedAt` is the file's modification time. A link joins two
22
+ * user-attributed usage events within retention (`use` and `feedback` are `null` when the store could not be read, and the counts are then zeros, not measurements); `modifiedAt` is the file's modification time. A link joins two
23
23
  * nodes by index and names its kind by index into `kinds`. `nodes.tags[i]` indexes `tags`, the asset's own frontmatter
24
24
  * tags. `duplicates` pairs assets whose stored embeddings are nearly the same, and `groups` gives each asset its group by
25
25
  * meaning and a place in 3D where alike assets sit close, as the last `akm index` stored them (index-layout-repository.ts);
@@ -48,6 +48,8 @@ function emptyGraph() {
48
48
  beliefs: [],
49
49
  /** Use figures count events from `source` at or after `since`. */
50
50
  use: null,
51
+ /** Feedback counts cover the same window; `null` when the store could not be read, so zeros are not a measurement. */
52
+ feedback: null,
51
53
  kinds: [],
52
54
  /** Every tag the assets carry, lower case; `nodes.tags[i]` indexes it. */
53
55
  tags: [],
@@ -112,7 +114,10 @@ async function readGraph() {
112
114
  const since = usageRetentionSince();
113
115
  const use = withReadonlyStateDb((state) => countUseByRef(state, since), null);
114
116
  const feedback = withReadonlyStateDb((state) => countFeedbackSignalsByRef(state, rows.map((row) => row.itemRef)), null);
115
- result.use = { since, source: "user" };
117
+ if (use)
118
+ result.use = { since, source: "user" };
119
+ if (feedback)
120
+ result.feedback = { since, source: "user" };
116
121
  for (const row of rows) {
117
122
  const counts = use?.get(row.itemRef);
118
123
  result.nodes.ref.push(row.itemRef);
@@ -176,6 +181,10 @@ async function readGraph() {
176
181
  const noted = [`${rows.length} assets and ${result.links.from.length} links of the enabled bundles.`];
177
182
  if (!use)
178
183
  noted.push("Use counts are zero: no usage history is available.");
184
+ if (!feedback)
185
+ noted.push("Feedback counts are zero: no feedback history is available.");
186
+ if (!result.groups)
187
+ noted.push("Groups by meaning and near-duplicates are not available: the last index stored no layout (it needs at least eight embedded assets).");
179
188
  return {
180
189
  available: true,
181
190
  note: noted.join(" "),
@@ -8,11 +8,13 @@
8
8
  */
9
9
  import { metricsWindow, readLlmRows, readUsageRows } from "../commands/metrics/metrics-cli.js";
10
10
  import { isRetireProposal } from "../commands/proposal/proposal-types.js";
11
+ import { resolveStashDir } from "../core/common.js";
12
+ import { USAGE_EVENT_RETENTION_DAYS } from "../indexer/usage/usage-events.js";
11
13
  import { readStateEvents } from "../storage/repositories/events-repository.js";
12
14
  import { listIndexCompletedEvents } from "../storage/repositories/metrics-repository.js";
13
15
  import { listStateProposals } from "../storage/repositories/proposals-repository.js";
14
16
  import { classifyOutcome, decidedAt, deciderOf, weekOf, weekRange } from "./derive.js";
15
- import { attempt, tryStashDir, withReadonlyStateDb } from "./readers.js";
17
+ import { attempt, withReadonlyStateDb } from "./readers.js";
16
18
  const DAY = 86_400_000;
17
19
  const FLAG_DAYS = 14;
18
20
  const COMPARE_DAYS = 28;
@@ -118,7 +120,7 @@ function harmLog(proposals, usage, reopened, sinceIso) {
118
120
  return items.sort((a, b) => b.at.localeCompare(a.at));
119
121
  }
120
122
  /** Before and after counts of how an asset was found and rated, around the day improve changed it. */
121
- function changedAssets(proposals, usage, now) {
123
+ function changedAssets(proposals, usage, now, usageSince) {
122
124
  const byRef = rowsByRef(usage);
123
125
  return proposals
124
126
  .filter((p) => (p.status === "accepted" || p.status === "reverted") && !isRetireProposal(p))
@@ -146,6 +148,8 @@ function changedAssets(proposals, usage, now) {
146
148
  afterDays,
147
149
  // Fewer than four weeks since the change: the "after" side is still filling.
148
150
  complete: afterDays >= COMPARE_DAYS,
151
+ // The "before" side starts earlier than the usage rows read (the window or the retention): it is not recorded.
152
+ beforeComplete: at - COMPARE_DAYS * DAY >= Date.parse(usageSince),
149
153
  };
150
154
  });
151
155
  }
@@ -174,9 +178,8 @@ export function improveImpact(input = {}) {
174
178
  const errors = {};
175
179
  // The store reads are what can fail (one malformed proposal row throws), so each degrades on its own; the
176
180
  // derivations below are pure functions of what was read.
177
- const stashDir = tryStashDir();
178
181
  const state = withReadonlyStateDb((db) => ({
179
- proposals: attempt(errors, "proposals", () => (stashDir ? listStateProposals(db, { stashDir, withContent: false }) : []), []),
182
+ proposals: attempt(errors, "proposals", () => listStateProposals(db, { stashDir: resolveStashDir(), withContent: false }), []),
180
183
  reopened: attempt(errors, "reopened", () => readStateEvents(db, { type: "proposal_reopened", since: window.since }).events, []),
181
184
  library: attempt(errors, "library", () => listIndexCompletedEvents(db, window.since, new Date(now + DAY).toISOString()), []),
182
185
  usage: attempt(errors, "usage", () => readUsageRows(db, window), []),
@@ -185,6 +188,9 @@ export function improveImpact(input = {}) {
185
188
  if (!state)
186
189
  return { available: false, since, errors };
187
190
  const { proposals, usage } = state;
191
+ // Usage rows older than their retention are purged on every index: the figures from them start no earlier.
192
+ const retainedFrom = new Date(now - USAGE_EVENT_RETENTION_DAYS * DAY).toISOString();
193
+ const usageSince = retainedFrom > window.since ? retainedFrom : window.since;
188
194
  const weeks = weekRange(window.since.slice(0, 10), new Date(now).toISOString().slice(0, 10));
189
195
  const lastPerWeek = new Map();
190
196
  for (const event of state.library) {
@@ -220,6 +226,9 @@ export function improveImpact(input = {}) {
220
226
  return {
221
227
  available: true,
222
228
  since,
229
+ /** Where the usage figures (flags, found and negative counts) start: the window, or later where retention cut them. */
230
+ usageSince,
231
+ usageComplete: retainedFrom <= window.since,
223
232
  weeks,
224
233
  summary: {
225
234
  kept: decided.filter((p) => p.status === "accepted").length,
@@ -234,7 +243,7 @@ export function improveImpact(input = {}) {
234
243
  library,
235
244
  harm,
236
245
  cost,
237
- changedAssets: changedAssets(proposals, usage, now),
246
+ changedAssets: changedAssets(proposals, usage, now, usageSince),
238
247
  judgeAndYou: judgeAndYou(proposals),
239
248
  ...(Object.keys(errors).length > 0 ? { errors } : {}),
240
249
  };
@@ -57,5 +57,5 @@ export function proposalBacklog(proposals, now) {
57
57
  }
58
58
  /** Activity per UTC day with the empty days inside the data's coverage filled in and partial days marked. */
59
59
  export function filledActivity(daily, window) {
60
- return zeroFill(daily, (day) => ({ day, search: 0, show: 0, curate: 0, feedback: 0 }), window);
60
+ return zeroFill(daily, (day) => ({ day, search: 0, show: 0, curate: 0, feedback: 0, rules: 0 }), window);
61
61
  }
@@ -3,9 +3,11 @@
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /** What people searched for and akm found nothing, grouped by query. */
5
5
  import { metricsWindow, readUsageRows } from "../commands/metrics/metrics-cli.js";
6
- import { withReadonlyStateDb } from "./readers.js";
6
+ import { stateDbUnavailable, withReadonlyStateDb } from "./readers.js";
7
+ /** An event the person made themselves, not an agent's, improve's or a task's. */
8
+ export const isUserEvent = (row) => row.source === "user";
7
9
  /** A search the user ran themselves, not a lookup of one asset and not an agent's search. */
8
- export const isUserSearch = (row) => row.eventType === "search" && row.ref === undefined && row.source === "user";
10
+ export const isUserSearch = (row) => row.eventType === "search" && row.ref === undefined && isUserEvent(row);
9
11
  const normalize = (query) => query.trim().replace(/\s+/g, " ").toLowerCase();
10
12
  /** The user's searches that found nothing, grouped by normalised query, repeats first then most recent. */
11
13
  export function missesFromRows(rows) {
@@ -32,9 +34,12 @@ export function missesFromRows(rows) {
32
34
  }
33
35
  export function searchMisses(input = {}) {
34
36
  const window = metricsWindow(input.since || "30d");
35
- const rows = withReadonlyStateDb((db) => readUsageRows(db, window), []);
37
+ const rows = withReadonlyStateDb((db) => readUsageRows(db, window), null);
38
+ if (!rows)
39
+ return stateDbUnavailable();
36
40
  const misses = missesFromRows(rows);
37
41
  return {
42
+ available: true,
38
43
  searches: rows.filter(isUserSearch).length,
39
44
  foundNothing: misses.reduce((sum, m) => sum + m.count, 0),
40
45
  misses,
@@ -0,0 +1,57 @@
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
+ * Links to assets that were renamed or moved on disk: which assets of a bundle still link to the old ref, with the
6
+ * new ref, and the rewrite of exactly those links. Both are `akm lint`'s `missing-ref` pass: the list is its
7
+ * findings that carry a new ref, the rewrite is its `fixMovedRefs` fix, so they never disagree with the CLI.
8
+ */
9
+ import path from "node:path";
10
+ import { akmLint } from "../commands/lint/index.js";
11
+ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
12
+ import { loadConfig } from "../core/config/config.js";
13
+ import { UsageError } from "../core/errors.js";
14
+ import { inspectWriteTarget } from "../core/write-source.js";
15
+ import { indexWrittenAssets } from "../indexer/index-written-assets.js";
16
+ import { resolveSourceEntries } from "../indexer/search/search-source.js";
17
+ import { interactive } from "./lease.js";
18
+ /** The akm bundles the sweep covers: lint reads other adapters' bundles through their own validators. */
19
+ function akmBundles(config, bundle) {
20
+ return resolveSourceEntries(undefined, config).flatMap((source) => {
21
+ if (!source.registryId || source.unresolved || (bundle !== undefined && source.registryId !== bundle))
22
+ return [];
23
+ return (source.adapterId ?? detectAdapterId(source.path)) === "akm" ? [{ name: source.registryId, source }] : [];
24
+ });
25
+ }
26
+ /** Per bundle, the links that name an old ref of an asset that moved: where, what is written, and where it points now. */
27
+ export async function movedLinks(input = {}) {
28
+ const config = loadConfig();
29
+ const bundles = [];
30
+ for (const { name, source } of akmBundles(config, input.bundle || undefined)) {
31
+ const found = await akmLint({ dir: source.path, rule: "missing-ref", config });
32
+ bundles.push({
33
+ bundle: name,
34
+ writable: source.writable === true,
35
+ writeBlocker: inspectWriteTarget(config, name).blocker,
36
+ links: found.flagged.flatMap((issue) => issue.movedFrom !== undefined && issue.movedTo !== undefined
37
+ ? [{ ref: issue.ref ?? issue.file, file: issue.file, from: issue.movedFrom, to: issue.movedTo }]
38
+ : []),
39
+ });
40
+ }
41
+ return { bundles, total: bundles.reduce((sum, bundle) => sum + bundle.links.length, 0) };
42
+ }
43
+ /** Rewrite the links to moved refs in one bundle, and nothing else. A read-only bundle is refused. */
44
+ export async function updateMovedLinks(input) {
45
+ const config = loadConfig();
46
+ const name = typeof input.bundle === "string" ? input.bundle.trim() : "";
47
+ const found = akmBundles(config, name || undefined)[0];
48
+ if (!name || !found)
49
+ throw new UsageError(`"${name}" is not a bundle of akm assets.`, "INVALID_FLAG_VALUE");
50
+ return interactive("ui-moved-links", async () => {
51
+ const result = await akmLint({ dir: found.source.path, fixMovedRefs: true, config });
52
+ const fixed = result.fixed.filter((issue) => issue.movedTo !== undefined);
53
+ const files = [...new Set(fixed.map((issue) => issue.file))];
54
+ await indexWrittenAssets(found.source.path, files.map((file) => path.join(found.source.path, file)), { bundleId: name });
55
+ return { bundle: name, rewritten: fixed.length, files };
56
+ });
57
+ }
@@ -0,0 +1,141 @@
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
+ * A new file in a folder of a bundle. akm types the folder (the indexer's own directory rules), starts the file with the
6
+ * text its type starts with (the workflow and task creators' own, the keys the type's validators require), and writes it
7
+ * through the writer every authored file goes through, so the same checks apply to every type. A folder with no type gets
8
+ * an empty file of the name given.
9
+ */
10
+ import fs from "node:fs";
11
+ import path from "node:path";
12
+ import { renderTaskYaml } from "../commands/tasks/tasks.js";
13
+ import { assertFlatAssetName, normalizeCreateSubPath } from "../core/asset/asset-create.js";
14
+ import { documentStashDirFor, refForFile } from "../core/asset/asset-placement.js";
15
+ import { serializeFrontmatter } from "../core/asset/asset-serialize.js";
16
+ import { frontmatterKeysFor } from "../core/asset/type-keys.js";
17
+ import { isWithin } from "../core/common.js";
18
+ import { loadConfig } from "../core/config/config.js";
19
+ import { UsageError } from "../core/errors.js";
20
+ import { appendEvent } from "../core/events.js";
21
+ import { resolveBundleWriteTarget } from "../core/mutation-target.js";
22
+ import { assertPlainWritable, assertWritableSource, commitWriteTargetBoundary, prepareWriteTargetForMutation, writeSourceFile, } from "../core/write-source.js";
23
+ import { indexWrittenAssets } from "../indexer/index-written-assets.js";
24
+ import { buildFileContext } from "../indexer/walk/file-context.js";
25
+ import { declaredTypeForPath } from "../indexer/walk/matchers.js";
26
+ import { buildWorkflowTemplate } from "../workflows/authoring/authoring.js";
27
+ import { folderBlocker, plainWriteBlocker } from "./file-actions.js";
28
+ import { interactive } from "./lease.js";
29
+ /** The extensions a new file may take, in the order a folder's type is tried when the name gives none. */
30
+ const EXTENSIONS = [".md", ".yml", ".sh"];
31
+ const typeAt = (relative) => declaredTypeForPath(buildFileContext("/", path.posix.join("/", relative)));
32
+ /** The file name a new file gets in `folder` and the type its place declares (null: none). `name` absent asks about the folder alone. */
33
+ export function planNewFile(folder, name) {
34
+ const candidates = name === undefined
35
+ ? EXTENSIONS.map((ext) => `new${ext}`)
36
+ : path.posix.extname(name)
37
+ ? [name]
38
+ : EXTENSIONS.map((ext) => `${name}${ext}`);
39
+ for (const fileName of candidates) {
40
+ const type = typeAt(path.posix.join(folder, fileName));
41
+ if (type !== undefined)
42
+ return { type, fileName: name === undefined ? undefined : fileName };
43
+ }
44
+ return { type: null, fileName: name };
45
+ }
46
+ /** The top-level folder akm's env and secret operations write to, and what a file made there is. */
47
+ const PROTECTED_FOLDERS = { env: "env", secrets: "secret" };
48
+ /**
49
+ * Whether a new file may be made in `folder` of the bundle, and the type it would have. Listings report it for the folder shown.
50
+ * A file made in the top-level `env/` or `secrets/` is an environment file or a secret, made through the protected editor
51
+ * (`through`), not by `documents.createFile`.
52
+ */
53
+ export function newFileVerdict(folder, blockers) {
54
+ const protectedType = PROTECTED_FOLDERS[folder];
55
+ if (protectedType !== undefined)
56
+ return blockers.plain === null
57
+ ? { allowed: true, type: protectedType, through: "protected-editor" }
58
+ : { allowed: false, reason: blockers.plain, type: protectedType };
59
+ const { type } = planNewFile(folder);
60
+ // A typed asset goes through akm's writer; a file of no type is a plain file.
61
+ const blocker = folderBlocker(folder) ?? blockers.plain ?? (type === null ? null : blockers.asset);
62
+ if (blocker !== null)
63
+ return { allowed: false, reason: blocker, type: null };
64
+ return type === "skill"
65
+ ? { allowed: false, reason: "A skill is a folder with a SKILL.md: create the folder first.", type }
66
+ : { allowed: true, type };
67
+ }
68
+ const humanize = (name) => name
69
+ .replace(/[-_]+/g, " ")
70
+ .replace(/\b\w/g, (letter) => letter.toUpperCase())
71
+ .trim() || "New file";
72
+ /** The text a new file of `type` starts with, from the owners that already create it. */
73
+ function startingText(type, stem) {
74
+ if (type === "workflow")
75
+ return buildWorkflowTemplate(stem);
76
+ if (type === "task")
77
+ return renderTaskYaml({ id: stem, schedule: "", command: 'echo "replace this command"' });
78
+ if (type === "script")
79
+ return "";
80
+ const asked = frontmatterKeysFor(type).filter((known) => known.required && known.stamped !== true);
81
+ const keys = Object.fromEntries(asked.map((known) => [known.key, known.key === "name" ? stem : ""]));
82
+ const frontmatter = Object.keys(keys).length > 0 ? `---\n${serializeFrontmatter(keys)}\n---\n\n` : "";
83
+ return `${frontmatter}# ${humanize(stem)}\n`;
84
+ }
85
+ function required(value, key) {
86
+ if (typeof value !== "string" || !value.trim())
87
+ throw new UsageError(`${key} is required.`);
88
+ return value.trim();
89
+ }
90
+ /** A new file in a folder, for any type. An existing file is refused. */
91
+ export async function createFile(input) {
92
+ const bundle = required(input.bundle, "bundle");
93
+ const name = required(input.name, "name");
94
+ assertFlatAssetName(name);
95
+ if (name === "." || name === ".." || name.includes("\0"))
96
+ throw new UsageError(`"${name}" is not a file name.`);
97
+ if (input.type !== undefined && input.folder !== undefined)
98
+ throw new UsageError("Name the folder or the type of the new file, not both.");
99
+ const typeFolder = input.type === undefined ? undefined : documentStashDirFor(input.type);
100
+ if (input.type !== undefined && typeFolder === undefined)
101
+ throw new UsageError(`akm keeps no folder of documents for the type "${input.type}".`);
102
+ const folder = normalizeCreateSubPath(typeFolder ?? input.folder);
103
+ if (typeof input.content !== "string" && input.content !== undefined)
104
+ throw new UsageError("content must be text.");
105
+ return interactive("ui-file-create", async () => {
106
+ const config = loadConfig();
107
+ const blocker = folderBlocker(folder) ?? plainWriteBlocker(config, bundle);
108
+ if (blocker !== null)
109
+ throw new UsageError(blocker);
110
+ const { type, fileName } = planNewFile(folder, name);
111
+ // A file of no type is a plain file; a typed asset goes through akm's writer, which takes akm bundles only.
112
+ const resolved = resolveBundleWriteTarget(config, bundle, { requireWritable: true });
113
+ const target = prepareWriteTargetForMutation(resolved, type === null ? { allowedAdapters: [resolved.source.adapterId ?? "akm"] } : undefined);
114
+ if (type === null)
115
+ assertPlainWritable(target.source, target.config);
116
+ else
117
+ assertWritableSource(target.source, target.config);
118
+ if (type === "skill" && fileName !== "SKILL.md")
119
+ throw new UsageError("A skill is a folder with a SKILL.md: create the folder first.");
120
+ const root = target.source.path;
121
+ const file = path.join(root, folder, fileName);
122
+ if (!isWithin(file, root))
123
+ throw new UsageError(`"${name}" resolves outside the bundle.`, "PATH_ESCAPE_VIOLATION");
124
+ if (fs.existsSync(file))
125
+ throw new UsageError("That file name is already used in this folder.", "RESOURCE_ALREADY_EXISTS");
126
+ const relative = path.posix.join(folder, fileName);
127
+ const stem = path.posix.basename(fileName, path.posix.extname(fileName));
128
+ const content = input.content ?? (type === null ? "" : startingText(type, stem));
129
+ writeSourceFile(target.source, file, content, relative, type ?? undefined);
130
+ commitWriteTargetBoundary(target, `Create ${relative}`);
131
+ const indexed = await indexWrittenAssets(root, [file], { bundleId: bundle });
132
+ const concept = type === null ? undefined : refForFile(type, root, file);
133
+ const ref = concept === undefined ? null : `${bundle}//${concept}`;
134
+ appendEvent({
135
+ eventType: "import",
136
+ ...(ref ? { ref } : {}),
137
+ metadata: { source: "-", path: file, force: false },
138
+ });
139
+ return { bundle, file: relative, type, ref, path: file, stashDir: root, indexed };
140
+ });
141
+ }
@@ -15,10 +15,10 @@ import { buildFileContext } from "../indexer/walk/file-context.js";
15
15
  import { declaredTypeForPath } from "../indexer/walk/matchers.js";
16
16
  import { listStateProposals } from "../storage/repositories/proposals-repository.js";
17
17
  import { classifyOutcome, decidedAt, weekOf } from "./derive.js";
18
- import { readBundleGitStatus, readRecentCommits } from "./git-read.js";
18
+ import { readRecentCommits } from "./git-read.js";
19
19
  import { interactive } from "./lease.js";
20
20
  import { PROPOSAL_AGE_BANDS, proposalAgeBand, proposalBacklog } from "./metrics.js";
21
- import { capSide, clampLimit, withReadonlyStateDb } from "./readers.js";
21
+ import { capSide, clampLimit, stateDbUnavailable, withReadonlyStateDb } from "./readers.js";
22
22
  const MAX_REJECT_REASON = 2000;
23
23
  const MAX_BATCH_IDS = 200;
24
24
  function summary(proposal) {
@@ -76,7 +76,7 @@ export function list(input = {}) {
76
76
  if (outcome && !["judge", "you", "unknown", "rejected", "reverted"].includes(outcome))
77
77
  throw new UsageError("Invalid outcome class.", "INVALID_FLAG_VALUE");
78
78
  const now = Date.now();
79
- return withReadonlyStateDb((db) => {
79
+ return (withReadonlyStateDb((db) => {
80
80
  // A list shows summaries, so the proposed content is not read.
81
81
  const all = listStateProposals(db, { stashDir: resolveStashDir(), withContent: false });
82
82
  const picked = status === "pending"
@@ -94,6 +94,7 @@ export function list(input = {}) {
94
94
  (!week || weekOf(decidedAt(p)) === week) &&
95
95
  (!outcome || classifyOutcome(p) === outcome));
96
96
  return {
97
+ available: true,
97
98
  status,
98
99
  totalCount: filtered.length,
99
100
  fullCount: picked.length,
@@ -101,7 +102,7 @@ export function list(input = {}) {
101
102
  backlog: proposalBacklog(picked, now),
102
103
  proposals: filtered.slice(0, limit).map(summary),
103
104
  };
104
- }, { status, totalCount: 0, fullCount: 0, bySource: {}, backlog: [], proposals: [] });
105
+ }, null) ?? stateDbUnavailable());
105
106
  }
106
107
  /** True when the proposal's target is an env or secret asset, whose content never leaves the machine's files via the UI. */
107
108
  function targetsSensitiveAsset(proposal) {
@@ -174,37 +175,16 @@ export function get(input) {
174
175
  export async function recentChanges(input = {}) {
175
176
  const limit = clampLimit(input.limit);
176
177
  const target = resolveWriteTarget(loadConfig(), undefined, { requireWritable: false });
177
- const commits = await readRecentCommits(target.source.path, limit);
178
+ const read = await readRecentCommits(target.source.path, limit);
178
179
  return {
179
180
  bundle: target.source.name,
180
181
  path: target.source.path,
181
- git: commits !== null,
182
- commits: commits ?? [],
182
+ git: read !== null,
183
+ commits: read?.commits ?? [],
184
+ ...(read?.error ? { error: read.error } : {}),
183
185
  };
184
186
  }
185
- /**
186
- * The commit an accept just made, if any. The accept functions do not return it,
187
- * so read the head commit of each accepted proposal's repository and keep one
188
- * that carries akm's accept subject and is newer than the request. `null` for a
189
- * bundle that is not a git repository (nothing was committed).
190
- */
191
- async function acceptCommit(accepted, startedMs) {
192
- const roots = new Set();
193
- for (const result of accepted) {
194
- const root = result.proposal.acceptedTarget?.root;
195
- if (root)
196
- roots.add(root);
197
- }
198
- for (const root of roots) {
199
- const last = (await readBundleGitStatus(root))?.lastCommit;
200
- if (!last || !/^akm (?:proposal )?accept:/.test(last.subject))
201
- continue;
202
- if (Date.parse(last.time) < startedMs - 2000)
203
- continue;
204
- return { ...last, repo: root };
205
- }
206
- return null;
207
- }
187
+ // ── Decisions ────────────────────────────────────────────────────────────────
208
188
  function acceptedView(result) {
209
189
  return { ...result, proposal: summary(result.proposal) };
210
190
  }
@@ -229,13 +209,9 @@ function batchIds(ids) {
229
209
  }
230
210
  return [...new Set(ids.map((id) => id.trim()))];
231
211
  }
232
- /** Accept one proposal exactly as `akm proposal accept` does, and report the commit it made. */
212
+ /** Accept one proposal exactly as `akm proposal accept` does; the result carries the commit it made, or why none. */
233
213
  export async function accept(input) {
234
- return interactive("ui-proposal-accept", async () => {
235
- const startedMs = Date.now();
236
- const result = await akmProposalAccept({ id: input.id });
237
- return { ...acceptedView(result), commit: await acceptCommit([result], startedMs) };
238
- });
214
+ return interactive("ui-proposal-accept", async () => acceptedView(await akmProposalAccept({ id: input.id })));
239
215
  }
240
216
  export async function reject(input) {
241
217
  const reason = rejectReason(input.reason);
@@ -286,14 +262,12 @@ export async function rejectMany(input) {
286
262
  export async function acceptMany(input) {
287
263
  const ids = batchIds(input.ids);
288
264
  return interactive("ui-proposal-accept", async () => {
289
- const startedMs = Date.now();
290
265
  const results = await akmProposalAcceptMany({ ids });
291
266
  const accepted = results.filter((r) => r.ok);
292
267
  return {
293
268
  accepted: accepted.length,
294
269
  failed: results.length - accepted.length,
295
270
  results: results.map((r) => (r.ok ? acceptedView(r) : { ...r, code: r.code ?? "ACCEPT_FAILED" })),
296
- commit: accepted.length > 0 ? await acceptCommit(accepted, startedMs) : null,
297
271
  };
298
272
  });
299
273
  }