akm-cli 0.8.6 → 0.8.14

package/dist/commands/env/env.js

@@ -0,0 +1,410 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Environment asset type (`env`) — whole `.env` file storage.
+ *
+ * An `env` asset holds a GROUP of related CONFIGURATION for an app or service
+ * (URLs, feature flags, and any credentials it needs) in a single `.env` file,
+ * sourced/injected wholesale. Values may or may not be sensitive — akm protects
+ * them all the same. For a single sensitive value used on its own for
+ * authentication (a token, key, or cert), use the `secret` type instead.
+ *
+ * Single keys can be managed with `akm env set <ref> KEY` (value read from stdin
+ * or `--from-env`/`--from-file`, never argv) and `akm env unset <ref> KEY...`,
+ * which do a minimal line-level edit that preserves existing comments and key
+ * order (see `setEnvKey` / `unsetEnvKeys`). You can also just edit the `.env`
+ * file with your own editor. Values are quoted/escaped only when necessary and
+ * round-trip through `dotenv`; the shell-load safety guarantee still lives on
+ * the READ path (see `buildShellExportScript` + `akm env export`).
+ *
+ * Invariant: env values must never be written to stdout, returned through the
+ * indexer, the `akm show` renderer, or any structured output channel. Key
+ * NAMES and start-of-line comments ARE surfaced by design (discoverability) —
+ * only values are secret. The supported value-load paths are:
+ *
+ *   - `akm env run <ref> -- <command>` — values injected into the child
+ *     process env (never via a shell), see `injectIntoEnv` / `loadEnv`. This is
+ *     the primary path and the only one safe for AI agents (no values ever
+ *     reach stdout). For an interactive shell, `akm env run <ref> -- $SHELL`.
+ *   - `akm env export <ref> --out <file>` — write parse-then-reserialized safe
+ *     `export KEY='value'` lines to a file (mode 0600) for `source`-ing. Values
+ *     are re-emitted single-quoted so a raw `.env` containing `X=$(cmd)` cannot
+ *     execute on load. `export` never prints values to stdout (would leak into
+ *     an agent's context); `path` prints only the file path.
+ *
+ * Value parsing is delegated to the `dotenv` package, and `dotenv` is also the
+ * serialisation oracle for `env set` (`setEnvKey`): a written value is only
+ * committed if `dotenv.parse` reads it back exactly, and the whole edit is
+ * re-parsed to confirm no other key was disturbed. We never hand-roll a
+ * quoting representation we cannot read back.
+ *
+ * Secret-token substitution: env VALUES may embed `${secret:NAME}` tokens, which
+ * are replaced at `env run` time with the value of the sibling `secret:NAME`
+ * asset in the SAME stash (see `resolveSecretTokens`). Substitution applies to
+ * values only, never keys; only the `${secret:...}` form is recognised —
+ * shell-style `${VAR}` / `$VAR` are left untouched. The secret lookup is
+ * injected so this module keeps its narrow dependency surface (dotenv +
+ * core/common) and never reaches into the secret resolver/source machinery.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { writeFileAtomic } from "../../core/common.js";
+import { UsageError } from "../../core/errors.js";
+/** Matches a KEY=value assignment line, capturing only the key. */
+const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** Scan lines and return KEY names in file order, without duplicates. */
+function scanKeys(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(ASSIGN_RE);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/**
+ * Scan lines and return start-of-line `#` comments (with the leading `#` and
+ * any leading whitespace stripped). Inline/trailing `#` after an assignment is
+ * never extracted.
+ */
+function scanComments(text) {
+    const comments = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            comments.push(trimmed.slice(1).trimStart());
+        }
+    }
+    return comments;
+}
+/**
+ * Read and return ONLY non-secret metadata (keys + start-of-line comments).
+ *
+ * The function reads the whole file into memory (same as any dotenv parser)
+ * but deliberately does not parse values — the LHS-only regex scanners above
+ * ensure no value content is retained or returned. The guarantee is that
+ * values never leave this function.
+ */
+export function listKeys(envPath) {
+    if (!fs.existsSync(envPath))
+        return { keys: [], comments: [] };
+    const text = fs.readFileSync(envPath, "utf8");
+    return { keys: scanKeys(text), comments: scanComments(text) };
+}
+/**
+ * Return structured `entries` pairing each key with the nearest preceding
+ * comment line (if any). This is an easier-to-consume shape than the parallel
+ * `keys[]` + `comments[]` of `listKeys` (QA #35).
+ *
+ * Values are never included — the same privacy guarantee as `listKeys`.
+ */
+export function listEntries(envPath) {
+    if (!fs.existsSync(envPath))
+        return [];
+    const text = fs.readFileSync(envPath, "utf8");
+    const lines = text.split(/\r?\n/);
+    const seen = new Set();
+    const entries = [];
+    let pendingComment;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            // Capture the most recent comment before a key
+            pendingComment = trimmed.slice(1).trimStart() || undefined;
+            continue;
+        }
+        const m = line.match(ASSIGN_RE);
+        if (m) {
+            const key = m[1];
+            if (!seen.has(key)) {
+                seen.add(key);
+                const entry = { key };
+                if (pendingComment)
+                    entry.comment = pendingComment;
+                entries.push(entry);
+            }
+            pendingComment = undefined;
+        }
+        else {
+            // Any non-comment, non-assignment line (including blank lines)
+            // breaks "nearest preceding comment line" association.
+            pendingComment = undefined;
+        }
+    }
+    return entries;
+}
+/**
+ * Read all KEY=value pairs from an env file. Intended for programmatic callers
+ * that need to inject values into a process environment. Callers MUST NOT write
+ * the returned values to stdout or any logged output.
+ *
+ * Value parsing (quoting, escapes, multi-line, etc.) is delegated to dotenv.
+ */
+export function loadEnv(envPath) {
+    if (!fs.existsSync(envPath))
+        return {};
+    const buf = fs.readFileSync(envPath);
+    return dotenv.parse(buf);
+}
+/**
+ * Load an env file and assign its values into `target` (defaults to
+ * `process.env`). Returns the list of keys that were set so the caller can
+ * log/observe without touching values.
+ *
+ * Existing keys in `target` are overwritten — callers who want to preserve
+ * pre-existing environment variables should filter before calling.
+ */
+export function injectIntoEnv(envPath, target = process.env) {
+    const env = loadEnv(envPath);
+    for (const [key, value] of Object.entries(env)) {
+        target[key] = value;
+    }
+    return Object.keys(env);
+}
+/**
+ * Serialise an env file's values as a POSIX shell script of `export KEY='value'`
+ * lines, with single-quote escaping (`'\''`). Every line is an assignment of a
+ * literal string — there is no expansion, command substitution, or
+ * non-assignment content, so `eval`-ing the output is safe regardless of what
+ * the source file contains.
+ *
+ * This is the trust boundary for shell loading: a raw `.env` may contain
+ * `X=$(rm -rf ~)`, which would execute if `source`d directly, but dotenv parses
+ * it to the literal string `$(rm -rf ~)` and we re-emit it single-quoted. This
+ * backs `akm env export <ref> --out <file>` (file-only; never printed to stdout).
+ *
+ * NOTE: `${secret:NAME}` token substitution is intentionally NOT applied here.
+ * The export path emits values single-quoted as literals, so an unsubstituted
+ * `${secret:NAME}` is written verbatim (it would expand to nothing under POSIX
+ * shells, never to the secret). Secret-token resolution is scoped to the
+ * `env run` value-injection path only; see `resolveSecretTokens`.
+ */
+export function buildShellExportScript(envPath) {
+    const env = loadEnv(envPath);
+    const lines = [];
+    for (const [key, value] of Object.entries(env)) {
+        // Defence in depth: dotenv already validates key shape, but reject any
+        // key we wouldn't be able to export safely.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const escaped = value.replace(/'/g, "'\\''");
+        lines.push(`export ${key}='${escaped}'`);
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/**
+ * Matches a `${secret:NAME}` substitution token in an env value. The captured
+ * NAME accepts the same character set as a secret asset name (letters, digits,
+ * `_`, `.`, `/`, `-`). Only this exact form is recognised — shell-style
+ * `${VAR}` and `$VAR` deliberately do not match and are left untouched.
+ */
+const SECRET_TOKEN_RE = /\$\{secret:([A-Za-z0-9_./-]+)\}/g;
+/**
+ * Replace every `${secret:NAME}` token in each value with the corresponding
+ * secret value, looked up via the injected `resolveSecret`. Keys are never
+ * touched. Multiple tokens per value and tokens embedded in larger strings
+ * (e.g. `Bearer ${secret:a}:${secret:b}`) are all substituted.
+ *
+ * `resolveSecret` returns `undefined` for an unknown secret name; such names are
+ * collected into `missing` (de-duplicated, in first-seen order) and their tokens
+ * are left unsubstituted in the returned values. Callers MUST treat a non-empty
+ * `missing` as a hard error and inject NOTHING — never partially inject.
+ *
+ * The lookup is injected so this module does not import the secret
+ * resolver/source machinery directly, preserving its narrow dependency surface.
+ * Resolved secret values must never be logged or printed by callers.
+ */
+export function resolveSecretTokens(values, resolveSecret) {
+    const missing = [];
+    const missingSeen = new Set();
+    const out = {};
+    const cache = new Map();
+    for (const [key, value] of Object.entries(values)) {
+        out[key] = value.replace(SECRET_TOKEN_RE, (match, name) => {
+            let resolved = cache.get(name);
+            if (!cache.has(name)) {
+                resolved = resolveSecret(name);
+                cache.set(name, resolved);
+            }
+            if (resolved === undefined) {
+                if (!missingSeen.has(name)) {
+                    missingSeen.add(name);
+                    missing.push(name);
+                }
+                return match;
+            }
+            return resolved;
+        });
+    }
+    return { values: out, missing };
+}
+/** Create an empty env file (does nothing if it already exists). */
+export function createEnv(envPath) {
+    ensureParentDir(envPath);
+    if (fs.existsSync(envPath))
+        return;
+    writeFileAtomic(envPath, "", 0o600);
+}
+/**
+ * Write (create or overwrite) an env file with the given text content,
+ * atomically at mode 0600. Used to ingest an existing `.env` file
+ * (`env create --from-file` / `--from-stdin`).
+ */
+export function writeEnv(envPath, content) {
+    ensureParentDir(envPath);
+    writeFileAtomic(envPath, content, 0o600);
+}
+/** Remove an env file (and its `.sensitive` marker, if present). Returns true if it existed. */
+export function removeEnv(envPath) {
+    if (!fs.existsSync(envPath))
+        return false;
+    fs.rmSync(envPath);
+    const marker = `${envPath}.sensitive`;
+    if (fs.existsSync(marker))
+        fs.rmSync(marker);
+    return true;
+}
+/** A valid env KEY name (same grammar as the assignment scanner). */
+export const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Build a `KEY=value` assignment line whose value is GUARANTEED to round-trip
+ * through `dotenv.parse` — dotenv is the serialisation oracle, so we never
+ * write a representation we cannot read back. Candidate representations are
+ * tried in order of readability (bare → double-quoted → single-quoted) and the
+ * first one `dotenv.parse` recovers exactly is used. If a value contains
+ * characters no inline representation can round-trip (e.g. both quote styles),
+ * we throw rather than silently corrupt the file.
+ */
+function serializeEnvAssignment(key, value) {
+    const candidates = [];
+    // Bare — only for simple values (no whitespace/quotes/#/$/control chars).
+    if (/^[A-Za-z0-9_@%+=:,./-]*$/.test(value))
+        candidates.push(`${key}=${value}`);
+    // Double-quoted — dotenv expands \n \r \t inside double quotes.
+    const dq = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    candidates.push(`${key}="${dq}"`);
+    // Single-quoted — dotenv takes the content literally (no escapes/expansion).
+    candidates.push(`${key}='${value}'`);
+    for (const line of candidates) {
+        try {
+            if (dotenv.parse(line)[key] === value)
+                return line;
+        }
+        catch {
+            // Not parseable as written; try the next representation.
+        }
+    }
+    throw new UsageError(`Value for "${key}" cannot be stored inline in a .env file (it contains characters dotenv cannot round-trip). ` +
+        "Edit the .env file directly, or choose a different value.");
+}
+/**
+ * Assert (using `dotenv.parse` as the oracle) that `after` set `key` to
+ * `expected` and left every other key from `before` byte-identical. This
+ * catches a line-level edit accidentally disturbing a quoted/multiline value.
+ */
+function assertEnvEditSafe(before, after, key) {
+    for (const [k, v] of Object.entries(before)) {
+        if (k !== key && after[k] !== v) {
+            throw new UsageError(`Editing "${key}" would disturb "${k}" (the .env file has a value layout dotenv could not safely round-trip). ` +
+                "Edit the .env file directly.");
+        }
+    }
+}
+/**
+ * Set (create or update) a single `KEY=value` entry in an env file, preserving
+ * the file's existing lines, comments, and key order. The first existing
+ * assignment of `key` is replaced in place; otherwise the entry is appended.
+ * Creates the file (and parent dirs) if absent. The value is never logged.
+ *
+ * The serialised value and the whole resulting file are verified with
+ * `dotenv.parse` before the write commits.
+ */
+export function setEnvKey(envPath, key, value) {
+    ensureParentDir(envPath);
+    const existing = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+    const assignment = serializeEnvAssignment(key, value);
+    const keyLineRe = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`);
+    const lines = existing.split(/\r?\n/);
+    let replaced = false;
+    const out = lines.map((line) => {
+        if (!replaced && keyLineRe.test(line)) {
+            replaced = true;
+            return assignment;
+        }
+        return line;
+    });
+    if (!replaced) {
+        while (out.length > 0 && out[out.length - 1] === "")
+            out.pop();
+        out.push(assignment);
+    }
+    let content = out.join("\n");
+    if (!content.endsWith("\n"))
+        content += "\n";
+    // Verify the edit with dotenv before committing it.
+    const after = dotenv.parse(content);
+    if (after[key] !== value) {
+        throw new UsageError(`Could not set "${key}" reliably (the .env file has a value layout dotenv could not round-trip). ` +
+            "Edit the .env file directly.");
+    }
+    assertEnvEditSafe(dotenv.parse(existing), after, key);
+    writeFileAtomic(envPath, content, 0o600);
+}
+/**
+ * Remove one or more `KEY=value` entries from an env file, preserving all other
+ * lines and comments. Returns which keys were present (removed) vs. absent.
+ *
+ * The result is verified with `dotenv.parse`: the removed keys are gone and
+ * every surviving key is byte-identical to before.
+ */
+export function unsetEnvKeys(envPath, keys) {
+    if (!fs.existsSync(envPath))
+        return { removed: [], missing: keys };
+    const text = fs.readFileSync(envPath, "utf8");
+    const before = dotenv.parse(text);
+    const present = new Set(Object.keys(before));
+    const toRemove = new Set(keys);
+    const out = text.split(/\r?\n/).filter((line) => {
+        const m = line.match(ASSIGN_RE);
+        return !(m && toRemove.has(m[1]));
+    });
+    let content = out.join("\n");
+    if (content.length > 0 && !content.endsWith("\n"))
+        content += "\n";
+    // Verify with dotenv: removed keys gone, survivors unchanged.
+    const after = dotenv.parse(content);
+    for (const k of toRemove) {
+        if (k in after) {
+            throw new UsageError(`Could not remove "${k}" reliably (the .env file has a value layout dotenv could not round-trip). ` +
+                "Edit the .env file directly.");
+        }
+    }
+    for (const [k, v] of Object.entries(before)) {
+        if (!toRemove.has(k) && after[k] !== v) {
+            throw new UsageError(`Removing those keys would disturb "${k}" (multiline/quoted value). Edit the .env file directly.`);
+        }
+    }
+    writeFileAtomic(envPath, content, 0o600);
+    return {
+        removed: keys.filter((k) => present.has(k)),
+        missing: keys.filter((k) => !present.has(k)),
+    };
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}

package/dist/commands/env/secret-cli.js

@@ -0,0 +1,259 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm secret` command family. Extracted verbatim from src/cli.ts (WS6) so the
+ * God Module shrinks; the `main.subCommands.secret` key and every subcommand's
+ * args/output shape are byte-identical. The ref-resolution helpers
+ * (parseSecretRef / makeSecretRef / resolveSecretPath, plus the shared
+ * findEnvSource) live in src/core/env-secret-ref.ts so env + secret share one
+ * copy.
+ *
+ * `akm secret` manages whole-file secrets under each stash's secrets/ directory.
+ * Unlike env files (.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).
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
+import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
+import { loadConfig } from "../../core/config/config.js";
+import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { getHyphenatedArg } from "../../output/context.js";
+import { readStdin } from "../../runtime.js";
+/** 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 (flat name, e.g. secret:deploy-key or just deploy-key; use --path for a subdirectory)",
+            required: true,
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under secrets/ to place the secret in (e.g. 'team'). The filename comes from the name.",
+        },
+        "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("./secret.js");
+            const { name, absPath, source } = resolveSecretPath(args.ref, { subPath: getStringArg(args, "path") });
+            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`);
+                }
+                const stdinBuf = await readStdin(MAX_SECRET_BYTES, () => new UsageError("Secret exceeds the 5 MB limit."));
+                // 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(stdinBuf.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 { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
+            if (isDangerousEnvKey(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("./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("./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 });
+        });
+    },
+});
+// Single source of truth: the routing set is derived from the subCommands keys
+// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
+const secretSubCommands = {
+    list: secretListCommand,
+    path: secretPathCommand,
+    run: secretRunCommand,
+    set: secretSetCommand,
+    remove: secretRemoveCommand,
+};
+const SECRET_SUBCOMMAND_SET = new Set(Object.keys(secretSubCommands));
+export const secretCommand = defineCommand({
+    meta: {
+        name: "secret",
+        description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
+    },
+    subCommands: secretSubCommands,
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
+                return;
+            output("secret-list", { secrets: listSecretsRecursive() });
+        });
+    },
+});