akm-cli 0.9.0 → 0.9.1-beta.2

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0",
+  "version": "0.9.1-beta.2",
   "type": "module",
-  "description": "akm (Agent Knowledge Manager) — A knowledge toolkit for AI agents: capture, curate, search, and share skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
+  "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.",
   "keywords": [
     "akm",
     "agent-knowledge-management",
@@ -21,7 +21,9 @@
     "mcp",
     "ai-coding-assistant",
     "agent-skills",
-    "skill-management"
+    "skill-management",
+    "capability-library",
+    "agent-capabilities"
   ],
   "homepage": "https://github.com/itlackey/akm#readme",
   "repository": {
@@ -33,7 +35,8 @@
   },
   "license": "MPL-2.0",
   "pinNotes": {
-    "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for."
+    "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for.",
+    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift."
   },
   "files": [
     "dist",
@@ -46,9 +49,12 @@
     "docs/migration/v0.7-to-v0.8.md",
     "docs/migration/v0.8-to-v0.9.md",
     "docs/migration/v0.9.0-troubleshooting.md",
+    "docs/reference/bundle-types.md",
     "docs/reference/cli.md",
     "docs/reference/configuration.md",
     "docs/reference/data-and-telemetry.md",
+    "docs/reference/supported-formats.md",
+    "docs/reference/workflow-schema.md",
     "docs/reference/workflows.md",
     "schemas"
   ],
@@ -71,11 +77,12 @@
     "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
+    "lint:active-docs-terminology": "bun scripts/lint-active-docs-terminology.ts",
     "lint:devto-posts": "bun scripts/lint-devto-posts.ts",
     "lint:devto-posts:fix": "bun scripts/lint-devto-posts.ts --fix",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check && bun scripts/lint-active-docs-terminology.ts",
     "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
     "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",
