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.
- package/CHANGELOG.md +20 -0
- package/dist/cli.js +2 -0
- package/dist/commands/agent/contribute-cli.js +7 -1
- package/dist/commands/backups-cli.js +103 -0
- package/dist/commands/health.js +1 -34
- package/dist/commands/improve/reflect-noise.js +0 -1
- package/dist/commands/lint/base-linter.js +24 -48
- package/dist/commands/lint/bundle-skip.js +27 -0
- package/dist/commands/lint/index.js +83 -45
- package/dist/commands/lint/tracked-secrets.js +43 -0
- package/dist/commands/lint/types.js +58 -0
- package/dist/commands/proposal/repository.js +5 -1
- package/dist/commands/sources/stash-skeleton.js +7 -26
- package/dist/core/adapter/adapters/akm-adapter.js +2 -2
- package/dist/core/adapter/adapters/akm-workflow-adapter.js +6 -1
- package/dist/core/adapter/adapters/shared.js +13 -25
- package/dist/core/asset/lint-text.js +14 -13
- package/dist/core/asset/stale-path.js +63 -0
- package/dist/core/config/schema/sources-bundles.js +3 -0
- package/dist/output/shapes/passthrough.js +1 -0
- package/dist/output/text/lint-format.js +90 -1
- package/dist/output/text/migrate.js +5 -0
- package/dist/scripts/akm-migrate-node.js +1149 -791
- package/dist/scripts/akm-migrate.js +1149 -791
- package/dist/sources/include.js +1 -1
- package/dist/sources/snapshot-fetchers/website-ingest.js +0 -2
- package/dist/workspace/backups.js +21 -0
- package/dist/workspace/cli-child.js +5 -1
- package/dist/workspace-node.mjs +2 -0
- package/dist/workspace.d.ts +4 -0
- package/dist/workspace.js +1 -0
- package/docs/architecture/internals/health-advisories.md +1 -2
- package/docs/guides/bundles.md +5 -4
- package/docs/integration/bundling-akm.md +9 -1
- package/docs/reference/asset-types.md +1 -2
- package/docs/reference/cli.md +83 -3
- package/docs/reference/configuration.md +8 -2
- package/docs/reference/data-and-telemetry.md +1 -0
- package/docs/reference/env-and-secrets.md +9 -4
- package/docs/reference/website-sources.md +2 -2
- package/docs/reference/workspace.md +1 -0
- package/package.json +1 -1
- package/schemas/akm-config.json +34 -0
- package/dist/commands/health/stash-exposure.js +0 -64
package/dist/sources/include.js
CHANGED
|
@@ -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"
|
|
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);
|
package/dist/workspace-node.mjs
CHANGED
package/dist/workspace.d.ts
CHANGED
|
@@ -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). |
|
package/docs/guides/bundles.md
CHANGED
|
@@ -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
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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. **
|
|
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
|
|
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
|
|
package/docs/reference/cli.md
CHANGED
|
@@ -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.
|
|
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
|
|
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`, `
|
|
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
|
|
162
|
-
`
|
|
163
|
-
|
|
164
|
-
|
|
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`,
|
|
110
|
-
|
|
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.
|
|
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": [
|
package/schemas/akm-config.json
CHANGED
|
@@ -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
|
-
}
|