akm-cli 0.10.261128 → 0.10.261129-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/cli.js +2 -0
  3. package/dist/commands/agent/contribute-cli.js +7 -1
  4. package/dist/commands/backups-cli.js +103 -0
  5. package/dist/commands/health.js +1 -34
  6. package/dist/commands/improve/reflect-noise.js +0 -1
  7. package/dist/commands/lint/base-linter.js +24 -48
  8. package/dist/commands/lint/bundle-skip.js +27 -0
  9. package/dist/commands/lint/index.js +83 -45
  10. package/dist/commands/lint/tracked-secrets.js +43 -0
  11. package/dist/commands/lint/types.js +58 -0
  12. package/dist/commands/proposal/repository.js +5 -1
  13. package/dist/commands/sources/stash-skeleton.js +7 -26
  14. package/dist/core/adapter/adapters/akm-adapter.js +2 -2
  15. package/dist/core/adapter/adapters/akm-workflow-adapter.js +6 -1
  16. package/dist/core/adapter/adapters/shared.js +13 -25
  17. package/dist/core/asset/lint-text.js +14 -13
  18. package/dist/core/asset/stale-path.js +63 -0
  19. package/dist/core/config/schema/sources-bundles.js +3 -0
  20. package/dist/output/shapes/passthrough.js +1 -0
  21. package/dist/output/text/lint-format.js +90 -1
  22. package/dist/output/text/migrate.js +5 -0
  23. package/dist/scripts/akm-migrate-node.js +1149 -791
  24. package/dist/scripts/akm-migrate.js +1149 -791
  25. package/dist/sources/include.js +1 -1
  26. package/dist/sources/snapshot-fetchers/website-ingest.js +0 -2
  27. package/dist/workspace/backups.js +21 -0
  28. package/dist/workspace/cli-child.js +5 -1
  29. package/dist/workspace-node.mjs +2 -0
  30. package/dist/workspace.d.ts +4 -0
  31. package/dist/workspace.js +1 -0
  32. package/docs/architecture/internals/health-advisories.md +1 -2
  33. package/docs/guides/bundles.md +5 -4
  34. package/docs/integration/bundling-akm.md +9 -1
  35. package/docs/reference/asset-types.md +1 -2
  36. package/docs/reference/cli.md +83 -3
  37. package/docs/reference/configuration.md +8 -2
  38. package/docs/reference/data-and-telemetry.md +1 -0
  39. package/docs/reference/env-and-secrets.md +9 -4
  40. package/docs/reference/website-sources.md +2 -2
  41. package/docs/reference/workspace.md +1 -0
  42. package/package.json +1 -1
  43. package/schemas/akm-config.json +34 -0
  44. package/dist/commands/health/stash-exposure.js +0 -64
@@ -83,7 +83,7 @@ function isIncludeEntryPattern(entry) {
83
83
  * negation); those fall through to being treated as a literal, almost
84
84
  * certainly non-matching path, same as an ordinary typo would.
85
85
  */