@@ -100,7 +107,7 @@
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0",
-    "better-sqlite3": "^11.8.0",
+    "better-sqlite3": "12.11.1",
     "sqlite-vec": "^0.1.9"
   },
   "engines": {

package/schemas/akm-config.json

@@ -45,7 +45,8 @@
                 "anyOf": [
                   {
                     "type": "integer",
-                    "exclusiveMinimum": 0
+                    "exclusiveMinimum": 0,
+                    "maximum": 2147483647
                   },
                   {
                     "type": "null"
@@ -122,7 +123,8 @@
                 "anyOf": [
                   {
                     "type": "integer",
-                    "exclusiveMinimum": 0
+                    "exclusiveMinimum": 0,
+                    "maximum": 2147483647
                   },
                   {
                     "type": "null"
@@ -1622,6 +1624,10 @@
           "type": "integer",
           "exclusiveMinimum": 0
         },
+        "defaultMapConcurrency": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
         "judgeEngine": {
           "type": "string",
           "maxLength": 63,
@@ -1693,7 +1699,8 @@
                     "anyOf": [
                       {
                         "type": "integer",
-                        "exclusiveMinimum": 0
+                        "exclusiveMinimum": 0,
+                        "maximum": 2147483647
                       },
                       {
                         "type": "null"
@@ -1770,7 +1777,8 @@
                     "anyOf": [
                       {
                         "type": "integer",
-                        "exclusiveMinimum": 0
+                        "exclusiveMinimum": 0,
+                        "maximum": 2147483647
                       },
                       {
                         "type": "null"
@@ -3270,6 +3278,10 @@
               "type": "integer",
               "exclusiveMinimum": 0
             },
+            "defaultMapConcurrency": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
             "judgeEngine": {
               "type": "string",
               "maxLength": 63,
@@ -3324,7 +3336,8 @@
           "anyOf": [
             {
               "type": "integer",
-              "exclusiveMinimum": 0
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
             },
             {
               "type": "null"

package/schemas/akm-task.json

@@ -25,21 +25,43 @@
     "params": { "type": "object" },
     "engine": { "type": "string", "minLength": 1 },
     "model": { "type": "string", "minLength": 1 },
-    "timeoutMs": { "type": ["integer", "null"], "minimum": 1 },
-    "llm": { "$ref": "#/definitions/llm" }
+    "timeoutMs": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "maximum": 2147483647,
+      "description": "Timeout in milliseconds, or null to disable it. Prompt tasks: the engine timeout. Command tasks: the subprocess timeout. Workflow tasks: the whole-run timeout — omit it to take the unattended default (DEFAULT_WORKFLOW_TASK_TIMEOUT_MS in src/tasks/runner.ts), null to run unbounded."
+    },
+    "maxSteps": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Workflow tasks only: stop after executing this many workflow steps (`akm workflow run --max-steps`)."
+    },
+    "maxRetries": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Workflow tasks only: retry a failed workflow step this many additional times (`akm workflow run --max-retries`)."
+    },
+    "llm": { "$ref": "#/definitions/llm" },
+    "redact": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "description": "NAMES ONLY: environment variable names whose values are scrubbed from this task's persisted run log and logs.db rows. Values never appear in a task file — a task file is indexed, searchable, and printed verbatim by `akm show`, so a literal secret here would leak more widely than the redaction closes. akm already scrubs config-declared credentials and infers others from the variable name; this is the escape hatch for a secret exported under a name none of those rules recognise. A name unset at run time contributes nothing."
+    }
   },
   "oneOf": [
     {
       "required": ["workflow"],
-      "not": { "anyOf": [{ "required": ["prompt"] }, { "required": ["command"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["timeoutMs"] }, { "required": ["llm"] }] }
+      "not": { "anyOf": [{ "required": ["prompt"] }, { "required": ["command"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["llm"] }] }
     },
     {
       "required": ["prompt"],
-      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["command"] }, { "required": ["params"] }] }
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["command"] }, { "required": ["params"] }, { "required": ["maxSteps"] }, { "required": ["maxRetries"] }] }
     },
     {
       "required": ["command"],
-      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["prompt"] }, { "required": ["params"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["llm"] }] }
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["prompt"] }, { "required": ["params"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["llm"] }, { "required": ["maxSteps"] }, { "required": ["maxRetries"] }] }
     }
   ],
   "definitions": {

package/schemas/akm-workflow.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://itlackey.github.io/akm/schemas/akm-workflow.json",
   "title": "AKM Workflow",
-  "description": "Unified akm workflow frontmatter (workflow-format-unification). One markdown asset: the standard AKM asset envelope (type/description/tags/when_to_use/xrefs/updated/timestamp + the OKF v0.2 machine-stamped families) plus the orchestration graph. Per-step prose instructions and gate rubrics live in the markdown body, joined to this graph by step id — see docs/reference/workflows.md. Hand-authored alongside src/workflows/program/schema.ts; the enum vocabularies and patterns here are pinned against the TypeScript constants by tests/integration/workflows/schema-drift.test.ts.",
+  "description": "Unified akm workflow frontmatter (workflow-format-unification). One markdown asset: the standard AKM asset envelope (type/description/tags/when_to_use/xrefs/updated/timestamp + the OKF v0.2 machine-stamped families) plus the orchestration graph. Per-step prose instructions and gate rubrics live in the markdown body, joined to this graph by step id — see docs/reference/workflow-schema.md. Hand-authored alongside src/workflows/program/schema.ts; the enum vocabularies and patterns here are pinned against the TypeScript constants by tests/integration/workflows/schema-drift.test.ts.",
   "type": "object",
   "required": ["steps"],
   "additionalProperties": false,
@@ -57,7 +57,7 @@
       "description": "A bare reference string: params.<name> or steps.<id>.output(.<ident>|[<int>])*. No ${{ }} delimiters — every position this appears in is a whole-value frontmatter field. Full grammar validation happens at compile time, not here."
     },
     "timeout": {
-      "description": "Duration: \"<n>ms\" | \"<n>s\" | \"<n>m\" | \"none\" (bare integers are milliseconds).",
+      "description": "Duration: \"<n>ms\" | \"<n>s\" | \"<n>m\" | \"none\" (bare integers are milliseconds). Must resolve to at most 2147483647 ms (setTimeout's 32-bit signed ceiling) — the parser enforces the same ceiling on the string form.",
       "oneOf": [
         {
           "type": "string",
@@ -65,10 +65,18 @@
         },
         {
           "type": "integer",
-          "minimum": 1
+          "minimum": 1,
+          "maximum": 2147483647
         }
       ]
     },
