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.
- package/CHANGELOG.md +58 -0
- package/STABILITY.md +11 -0
- package/dist/assets/hints/cli-hints-full.md +1 -1
- package/dist/assets/hints/cli-hints-short.md +1 -0
- package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
- package/dist/cli/usage-report.js +184 -0
- package/dist/cli/usage.js +24 -7
- package/dist/cli.js +8 -2
- package/dist/commands/completions.js +5 -4
- package/dist/commands/health/checks.js +18 -4
- package/dist/commands/health/connections-and-harnesses-check.js +1 -0
- package/dist/commands/health/egress.js +1 -2
- package/dist/commands/health/plugin-staleness.js +75 -159
- package/dist/commands/health/scheduler-binary.js +7 -2
- package/dist/commands/health/semantic-search-check.js +7 -6
- package/dist/commands/health/version-drift.js +2 -0
- package/dist/commands/improve/extract.js +2 -2
- package/dist/commands/improve/preparation.js +6 -1
- package/dist/commands/lint/base-linter.js +90 -48
- package/dist/commands/lint/index.js +128 -185
- package/dist/commands/lint/moved-refs.js +69 -0
- package/dist/commands/lint/scope.js +41 -0
- package/dist/commands/metrics/collect.js +25 -2
- package/dist/commands/metrics/report-view.js +11 -2
- package/dist/commands/proposal/proposal.js +7 -2
- package/dist/commands/proposal/repository.js +16 -11
- package/dist/commands/read/rules.js +142 -0
- package/dist/commands/read/search-cli.js +5 -5
- package/dist/commands/read/search.js +1 -1
- package/dist/commands/sources/plugin-upgrade.js +139 -71
- package/dist/commands/sources/source-clone.js +4 -4
- package/dist/commands/sources/sources-cli.js +3 -20
- package/dist/commands/sources/sync.js +24 -0
- package/dist/commands/tasks/tasks.js +1 -1
- package/dist/core/adapter/adapters/akm-adapter.js +32 -23
- package/dist/core/adapter/adapters/akm-lint.js +55 -61
- package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
- package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
- package/dist/core/adapter/adapters/okf-adapter.js +5 -9
- package/dist/core/adapter/adapters/shared.js +52 -200
- package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
- package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
- package/dist/core/adapter/validate-context.js +7 -11
- package/dist/core/asset/asset-placement.js +29 -0
- package/dist/core/asset/frontmatter-edit.js +124 -0
- package/dist/core/asset/lint-text.js +18 -2
- package/dist/core/asset/llm-wiki-root.js +30 -0
- package/dist/core/asset/ref-rewrite.js +39 -0
- package/dist/core/asset/type-keys.js +59 -0
- package/dist/core/config/schema/local-state.js +5 -1
- package/dist/core/config/schema/output.js +4 -4
- package/dist/core/config/schema/search.js +4 -0
- package/dist/core/write-source.js +75 -25
- package/dist/indexer/index-written-assets.js +16 -8
- package/dist/indexer/indexer.js +68 -19
- package/dist/indexer/legacy-refs.js +1 -26
- package/dist/indexer/links/declared-links.js +13 -11
- package/dist/indexer/ref-moves.js +75 -0
- package/dist/indexer/search/db-search.js +3 -2
- package/dist/indexer/walk/place-rules.js +25 -0
- package/dist/indexer/walk/walker.js +5 -1
- package/dist/integrations/session-logs/pre-filter.js +1 -0
- package/dist/output/context.js +6 -2
- package/dist/output/shapes/passthrough.js +1 -0
- package/dist/output/text/rules.js +14 -0
- package/dist/output/text.js +2 -0
- package/dist/scripts/akm-migrate-node.js +4651 -3584
- package/dist/scripts/akm-migrate.js +4650 -3584
- package/dist/setup/registry-stash-loader.js +4 -2
- package/dist/sources/providers/git-stash.js +13 -5
- package/dist/storage/repositories/index-entries-repository.js +8 -3
- package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
- package/dist/workspace/activity.js +69 -8
- package/dist/workspace/asset-improve.js +9 -5
- package/dist/workspace/assets.js +33 -19
- package/dist/workspace/bundle-files.js +39 -2
- package/dist/workspace/bundles.js +53 -3
- package/dist/workspace/check-text.js +121 -0
- package/dist/workspace/config.js +3 -0
- package/dist/workspace/copy-entry.js +129 -0
- package/dist/workspace/derive.js +13 -4
- package/dist/workspace/documents.js +11 -16
- package/dist/workspace/file-actions.js +130 -0
- package/dist/workspace/frontmatter.js +41 -0
- package/dist/workspace/git-read.js +42 -27
- package/dist/workspace/graph.js +11 -2
- package/dist/workspace/impact.js +14 -5
- package/dist/workspace/metrics.js +1 -1
- package/dist/workspace/misses.js +8 -3
- package/dist/workspace/moved-links.js +57 -0
- package/dist/workspace/new-file.js +141 -0
- package/dist/workspace/proposals.js +12 -38
- package/dist/workspace/pulse.js +16 -9
- package/dist/workspace/readers.js +14 -0
- package/dist/workspace/sensitive.js +12 -6
- package/dist/workspace/setup.js +2 -1
- package/dist/workspace/stats.js +4 -0
- package/dist/workspace.d.ts +100 -1
- package/docs/architecture/adapters.md +15 -0
- package/docs/architecture/internals/health-advisories.md +13 -8
- package/docs/architecture/internals/indexing.md +1 -0
- package/docs/architecture/internals/storage-locations.md +3 -3
- package/docs/architecture/persisted-data-compat.md +2 -0
- package/docs/architecture/specs/ref.md +27 -13
- package/docs/guides/author-bundles.md +13 -12
- package/docs/integration/bundling-akm.md +3 -0
- package/docs/maintainers/implementation-details.md +1 -1
- package/docs/reference/api.md +3 -3
- package/docs/reference/cli.md +143 -35
- package/docs/reference/configuration.md +2 -1
- package/docs/reference/data-and-telemetry.md +49 -10
- package/docs/reference/workspace.md +122 -36
- package/package.json +1 -1
- package/schemas/akm-config.json +6 -0
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,64 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- A file or folder renamed or moved on disk is the same asset. `akm index` (full or incremental) pairs an entry whose file is gone with the new file of the same content, in the same bundle or another, and carries its history to the new ref: the index row (vector, links and utility stay, nothing is embedded again), the `state.db` rows keyed by the old ref (usage, feedback, proposals, events, improve ledger, salience, outcome, task and workflow history) and cached model results. Files that share a content hash pair by file name one to one; anything ambiguous is indexed as new and named in a warning, and a file edited as well as moved is a new asset. The result's `moves` (`{ moved: [{ from, to }], unpaired }`) is present when a file was paired or could not be, and each move is recorded as a `moved` event. There is no move command: `mv` or a file manager is the move.
|
|
12
|
+
- `akm lint` reports a link to a moved ref as a `missing-ref` carrying `movedFrom` and `movedTo`, and `--fix` rewrites it (frontmatter and prose, not code fences). A `missing-ref` with no recorded move is reported as before and never rewritten. `akm-cli/workspace`: `assets.movedLinks` lists, per akm bundle, the links that name an old ref, and `assets.updateMovedLinks` rewrites exactly those in one writable bundle (the same lint pass).
|
|
13
|
+
- `akm-cli/workspace`: what may be done to a file or folder. `assets.bundleFiles` entries and `assets.show` carry `actions` (`read`, `edit`, `move` for rename or move, `copy`, `retire`, `delete`), each `{ allowed: true }` or `{ allowed: false, reason }`, computed from the checks the operations run: the read-only sentence for a bundle that is read-only (reading, editing, moving and deleting are plain file operations, so a writable bundle of any adapter still takes them), the write path's adapter sentence for retiring or making a typed asset in a bundle of another adapter, env and secret files, the managed `.git/` and `.akm/` folders, a skill that moves as its folder, a file that is not text (or cannot be opened, with the cause), the retire guard, and an asset that is retired rather than deleted. `assets.bundleFiles` also reports `newFile` for the folder shown.
|
|
14
|
+
- `akm-cli/workspace`: `documents.createFile` makes a new file in a folder of a bundle, for any type. akm types the folder with the indexer's directory rules, starts the file with the text its type starts with (the workflow and task creators' own, or the keys the type's validators require), and writes it through the writer every authored file goes through; a folder with no type gets an empty file of the name given. `documents.createKnowledge` is now a call to it and returns `{ bundle, file, type, ref, path, stashDir, indexed }`.
|
|
15
|
+
- `akm-cli/workspace`: `documents.check` returns the findings `akm lint` reports for text about to be saved at a path of an akm bundle (with lines where the check knows one) and whether akm could still read the asset (frontmatter that parses, a workflow that compiles, a task that validates), without writing anything. `documents.frontmatter` returns a file's frontmatter as keys and values in file order and the keys akm knows for its type with the required ones marked; `documents.applyFrontmatter` applies key changes (set, remove) to a text and leaves the body and every untouched key as written.
|
|
16
|
+
- `akm-cli/workspace`: `bundles.commit` runs `akm sync` for one bundle and returns what it did, and `bundles.list`'s `git` carries `uncommitted`, the files a sync would commit now (not the lines of `git status`; `null` when git could not list them). `akm sync` itself is unchanged.
|
|
17
|
+
- A daily usage report, on by default: at most once a UTC day per surface, the CLI (`cli_daily`) and AKM Desktop (`desktop_daily`, through the new `akm-cli/workspace` `activity.reportUsage`) send anonymous command counts and library sizes (bundles, indexed assets by type) to a self-hosted Aptabase at `reporting.fwdslsh.dev`. Never queries, refs, paths, names or argument values. `akm config set usage.report false` turns it off; `--read-only`, `usage.capture: false`, CI and test runs send nothing, and a failed send is never retried or shown. Experimental. See [Data and Telemetry](docs/reference/data-and-telemetry.md#daily-usage-report).
|
|
18
|
+
- `akm rules [--project <name>|none] [--from <bundle>]... [--filter <key>=<value>]...` prints the rules that apply here, in full: the project's first, then shared ones, read from the files (no index needed) and recorded as one `rules` usage event per call, never a search or a show. `akm metrics` reports rule loads, rules and characters per load, and loads per rule. Experimental.
|
|
19
|
+
- `akm health` and `akm doctor` JSON: every check whose `status` is `unknown` carries a `reason` that says why it has no result: `off` (the feature is turned off), `not-probed` (the probe was not asked for), `blocked` (the check could not run or could not decide) or `idle` (nothing has happened yet). A check with any other status has none. AKM Desktop groups unknown checks by it instead of reading the message.
|
|
20
|
+
- `akm proposal accept` JSON (and each entry of a multi-id accept) carries `commit`: `{ "committed": true, "sha" }`, or `{ "committed": false, "reason", "error"? }` with `reason` `not-git`, `ignored`, `nothing-to-commit` or `failed`. AKM Desktop's accept receipt prints it, so a failed commit is shown as failed instead of as silence.
|
|
21
|
+
- `akm-cli/workspace` `bundles.list` reports, per bundle, `writeBlocker` (the sentence akm's write path would refuse with, or `null` when a write would be accepted) and `identity` (one name for where the bundle comes from, equal for the same repository however its address is written); and, once, `writeTarget` (where a write goes when no bundle is named, and why none does or why it would be refused) and `starter` (the starter bundle's `source` and `identity`). `assets.projectOverview`'s `writeBundle` reports `writeBlocker` in place of `usable`.
|
|
22
|
+
- `akm-cli/workspace`: `bundles.index` runs the incremental index, which pairs a file renamed or moved on disk with its asset (`moves` in the result); `assets.bundleFiles` also reports `place` (whether a folder may be made in the folder shown or an entry moved into it) and each entry's `size` and `modified`.
|
|
23
|
+
- AKM Desktop's Files view is a file manager. Every file and folder has a menu (right-click, the menu key, a button on each row) with New file, New folder, Rename, Move to…, Copy to…, Retire, Delete and Reveal in file manager, each offered or disabled from akm's verdicts with akm's sentence. Rename is inline, Move to… and Copy to… use a folder picker that is the tree, a drag onto a folder asks once. A move or rename is a plain rename on disk followed by the index, so the asset keeps its usage, feedback and proposal history and the open page follows it; a notice counts the links that still name the old place and one button rewrites them. New names what akm says the folder holds and makes it in the current folder; an empty folder or a file that is no asset is deleted after one confirmation; the list shows size and modified time. Git bundles show akm's uncommitted count and a Commit button.
|
|
24
|
+
- `akm-cli/workspace`: `assets.bundleFiles` `newFile` names an environment file or a secret (`through: "protected-editor"`) in the top-level `env/` and `secrets/`; `documents.check` names a file by its bundle path, not its scratch folder; `documents.frontmatter` returns `markdown` and `bodyStart` (in a bundle of any adapter) and `applyFrontmatter` the new `bodyStart`; `sensitive.describe` returns `actions: {edit, delete}` with akm's sentence in place of `writable`; `documents.createFile` takes a `type` in place of a folder; `assets.copyEntry` copies a file or folder to a chosen folder; `bundles.list`'s `git.dirtyPaths` is removed (`uncommitted` is the count).
|
|
25
|
+
- AKM Desktop shows a file's frontmatter as Properties under the title for every kind and edits it as fields (akm applies each change; unknown keys and the body stay as written, with a Text switch for the whole file). A script reads as code, a task as YAML, Source is the whole file. Save checks the text with akm first: findings are listed beside the editor with their lines, a text akm could not read as the asset stops the save with Save anyway, and the file is then shown as not indexed with akm's reason.
|
|
26
|
+
- `akm-cli/workspace`: `activity.taskHistory` runs carry `targetKind`, `targetRef` and `engine`, and `activity.taskRunLog` returns a task run's recorded output from `logs.db` (read-only; `available: false` when there is none). `setup.detect`'s harnesses carry `modelWorkReadOnly`, whether akm's model calls on that program can be limited to reading and searching. AKM Desktop's task run view shows what the run executed and a Log output section; Setup's "Choose it only if you accept that" follows `modelWorkReadOnly`, not the wording of the note.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- AKM Desktop's move is no longer a copy then a retirement of the original: the copy form, its texts and the old Move form are gone, and a moved asset keeps its identity. "New knowledge" on every folder is replaced by a button named for the folder's type; Environment file and Secret are under "New protected file". An asset page offers Edit page and Retire from akm's verdicts for its file (disabled with akm's reason) instead of from its type, and a read-only bundle's controls are no longer hidden without a reason.
|
|
31
|
+
- The base asset checks (`unquoted-colon`, `missing-updated`, `stale-path`, `missing-ref`, `redacted-content`) and the per-type checks (a command's and an agent's `name` and `type`, a fact's `category`, a task's source, a memory stub, a workflow stub and its compile findings) have one implementation, which the `akm lint` sweep and every adapter's `validate` (the lint of a bundle of another adapter) both run, with the run's own config, so an exemption or a fix to a rule reaches both. For a bundle of another adapter: `redacted-content` and the workflow compile advisories are now reported; a `missing-ref` reads `missing ref: <ref> (resolved to <path>)` (or `(frontmatter <key>; resolved to <path>)`); a ref is looked up as in an akm bundle (a qualified ref in the bundle it names, a retired memory's archive and a moved ref count); and a file inside an LLM Wiki of the bundle is exempt from `missing-updated` and `missing-name-or-type`. A pending change in a `ValidateContext` no longer satisfies a ref in the base checks.
|
|
32
|
+
- `akm lint` checks every ref a file declares in frontmatter (`xrefs`, `supersededBy`, `contradictedBy`, `currentBeliefRefs`, `sources`, `refs`, the keys the index reads as links) whatever folder it points into, and reads it as the index does (a wiki page's `raw/x.md` and `wiki:<name>/pages/x` are relative to its wiki). Before, only a ref that led with an akm type folder was checked, and `currentBeliefRefs` and `sources` were not. A word in prose is a ref only when it looks like one, as before. On a fixture with a wiki of 30 raw snapshots and 20 pages and one note, `missing-ref` findings went from 1 to 12; on an OKF bundle of 10 concepts with 5 dangling `xrefs` they stay at 5.
|
|
33
|
+
- `akm lint` does not apply `missing-updated` or `missing-name-or-type` to a file inside an LLM Wiki (a folder with `schema.md` and `pages/`): a wiki keeps its own schema and is written by the wiki's own process, so its raw snapshots and pages are not authored akm assets. Every other check still runs on them. On a wiki fixture (3 raw snapshots, 3 pages, 1 loose file) the per-rule counts went from `missing-updated` 7, `missing-name-or-type` 1, `missing-ref` 2 to `missing-updated` 1 (the loose file), `missing-ref` 2.
|
|
34
|
+
- `akm lint` of an akm bundle reads the files the indexer would index and types each by the indexer's classification, instead of the files under the type folders: it now reaches Markdown assets under a wiki folder, a loose folder and the bundle root, and no longer reads a dot-directory or a git-ignored file inside a type folder, which the indexer never lists. `env/` and `secrets/` are never read. On a fixture with files under a wiki folder and a loose folder the per-rule counts went from 2 findings (`missing-name-or-type` 1, `missing-updated` 1) to 12 (`missing-updated` 5, `missing-name-or-type` 2, `missing-ref` 2, `stale-path` 1, `unquoted-colon` 1, `redacted-content` 1).
|
|
35
|
+
- `indexWrittenAssets` recognizes a file through the named bundle's own adapter, and Desktop's plain save reports what it returns, not `indexed: true` for a bundle whose index it never refreshed.
|
|
36
|
+
- `akm lint` checks a qualified ref (`bundle//concept`) in the bundle it names, so one whose concept exists only in another bundle is now reported; an unqualified ref is looked up in every bundle as before. On a fixture with one such ref, `missing-ref` findings went from 1 to 2.
|
|
37
|
+
- AKM Desktop's plain-file routes refuse what akm reports as not allowed for the file: they read and wrote `.git/config` and files under `.akm/` before. A save into a read-only bundle is refused with the write path's sentence ("source <name> is not writable") instead of Desktop's own, and a file akm cannot open is refused with its cause (400) instead of failing as a 500.
|
|
38
|
+
- A failure to carry an asset's history to a re-keyed ref during `akm index` is a warning in the index result, not only a line on stderr.
|
|
39
|
+
- Which bundles supply rules to a session, once the plugins load them with `akm rules`: the project's `from`, else the default bundle and the project's write bundle; with no project, the default bundle. The plugins' search-based listing read the shared rules of every enabled bundle the selection read, so a bundle installed from a registry or a git URL could add a rule to every session. Name such a bundle in the project's `from` to keep loading its rules. Search and curate are unchanged.
|
|
40
|
+
- `akm upgrade --check` reports what an update would do to the Claude Code and Codex plugins: the version it would install on the channel in force (`pending` with `to`), `current`, or the reason the marketplace could not be read. It reads the channel's build from the marketplace the harness registered, with the function the real update uses, so the plan and the update agree. The check now reads that remote; it still changes nothing.
|
|
41
|
+
- `akm health`'s Claude and Codex plugin checks read the newest plugin build the way `akm upgrade --check` does: the catalog of the channel's branch of the source and ref the harness registered, from a blobless, no-checkout clone (about 0.3 MB instead of the whole branch, 54 MB for `next`). The tag listing is gone. Health's "available" version is now the build the channel offers, a failed read says why in the message, a harness with no registered source is `unknown` (reason `blocked`), and a marketplace pinned to a tag is not read and offers nothing newer.
|
|
42
|
+
- AKM Desktop's Software page has one release channel for the CLI and plugins. Check runs `akm upgrade --check --channel <chosen>`, Update runs `akm upgrade --channel <chosen>`, and each plugin shows what akm reports: its version, the channel it follows and what Update would do. The Switch button and the CLI channel Desktop inferred from the version are gone. With no saved choice Desktop uses the channel akm reports for the installed CLI. Update is held only when the CLI itself would move past the engine in the app.
|
|
43
|
+
- AKM Desktop no longer links an improve run to a scheduled task run by task name and a five-minute window: no record ties the two, so the improve run page states the run's own facts only. A task run's history shows what the run executed and its recorded output (below). `akm-cli/workspace` `proposals.accept` and `proposals.acceptMany` carry the accept's `commit` as above in place of the commit read back from the repository's newest subject.
|
|
44
|
+
- AKM Desktop decides whether a bundle can take a write from akm's `writeBlocker`, not from `enabled`, `writable` and the adapter, wherever it offers a destination (copy, move, new file, protected file, project write bundle), and shows akm's sentence for a bundle it cannot use.
|
|
45
|
+
|
|
46
|
+
### Removed
|
|
47
|
+
|
|
48
|
+
- AKM Desktop's Source history no longer shows a "Made by" badge or filter, and the commit entries of `akm-cli/workspace` `proposals.recentChanges` and `assets.history` no longer carry `origin`: it was judged from the commit subject, so a hand-written "Remember to rotate the key" read as akm's. Each commit shows its own author, date and subject; akm's commit messages are unchanged.
|
|
49
|
+
|
|
50
|
+
### Fixed
|
|
51
|
+
|
|
52
|
+
- AKM Desktop's asset page says why its usage and proposal read failed instead of only that it is unavailable. The Software page's hold on Update no longer guesses from the shape of a version whether Desktop's channel will offer that release.
|
|
53
|
+
- AKM Desktop's Activity views show what akm reports and say when akm reported nothing. `assets.searchMisses` and `activity.retrievalTrend` return `available: false` with the reason when `state.db` is absent or needs a migration, and the Runs, Usage and search-gap views and the Library map's searches that found nothing say so instead of "No runs recorded" or "No searches"; `activity.overview` names it in `errors.state`. `activity.pulse`, `assets.improvement` and `activity.improveImpact` report an unresolvable bundle directory instead of reading it as no proposals. Needs attention counts every failed task run from akm's full count, not the pulse's three-row preview; the Usage summary calls the proposals counted in its window "updated in this window" instead of "pending"; Repeated search gaps lists the queries akm marks `repeated`.
|
|
54
|
+
- `activity.improveImpact` returns `usageSince`, `usageComplete` and, per changed asset, `beforeComplete`, so a change whose 28 days before are older than the usage akm keeps shows "Not recorded", not 0. `activity.retrievalTrend` marks `partial` weeks and returns `enoughHistory`: no centre or usual range is drawn from fewer than four whole weeks. `activity.events` rows carry `byPerson`; Replay plays the person's events by default so its figures match the Usage tab, offers everyone's, and shows curates apart from searches. The workflow trace header sums tokens from the attempts akm reported and says "tokens not reported" when none did, and units that name no step get no invented status.
|
|
55
|
+
- AKM Desktop's protected-file view names a file akm types `env` or `secret` below the top level of a bundle as one akm manages only at the top level, in `env/` or `secrets/`; it opens, shows and changes nothing there.
|
|
56
|
+
- `akm lint` sweeps and accepts files in `rules/` and `instructions/`, which it had skipped: it now takes its folders from the asset registry instead of its own list. `akm lint rules/x.md` no longer fails with "not under a known asset directory". `--type` takes a type name (`rule`) or its folder name (`rules`), so every value shell completion offers is accepted. Types that search leaves out by default (`search.defaultExcludeTypes`, default `session`) are left out of the sweep unless `--type` names one; a single file is always linted. A file under `env/` or `secrets/` is refused, never read. The `bundlePolicy` migration strips `lint_skip` in the same folders.
|
|
57
|
+
- Usage records `--type` values `task`, `session`, `fact`, `instruction`, `rule`, `any` and folder names such as `memories` instead of `[redacted]`. Shell completion and the output config accept the `--format` and `--detail` values the output module defines.
|
|
58
|
+
- AKM Desktop no longer opens a nested `env/` or `secrets/` file in the plain editor: any file akm types `env` or `secret` is refused by the plain file routes, and a file akm's listing does not report is not opened.
|
|
59
|
+
- AKM Desktop says when it could not read something instead of showing a good state: an absent or unmigrated `state.db` is "unavailable" in Review, the pending badge and the Overview (it read as "All caught up"); a failed `git` read says why (it read as "Clean", "No commits" or "Detached HEAD"); an unreadable `preferences.json` is reported and moved aside on the next save instead of being silently replaced by defaults; the Library map no longer decides that usage is missing from a note's wording.
|
|
60
|
+
- AKM Desktop's embedding coverage counts the current model's vectors against embeddable entries, as akm's readiness check does; the "No model connection configured" item follows akm's learning status; new content goes where akm says it goes; the starter bundle is recognised by its source, not by a name containing `akm-stash`.
|
|
61
|
+
- AKM Desktop's Library map says when akm could not report something instead of drawing it as zero: feedback it could not read is "unavailable" (it read "Disliked 0" and "Liked · disliked 0 · 0"), near-duplicates it has no layout for are "unavailable" (they read "Near-duplicates inside 0"), and an asset with no readable edit time is not classed as unread. `akm-cli/workspace` `assets.graph` adds to its `note` that groups and near-duplicates are not available when the last index stored no layout.
|
|
62
|
+
- AKM Desktop's 3D Library map says how many assets it leaves out: an asset with no group by meaning (not embedded, or added since the last index build) is not a point, and the map now states the count instead of titling itself "every asset".
|
|
63
|
+
- AKM Desktop's Project assets page and Project overview say "Counts unknown" when akm reports no count for a bundle (it cannot be read, or nothing is indexed). The assets page read "0 eligible of 0 indexed" and blamed the project's filters; one presenter now serves both pages.
|
|
64
|
+
- AKM Desktop's setup no longer decides that a plugin "was built for a different akm" by comparing its version with the engine's major and minor. The agent cards show what `akm upgrade --check` reports for that plugin (a tick for `current`, akm's own text for a pending, deferred or failed update, with its engine-skew message), and claim nothing until a check has run.
|
|
65
|
+
- AKM Desktop's new-file editor says "That file name is already used" when akm's error code is `RESOURCE_ALREADY_EXISTS`, not when the message contains "already exists": a reworded message no longer shows akm's raw `--force` sentence, and an unrelated error that says "already exists" is no longer reported as a name collision.
|
|
66
|
+
|
|
9
67
|
## [0.10.261129] - 2026-11-16
|
|
10
68
|
|
|
11
69
|
### Added
|
package/STABILITY.md
CHANGED
|
@@ -42,6 +42,7 @@ check the [migration guide](docs/migration/v0.10-to-v0.11.md) for availability.
|
|
|
42
42
|
| `akm search` | Stable | `--include-proposed` and `--include-sessions` are Deprecated, removed in 0.11: use `--include quality=proposed` and `--include type=<excluded-type>`; `type=` also takes a custom type listed in `search.defaultExcludeTypes` (read from the config file only, not from `extends` layers). `--by-usage` is Deprecated, removed in 0.11: use `akm doctor metrics assets` (first in 0.10.261120; same filters and result fields). |
|
|
43
43
|
| `akm curate` | Stable | `--max-tokens` aliases the existing `--pack` budget and output. Both are opt-in; the unbudgeted default stays unchanged. Conflicting explicit budgets are rejected. `--pack` and the unpacked default are Deprecated, removed in 0.11 when curate returns bounded packed context by default. |
|
|
44
44
|
| `akm show` | Stable | `--outline` and `--lead` are additive aliases. `--max-tokens` bounds body fields (after any frontmatter) on whole/exact/lead reads and reports estimation/truncation; legacy unbudgeted output is unchanged. `--outline` with `--lead` or a budget, `--detail brief` with `--lead`, and `--detail brief` with `--max-tokens` and no lead context are usage errors; `--detail brief --context lead [--max-chars|--max-tokens]` keeps working as in 0.10.261118. `--context`, `--max-chars` and `--detail` are Deprecated, removed in 0.11 (exact reads become the default). |
|
|
45
|
+
| `akm rules` | Experimental | First in 0.10.261130. Prints the rules that apply here, in full, read from the files of the project's bundles (`--from`, else the project's `from`, else the default bundle and the project's write bundle); `--project`, `--from` and `--filter` as in search. Records one `rules` usage event per call. The flags, the `{ project?, bundles, rules }` JSON shape and the `rules` metrics section may change in any release. |
|
|
45
46
|
| `akm remember` | Stable | `--source`, `--description`, and `--expires` work independently of tags. Capture and enrichment processes are unchanged. `--auto`, `--enrich` and `--show-similar` are Deprecated, removed in 0.11 with no replacement flag; they print a notice since 0.10.261120. |
|
|
46
47
|
| `akm import` | Stable | Additive `--asset-ref` and `--type task` modes, first in 0.10.261119; existing document inputs unchanged. `--type task` writes `scheduler.enabled` deliberately, to keep a stale scheduler row from activating the new task. |
|
|
47
48
|
| `akm sync` | Stable | |
|
|
@@ -262,6 +263,16 @@ the collected baseline through the 0.11 storage migration, which keeps it in
|
|
|
262
263
|
`metrics.db` in the resolved data directory;
|
|
263
264
|
the migration guide tracks the data contract, retention, and verification.
|
|
264
265
|
|
|
266
|
+
### Daily usage report (Experimental)
|
|
267
|
+
|
|
268
|
+
0.10.x also sends one anonymous report a day per surface (the CLI and AKM Desktop, through
|
|
269
|
+
`akm-cli/workspace` `activity.reportUsage`) to a self-hosted Aptabase: command counts from the
|
|
270
|
+
data above and library sizes, never argument values, refs, paths or names. It is on by default and
|
|
271
|
+
`usage.report: false` in the config file turns it off; `--read-only`, `usage.capture: false`, CI and
|
|
272
|
+
test runs send nothing. The key, the event fields and `activity.reportUsage` are Experimental: the
|
|
273
|
+
fields may change between releases, and every change is listed in
|
|
274
|
+
[Data and Telemetry](docs/reference/data-and-telemetry.md#daily-usage-report).
|
|
275
|
+
|
|
265
276
|
### Remaining scheduled 0.11 removals and breaking changes
|
|
266
277
|
|
|
267
278
|
The reviewed 0.11 branch already removes implicit
|
|
@@ -15,7 +15,7 @@ akm search "<query>" --limit 10 # Limit results
|
|
|
15
15
|
akm search "<query>" --detail full # Include scores, paths, timing
|
|
16
16
|
akm search "memories/projectA/" # Enumerate a subtree (conceptId prefix; trailing slash required)
|
|
17
17
|
akm search "knowledge/" # List every knowledge item
|
|
18
|
-
akm
|
|
18
|
+
akm rules # The rules that apply here, in full (project's first, then shared)
|
|
19
19
|
akm doctor metrics assets --detail normal # Assets shown most in the project
|
|
20
20
|
akm search "team-catalog//" # List every item in one bundle
|
|
21
21
|
```
|
|
@@ -10,6 +10,7 @@ akm curate "<task>" --max-tokens 4000 # Same hits' content as one bundle of at m
|
|
|
10
10
|
akm search "<query>" # Local sources (or the project's `from`); --type <t> filters
|
|
11
11
|
akm search "<query>" --from all # Also search registries
|
|
12
12
|
akm show <ref> # Read an asset
|
|
13
|
+
akm rules # The rules that apply here, in full
|
|
13
14
|
akm run <ref> # Run an agent, command, task or workflow asset
|
|
14
15
|
akm doctor # Health checks; `doctor metrics|info|log` report
|
|
15
16
|
akm help <command> # A command's options
|
|
@@ -13,7 +13,7 @@ updated: 2026-11-08
|
|
|
13
13
|
|
|
14
14
|
# Rule authoring conventions
|
|
15
15
|
|
|
16
|
-
A rule is a short bullet list of things an agent must do for a project. The AKM agent plugins load the applicable rules at session start and after compaction, so every line costs context on every task.
|
|
16
|
+
A rule is a short bullet list of things an agent must do for a project. The AKM agent plugins load the applicable rules (`akm rules`) at session start and after compaction, so every line costs context on every task. Rules load only from the default bundle, the project's write bundle or the bundles in its `from`, so put a team's shared rules in a bundle the project lists.
|
|
17
17
|
|
|
18
18
|
- One rule per bullet, imperative, checkable ("Run the focused tests for changed behavior"). No background or rationale; put that in knowledge.
|
|
19
19
|
- Keep a file to a handful of bullets and one topic. Split by topic (`rules/acme/testing.md`), not by length.
|
|
@@ -0,0 +1,184 @@
|
|
|
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
|
+
* The daily usage report: at most one event per surface (`cli`, `desktop`) per UTC day, to the owner's self-hosted
|
|
6
|
+
* Aptabase. Counts only: no argument value, ref, path, bundle name or instance id is ever read into it. The
|
|
7
|
+
* fields sent are listed in docs/reference/data-and-telemetry.md. Every failure is swallowed; the report never
|
|
8
|
+
* changes a command's output or exit code.
|
|
9
|
+
*/
|
|
10
|
+
import { randomUUID } from "node:crypto";
|
|
11
|
+
import os from "node:os";
|
|
12
|
+
import { loadConfig } from "../core/config/config.js";
|
|
13
|
+
import { peekConfigValue } from "../core/config/peek.js";
|
|
14
|
+
import { getDbPath } from "../core/paths.js";
|
|
15
|
+
import { isKnownType } from "../core/recognition-util.js";
|
|
16
|
+
import { openDatabase } from "../storage/database.js";
|
|
17
|
+
import { getEntryCountByType } from "../storage/repositories/index-entries-repository.js";
|
|
18
|
+
import { pkgVersion } from "../version.js";
|
|
19
|
+
import { openUsage, readUsage } from "./usage.js";
|
|
20
|
+
// The Aptabase app key is write-only and public by design (it ships in every Aptabase SDK). The host is fixed:
|
|
21
|
+
// no environment variable or config key can redirect it.
|
|
22
|
+
const ENDPOINT = "https://reporting.fwdslsh.dev/api/v0/event";
|
|
23
|
+
const APP_KEY = "A-SH-4111202318";
|
|
24
|
+
const SEND_TIMEOUT_MS = 1500;
|
|
25
|
+
const DAY_MS = 86_400_000;
|
|
26
|
+
/** No test run and no CI run reaches the network: `CI`, `bun test` (`NODE_ENV=test`, `BUN_TEST`). */
|
|
27
|
+
function underTestOrCi(env) {
|
|
28
|
+
return Boolean(env.CI) || env.NODE_ENV === "test" || env.BUN_TEST === "1";
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Whether the report is on, from the effective config (`extends` layers included): off when any layer sets
|
|
32
|
+
* `usage.report: false` and no nearer layer overrides it. A config that cannot be loaded is "not enabled": akm
|
|
33
|
+
* cannot confirm the person has not opted out, so nothing is sent.
|
|
34
|
+
*/
|
|
35
|
+
export function usageReportEnabled() {
|
|
36
|
+
try {
|
|
37
|
+
return loadConfig().usage?.report !== false;
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
function day(at) {
|
|
44
|
+
return at.toISOString().slice(0, 10);
|
|
45
|
+
}
|
|
46
|
+
function addDays(utcDay, days) {
|
|
47
|
+
return day(new Date(Date.parse(`${utcDay}T00:00:00Z`) + days * DAY_MS));
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Take today for `surface`: true for exactly one caller per UTC day, across concurrent processes (one atomic
|
|
51
|
+
* upsert). A store created today claims nothing, so a fresh install or sandbox reports from its next UTC day.
|
|
52
|
+
* Returns the previously reported day (undefined before the first report).
|
|
53
|
+
*/
|
|
54
|
+
function claimDay(surface, today) {
|
|
55
|
+
const db = openUsage();
|
|
56
|
+
try {
|
|
57
|
+
const started = db.prepare("SELECT value FROM cli_usage_meta WHERE key='collectionStart'").get()?.value;
|
|
58
|
+
if (started === undefined || started.slice(0, 10) >= today)
|
|
59
|
+
return undefined;
|
|
60
|
+
const key = `report.${surface}.last_day`;
|
|
61
|
+
const last = db.prepare("SELECT value FROM cli_usage_meta WHERE key=?").get(key)
|
|
62
|
+
?.value;
|
|
63
|
+
// Already reported today (every command after the first): a read only, no write lock on the shared store.
|
|
64
|
+
if (last !== undefined && last >= today)
|
|
65
|
+
return undefined;
|
|
66
|
+
const claimed = db
|
|
67
|
+
.prepare("INSERT INTO cli_usage_meta(key,value) VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value WHERE cli_usage_meta.value < excluded.value")
|
|
68
|
+
.run(key, today).changes;
|
|
69
|
+
return claimed ? { last } : undefined;
|
|
70
|
+
}
|
|
71
|
+
finally {
|
|
72
|
+
db.close();
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** Counts of the complete UTC days after `last` up to yesterday, from the durable aggregates. */
|
|
76
|
+
function cliCounts(last, today) {
|
|
77
|
+
const since = last === undefined ? today : addDays(last, 1);
|
|
78
|
+
const until = addDays(today, -1);
|
|
79
|
+
const props = { period_days: 0, commands: 0, failures: 0 };
|
|
80
|
+
if (since > until)
|
|
81
|
+
return props;
|
|
82
|
+
props.period_days = (Date.parse(`${until}T00:00:00Z`) - Date.parse(`${since}T00:00:00Z`)) / DAY_MS + 1;
|
|
83
|
+
const report = readUsage({ since, until, aggregatesOnly: true });
|
|
84
|
+
for (const row of report.aggregates) {
|
|
85
|
+
const dimensions = row.dimensions;
|
|
86
|
+
const attempts = Number(row.attempts);
|
|
87
|
+
props.commands = (props.commands ?? 0) + attempts;
|
|
88
|
+
props.failures = (props.failures ?? 0) + Number(row.failures);
|
|
89
|
+
if (dimensions.source && ["user", "agent", "task", "improve"].includes(dimensions.source)) {
|
|
90
|
+
const key = `src_${dimensions.source}`;
|
|
91
|
+
props[key] = (props[key] ?? 0) + attempts;
|
|
92
|
+
}
|
|
93
|
+
const name = (dimensions.command?.[0] ?? "").replace(/[^a-z0-9-]/g, "") || "other";
|
|
94
|
+
const key = `cmd_${name}`.slice(0, 40);
|
|
95
|
+
props[key] = (props[key] ?? 0) + attempts;
|
|
96
|
+
}
|
|
97
|
+
for (const key of ["src_user", "src_agent", "src_task", "src_improve"])
|
|
98
|
+
props[key] ??= 0;
|
|
99
|
+
return props;
|
|
100
|
+
}
|
|
101
|
+
/** Enabled bundle count from the config file, and the indexed asset counts (by akm's own types) from the read-only index. Absent when unreadable. */
|
|
102
|
+
function librarySnapshot() {
|
|
103
|
+
const props = {};
|
|
104
|
+
const bundles = peekConfigValue(["bundles"]);
|
|
105
|
+
if (typeof bundles === "object" && bundles !== null) {
|
|
106
|
+
props.bundles = Object.values(bundles).filter((b) => b?.enabled !== false).length;
|
|
107
|
+
}
|
|
108
|
+
try {
|
|
109
|
+
const db = openDatabase(getDbPath(), { readonly: true, create: false });
|
|
110
|
+
try {
|
|
111
|
+
db.exec("PRAGMA busy_timeout=250; PRAGMA query_only=ON;");
|
|
112
|
+
const byType = getEntryCountByType(db);
|
|
113
|
+
props.assets = Object.values(byType).reduce((sum, n) => sum + n, 0);
|
|
114
|
+
// A type outside akm's own set is named by a bundle's adapter or the user: it is counted, never named.
|
|
115
|
+
for (const [type, n] of Object.entries(byType)) {
|
|
116
|
+
const key = isKnownType(type) ? `assets_${type}` : "assets_other";
|
|
117
|
+
props[key] = (props[key] ?? 0) + n;
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
finally {
|
|
121
|
+
db.close();
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
catch {
|
|
125
|
+
// No index, or one that cannot be read: the snapshot omits the asset counts.
|
|
126
|
+
}
|
|
127
|
+
return props;
|
|
128
|
+
}
|
|
129
|
+
function systemProps(version) {
|
|
130
|
+
const platform = process.platform;
|
|
131
|
+
return {
|
|
132
|
+
isDebug: false,
|
|
133
|
+
locale: Intl.DateTimeFormat().resolvedOptions().locale,
|
|
134
|
+
osName: platform === "linux" ? "Linux" : platform === "darwin" ? "macOS" : platform === "win32" ? "Windows" : platform,
|
|
135
|
+
osVersion: os.release(),
|
|
136
|
+
engineName: process.versions.bun ? "bun" : "node",
|
|
137
|
+
engineVersion: process.versions.bun ?? process.versions.node,
|
|
138
|
+
appVersion: version,
|
|
139
|
+
sdkVersion: `akm@${version}`,
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
/** Send the surface's daily event when it is due. Resolves true when the server accepted it; never throws. */
|
|
143
|
+
export async function reportUsageIfDue({ surface, version = pkgVersion }, deps = {}) {
|
|
144
|
+
try {
|
|
145
|
+
const env = deps.env ?? process.env;
|
|
146
|
+
if (underTestOrCi(env) || !usageReportEnabled())
|
|
147
|
+
return false;
|
|
148
|
+
const now = deps.now ?? new Date();
|
|
149
|
+
const today = day(now);
|
|
150
|
+
const claim = claimDay(surface, today);
|
|
151
|
+
if (!claim)
|
|
152
|
+
return false;
|
|
153
|
+
const props = {
|
|
154
|
+
...(surface === "cli" ? cliCounts(claim.last, today) : {}),
|
|
155
|
+
...librarySnapshot(),
|
|
156
|
+
};
|
|
157
|
+
const controller = new AbortController();
|
|
158
|
+
const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? SEND_TIMEOUT_MS);
|
|
159
|
+
try {
|
|
160
|
+
const response = await (deps.fetch ?? fetch)(ENDPOINT, {
|
|
161
|
+
method: "POST",
|
|
162
|
+
headers: { "App-Key": APP_KEY, "Content-Type": "application/json" },
|
|
163
|
+
body: JSON.stringify({
|
|
164
|
+
timestamp: now.toISOString(),
|
|
165
|
+
sessionId: randomUUID(),
|
|
166
|
+
eventName: `${surface}_daily`,
|
|
167
|
+
systemProps: systemProps(version),
|
|
168
|
+
props,
|
|
169
|
+
}),
|
|
170
|
+
signal: controller.signal,
|
|
171
|
+
});
|
|
172
|
+
if (!response.ok)
|
|
173
|
+
return false;
|
|
174
|
+
const body = (await response.json().catch(() => ({})));
|
|
175
|
+
return !body?.error;
|
|
176
|
+
}
|
|
177
|
+
finally {
|
|
178
|
+
clearTimeout(timer);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
catch {
|
|
182
|
+
return false;
|
|
183
|
+
}
|
|
184
|
+
}
|
package/dist/cli/usage.js
CHANGED
|
@@ -4,10 +4,12 @@
|
|
|
4
4
|
import { randomUUID } from "node:crypto";
|
|
5
5
|
import fs from "node:fs";
|
|
6
6
|
import path from "node:path";
|
|
7
|
+
import { stashDirNames } from "../core/asset/asset-placement.js";
|
|
7
8
|
import { peekConfigValue } from "../core/config/peek.js";
|
|
8
9
|
import { getDataDir } from "../core/paths.js";
|
|
9
|
-
import { isKnownType } from "../core/recognition-util.js";
|
|
10
|
+
import { isKnownType, KNOWN_TYPES } from "../core/recognition-util.js";
|
|
10
11
|
import { hasSignalOwner, observeSignal } from "../core/signal-observers.js";
|
|
12
|
+
import { DETAIL_VALUES, OUTPUT_FORMATS } from "../output/context.js";
|
|
11
13
|
import { openDatabase } from "../storage/database.js";
|
|
12
14
|
import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
|
|
13
15
|
import { resolveAgentIdentity } from "../workflows/runtime/agent-identity.js";
|
|
@@ -15,9 +17,9 @@ import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray } from
|
|
|
15
17
|
// Enum-like string flags are not enums in citty. Keep this finite allowlist
|
|
16
18
|
// independent of user data and never infer safety from the supplied value.
|
|
17
19
|
const SAFE_VALUES = {
|
|
18
|
-
format:
|
|
19
|
-
detail:
|
|
20
|
-
type: [
|
|
20
|
+
format: OUTPUT_FORMATS,
|
|
21
|
+
detail: DETAIL_VALUES,
|
|
22
|
+
type: [...KNOWN_TYPES, "any", ...stashDirNames()],
|
|
21
23
|
};
|
|
22
24
|
/** Scan declared identities only. Unknown spellings can themselves contain secrets. */
|
|
23
25
|
export function describeUsage(root, raw) {
|
|
@@ -200,7 +202,7 @@ function usagePath() {
|
|
|
200
202
|
// `schema_migrations` ledger, so they use their own `cli_usage_` names and a
|
|
201
203
|
// version in `cli_usage_meta` (never PRAGMA user_version or schema_migrations).
|
|
202
204
|
const USAGE_SCHEMA = 1;
|
|
203
|
-
function openUsage(filename) {
|
|
205
|
+
export function openUsage(filename = usagePath()) {
|
|
204
206
|
fs.mkdirSync(path.dirname(filename), { recursive: true });
|
|
205
207
|
const db = openDatabase(filename);
|
|
206
208
|
try {
|
|
@@ -235,6 +237,18 @@ export function setResolvedUsageAssetType(type, executor) {
|
|
|
235
237
|
function captureDisabledByConfig() {
|
|
236
238
|
return peekConfigValue(["usage", "capture"]) === false;
|
|
237
239
|
}
|
|
240
|
+
function readOnlyRequested(usage) {
|
|
241
|
+
return usage.arguments.some((a) => a.name === "read-only" && a.explicit && a.value === true);
|
|
242
|
+
}
|
|
243
|
+
/** Whether this invocation records no counts (`--read-only` or `usage.capture: false`), so there is nothing to report. */
|
|
244
|
+
export function usageCaptureOff(root, raw) {
|
|
245
|
+
try {
|
|
246
|
+
return readOnlyRequested(describeUsage(root, raw)) || captureDisabledByConfig();
|
|
247
|
+
}
|
|
248
|
+
catch {
|
|
249
|
+
return true;
|
|
250
|
+
}
|
|
251
|
+
}
|
|
238
252
|
export function startUsage(root, raw, version) {
|
|
239
253
|
const started = Date.now();
|
|
240
254
|
const id = randomUUID();
|
|
@@ -254,7 +268,7 @@ export function startUsage(root, raw, version) {
|
|
|
254
268
|
const usage = describeUsage(root, raw);
|
|
255
269
|
// `--read-only` promises no writes, and the config key turns capture off.
|
|
256
270
|
// Either way nothing is opened, written or finalized.
|
|
257
|
-
if (usage
|
|
271
|
+
if (readOnlyRequested(usage))
|
|
258
272
|
return () => { };
|
|
259
273
|
if (captureDisabledByConfig())
|
|
260
274
|
return () => { };
|
|
@@ -470,7 +484,10 @@ export function readUsage(filter = {}) {
|
|
|
470
484
|
unfinished: Number(row.attempts) - Number(row.completed),
|
|
471
485
|
});
|
|
472
486
|
}
|
|
473
|
-
|
|
487
|
+
const detailRows = filter.aggregatesOnly
|
|
488
|
+
? []
|
|
489
|
+
: db.prepare("SELECT * FROM cli_usage_invocations ORDER BY ts,id").all();
|
|
490
|
+
for (const row of detailRows) {
|
|
474
491
|
const data = JSON.parse(String(row.data));
|
|
475
492
|
if (selected({ ...data, day: String(data.ts).slice(0, 10) }))
|
|
476
493
|
empty.details.push({
|
package/dist/cli.js
CHANGED
|
@@ -70,7 +70,8 @@ import { warnDeprecatedUse } from "./cli/deprecations.js";
|
|
|
70
70
|
import { cittyComparableName, findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
|
|
71
71
|
import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, withoutHelpHiddenArgs, } from "./cli/shared.js";
|
|
72
72
|
import { assertKnownFlags, consumeConfigFileFlag } from "./cli/unknown-flags.js";
|
|
73
|
-
import { startUsage } from "./cli/usage.js";
|
|
73
|
+
import { startUsage, usageCaptureOff } from "./cli/usage.js";
|
|
74
|
+
import { reportUsageIfDue } from "./cli/usage-report.js";
|
|
74
75
|
import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
|
|
75
76
|
import { backupsCommand } from "./commands/backups-cli.js";
|
|
76
77
|
import { commandCommand } from "./commands/command/command-cli.js";
|
|
@@ -96,6 +97,7 @@ import { modelsCommand } from "./commands/models-cli.js";
|
|
|
96
97
|
import { doctorLogCommand, logCommand } from "./commands/observability-cli.js";
|
|
97
98
|
import { proposalCommand } from "./commands/proposal/proposal-cli.js";
|
|
98
99
|
import { rememberCommand } from "./commands/read/remember-cli.js";
|
|
100
|
+
import { rulesCommand } from "./commands/read/rules.js";
|
|
99
101
|
import { curateCommand, searchCommand, showCommand } from "./commands/read/search-cli.js";
|
|
100
102
|
import { registryCommand } from "./commands/registry-cli.js";
|
|
101
103
|
import { runAssetCommand } from "./commands/run-cli.js";
|
|
@@ -604,6 +606,7 @@ const commands = {
|
|
|
604
606
|
search: searchCommand,
|
|
605
607
|
curate: curateCommand,
|
|
606
608
|
show: showCommand,
|
|
609
|
+
rules: rulesCommand,
|
|
607
610
|
run: runAssetCommand,
|
|
608
611
|
workflow: workflowCommand,
|
|
609
612
|
remember: rememberCommand,
|
|
@@ -926,7 +929,7 @@ function buildUsageParentForPath(path) {
|
|
|
926
929
|
const HELP_SECTIONS = [
|
|
927
930
|
{
|
|
928
931
|
title: "AGENT LOOP",
|
|
929
|
-
commands: ["curate", "search", "show", "feedback", "remember"],
|
|
932
|
+
commands: ["curate", "search", "show", "rules", "feedback", "remember"],
|
|
930
933
|
},
|
|
931
934
|
{
|
|
932
935
|
title: "ASSETS",
|
|
@@ -1163,6 +1166,9 @@ export async function runCli() {
|
|
|
1163
1166
|
// Deliver catchable signals queued during synchronous child execution.
|
|
1164
1167
|
await new Promise((resolve) => setImmediate(resolve));
|
|
1165
1168
|
finishUsage();
|
|
1169
|
+
// After the command's own work; never changes output or exit code (see src/cli/usage-report.ts).
|
|
1170
|
+
if (!usageCaptureOff(main, originalArgs))
|
|
1171
|
+
await reportUsageIfDue({ surface: "cli", version: pkgVersion });
|
|
1166
1172
|
}
|
|
1167
1173
|
}
|
|
1168
1174
|
/** Apply `--config <file>` (stripping it from argv) and normalise `AKM_CONFIG_FILE` to an absolute path. */
|
|
@@ -4,11 +4,12 @@
|
|
|
4
4
|
import fs from "node:fs";
|
|
5
5
|
import os from "node:os";
|
|
6
6
|
import path from "node:path";
|
|
7
|
-
import { placementTypes } from "../core/asset/asset-placement.js";
|
|
7
|
+
import { documentTypes, placementTypes } from "../core/asset/asset-placement.js";
|
|
8
|
+
import { DETAIL_VALUES, OUTPUT_FORMATS } from "../output/context.js";
|
|
8
9
|
const FLAG_VALUES = {
|
|
9
|
-
"--format": [{ values: [
|
|
10
|
-
"--detail": [{ values: [
|
|
11
|
-
"--type": [{ values: () => [...placementTypes(), "any"] }],
|
|
10
|
+
"--format": [{ values: [...OUTPUT_FORMATS] }],
|
|
11
|
+
"--detail": [{ values: [...DETAIL_VALUES] }],
|
|
12
|
+
"--type": [{ paths: ["akm lint"], values: () => documentTypes() }, { values: () => [...placementTypes(), "any"] }],
|
|
12
13
|
"--shell": [{ values: ["bash"] }],
|
|
13
14
|
"--from": [{ paths: ["akm search", "akm curate"], values: ["local", "registry", "all"] }],
|
|
14
15
|
};
|
|
@@ -125,7 +125,9 @@ export const HEALTH_CHECKS = [
|
|
|
125
125
|
name: "state-db-round-trip",
|
|
126
126
|
kind: "deterministic",
|
|
127
127
|
// A skipped probe proved nothing: it is unknown, not a pass.
|
|
128
|
-
|
|
128
|
+
...(ctx.probe.skipped
|
|
129
|
+
? { status: "unknown", reason: "not-probed" }
|
|
130
|
+
: { status: ctx.probe.ok ? "pass" : "fail" }),
|
|
129
131
|
confidence: "high",
|
|
130
132
|
message: ctx.probe.skipped
|
|
131
133
|
? "state.db append/read round-trip skipped: this run is read-only."
|
|
@@ -244,7 +246,11 @@ export const HEALTH_CHECKS = [
|
|
|
244
246
|
return {
|
|
245
247
|
name: "improve-failures",
|
|
246
248
|
kind: "deterministic",
|
|
247
|
-
|
|
249
|
+
...(failedRunIds.length > 0
|
|
250
|
+
? { status: "warn" }
|
|
251
|
+
: interruptedRunIds.length > 0
|
|
252
|
+
? { status: "unknown", reason: "blocked" }
|
|
253
|
+
: { status: "pass" }),
|
|
248
254
|
confidence: "high",
|
|
249
255
|
message: failedRunIds.length > 0 || interruptedRunIds.length > 0
|
|
250
256
|
? `${failedRunIds.length} improve run(s) recorded failures since ${ctx.since}.${interruption ? ` ${interruption}` : ""} Inspect \`akm doctor --since ${ctx.since} --group-by run\`.`
|
|
@@ -346,7 +352,9 @@ export const HEALTH_CHECKS = [
|
|
|
346
352
|
};
|
|
347
353
|
const totalRows = rows.reduce((sum, row) => sum + row.count, 0);
|
|
348
354
|
if (totalRows === 0) {
|
|
349
|
-
|
|
355
|
+
// Extraction is off when the strategy does not enable it; with the config unreadable that is not known.
|
|
356
|
+
const reason = !ctx.proposalQueue ? "blocked" : ctx.proposalQueue.extractEnabled ? "idle" : "off";
|
|
357
|
+
return { ...base, status: "unknown", reason, message: `No extraction recorded in the last ${days} days.` };
|
|
350
358
|
}
|
|
351
359
|
// `read_failed` / `exception` land in the ledger as `failed`, not `skipped`.
|
|
352
360
|
const nothingHarvested = rows.every((row) => ["skipped", "failed", "proposal_write_failed"].includes(row.outcome));
|
|
@@ -412,13 +420,19 @@ export const HEALTH_CHECKS = [
|
|
|
412
420
|
return {
|
|
413
421
|
...base,
|
|
414
422
|
status: "unknown",
|
|
423
|
+
reason: "blocked",
|
|
415
424
|
message: "The primary stash or config could not be read; the proposal queue owner was not checked.",
|
|
416
425
|
};
|
|
417
426
|
}
|
|
418
427
|
const { stashDir, extractEnabled, problem } = ctx.proposalQueue;
|
|
419
428
|
const ranRecently = ctx.sessionExtractionLedger.rows.some((row) => row.count > 0);
|
|
420
429
|
if (!extractEnabled && !ranRecently) {
|
|
421
|
-
return {
|
|
430
|
+
return {
|
|
431
|
+
...base,
|
|
432
|
+
status: "unknown",
|
|
433
|
+
reason: "off",
|
|
434
|
+
message: "Learning is off, so the proposal queue owner was not checked.",
|
|
435
|
+
};
|
|
422
436
|
}
|
|
423
437
|
if (!problem)
|
|
424
438
|
return { ...base, status: "pass", message: `The proposal queue of ${stashDir} has a writable owner.` };
|
|
@@ -5,8 +5,7 @@
|
|
|
5
5
|
* `egress-endpoints` advisory for `akm health` (meta-review 08, surfaces 3/9):
|
|
6
6
|
* the remote-destination list, for eyeball diff. A pure projection over the
|
|
7
7
|
* effective config (no process.env reads); silent when nothing remote is
|
|
8
|
-
* configured, matching the `
|
|
9
|
-
* advisories' pattern.
|
|
8
|
+
* configured, matching the `binary-config-skew` advisory's pattern.
|
|
10
9
|
*/
|
|
11
10
|
import { redactCredentialPatterns } from "../../core/redaction.js";
|
|
12
11
|
import { formatRegistryUrl } from "../../core/registry-url.js";
|