86
- function includeEntryToRegExp(entry) {
86
+ export function includeEntryToRegExp(entry) {
87
87
  const normalized = entry.split(path.sep).join("/");
88
88
  let pattern = "";
89
89
  for (let i = 0; i < normalized.length;) {
@@ -921,8 +921,6 @@ function buildMarkdownSnapshot(page, slug, tags) {
921
921
  `sourceUrl: ${JSON.stringify(page.url)}`,
922
922
  `title: ${JSON.stringify(title)}`,
923
923
  `updated: ${todayIso()}`,
924
- "lint_skip:",
925
- " - stale-path",
926
924
  "tags:",
927
925
  ...normalizedTags.map((tag) => ` - ${JSON.stringify(tag)}`),
928
926
  "---",
@@ -0,0 +1,21 @@
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
+ /** The old backups akm keeps in its data directory. */
5
+ import { UsageError } from "../core/errors.js";
6
+ import { runCli } from "./cli-child.js";
7
+ /**
8
+ * `akm backups prune`: remove backups older than `olderThan` (a duration such as `30d`; default 30d), keeping the newest
9
+ * of each folder. `dryRun` reports what would be removed and removes nothing; a real run needs `confirm`.
10
+ */
11
+ export async function prune(input = {}) {
12
+ const dryRun = input.dryRun === true;
13
+ if (!dryRun && input.confirm !== true)
14
+ throw new UsageError("Confirm removing the old backups first.");
15
+ return runCli([
16
+ "backups",
17
+ "prune",
18
+ ...(dryRun ? ["--dry-run"] : ["--yes"]),
19
+ ...(input.olderThan ? [`--older-than=${input.olderThan}`] : []),
20
+ ]);
21
+ }
@@ -88,7 +88,11 @@ export async function runCli(args, input, userFeedback = false) {
88
88
  return;
89
89
  }
90
90
  try {
91
- resolve(parseCommandResponse(stdout, args[0] === "bundle" ? bundleShape(args[1]) : args[0] === "task" ? `task-${args[1]}` : args[0]));
91
+ resolve(parseCommandResponse(stdout, args[0] === "bundle"
92
+ ? bundleShape(args[1])
93
+ : args[0] === "task" || args[0] === "backups"
94
+ ? `${args[0]}-${args[1]}`
95
+ : args[0]));
92
96
  }
93
97
  catch (error) {
94
98
  reject(error);
@@ -16,6 +16,7 @@ const {
16
16
  UsageError,
17
17
  activity,
18
18
  assets,
19
+ backups,
19
20
  bundles,
20
21
  config,
21
22
  documents,
@@ -37,6 +38,7 @@ export {
37
38
  UsageError,
38
39
  activity,
39
40
  assets,
41
+ backups,
40
42
  bundles,
41
43
  config,
42
44
  documents,
@@ -107,6 +107,10 @@ export namespace assets {
107
107
  function searchMisses(input?: { since?: string }): unknown;
108
108
  function show(input: { ref: string }): Promise<unknown>;
109
109
  }
110
+ export namespace backups {
111
+ /** `akm backups prune`: remove backups older than `olderThan` (default 30d), keeping the newest of each folder. A real run needs `confirm`; `dryRun` removes nothing. */
112
+ function prune(input?: { olderThan?: string; dryRun?: boolean; confirm?: boolean }): Promise<Record<string, unknown>>;
113
+ }
110
114
  export namespace bundles {
111
115
  function add(input: { source: string; name?: string; writable?: boolean }): Promise<unknown>;
112
116
  function list(): Promise<unknown>;
package/dist/workspace.js CHANGED
@@ -10,6 +10,7 @@ export { AkmError, CONFLICT_CODES, ConfigError, NotFoundError, TransientError, U
10
10
  export { indexWrittenAssets } from "./indexer/index-written-assets.js";
11
11
  export * as activity from "./workspace/activity.js";
12
12
  export * as assets from "./workspace/assets.js";
13
+ export * as backups from "./workspace/backups.js";
13
14
  export * as bundles from "./workspace/bundles.js";
14
15
  export * as config from "./workspace/config.js";
15
16
  export * as documents from "./workspace/documents.js";
@@ -80,12 +80,11 @@ says so in the message (`remoteUnavailable` in the evidence) and is `unknown`, n
80
80
  | `scheduler-binary` | `warn`: the akm binary recorded in the scheduler reports a different version than the running CLI. `unknown`: `--no-probe`, no scheduled task installed, no scheduler binary on this host (no `crontab`), or the recorded binary cannot be run. | Run `akm doctor scheduler sync` to rebind the schedule. |
81
81
  | `cli-usage-store` | `warn`: `metrics.db`, which holds the CLI usage tables (`cli_usage_meta`, `cli_usage_invocations`, `cli_usage_aggregates`), exists but cannot be read. Usage capture is fail-open, so an unreadable store stops collection without failing any command; this check is the only signal. Silent when the file is absent or readable. It never recreates the tables. | Move or delete `metrics.db` to restart collection. |
82
82
  | `index-state-generation` | `warn`: usage links in state.db point at index entries that no longer match (an index and state.db from different generations). | Stop concurrent writers and run `akm index --full`. |
83
- | `stash-git-exposure` | `warn`, one per bundle: `env/` or `secrets/` files are tracked by git in a configured bundle (the working stash included) and that bundle has a remote. Skipped for a bundle with no `.git` at its root. | Run `git rm --cached` on the listed files and add `env/` and `secrets/` to `.gitignore`. A `.gitignore` rule alone does not untrack files. To keep tracking them on purpose, add `# akm: intentionally track env and secrets` to the stash `.gitignore`; the advisory is then not reported. |
84
83
  | `binary-config-skew` | `warn`: `config.json` has a `configVersion` newer than this binary knows. | Upgrade this install. |
85
84
  | `egress-endpoints` | Every remote destination in the effective config, as one informational entry: enabled registries, git and website bundles, each connection's endpoint and the embedding endpoint (credentials in a URL are masked). Silent when nothing remote is configured. | Eyeball it against what you expect; a destination you did not configure came from an `extends` base or a shared bundle. |
86
85
  | `type-directory-disagreement` | `warn`: an indexed asset's resolved type differs from the type its directory declares. Each line gives the file, both types, and the classifier signal that won (`winner`). | Review the listed files. Explicit frontmatter overrides (for example `agent:` declaring a command) are marked `known-good override`. A body mention of `$ARGUMENTS` is not command intent; run `akm index` to repair old classifications without editing the documents. |
87
86
  | `memory-cleanup-archive` | `pass` with size and file count when the working bundle has `.akm/memory-cleanup/archive` content and no git history (the purge does not run there). `warn` when a git-backed bundle has archived files the purge cannot remove (untracked, modified, or unverifiable in git). | Commit the archived files so the purge can remove them once they age out. |
88
- | `data-dir-usage` | `warn`: the data directory is over 1 GB and either more than 3 times the size of `state.db`, `index.db`, and `logs.db` (with their WAL and SHM files), or one top-level subdirectory holds more than half of it. The message names that subdirectory and its size. | Inspect the named subdirectory. `backups/tasks/` holds task-file snapshots written by `akm migrate apply`. |
87
+ | `data-dir-usage` | `warn`: the data directory is over 1 GB and either more than 3 times the size of `state.db`, `index.db`, and `logs.db` (with their WAL and SHM files), or one top-level subdirectory holds more than half of it. The message names that subdirectory and its size. | Inspect the named subdirectory. `backups/tasks/` holds task-file snapshots written by `akm migrate apply`; `akm backups prune --dry-run` shows how much the old ones would free. |
89
88
  | `plugin-version` | One row per native `claude plugin list --json` AKM installation, with scope, enabled state and install path; cached versions are never used to choose an installation. Disabled and other-project installations are inert. Missing metadata or multiple applicable paths/versions produce `unknown`, since the native list does not identify which conflicting installation a running session loaded. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. The newest-tag lookup is `--probe`-gated: with `--no-probe` the row is `unknown` ("not probed"); a lookup that fails (offline) is `unknown` and says the remote could not be read. The plugin runs the `akm-cli` its `package.json` pins (`dependencies["akm-cli"]`, an exact version), never an `akm` on `PATH`, and that copy shares the host's databases with the running CLI, so the pin is compared locally whatever `--probe` says: `pinnedCliVersion` and `cliMatches` in the evidence, `unknown` when the manifest has no exact pin. `warn`: the plugin is stale, or its pin differs from the running CLI — the message says which side is older. | A stale plugin: run the `claude plugin update <ref>` command in the message. A pin newer than the CLI: `akm upgrade`. A pin older than the CLI on a plugin that is current on its channel: nothing to update until that channel publishes a build for the running akm. |
90
89
  | `codex-plugin-version` | The same for Codex, when its `config.toml` registers the `akm-plugins` marketplace: the installed version from `codex plugin list --marketplace akm-plugins --json`, and the newest release on the channel the marketplace entry's `ref` follows (none or `main`: the newest stable tag; `next`: the tag at that branch's head; a tag: that release), read with `git ls-remote` against `https://github.com/itlackey/akm-plugins` (`--probe`-gated; a failed read says so). `unknown` when `codex` is not on `PATH` or the listing fails; omitted when the marketplace is not registered or the plugin is not installed. Codex gives no path to the plugin's files, so its `akm-cli` pin is not compared. | Run `codex plugin marketplace upgrade akm-plugins`. |
91
90
  | `opencode-plugin-version` | The OpenCode plugin's bundled `akm-cli`, read from its `package.json`, never executed. Both OpenCode checks require a configured plugin: cached files alone do not establish an installation. OpenCode 1 reads the configured `plugin` spec's cache (`akm-opencode` means `akm-opencode@latest`); only a configured bare name may fall back to the legacy `packages/akm-opencode` folder. A missing configured spec never selects another cache. OpenCode 1 exact version pins are reported as pinned with no staleness verdict. OpenCode 2 (`opencode-v2-plugin-version`) reads `npm/<spec>/<newest build>/node_modules` for the configured `plugins` or `plugin` spec (`akm-opencode-v2` means `@latest`), ignoring every other spec; its bundled CLI is compared with the host CLI even for exact pins. These local checks are not `--probe`-gated. `warn`: the bundled version differs from the running CLI; the message says which side is older. Omitted with no configured plugin or readable matching cache. | Bundled akm-cli newer than the CLI: `akm upgrade`. Older: update the plugin once its channel publishes a build for the running akm (`akm upgrade` checks and updates it). |
@@ -176,10 +176,11 @@ bundle keeps its previous contents and index. If an update is interrupted, rerun
176
176
  `akm bundle update <name>`, then `akm doctor`, and `akm index --full` if health
177
177
  reports an index or state mismatch.
178
178
 
179
- New bundles get a `.gitignore` that keeps `env/` and `secrets/` out of git. A
180
- private bundle that versions them on purpose can put
181
- `# akm: intentionally track env and secrets` anywhere in its root `.gitignore`
182
- and akm leaves the file alone.
179
+ New bundles get `env/` and `secrets/` lines in their `.gitignore` (added only
180
+ when the file mentions neither), and akm's own commits follow git. `akm lint`
181
+ reports an `env/` or `secrets/` file that git tracks in a bundle with a remote
182
+ as `tracked-secrets`; a private bundle that versions them on purpose lists
183
+ `"tracked-secrets": ["**"]` under `lint.skip` in its config entry.
183
184
 
184
185
  **Example: keep bundles fresh**
185
186
 
@@ -59,7 +59,13 @@ In order, every run applies (or, under `status`/`--dry-run`, plans):
59
59
  `WORK/x`), in frontmatter and body, rewritten under one backup directory per
60
60
  run. An old spelling that is now another file's ref is listed in `shadowed`
61
61
  and left as written.
62
- 6. **Residue sweep**: superseded pre-0.9.0 `.akm` files in the stash and the
62
+ 6. **Bundle policy** (`bundlePolicy`): in each writable bundle, `lint_skip:`
63
+ frontmatter is stripped from the assets, and a `.gitignore` carrying the old
64
+ `# akm: intentionally track env and secrets` marker adds
65
+ `"tracked-secrets": ["**"]` to the bundle's `lint.skip`. `.gitignore` is
66
+ never modified. The config is written first, the files then under one
67
+ backup directory per run.
68
+ 7. **Residue sweep**: superseded pre-0.9.0 `.akm` files in the stash and the
63
69
  transaction-journal, maintenance-barrier, lock-mutex and version-stamp
64
70
  files older releases kept under `$DATA`/`$STATE`/`$CONFIG` (`deadResidue`).
65
71
 
@@ -80,6 +86,7 @@ same step names):
80
86
  "taskFiles": { "schemaVersion": 1, "changed": 0, "skipped": 0, "blocked": 0, "files": [] },
81
87
  "assetEngineKeys": { "schemaVersion": 1, "changed": 0, "skipped": 0, "files": [] },
82
88
  "assetContentRefs": { "schemaVersion": 1, "changed": 0, "skipped": 0, "refs": 0, "files": [], "shadowed": [] },
89
+ "bundlePolicy": { "schemaVersion": 1, "changed": 0, "bundles": [], "notes": [] },
83
90
  "deadResidue": { "pending": [] }
84
91
  }
85
92
  ```
@@ -133,6 +140,7 @@ Key fields:
133
140
  | `taskFiles` | `changed`/`skipped`/`blocked` counts and a `files[]` array with each file's `status` and `reason`. |
134
141
  | `assetEngineKeys` | `changed`/`skipped` counts and a `files[]` array with each rewritten file's `rewrites` (`at`, `from`, `to`). |
135
142
  | `assetContentRefs` | `changed`/`skipped` file counts, `refs` (old-spelling refs found), a `files[]` array with each file's `refs`, and `shadowed[]` (`bundleId`, `from`, `to`): old spellings another file holds as its ref, not rewritten; and `reconcile[]`, present after an apply that rewrote files inside a git checkout: the checkout path and how to review, commit or restore the edits. Only asset files, `index.md` and wiki `schema.md` are rewritten. |
143
+ | `bundlePolicy` | `changed` (files to rewrite plus bundles whose config gains the skip), `bundles[]` (`bundleId`, `stripped`: assets whose `lint_skip` is removed, `skipTrackedSecrets`), and `notes[]`: a bundle with the marker and no config entry. After a real apply: `applied`, and `backupPath` when files were rewritten. |
136
144
  | `backupPath` / `applied` | Present after a real apply that rewrote at least one task file: the run's backup directory and how many files it rewrote. |
137
145
  | `deadResidue` | `{ pending: [...] }` under a read-only run, `{ removed: [...] }` after apply. Each entry carries `relativePath` and `sizeBytes`; a removal entry adds `removed` (a boolean) and an `error` when the delete failed. A failed delete does not set `status` to `blocked`. |
138
146
 
@@ -132,8 +132,7 @@ root-scoped: a nested `.scratch/` is ordinary content, and the existing
132
132
  `akm bundle create` (and `akm setup`, which reuses it) creates
133
133
  `.scratch/README.md` and adds `/.scratch/` to `.gitignore`. Re-running it
134
134
  restores a missing README or rule without touching existing scratch files or a
135
- customized README; the Git ignore rule is added even when the secret-ignore
136
- block or its track-secrets opt-out is present. Existing bundles work without
135
+ customized README. Existing bundles work without
137
136
  the directory, and reads never create it. Index exclusion is independent of Git
138
137
  tracking: ignoring `.scratch/` does not untrack files already committed.
139
138
 
@@ -2622,7 +2622,15 @@ in order:
2622
2622
  and is listed in `assetContentRefs.shadowed`. JSON, plain text, scripts and
2623
2623
  other files are never read or rewritten, so frozen corpora and captured
2624
2624
  results stay byte-for-byte, and a second run changes nothing;
2625
- 6. superseded residue removed (`deadResidue`): pre-0.9.0 `.akm` leftovers in
2625
+ 6. stale bundle policy removed from files (`bundlePolicy`), in writable
2626
+ bundles: an asset's `lint_skip:` frontmatter is stripped (lint skips live in
2627
+ the bundle's `lint.skip` config), and a `.gitignore` with the old
2628
+ `# akm: intentionally track env and secrets` line adds
2629
+ `"tracked-secrets": ["**"]` to that bundle's `lint.skip`. `.gitignore` is
2630
+ never modified. The config is written first (its own backup), then the
2631
+ files under one backup directory per run. A bundle with that line and no
2632
+ config entry is listed in `bundlePolicy.notes`;
2633
+ 7. superseded residue removed (`deadResidue`): pre-0.9.0 `.akm` leftovers in
2626
2634
  the stash, and the transaction-journal, maintenance-barrier, lock-mutex and
2627
2635
  version-stamp files older releases kept under `$DATA`, `$STATE` and
2628
2636
  `$CONFIG`.
@@ -2658,6 +2666,32 @@ forces `status: "blocked"` and adds a matching line to `blockers`, so
2658
2666
  `akm migrate status|apply` reports the plan and exits 1 (not the internal-error
2659
2667
  70) the same way it does for any other blocked plan.
2660
2668
 
2669
+ ### backups prune
2670
+
2671
+ Remove old backups from the data directory. `akm migrate apply` copies each
2672
+ file into `backups/<folder>/<timestamp>-<id>/` (`tasks`, `asset-engine-keys`,
2673
+ `asset-content-refs`) before it rewrites it, and nothing deletes those copies
2674
+ later; `akm health` reports a `backups/` that has grown large (`data-dir-usage`).
2675
+ Nothing reads an old backup back at run time, so removing one only gives up
2676
+ restoring that run by hand.
2677
+
2678
+ ```sh
2679
+ akm backups prune --dry-run # what would go, nothing removed
2680
+ akm backups prune # prompts; --yes skips the prompt
2681
+ akm backups prune --older-than 7d --yes
2682
+ ```
2683
+
2684
+ | Flag | Meaning |
2685
+ | --- | --- |
2686
+ | `--older-than <duration>` | Remove entries last modified longer ago than this (`30d`, `12h`, `3M`; default `30d`). |
2687
+ | `--dry-run` | Report the same result and remove nothing. |
2688
+ | `--yes`, `-y` | Skip the confirmation prompt, which a non-interactive run requires. |
2689
+
2690
+ The newest entry of each folder is always kept, however old, so the latest
2691
+ rollback point survives. The result is `{dryRun, olderThan, cutoff, count, bytes,
2692
+ folders: [{folder, count, bytes, kept}]}`: what was removed (or would be) in
2693
+ total and per folder. A missing `backups/` directory is nothing to prune.
2694
+
2661
2695
  ### config
2662
2696
 
2663
2697
  Read and write configuration. Bare `akm config` runs `akm config list`.
@@ -3302,6 +3336,7 @@ akm lint --type workflows # Only lint one asset type
3302
3336
  akm lint --dir ~/other-bundle # Override the bundle root (default: from config)
3303
3337
  akm lint --fail-on-flagged # CI-friendly: exit non-zero when summary.flagged > 0
3304
3338
  akm lint --prune-dangling-edges # Opt-in: drop belief edges whose target is gone
3339
+ akm lint --rule stale-path # List one rule's findings, grouped by asset
3305
3340
  ```
3306
3341
 
3307
3342
  | Argument or flag | Description |
@@ -3310,12 +3345,57 @@ akm lint --prune-dangling-edges # Opt-in: drop belief edges whose target is gone
3310
3345
  | `--fix` (alias `--auto-fix`) | Apply auto-fixes in place. Refused with a usage error when the target bundle is configured `writable: false`. |
3311
3346
  | `--dir` | Override the bundle root directory (default: from config) |
3312
3347
  | `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`). **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
3348
+ | `--rule` | List this rule's findings grouped by asset: the asset ref and file, then each finding with its line, path, reason, nearest existing directory and line text. Combines with `--type`. A listing: it cannot combine with `--fix` or `--prune-dangling-edges`. An unknown rule name warns and shows every rule. |
3313
3349
  | `--fail-on-flagged` | Exit non-zero when `summary.flagged > 0`. Default: exit 0 regardless of findings. |
3314
3350
  | `--prune-dangling-edges` | Opt-in repair (#884): drop `supersededBy`/`contradictedBy` entries whose target has neither a file nor a prune tombstone. **Not** implied by `--fix` — it edits well-formed files to delete a belief-graph claim, so review a plain `akm lint` report first. Clears the same `writable: false` gate `--fix` does. |
3315
3351
 
3316
3352
  Returns `fixed[]` and `flagged[]` arrays plus a `summary: { fixed, flagged }`
3317
- count. Each entry carries `file`, `issue`, `detail`, and whether it was
3318
- `fixed`.
3353
+ count and `byRule: { <rule>: { findings, assets } }` for the flagged findings.
3354
+ Each entry carries `file`, `issue`, `detail`, whether it was `fixed`, and, for
3355
+ a finding about one asset of the bundle, its `ref`.
3356
+
3357
+ The default text output is one line per rule: its findings and assets, the
3358
+ three folders holding most of them, whether `--fix` fixes it, and how to fix
3359
+ it. `akm lint --rule <rule>` lists that rule's findings.
3360
+
3361
+ ```
3362
+ stale-path: 41 findings in 12 assets; memories (30), knowledge/guides (11); --fix does not fix it; correct the path; ...
3363
+ ```
3364
+
3365
+ `stale-path` reports an absolute path in an asset that does not exist, so an
3366
+ agent can find it and correct it. It judges only paths this machine can check:
3367
+ under the current user's home, under a configured bundle or project root
3368
+ (`projects`), and under `/tmp`. Paths under `/opt`, `/var`, `/etc`, `/root` or
3369
+ another user's home are not checked unless they sit under a bundle or project
3370
+ root. A line that says it records the past or an example ("historically",
3371
+ "formerly", "for example", "e.g.") and a section under a History, Changelog,
3372
+ Archive or Examples heading are skipped, as are run-time filename templates
3373
+ (`<stamp>`, `{stamp}`, `YYYYMMDD`, globs). Each finding carries `ref`, `file`,
3374
+ `line` (1-based, in the file), `path`, `lineText`, `nearestExisting` (the
3375
+ deepest existing directory above the path) and `reason`: `missing` for a path
3376
+ under the home, a bundle or a project, `ephemeral` for a `/tmp` path that no
3377
+ longer exists. To clear a finding, correct the path, or say on the line that it
3378
+ records the past or an example, or move it under a History or Examples heading.
3379
+
3380
+ `tracked-secrets` flags each `env/` or `secrets/` file that git tracks in a
3381
+ bundle that has a remote (a push can leak it); `git rm --cached` the file.
3382
+
3383
+ `missing-updated` does not apply to skills. `redacted-content` ignores
3384
+ `[REDACTED]` in code (fenced, indented and inline), quotes and table cells.
3385
+
3386
+ A bundle skips a rule for some of its assets in its config entry:
3387
+ `lint.skip` maps any rule lint reports to globs matched against the path
3388
+ relative to the bundle root, where `**` is the whole bundle. A rule name lint
3389
+ does not know is warned about once and ignored.
3390
+
3391
+ ```json
3392
+ "bundles": {
3393
+ "docs": {
3394
+ "path": "~/docs",
3395
+ "lint": { "skip": { "stale-path": ["skills/sec/**", "knowledge/articles/**"], "tracked-secrets": ["**"] } }
3396
+ }
3397
+ }
3398
+ ```
3319
3399
 
3320
3400
  Task files are checked for more than their fields: a `tasks/*.yml` whose YAML
3321
3401
  does not parse is reported as `invalid-task-yaml` (it used to fall through as an
@@ -656,7 +656,7 @@ that rule's default list, and `[]` turns the rule off.
656
656
  |---|---|---|
657
657
  | `placeholders` | `placeholder_added` | `please confirm`, `please verify`, `to be confirmed`, `to be determined`, `to be verified` |
658
658
  | `metaCommentary` | `meta_commentary_added` | `feedback signal`, `feedback signals`, `feedback indicate`, `feedback indicates`, `feedback suggest`, `feedback suggests`, `feedback ask`, `feedback asks`, `feedback says`, `feedback report`, `feedback reports`, `feedback request`, `feedback requests`, `this revision`, `the source asset`, `the source note`, `the source memory`, `the original asset`, `the original note`, `the original memory`, `the original version of this`, `quality gate rejected`, `proposal rejected` |
659
- | `frontmatterKeys` | `frontmatter_copied_into_body` | `sources`, `updated`, `inferenceProcessed`, `captureMode`, `beliefState`, `xrefs`, `contradictedBy`, `outcomeData`, `orderedActions`, `generated`, `verified`, `description`, `when_to_use`, `tags`, `searchHints`, `quality`, `salience`, `salienceInputs`, `lint_skip`, `type` |
659
+ | `frontmatterKeys` | `frontmatter_copied_into_body` | `sources`, `updated`, `inferenceProcessed`, `captureMode`, `beliefState`, `xrefs`, `contradictedBy`, `outcomeData`, `orderedActions`, `generated`, `verified`, `description`, `when_to_use`, `tags`, `searchHints`, `quality`, `salience`, `salienceInputs`, `type` |
660
660
 
661
661
  `placeholders` and `metaCommentary` entries are plain phrases, not patterns:
662
662
  whole words, in any case, with any run of whitespace between words.
@@ -915,11 +915,17 @@ the key is ignored, and enables nothing; `akm migrate apply` drops it.
915
915
  and `defaultBundle` are the 0.9 source configuration shape — see
916
916
  [Concepts](../guides/concepts.md) and the [CLI reference](cli.md) for the
917
917
  full bundle model (`path`, `git`, `website`, `npm`, `writable`, `registryId`,
918
- `components`). `defaultBundle` must name a key in `bundles` when set. A
918
+ `components`, `lint`). `defaultBundle` must name a key in `bundles` when set. A
919
919
  bundle's `components.<id>.adapter` key pins it to a specific format adapter
920
920
  instead of relying on auto-detection — see [Bundle Types](bundle-types.md)
921
921
  for the full adapter list and what each one reads/writes.
922
922
 
923
+ A bundle entry also carries the lint policy for its own files:
924
+
925
+ | Key | Purpose |
926
+ | --- | --- |
927
+ | `lint.skip` | `{ "<rule>": ["<glob>", ...] }`: lint skips the rule for files whose bundle-relative path matches a glob (`**` is the whole bundle), for example `"stale-path": ["skills/sec/**"]` or `"tracked-secrets": ["**"]`. Any rule `akm lint` reports can be skipped. See [`akm lint`](cli.md#lint). A rule name lint does not know is warned about once and ignored. |
928
+
923
929
  Each physical content root has one bundle id. Duplicate paths and symbolic-link
924
930
  aliases are rejected because source ownership, scheduler authority, and default
925
931
  selection must not depend on which spelling a caller used. If an older config
@@ -89,6 +89,7 @@ Windows uses per-user app-data directories (`%LOCALAPPDATA%\akm\data`,
89
89
  | `state.db.pre-<migration id>.bak` | A copy of `state.db` taken before a migration that drops schema (`018`, `028`) runs. Yours to delete. |
90
90
  | `workflow-run-locks/` | One lock file per running workflow run. |
91
91
  | `backups/tasks/` | Copies of task files made by `akm migrate apply` before it rewrites them. |
92
+ | `backups/asset-content-refs/` | Copies of the markdown and YAML files `akm migrate apply` rewrote to the current ref spelling. `akm backups prune` removes the old ones. |
92
93
  | `backups/asset-engine-keys/` | Copies of commands, agents, workflows and task sources made by `akm migrate apply` before it rewrites their `engine:` key. |
93
94
  | `migrate/engine-targets.json` | The connection or harness each old engine name became, kept by `akm migrate apply` until every `engine:` key is rewritten. |
94
95
  | `opencode-runtime/` | Everything akm's own agent runtime keeps: OpenCode's `config/` (with akm's plugin), `data/` (logs, repositories, shell output, and `data/opencode/opencode.db`, the runtime's sessions, which `akm proposal extract --type opencode` reads back, read-only), `cache/`, `state/` and `tmp/` (the binary's own native pieces). Recreated on next use; deleting it loses the runtime's session history. |
@@ -158,10 +158,15 @@ a symlink out of the bundle.
158
158
 
159
159
  ### Indexing
160
160
 
161
- `akm bundle create` makes the bundle a git repository whose `.gitignore` lists
162
- `env/` and `secrets/`, so those files are never committed. The indexer skips
163
- git-ignored files everywhere else, but it still indexes the files under a
164
- bundle's `env/` and `secrets/` directories when git ignores them: `akm search
161
+ `akm bundle create` makes the bundle a git repository and adds `env/` and
162
+ `secrets/` lines to its `.gitignore` when the file mentions neither, so those
163
+ files are not committed; akm's own commits follow git and apply no further
164
+ filter. `akm lint` reports an `env/` or `secrets/` file that git tracks in a
165
+ bundle with a remote as `tracked-secrets`; a bundle that versions them on
166
+ purpose lists `"tracked-secrets": ["**"]` under `lint.skip` in its config
167
+ entry. The indexer skips git-ignored files everywhere else, but it still
168
+ indexes the files under a bundle's `env/` and `secrets/` directories when git
169
+ ignores them: `akm search
165
170
  --type env` and `akm show env/<name>` find an env file of a default bundle after
166
171
  `akm index`. The index holds key names only for an env file and the name for a
167
172
  secret; values are never indexed. `env list`, `env path`, `env export`,
@@ -106,8 +106,8 @@ export interface WikiSnapshotFetcher {
106
106
 
107
107
  `markdown` should contain only the body content. akm still wraps the result in
108
108
  the standard raw snapshot frontmatter (`name`, `description`, `sourceUrl`,
109
- `title`, `updated`, a `lint_skip` entry for `stale-path`, and `tags`) so
110
- downstream wiki tooling continues to work normally.
109
+ `title`, `updated`, and `tags`) so downstream wiki tooling continues to work
110
+ normally.
111
111
 
112
112
  Custom `tags` are appended to the default snapshot tags (`website` and the
113
113
  resolved hostname). They do not replace those defaults.
@@ -871,6 +871,7 @@ retry a failed write automatically.
871
871
  | `tasks.list` | `{}` → `{tasks: [{id, schedule, enabled, description?}]}`: the default bundle's tasks that have a schedule, and whether this host has each enabled (`scheduler.enabled`). Reads only. |
872
872
  | `tasks.enable` | `{task}` → `akm task enable --bundle=<default bundle> -- <task>`: schedules the task in this host's scheduler and syncs the OS scheduler (cron, launchd or Task Scheduler). Returns `{ref, enabled, changed, sync}`. An unknown task is `not-found`. |
873
873
  | `tasks.disable` | `{task}` → `akm task disable --bundle=<default bundle> -- <task>`: the reverse. |
874
+ | `backups.prune` | `{olderThan?, dryRun?: true, confirm?: true}` → `akm backups prune [--dry-run \| --yes] [--older-than=<duration>]`. Removes entries under the data directory's `backups/` older than `olderThan` (default `30d`) and keeps the newest entry of each folder. A dry run reports `{dryRun, olderThan, cutoff, count, bytes, folders: [{folder, count, bytes, kept}]}` and removes nothing; a real run returns the same and needs `confirm: true`. |
874
875
  | `bundles.add` | `{source, name?, writable?}` → `akm bundle add`, including source validation. Existing provider restrictions apply; no insecure-transport bypass is exposed. |
875
876
  | `bundles.update` | `{bundle}` → `akm bundle update -- <bundle>`. Fetches/reindexes only on explicit submission. A rare update requiring destructive confirmation remains refused; `--yes` is never passed silently. |
876
877
  | `bundles.rename` | `{bundle, name, dryRun?: true}` → `akm bundle rename [--dry-run] -- <bundle> <name>`. The result is the CLI's rename plan (`applied` is `false` for a dry run). |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261128",
3
+ "version": "0.10.261129-beta.1",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [
@@ -500,6 +500,23 @@
500
500
  },
501
501
  "additionalProperties": {}
502
502
  }
503
+ },
504
+ "lint": {
505
+ "type": "object",
506
+ "properties": {
507
+ "skip": {
508
+ "type": "object",
509
+ "propertyNames": {
510
+ "type": "string"
511
+ },
512
+ "additionalProperties": {
513
+ "type": "array",
514
+ "items": {
515
+ "type": "string"
516
+ }
517
+ }
518
+ }
519
+ }
503
520
  }
504
521
  },
505
522
  "additionalProperties": {}
@@ -2473,6 +2490,23 @@
2473
2490
  },
2474
2491
  "additionalProperties": {}
2475
2492
  }
2493
+ },
2494
+ "lint": {
2495
+ "type": "object",
2496
+ "properties": {
2497
+ "skip": {
2498
+ "type": "object",
2499
+ "propertyNames": {
2500
+ "type": "string"
2501
+ },
2502
+ "additionalProperties": {
2503
+ "type": "array",
2504
+ "items": {
2505
+ "type": "string"
2506
+ }
2507
+ }
2508
+ }
2509
+ }
2476
2510
  }
2477
2511
  },
2478
2512
  "additionalProperties": {}
@@ -1,64 +0,0 @@
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
- * `stash-git-exposure` surfaces advisory for `akm health` (08-F1).
6
- *
7
- * Versioning the stash is a supported use case (private-remote backup), so a
8
- * tracked `env/`/`secrets/` directory is NOT wrong by itself. The leak moment
9
- * is when secret assets are git-TRACKED **and** a remote is configured — only
10
- * then can a `git push` exfiltrate tokens/keys. Warn on exactly that
11
- * combination; stay silent on the tracked-but-no-remote opt-in so the advisory
12
- * catches the exposure without nagging the intentional backup. A stash whose
13
- * `.gitignore` carries the intentional-tracking marker has acknowledged the
14
- * risk, so it is not warned about at all.
15
- */
16
- import { spawnSync } from "node:child_process";
17
- import fs from "node:fs";
18
- import path from "node:path";
19
- import { STASH_GITIGNORE_TRACK_SECRETS_MARKER } from "../sources/stash-skeleton.js";
20
- const realGit = (stashDir, args) => {
21
- const result = spawnSync("git", ["-C", stashDir, ...args], { encoding: "utf8", timeout: 5_000 });
22
- return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
23
- };
24
- /** True when the stash `.gitignore` carries the explicit intentional-tracking marker. */
25
- function hasIntentionalTrackingMarker(stashDir) {
26
- try {
27
- return fs.readFileSync(path.join(stashDir, ".gitignore"), "utf8").includes(STASH_GITIGNORE_TRACK_SECRETS_MARKER);
28
- }
29
- catch {
30
- return false;
31
- }
32
- }
33
- /**
34
- * Build the `stash-git-exposure` advisory, or `undefined` when there is nothing
35
- * to warn about (tracking acknowledged by the marker, not a git repo, no
36
- * tracked env/secret assets, or no remote).
37
- */
38
- export function collectStashExposureAdvisory(stashDir, git = realGit) {
39
- if (hasIntentionalTrackingMarker(stashDir))
40
- return undefined;
41
- // Not a git work tree → nothing to expose.
42
- if (!git(stashDir, ["rev-parse", "--is-inside-work-tree"]).ok)
43
- return undefined;
44
- const tracked = git(stashDir, ["ls-files", "--", "env", "secrets"]);
45
- if (!tracked.ok || tracked.stdout.length === 0)
46
- return undefined; // no secret assets tracked
47
- const remotes = git(stashDir, ["remote"]);
48
- if (!remotes.ok || remotes.stdout.length === 0)
49
- return undefined; // no push target → no leak path
50
- const trackedFiles = tracked.stdout.split("\n").filter(Boolean);
51
- const preview = trackedFiles.slice(0, 5).join(", ") + (trackedFiles.length > 5 ? `, +${trackedFiles.length - 5} more` : "");
52
- return {
53
- name: "stash-git-exposure",
54
- kind: "deterministic",
55
- status: "warn",
56
- confidence: "high",
57
- message: `Bundle at ${stashDir}: ${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
58
- `a 'git push' can leak tokens/keys (${preview}). ` +
59
- "Run 'git rm --cached' on them (a .gitignore rule alone does NOT untrack already-tracked " +
60
- "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm bundle create scaffolds it), " +
61
- `or, to keep tracking them on purpose, add '${STASH_GITIGNORE_TRACK_SECRETS_MARKER}' to .gitignore.`,
62
- evidence: { bundleRoot: stashDir, trackedSecretFiles: trackedFiles },
63
- };
64
- }