akm-cli 0.8.0-rc.7 → 0.8.0-rc.9

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-28
+
+### Fixed
+
+- **Consolidation `delete_failed` on stale index entries** — when consolidation
+  successfully deleted a memory file, the index DB was not re-indexed between
+  runs. Subsequent runs loaded the stale DB entry into their memory map, the LLM
+  re-proposed the deletion, and `deleteAssetFromSource` threw "not found in
+  source" — appearing as `delete_failed` in skipReasons. Fix: `loadMemoriesForSource`
+  now filters entries whose file no longer exists on disk before building chunks,
+  so phantom memories are never sent to the LLM. A secondary catch in the delete
+  handler emits `delete_already_gone` instead of `delete_failed` when the file
+  is confirmed absent.
+
 > **CI / Docker users:** the 0.8.0 storage split moved `akm.lock`, the event
 > database, and the registry cache out of `$XDG_CONFIG_HOME/akm/` into
 > `$XDG_DATA_HOME`, `$XDG_STATE_HOME`, and `$XDG_CACHE_HOME` respectively. If
@@ -65,6 +79,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
+- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Management** — `akm` stands for Agent Knowledge Management going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
+
 - **Config layer rewrite** — single-source-of-truth Zod schema in
   `src/core/config-schema.ts` replaces the per-field parse switch AND
   the per-shape load-time parser. Adding a new config field is now one

package/README.md

@@ -1,6 +1,6 @@
-# akm -- Agent Kit Manager
+# akm -- Agent Knowledge Management
 
-> **akm** (Agent Kit Manager) -- A package manager for AI agent skills, commands, tools, and knowledge.
+> **akm** (Agent Knowledge Management) -- A package manager for AI agent skills, commands, tools, and knowledge.
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![npm downloads](https://img.shields.io/npm/dm/akm-cli)](https://www.npmjs.com/package/akm-cli)

package/dist/cli.js

@@ -2051,6 +2051,258 @@ const vaultCommand = defineCommand({
         });
     },
 });
