akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -19,24 +19,22 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
-import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
-import { deriveCanonicalAssetName, resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
-import { isWithin, writeFileAtomic } from "../../core/common.js";
+import { deriveCanonicalAssetName } from "../../core/asset/asset-placement.js";
+import { writeFileAtomic } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
-import { findEnvSource, makeEnvRef, parseEnvRef, resolveEnvPath } from "../../core/env-secret-ref.js";
+import { makeEnvRef, resolveEnvPath, resolveEnvWriteTarget, withEnvSecretWrite } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
-import { appendEvent } from "../../core/events.js";
-import { isQuiet } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { parseFlagValue } from "../../output/context.js";
 import { readStdin } from "../../runtime.js";
 import { buildChildEnv } from "./child-env.js";
+import { sensitiveMarkerPath } from "./marker-path.js";
 /**
  * Walk each stash's env files and return one entry per `.env` file, using the
  * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
- * `env:team/prod`, `env/team/.env` → `env:team/default`).
+ * `env/team/prod`, `env/team/.env` → `env/team/default`).
  */
 function listEnvsRecursive(listKeysFn) {
     const result = [];
@@ -59,7 +57,7 @@ function listEnvsRecursive(listKeysFn) {
                 if (!canonical)
                     continue;
                 // Skip sensitive envs: a sibling .sensitive marker file suppresses listing.
-                const markerPath = full.replace(/\.env$/, ".sensitive");
+                const markerPath = sensitiveMarkerPath(full, "env");
                 if (fs.existsSync(markerPath))
                     continue;
                 const { keys } = listKeysFn(full);
@@ -71,7 +69,7 @@ function listEnvsRecursive(listKeysFn) {
     return result;
 }
 const envListCommand = defineJsonCommand({
-    meta: { name: "list", description: "List all env files across all stashes with their key names (no values)" },
+    meta: { name: "list", description: "List all env files across all bundles with their key names (no values)" },
     async run() {
         const { listKeys } = await import("./env.js");
         output("env-list", { envs: listEnvsRecursive(listKeys) });
@@ -99,31 +97,29 @@ const envCreateCommand = defineJsonCommand({
             description: "Exclude this env file from env list output and the search index",
             default: false,
         },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
+        },
     },
     async run({ args }) {
         const { createEnv, writeEnv } = await import("./env.js");
-        // `create` always targets env/, never the frozen vaults/ copy.
-        const parsed = parseEnvRef(args.name);
-        // `name` is flat; subdirectory placement is `--path`'s job.
-        assertFlatAssetName(parsed.name);
-        parsed.name = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), parsed.name);
-        const source = findEnvSource(parsed.origin);
-        const envRoot = path.join(source.path, "env");
-        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-        if (!isWithin(absPath, envRoot)) {
-            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-        }
+        // `create` always targets env/, never the frozen vaults/ copy. `--path` is
+        // the subdirectory; `--target` selects the writable destination source.
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.name, args.target, {
+            subPath: getStringArg(args, "path"),
+        });
         const fromFile = args["from-file"];
         const fromStdin = args["from-stdin"] === true;
         if (fromFile !== undefined && fromStdin) {
             throw new UsageError("Pass only one of --from-file or --from-stdin.", "INVALID_FLAG_VALUE");
         }
+        let content;
         if (fromFile !== undefined || fromStdin) {
             // Ingest path: never silently clobber an existing env file.
             if (fs.existsSync(absPath)) {
-                throw new UsageError(`Env "${makeEnvRef(parsed.name, source)}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
+                throw new UsageError(`Env "${ref}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
             }
-            let content;
             if (fromFile !== undefined) {
                 if (!fs.existsSync(fromFile)) {
                     throw new NotFoundError(`Source file not found: ${fromFile}`, "FILE_NOT_FOUND");
@@ -135,18 +131,24 @@ const envCreateCommand = defineJsonCommand({
                 const buf = await readStdin(MAX_ENV_BYTES, () => new UsageError("Env file exceeds 1 MB limit.", "INVALID_FLAG_VALUE"));
                 content = buf.toString("utf8");
             }
-            writeEnv(absPath, content);
-        }
-        else {
-            createEnv(absPath);
         }
+        const written = [absPath];
+        const markerPath = sensitiveMarkerPath(absPath, "env");
         if (args.sensitive) {
-            const markerPath = absPath.replace(/\.env$/, ".sensitive");
-            if (!fs.existsSync(markerPath)) {
-                fs.writeFileSync(markerPath, "", { mode: 0o600 });
-            }
+            written.push(markerPath);
         }
-        output("env-create", { ref: makeEnvRef(parsed.name, source) });
+        withEnvSecretWrite(target, { type: "env", name }, "Update", written, () => {
+            if (content !== undefined)
+                writeEnv(absPath, content);
+            else
+                createEnv(absPath);
+            if (args.sensitive) {
+                if (!fs.existsSync(markerPath)) {
+                    writeFileAtomic(markerPath, "", 0o600);
+                }
+            }
+        });
+        output("env-create", { ref });
     },
 });
 const envPathCommand = defineJsonCommand({
@@ -170,6 +172,22 @@ const envPathCommand = defineJsonCommand({
             process.stderr.write(`warning: this is the raw file path. Do NOT \`source\` it (shell substitutions in the file would execute).\n` +
                 `         To inject values run: akm env run ${args.ref} -- <command>\n`);
         }
+        // F3/B3: this stdout write IS the payload — a bare absolute path for
+        // shell substitution (`$(akm env path <ref>)`, Docker `_FILE` /
+        // `--env-file`) — not a field inside a result envelope. `env path` is
+        // now declared format-exempt (src/output/format-exempt.ts, same
+        // classification as `env run`/`secret run`/`help`), so `--format`
+        // WARNS rather than doing anything to this write (src/cli.ts's startup
+        // `isFormatExemptCommand` check). An earlier version of this fix routed
+        // this through `output()` with a `{ path }` envelope so `--format`
+        // "worked" — but the CLI's process-wide default format is `json`, so a
+        // bare `akm env path <ref>` (exactly how `$(akm env path foo)` is
+        // written, with no explicit `--format`) started emitting
+        // `{"path":"..."}` instead of the raw path, breaking every existing
+        // shell substitution silently. Declaring the exemption is the correct
+        // fix: it keeps this byte-identical to history and makes the
+        // already-broken combination (`--format` + this command) loud instead
+        // of silent, per STABILITY.md's promise for exempt commands.
         process.stdout.write(`${absPath}\n`);
     },
 });
@@ -205,11 +223,10 @@ const envExportCommand = defineJsonCommand({
  * for process-hijacking variables.
  */
 async function runEnvInjected(target, opts) {
-    const dashIndex = process.argv.indexOf("--");
-    if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
+    const command = getParsedInvocation().passthroughArgs();
+    if (command.length === 0) {
         throw new UsageError("Missing command. Usage: akm env run <ref> -- <command>");
     }
-    const command = process.argv.slice(dashIndex + 1);
     const { name, absPath, source } = resolveEnvPath(target);
     if (!fs.existsSync(absPath)) {
         // Help users who reach for the removed single-key `ref/KEY` form.
@@ -226,70 +243,20 @@ async function runEnvInjected(target, opts) {
                 }
                 if (baseExists) {
                     throw new UsageError(`'akm env run' injects the whole file; the single-key '<ref>/${maybeKey}' form was removed.\n` +
-                        `       For one value use a secret: \`akm secret run secret:${maybeKey} ${maybeKey} -- <command>\`.`, "INVALID_FLAG_VALUE");
+                        `       For one value use a secret: \`akm secret run secrets/${maybeKey} ${maybeKey} -- <command>\`.`, "INVALID_FLAG_VALUE");
                 }
             }
         }
         throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
     }
-    const { loadEnv } = await import("./env.js");
-    const allValues = loadEnv(absPath);
-    // Value-safe key filtering (--only / --except operate on key NAMES only).
-    let envValues = allValues;
-    if (opts.only && opts.except) {
-        throw new UsageError("Pass only one of --only or --except.", "INVALID_FLAG_VALUE");
-    }
-    if (opts.only) {
-        const wanted = new Set(opts.only);
-        const missing = opts.only.filter((k) => !(k in allValues));
-        if (missing.length > 0) {
-            process.stderr.write(`warning: --only key(s) not present in ${makeEnvRef(name, source)}: ${missing.join(", ")}\n`);
-        }
-        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => wanted.has(k)));
-    }
-    else if (opts.except) {
-        const excluded = new Set(opts.except);
-        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => !excluded.has(k)));
-    }
-    // Substitute `${secret:NAME}` tokens in values with the value of the sibling
-    // secret asset in the SAME stash. The lookup is injected so commands/env.ts
-    // keeps its narrow dependency surface; we resolve each name against this env's
-    // own `source`. A missing secret is a hard error — inject NOTHING (no partial
-    // injection). Resolved values are never logged or printed.
-    const { resolveSecretTokens } = await import("./env.js");
-    const { readValue } = await import("./secret.js");
-    const secretsRoot = path.join(source.path, "secrets");
-    const resolveSecret = (secretName) => {
-        const secretPath = resolveAssetPathFromName("secret", secretsRoot, secretName);
-        // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
-        if (!isWithin(secretPath, secretsRoot)) {
-            throw new UsageError(`Secret name "${secretName}" escapes the secrets directory.`);
-        }
-        if (!fs.existsSync(secretPath))
-            return undefined;
-        // Match `secret run`: read utf8, do not trim (stay consistent with that path).
-        return readValue(secretPath).toString("utf8");
-    };
-    const { values: substituted, missing } = resolveSecretTokens(envValues, resolveSecret);
-    if (missing.length > 0) {
-        const envRef = makeEnvRef(name, source);
-        throw new NotFoundError(`Env "${envRef}" references secret(s) not found in its stash: ${missing.map((n) => `secret:${n}`).join(", ")}. Nothing was injected.`, "FILE_NOT_FOUND", `Create the missing secret, e.g. \`akm secret set secret:${missing[0]}\`.`);
-    }
-    envValues = substituted;
-    const keys = Object.keys(envValues);
-    // Scan injected keys for known process-hijacking variables (LD_PRELOAD,
-    // PATH, ...). Block for third-party-sourced stashes (origin has a registryId);
-    // warn for the operator's own first-party stash, where they own the file.
-    const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-    const dangerous = keys.filter(isDangerousEnvKey);
-    if (dangerous.length > 0) {
-        const detail = `Env "${makeEnvRef(name, source)}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
-        if (source.registryId) {
-            throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
-                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
-        }
-        process.stderr.write(`warning: ${detail} Injecting anyway (first-party stash).\n`);
-    }
+    // Load → filter → secret-substitute → dangerous-key policy → keys-only
+    // audit event. Shared with the workflow engine's per-unit env bindings —
+    // see env-binding.ts for the extracted core and its safety invariants.
+    const { resolveEnvBinding } = await import("./env-binding.js");
+    const { values: envValues } = resolveEnvBinding(target, {
+        only: opts.only,
+        except: opts.except,
+    });
     const mergedEnv = buildChildEnv(process.env, {
         clean: opts.clean === true,
         inherit: opts.inherit ?? [],
@@ -297,12 +264,6 @@ async function runEnvInjected(target, opts) {
     for (const [envKey, envValue] of Object.entries(envValues)) {
         mergedEnv[envKey] = envValue;
     }
-    // Audit trail: keys only, never values.
-    appendEvent({
-        eventType: "env_access",
-        ref: makeEnvRef(name, source),
-        metadata: { keys },
-    });
     const result = spawnSync(command[0], command.slice(1), {
         stdio: "inherit",
         env: mergedEnv,
@@ -320,7 +281,15 @@ async function runEnvInjected(target, opts) {
         }
         throw err;
     }
-    process.exit(result.status ?? 0);
+    // R-067: was `process.exit(result.status ?? 0)`, which terminates the
+    // process synchronously and skips the `finally { await
+    // disposeDispatchResources(); }` block in src/cli.ts's `runCommand` — even
+    // on the success path, since this call was unconditional. Setting
+    // `process.exitCode` and returning lets cleanup run while still exiting
+    // with the child's exact status once the event loop drains, matching the
+    // pattern `emitJsonError` (src/cli/shared.ts) already established.
+    process.exitCode = result.status ?? 0;
+    return;
 }
 /** Parse a comma/space-separated key list flag into a trimmed, non-empty array. */
 function parseKeyListFlag(raw) {
@@ -337,7 +306,7 @@ const envRunCommand = defineJsonCommand({
         name: "run",
         description: 
         // biome-ignore lint/suspicious/noTemplateCurlyInString: literal `${secret:NAME}` token syntax documented for users, not interpolation
-        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `secret:NAME` value from the same stash. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
+        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `${secret:NAME}` value from the same bundle. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
     },
     args: {
         target: { type: "positional", description: "Env ref", required: true },
@@ -370,15 +339,13 @@ const envRemoveCommand = defineJsonCommand({
     args: {
         ref: { type: "positional", description: "Env ref", required: true },
         yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
+        },
     },
     async run({ args }) {
-        const parsed = parseEnvRef(args.ref);
-        const source = findEnvSource(parsed.origin);
-        const envRoot = path.join(source.path, "env");
-        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-        if (!isWithin(absPath, envRoot)) {
-            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-        }
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.ref, args.target);
         const { confirmDestructive } = await import("../../cli/confirm.js");
         const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
             yes: args.yes === true,
@@ -388,122 +355,18 @@ const envRemoveCommand = defineJsonCommand({
             return;
         }
         if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
+            throw new NotFoundError(`Env not found: ${ref}`);
         }
         const { removeEnv } = await import("./env.js");
-        const removed = removeEnv(absPath);
-        output("env-remove", { ref: makeEnvRef(parsed.name, source), removed });
-    },
-});
-const envSetCommand = defineJsonCommand({
-    meta: {
-        name: "set",
-        description: "Set (create or update) a single KEY in an env file: `akm env set <ref> <KEY>`. The value is read from stdin by default (never via argv); use --from-env <VAR> or --from-file <path>. Preserves existing comments and key order; the value is never printed. Creates the env file if it does not exist.",
-    },
-    args: {
-        ref: { type: "positional", description: "Env ref (e.g. env:prod or just prod)", required: true },
-        key: { type: "positional", description: "Key name to set (e.g. API_URL)", required: true },
-        "from-env": { type: "string", description: "Read the value from the named environment variable" },
-        "from-file": { type: "string", description: "Read the value from this file" },
-    },
-    async run({ args }) {
-        const parsed = parseEnvRef(args.ref);
-        const source = findEnvSource(parsed.origin);
-        const envRoot = path.join(source.path, "env");
-        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-        if (!isWithin(absPath, envRoot)) {
-            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-        }
-        const key = String(args.key);
-        const { ENV_KEY_RE, setEnvKey } = await import("./env.js");
-        if (!ENV_KEY_RE.test(key)) {
-            throw new UsageError(`Invalid env key "${key}". Keys match [A-Za-z_][A-Za-z0-9_]*.`, "INVALID_FLAG_VALUE");
-        }
-        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_ENV_VALUE_BYTES = 1024 * 1024; // 1 MB
-        let value;
-        if (fromFile !== undefined) {
-            if (!fs.existsSync(fromFile)) {
-                throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
-            }
-            const buf = fs.readFileSync(fromFile);
-            if (buf.byteLength > MAX_ENV_VALUE_BYTES)
-                throw new UsageError("Value exceeds the 1 MB limit.");
-            value = buf.toString("utf8");
-        }
-        else if (fromEnv !== undefined) {
-            const v = process.env[fromEnv];
-            if (v === undefined) {
-                throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
-            }
-            value = v;
-        }
-        else {
-            const buf = await readStdin(MAX_ENV_VALUE_BYTES, () => new UsageError("Value exceeds the 1 MB limit."));
-            // Strip a single trailing newline so `echo "$VAL" | akm env set` is exact.
-            value = buf.toString("utf8").replace(/\n$/, "");
-        }
-        setEnvKey(absPath, key, value);
-        // Warn (never block) on process-hijacking key names, matching the env-run audit.
-        const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-        if (isDangerousEnvKey(key) && !isQuiet()) {
-            process.stderr.write(`warning: "${key}" can influence process execution when this env is loaded via 'akm env run'.\n`);
-        }
-        output("env-set", { ref: makeEnvRef(parsed.name, source), key });
-    },
-});
-const envUnsetCommand = defineJsonCommand({
-    meta: {
-        name: "unset",
-        description: "Remove one or more KEYs from an env file: `akm env unset <ref> <KEY...>`. Preserves other keys and comments. To remove the whole file, use `akm env remove`.",
-    },
-    args: {
-        ref: { type: "positional", description: "Env ref (e.g. env:prod or just prod)", required: true },
-        // `key` is read from the raw positionals (one or more) in run(); declared
-        // non-required so citty doesn't block before we emit a structured error.
-        key: { type: "positional", description: "Key name(s) to remove (one or more)", required: false },
-    },
-    async run({ args }) {
-        const parsed = parseEnvRef(args.ref);
-        const source = findEnvSource(parsed.origin);
-        const envRoot = path.join(source.path, "env");
-        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-        if (!isWithin(absPath, envRoot)) {
-            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-        }
-        if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
-        }
-        // citty puts every positional in `args._` (incl. the ref at [0]); the keys
-        // are the remaining positionals. citty also mis-captures the space-separated
-        // value of a global flag (`--format json`) as a positional, so drop any
-        // token that is actually a global flag's value (cli.ts:1335 documents this).
-        const globalFlagValues = new Set(["--format", "--shape", "--detail", "--scope", "--filter", "--target"]
-            .map((flag) => parseFlagValue(process.argv, flag))
-            .filter((v) => typeof v === "string"));
-        const keys = (Array.isArray(args._) ? args._.map(String) : [])
-            .slice(1)
-            .filter((k) => !globalFlagValues.has(k));
-        if (keys.length === 0) {
-            throw new UsageError("Usage: akm env unset <ref> <KEY...> (one or more keys).", "MISSING_REQUIRED_ARGUMENT");
-        }
-        const { ENV_KEY_RE, unsetEnvKeys } = await import("./env.js");
-        const invalid = keys.filter((k) => !ENV_KEY_RE.test(k));
-        if (invalid.length > 0) {
-            throw new UsageError(`Invalid env key(s): ${invalid.join(", ")}.`, "INVALID_FLAG_VALUE");
-        }
-        const { removed, missing } = unsetEnvKeys(absPath, keys);
-        output("env-unset", { ref: makeEnvRef(parsed.name, source), removed, missing });
+        const removed = withEnvSecretWrite(target, { type: "env", name }, "Remove", [absPath, sensitiveMarkerPath(absPath, "env")], () => removeEnv(absPath));
+        output("env-remove", { ref, removed });
     },
 });
 export const envCommand = defineGroupCommand({
     meta: {
         name: "env",
-        description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
+        description: "Manage `.env` files — configuration values an app loads together (URLs, flags, and any credentials it needs).\n\n" +
+            "Values may or may not be sensitive; akm protects them all the same way — key names are visible, values never appear in structured output. For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
     subCommands: {
         list: envListCommand,
@@ -511,12 +374,9 @@ export const envCommand = defineGroupCommand({
         export: envExportCommand,
         run: envRunCommand,
         create: envCreateCommand,
-        set: envSetCommand,
-        unset: envUnsetCommand,
         remove: envRemoveCommand,
     },
-    async defaultRun() {
-        const { listKeys } = await import("./env.js");
-        output("env-list", { envs: listEnvsRecursive(listKeys) });
-    },
+    // No `defaultRun`: bare `akm env` is a usage error (exit 2), the canonical
+    // bare-group behavior — owner ruling 12. Run `akm env list` for what the
+    // bare form used to print.
 });