+    "engineName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+      "description": "Named engine: lowercase dash-separated words of letters and digits, starting with a letter. Same grammar the frozen-plan decoder enforces (src/workflows/resource-limits.ts WORKFLOW_ENGINE_NAME_PATTERN)."
+    },
     "onError": {
       "description": "Failure policy: fail the step on the first unit failure (default), or record failures and let the gate decide.",
       "enum": ["fail", "continue"]
@@ -140,7 +148,7 @@
     },
     "jsonSchemaObject": {
       "type": "object",
-      "description": "A JSON Schema declaration (validated as a schema by the compiler, not here)."
+      "description": "A JSON Schema declaration. The parser validates it as a schema definition against the runtime's enforced subset (src/core/json-schema.ts checkJsonSchemaDefinition): typo'd type names and keywords outside the subset (e.g. $ref, const, format, patternProperties) are authoring-time errors, not silent no-ops."
     },
     "retry": {
       "type": "object",
@@ -151,6 +159,7 @@
         "max": {
           "type": "integer",
           "minimum": 0,
+          "maximum": 100,
           "description": "Maximum retry attempts per unit."
         },
         "on": {
@@ -186,8 +195,7 @@
       "additionalProperties": false,
       "properties": {
         "engine": {
-          "type": "string",
-          "minLength": 1
+          "$ref": "#/definitions/engineName"
         },
         "model": {
           "type": "string",
@@ -205,14 +213,79 @@
         }
       }
     },
-    "unit": {
+    "exec": {
       "type": "object",
-      "description": "Optional dispatch-override bag for a unit/map step. A step with none of these carries the run's engine/model/timeout defaults verbatim.",
+      "description": "Run a shell command as this unit instead of dispatching to an engine. `command` is an ARGV ARRAY and there is no shell-string form: the child is spawned directly, so shell metacharacters (`;` `|` `&&` `$(…)` `>` `*`) are inert literal argument bytes — the quoting/injection class simply does not exist. Write the interpreter explicitly (e.g. [\"bash\", \"-lc\", \"a | b\"]) when a pipeline is really wanted. stdout is the promoted step artifact with trailing newlines stripped (like shell `$(…)`); when the unit declares an `output` schema, stdout must instead be exactly one JSON value, which is validated against it. A non-zero exit fails the unit with failure reason `non_zero_exit`, honoring `retry:` and `on_error:` like any other unit. The child's environment is an ALLOWLIST by default (PATH, HOME, locale/temp vars, the Windows process-creation essentials) — widen it with `pass_env` or `inherit_env`.",
+      "required": ["command"],
       "additionalProperties": false,
       "properties": {
-        "engine": {
+        "command": {
+          "type": "array",
+          "description": "argv; command[0] is the program, resolved through PATH. Never shell-parsed.",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          }
+        },
+        "cwd": {
           "type": "string",
+          "description": "Optional RELATIVE working directory inside the unit's working directory (its fresh worktree under `isolation: worktree`). Absolute paths, Windows drive letters, \"~\", and \"..\" segments are rejected here, and containment is re-checked against the resolved base — symlinks included — before the command is spawned.",
           "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "^(?!/|\\\\|~|[A-Za-z]:)(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$"
+        },
+        "pass_env": {
+          "type": "array",
+          "description": "Extra environment variable NAMES copied through from akm's own environment on top of the default allowlist — for a per-machine toolchain variable (e.g. CARGO_HOME) that no committed `env:` asset could carry. NAMES ONLY: values never appear in a workflow, and unlike `env:` bindings these values are NOT redacted from the command's output, so never list a credential here.",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+          }
+        },
+        "inherit_env": {
+          "type": "boolean",
+          "description": "Give the command akm's ENTIRE environment instead of the default allowlist. Opt in only when a command genuinely needs the caller's whole environment (a wrapper script, a toolchain with many ambient variables); prefer `pass_env` or `env:` bindings, which keep what the command can see explicit in the frontmatter diff. Dispatch-significant: toggling it changes the unit's input hash."
+        }
+      }
+    },
+    "unit": {
+      "type": "object",
+      "description": "Optional dispatch-override bag for a unit/map step. A step with none of these carries the run's engine/model/timeout defaults verbatim. Declaring `exec` turns the step into a shell-command unit: it names no engine, so `engine`, `model`, and `llm` are rejected alongside it.",
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "required": ["exec"]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": ["engine"]
+                },
+                {
+                  "required": ["model"]
+                },
+                {
+                  "required": ["llm"]
+                }
+              ]
+            }
+          }
+        }
+      ],
+      "properties": {
+        "exec": {
+          "$ref": "#/definitions/exec"
+        },
+        "engine": {
+          "$ref": "#/definitions/engineName",
           "description": "Named engine selected when the workflow run is created."
         },
         "model": {
@@ -236,11 +309,12 @@
         },
         "env": {
           "type": "array",
+          "uniqueItems": true,
           "items": {
             "type": "string",
             "minLength": 1
           },
-          "description": "Env asset refs injected into the dispatched unit env."
+          "description": "Env asset refs injected into the dispatched unit env. Entries must be unique: the frozen-plan decoder rejects duplicates at run start."
         },
         "isolation": {
           "$ref": "#/definitions/isolation"
@@ -260,7 +334,8 @@
         "concurrency": {
           "type": "integer",
           "minimum": 1,
-          "description": "Max concurrent units for this step; capped by the engine's global limit."
+          "maximum": 64,
+          "description": "Max concurrent units for this step. Defaults to workflow.defaultMapConcurrency (4 when unset) — a map step is parallel by default since 0.9.1; write 1 for serial execution. The effective width is the minimum of this, workflow.maxConcurrency, the selected engine's concurrency, and the host CPU cap."
         },
         "reducer": {
           "$ref": "#/definitions/reducer"
@@ -276,7 +351,9 @@
       "additionalProperties": false,
       "properties": {
         "match": {
-          "type": ["string", "number", "boolean"]
+          "type": ["string", "number", "boolean"],
+          "minLength": 1,
+          "description": "Branch key. An empty string is rejected: the frozen-plan decoder requires every `when` key to be non-empty."
         },
         "step": {
           "$ref": "#/definitions/identifier"
@@ -314,6 +391,7 @@
         "max_loops": {
           "type": "integer",
           "minimum": 1,
+          "maximum": 100,
           "description": "Evaluator-optimizer loop bound."
         }
       }
@@ -322,10 +400,11 @@
       "type": "array",
       "minItems": 1,
       "maxItems": 64,
+      "uniqueItems": true,
       "items": {
         "$ref": "#/definitions/reference"
       },
-      "description": "Prior-step artifacts this unit/map step consumes, as reference strings (sub-paths legal). Attached to the dispatched unit as structured context; never spliced into instructions."
+      "description": "Prior-step artifacts this unit/map step consumes, as reference strings (sub-paths legal). Attached to the dispatched unit as structured context; never spliced into instructions. Entries must be unique: the frozen-plan decoder rejects duplicates at run start."
     },
     "step": {
       "type": "object",