akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/env/env.js

@@ -18,10 +18,13 @@
  * 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:
+ * Invariant: nothing from an env file except key NAMES may be written to
+ * stdout, returned through the indexer, the `akm show` renderer, or any
+ * structured output channel. Key NAMES are surfaced for discoverability;
+ * comment text is NOT — real .env files routinely carry commented-out
+ * `KEY=value` lines and free-text notes containing live credentials, so
+ * comments are treated exactly like values. 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
@@ -71,75 +74,19 @@ function scanKeys(text) {
     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).
+ * Read and return ONLY non-secret metadata: key names.
  *
  * 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.
+ * but deliberately does not parse values — the LHS-only regex scanner above
+ * ensures no value content is retained or returned. Comment text is never
+ * returned either: comments routinely contain commented-out `KEY=value`
+ * credentials and free-text secrets, so they 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 [];
+        return { keys: [] };
     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;
+    return { keys: scanKeys(text) };
 }
 /**
  * Read all KEY=value pairs from an env file. Intended for programmatic callers

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

@@ -18,17 +18,25 @@
 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 { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } 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";
+import { buildChildEnv } from "./child-env.js";
+function parseKeyListFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const keys = raw
+        .split(/[,\s]+/)
+        .map((k) => k.trim())
+        .filter(Boolean);
+    return keys.length > 0 ? keys : undefined;
+}
 /** Walk `secrets/` across all stashes, returning one entry per secret file. */
 function listSecretsRecursive() {
     const result = [];
@@ -60,18 +68,16 @@ function listSecretsRecursive() {
     }
     return result;
 }
-const secretListCommand = defineCommand({
+const secretListCommand = defineJsonCommand({
     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() });
-        });
+    async run() {
+        output("secret-list", { secrets: listSecretsRecursive() });
     },
 });
-const secretSetCommand = defineCommand({
+const secretSetCommand = defineJsonCommand({
     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.",
@@ -89,49 +95,47 @@ const secretSetCommand = defineCommand({
         "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");
+    async run({ args }) {
+        const { setSecret } = await import("./secret.js");
+        const { name, absPath, source } = resolveSecretPath(args.ref, { subPath: getStringArg(args, "path") });
+        const fromEnv = args["from-env"];
+        const fromFile = 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");
             }
-            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.");
-                }
+            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 (fromEnv !== undefined) {
+            const envVal = process.env[fromEnv];
+            if (envVal === undefined) {
+                throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
             }
-            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");
+            value = Buffer.from(envVal, "utf8");
+        }
+        else {
+            if (process.stdin.isTTY) {
+                process.stderr.write(`Enter value for secret "${name}" (Ctrl-D when done):\n`);
             }
-            setSecret(absPath, value);
-            output("secret-set", { ref: makeSecretRef(name, source) });
-        });
+            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({
+const secretPathCommand = defineJsonCommand({
     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)`.",
@@ -139,121 +143,119 @@ const secretPathCommand = defineCommand({
     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`);
-        });
+    async run({ args }) {
+        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({
+const secretRunCommand = defineJsonCommand({
     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.",
+        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. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
     },
     args: {
         ref: { type: "positional", description: "Secret ref", required: true },
         var: { type: "positional", description: "Environment variable name to inject the value into", required: true },
+        clean: {
+            type: "boolean",
+            description: "Start the child with a minimal inherited environment (PATH/HOME/locale/terminal basics) instead of the full parent environment.",
+            default: false,
+        },
+        inherit: {
+            type: "string",
+            description: "When used with --clean, also inherit these parent env vars (comma-separated). Ignored without --clean.",
+        },
     },
-    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)}`);
+    async run({ args }) {
+        // 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 = buildChildEnv(process.env, {
+            clean: args.clean === true,
+            inherit: parseKeyListFlag(args.inherit) ?? [],
+        });
+        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'.`);
             }
-            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;
+            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.`);
             }
-            process.exit(result.status ?? 0);
-        });
+            throw err;
+        }
+        process.exit(result.status ?? 0);
     },
 });
-const secretRemoveCommand = defineCommand({
+const secretRemoveCommand = defineJsonCommand({
     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 });
+    async run({ args }) {
+        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({
+export const secretCommand = defineGroupCommand({
     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() });
-        });
+    subCommands: {
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
+    },
+    defaultRun() {
+        output("secret-list", { secrets: listSecretsRecursive() });
     },
 });