+// ── secret ──────────────────────────────────────────────────────────────────
+//
+// `akm secret` manages whole-file secrets under each stash's secrets/ directory.
+// Unlike vaults (.env key/value), the ENTIRE file is the secret value. The bytes
+// are NEVER written to stdout or structured output. Values reach a command only
+// via `akm secret run` (injected into a child env var) or `akm secret path`
+// (the Docker /run/secrets + `_FILE` convention).
+function parseSecretRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `secret:${ref}`);
+}
+function makeSecretRef(name, source) {
+    return source?.registryId ? `${source.registryId}//secret:${name}` : `secret:${name}`;
+}
+function resolveSecretPath(ref) {
+    const parsed = parseSecretRef(ref);
+    if (parsed.type !== "secret") {
+        throw new UsageError(`Expected a secret ref (secret:<name>); got "${ref}".`);
+    }
+    // Source resolution is identical for every asset type; reuse the vault helper.
+    const source = findVaultSource(parsed.origin);
+    const typeRoot = path.join(source.path, "secrets");
+    const absPath = resolveAssetPathFromName("secret", typeRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
+    }
+    return { name: parsed.name, absPath, source };
+}
+/** Walk `secrets/` across all stashes, returning one entry per secret file. */
+function listSecretsRecursive() {
+    const result = [];
+    for (const source of resolveSourceEntries(undefined, loadConfig())) {
+        const secretsDir = path.join(source.path, "secrets");
+        if (!fs.existsSync(secretsDir))
+            continue;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (entry.name.endsWith(".lock") || entry.name.endsWith(".sensitive"))
+                    continue;
+                // A sibling `<name>.sensitive` marker suppresses listing.
+                if (fs.existsSync(`${full}.sensitive`))
+                    continue;
+                const canonical = deriveCanonicalAssetName("secret", secretsDir, full);
+                if (!canonical)
+                    continue;
+                result.push({ ref: makeSecretRef(canonical, source), path: full });
+            }
+        };
+        walk(secretsDir);
+    }
+    return result;
+}
+const secretListCommand = defineCommand({
+    meta: {
+        name: "list",
+        description: "List all secrets across all stashes by name (the file contents are never shown)",
+    },
+    run() {
+        return runWithJsonErrors(async () => {
+            output("secret-list", { secrets: listSecretsRecursive() });
+        });
+    },
+});
+const secretSetCommand = defineCommand({
+    meta: {
+        name: "set",
+        description: "Create or overwrite a secret. The value is read from stdin by default (never via argv). Use --from-file <path> to import an existing file byte-exact, or --from-env <VAR> to read from an environment variable. Multi-line values are allowed.",
+    },
+    args: {
+        ref: { type: "positional", description: "Secret ref (e.g. secret:deploy-key or just deploy-key)", required: true },
+        "from-file": { type: "string", description: "Read the value from this file (stored byte-exact)" },
+        "from-env": { type: "string", description: "Read the value from the named environment variable" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { setSecret } = await import("./commands/secret.js");
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            const fromEnv = getHyphenatedArg(args, "from-env");
+            const fromFile = getHyphenatedArg(args, "from-file");
+            if (fromEnv !== undefined && fromFile !== undefined) {
+                throw new UsageError("Pass only one of --from-file or --from-env (or use stdin).", "INVALID_FLAG_VALUE");
+            }
+            const MAX_SECRET_BYTES = 5 * 1024 * 1024; // 5 MB
+            let value;
+            if (fromFile !== undefined) {
+                if (!fs.existsSync(fromFile)) {
+                    throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
+                }
+                value = fs.readFileSync(fromFile);
+                if (value.byteLength > MAX_SECRET_BYTES) {
+                    throw new UsageError("Secret exceeds the 5 MB limit.");
+                }
+            }
+            else if (fromEnv !== undefined) {
+                const envVal = process.env[fromEnv];
+                if (envVal === undefined) {
+                    throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
+                }
+                value = Buffer.from(envVal, "utf8");
+            }
+            else {
+                if (process.stdin.isTTY) {
+                    process.stderr.write(`Enter value for secret "${name}" (Ctrl-D when done):\n`);
+                }
+                let totalBytes = 0;
+                const chunks = [];
+                for await (const chunk of Bun.stdin.stream()) {
+                    totalBytes += chunk.byteLength;
+                    if (totalBytes > MAX_SECRET_BYTES) {
+                        throw new UsageError("Secret exceeds the 5 MB limit.");
+                    }
+                    chunks.push(chunk);
+                }
+                // Strip a single trailing newline so `echo "$TOKEN" | akm secret set`
+                // stores the token without the shell-added newline. Use --from-file for
+                // byte-exact storage of multi-line material (PEM keys, certs).
+                value = Buffer.from(Buffer.concat(chunks).toString("utf8").replace(/\n$/, ""), "utf8");
+            }
+            setSecret(absPath, value);
+            output("secret-set", { ref: makeSecretRef(name, source) });
+        });
+    },
+});
+const secretPathCommand = defineCommand({
+    meta: {
+        name: "path",
+        description: "Print the absolute secret file path for the Docker `_FILE` convention, e.g. `MY_SECRET_FILE=$(akm secret path secret:deploy-key)`.",
+    },
+    args: {
+        ref: { type: "positional", description: "Secret ref", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
+            }
+            process.stdout.write(`${absPath}\n`);
+        });
+    },
+});
+const secretRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Run a command with a secret's value injected into an env var: `akm secret run <ref> <VAR> -- <command>`. The value is set as $VAR in the child process only.",
+    },
+    args: {
+        ref: { type: "positional", description: "Secret ref", required: true },
+        var: { type: "positional", description: "Environment variable name to inject the value into", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            // Validate the target env var name FIRST (before the command split) so a
+            // dangerous/invalid name is rejected regardless of how the command is
+            // supplied — and so the failure does not depend on argv parsing.
+            const varName = args.var;
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) {
+                throw new UsageError(`"${varName}" is not a valid environment variable name.`, "INVALID_FLAG_VALUE");
+            }
+            const { isDangerousVaultKey } = await import("./commands/lint/vault-key-rules.js");
+            if (isDangerousVaultKey(varName)) {
+                throw new UsageError(`Refusing to inject a secret into "${varName}": it is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`, "INVALID_FLAG_VALUE");
+            }
+            const dashIndex = process.argv.indexOf("--");
+            if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
+                throw new UsageError("Missing command. Usage: akm secret run <ref> <VAR> -- <command>");
+            }
+            const command = process.argv.slice(dashIndex + 1);
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
+            }
+            const { readValue } = await import("./commands/secret.js");
+            const mergedEnv = { ...process.env };
+            mergedEnv[varName] = readValue(absPath).toString("utf8");
+            // Audit trail: record access by ref + var name only — never the value.
+            appendEvent({
+                eventType: "secret_access",
+                ref: makeSecretRef(name, source),
+                metadata: { var: varName },
+            });
+            const result = spawnSync(command[0], command.slice(1), {
+                stdio: "inherit",
+                env: mergedEnv,
+            });
+            if (result.error) {
+                const err = result.error;
+                if (err.code === "ENOENT") {
+                    throw new NotFoundError(`Command not found: ${command[0]}`, "FILE_NOT_FOUND", `Install '${command[0]}' or add its directory to PATH before invoking 'akm secret run'.`);
+                }
+                if (err.code === "EACCES") {
+                    throw new ConfigError(`Command not executable: ${command[0]}`, "STASH_DIR_UNREADABLE", `Add execute permission ('chmod +x ${command[0]}') or invoke via an interpreter.`);
+                }
+                throw err;
+            }
+            process.exit(result.status ?? 0);
+        });
+    },
+});
+const secretRemoveCommand = defineCommand({
+    meta: { name: "remove", description: "Remove a secret (and its .sensitive marker, if any)" },
+    args: {
+        ref: { type: "positional", description: "Secret ref", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove secret "${args.ref}"? This cannot be undone.`, {
+                yes: args.yes === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
+            const { removeSecret } = await import("./commands/secret.js");
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
+            }
+            const removed = removeSecret(absPath);
+            output("secret-remove", { ref: makeSecretRef(name, source), removed });
+        });
+    },
+});
+const secretCommand = defineCommand({
+    meta: {
+        name: "secret",
+        description: "Manage whole-file secrets (PEM keys, tokens, certs). Names are visible; the file contents are the value and never appear in structured output.",
+    },
+    subCommands: {
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
+                return;
+            output("secret-list", { secrets: listSecretsRecursive() });
+        });
+    },
+});
 // ── Wiki subcommands ─────────────────────────────────────────────────────────
 const wikiCreateCommand = defineCommand({
     meta: { name: "create", description: "Scaffold a new wiki under <stashDir>/wikis/<name>/" },
@@ -3171,11 +3423,11 @@ const tasksCommand = defineCommand({
         });
     },
 });
-const main = defineCommand({
+export const main = defineCommand({
     meta: {
         name: "akm",
         version: pkgVersion,
-        description: "Agent Kit Manager — search, show, and manage assets from your stash.",
+        description: "Agent Knowledge Management — search, show, and manage assets from your stash.",
     },
     args: {
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)", default: "json" },
@@ -3243,12 +3495,14 @@ const main = defineCommand({
         hints: hintsCommand,
         completions: completionsCommand,
         vault: vaultCommand,
+        secret: secretCommand,
         wiki: wikiCommand,
         tasks: tasksCommand,
     },
 });
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset"]);
 const VAULT_SUBCOMMAND_SET = new Set(["list", "path", "run", "create", "set", "unset"]);
+const SECRET_SUBCOMMAND_SET = new Set(["list", "path", "run", "set", "remove"]);
 const WIKI_SUBCOMMAND_SET = new Set([
     "create",
     "register",
@@ -3267,62 +3521,69 @@ const EXIT_GENERAL = 1;
  *  fired but no hard failure). Chosen as 4 to avoid colliding with EXIT_GENERAL
  *  (1) and USAGE (2). CI monitors can map: 0=pass, 4=warn, 1=fail. */
 const EXIT_HEALTH_WARN = 4;
-// citty reads process.argv directly and does not accept a custom argv array,
-// so we must replace process.argv with the normalized version before runMain.
-process.argv = normalizeShowArgv(process.argv);
-// Resolve output mode once at startup from the (normalized) argv and persisted
-// config. All subsequent output() calls read from this in-memory singleton.
-// `initOutputMode` can throw a UsageError when --format/--detail values are
-// invalid; surface it through the same JSON-error path the rest of the CLI uses
-// rather than letting the raw exception escape with a stack trace.
-try {
-    applyEarlyStderrFlags(process.argv);
-    initOutputMode(process.argv, loadConfig().output ?? {});
-}
-catch (error) {
-    emitJsonError(error);
-}
-// One-time cleanup of stale 0.7.x index file at the old cache location.
-// 0.8.0 moved the index to $XDG_DATA_HOME/akm/index.db (getDataDir()).
-// If the old file exists at $XDG_CACHE_HOME/akm/index.db, remove it so the
-// user isn't confused by a phantom DB. Best-effort; never fatal.
-try {
-    const oldIndexPath = path.join(getCacheDir(), "index.db");
-    if (fs.existsSync(oldIndexPath)) {
-        fs.rmSync(oldIndexPath, { force: true });
-        fs.rmSync(`${oldIndexPath}-shm`, { force: true });
-        fs.rmSync(`${oldIndexPath}-wal`, { force: true });
-        warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
+// Only run the CLI when this module is the direct entry point. When it is
+// imported (e.g. by the in-process test harness in tests/_helpers/cli.ts),
+// `import.meta.main` is false and we skip all startup side effects (argv
+// mutation, output-mode init, index cleanup, banner, runMain) so importers
+// can drive the `main` command themselves without the process exiting.
+if (import.meta.main) {
+    // citty reads process.argv directly and does not accept a custom argv array,
+    // so we must replace process.argv with the normalized version before runMain.
+    process.argv = normalizeShowArgv(process.argv);
+    // Resolve output mode once at startup from the (normalized) argv and persisted
+    // config. All subsequent output() calls read from this in-memory singleton.
+    // `initOutputMode` can throw a UsageError when --format/--detail values are
+    // invalid; surface it through the same JSON-error path the rest of the CLI uses
+    // rather than letting the raw exception escape with a stack trace.
+    try {
+        applyEarlyStderrFlags(process.argv);
+        initOutputMode(process.argv, loadConfig().output ?? {});
     }
-}
-catch {
-    // Non-fatal; one-time warning only.
-}
-// First-time-user breadcrumb: when run with no subcommand AND no config
-// exists yet AND stderr is a TTY, print a friendly pointer to `akm setup`
-// above citty's auto-generated usage block. Triggers only when stdin/stderr
-// are interactive (so JSON-output users / CI consumers see nothing extra)
-// and stays silent for any flag-only invocation citty would handle itself
-// (--help, --version).
-(function maybePrintFirstTimeBanner() {
-    const argv = process.argv.slice(2);
-    // Fire only on completely bare `akm` invocation. Any explicit flag or
-    // subcommand means the user knows what they want.
-    if (argv.length > 0)
-        return;
-    if (!process.stderr.isTTY)
-        return;
+    catch (error) {
+        emitJsonError(error);
+    }
+    // One-time cleanup of stale 0.7.x index file at the old cache location.
+    // 0.8.0 moved the index to $XDG_DATA_HOME/akm/index.db (getDataDir()).
+    // If the old file exists at $XDG_CACHE_HOME/akm/index.db, remove it so the
+    // user isn't confused by a phantom DB. Best-effort; never fatal.
     try {
-        if (fs.existsSync(getConfigPath()))
-            return;
+        const oldIndexPath = path.join(getCacheDir(), "index.db");
+        if (fs.existsSync(oldIndexPath)) {
+            fs.rmSync(oldIndexPath, { force: true });
+            fs.rmSync(`${oldIndexPath}-shm`, { force: true });
+            fs.rmSync(`${oldIndexPath}-wal`, { force: true });
+            warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
+        }
     }
     catch {
-        // If we can't resolve the config path, assume non-fresh and stay silent.
-        return;
+        // Non-fatal; one-time warning only.
     }
-    console.error(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
-})();
-runMain(main);
+    // First-time-user breadcrumb: when run with no subcommand AND no config
+    // exists yet AND stderr is a TTY, print a friendly pointer to `akm setup`
+    // above citty's auto-generated usage block. Triggers only when stdin/stderr
+    // are interactive (so JSON-output users / CI consumers see nothing extra)
+    // and stays silent for any flag-only invocation citty would handle itself
+    // (--help, --version).
+    (function maybePrintFirstTimeBanner() {
+        const argv = process.argv.slice(2);
+        // Fire only on completely bare `akm` invocation. Any explicit flag or
+        // subcommand means the user knows what they want.
+        if (argv.length > 0)
+            return;
+        if (!process.stderr.isTTY)
+            return;
+        try {
+            if (fs.existsSync(getConfigPath()))
+                return;
+        }
+        catch {
+            // If we can't resolve the config path, assume non-fresh and stay silent.
+            return;
+        }
+        console.error(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
+    })();
+    runMain(main);
+}
 // ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
 function loadHints(detail = "normal") {
     const filename = detail === "full" ? "AGENTS.full.md" : "AGENTS.md";