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

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

@@ -19,23 +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 { 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 = [];
@@ -58,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);
@@ -70,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) });
@@ -98,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");
@@ -134,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({
@@ -169,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`);
     },
 });
@@ -204,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.
@@ -225,7 +243,7 @@ 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");
                 }
             }
         }
@@ -263,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) {
@@ -280,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 },
@@ -313,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,
@@ -331,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,
@@ -454,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.
 });

package/dist/commands/env/env.js

@@ -10,13 +10,10 @@
  * 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`).
+ * akm does not manage individual keys — 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 lives on the READ path
+ * (see `buildShellExportScript` + `akm env export`).
  *
  * Invariant: nothing from an env file except key NAMES may be written to
  * stdout, returned through the indexer, the `akm show` renderer, or any
@@ -27,20 +24,18 @@
  * 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`.
+ *     process env (never via a shell), see `loadEnv` (loaded by
+ *     `env-binding.ts#resolveEnvBinding`, then merged into the child env by
+ *     `env-cli.ts`). 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.
+ * Value parsing is delegated to the `dotenv` package.
  *
  * 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`
@@ -54,7 +49,7 @@ 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";
+import { sensitiveMarkerPath } from "./marker-path.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. */
@@ -101,21 +96,6 @@ export function loadEnv(envPath) {
     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
@@ -214,142 +194,11 @@ export function removeEnv(envPath) {
     if (!fs.existsSync(envPath))
         return false;
     fs.rmSync(envPath);
-    const marker = `${envPath}.sensitive`;
+    const marker = sensitiveMarkerPath(envPath, "env");
     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))

package/dist/commands/env/marker-path.js

@@ -0,0 +1,6 @@
+// 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/.
+export function sensitiveMarkerPath(assetPath, type) {
+    return type === "env" ? assetPath.replace(/\.env$/, ".sensitive") : `${assetPath}.sensitive`;
+}