envpkt 0.11.9 → 0.13.0

package/README.md

@@ -210,6 +210,32 @@ const result = boot() // decrypts sealed values, injects into process.env
 
 Mixed mode is supported — sealed values take priority, with fnox as fallback for keys without `encrypted_value`.
 
+## GitHub Actions
+
+A composite action resolves the credentials in `envpkt.toml` into the CI job — with secret values masked in the log — so later steps just see them as environment variables:
+
+```yaml
+- uses: actions/checkout@v5
+
+# Sealed packets are decrypted with the `age` CLI (not preinstalled on runners).
+- run: sudo apt-get update && sudo apt-get install -y age
+
+- uses: jordanburke/envpkt@v0.12.0
+  with:
+    config: ./envpkt.toml
+    strict: "true" # fail the build if a credential is expired/unhealthy
+  env:
+    ENVPKT_AGE_KEY: ${{ secrets.ENVPKT_AGE_KEY }}
+
+- run: ./deploy.sh # sees the resolved vars; secret values redacted in the log
+```
+
+**How it works.** Commit sealed (`encrypted_value`) packets to the repo and supply the age private key as the `ENVPKT_AGE_KEY` secret. `boot()` materializes the inline key to a `0600` temp file to decrypt, then [`env github`](#envpkt-env-github) masks each secret (`::add-mask::`) and writes it to `$GITHUB_ENV`. Identity precedence: `identity.key_file` → `ENVPKT_AGE_KEY_FILE` → `ENVPKT_AGE_KEY` (inline) → `~/.envpkt/age-key.txt`.
+
+**Inputs:** `config`, `version` (npm version to run, default `latest`), `strict`, `profile`.
+
+> Decrypting sealed packets requires the [`age`](https://github.com/FiloSottile/age) CLI on the runner (install it first, as above) — not needed if you only inject plaintext `[env.*]` defaults or resolve via fnox. Pin to a released tag (e.g. `@v0.12.0`); no moving major tag (`@v1`) is published yet. Node is assumed present; add `actions/setup-node` first to pin a version.
+
 ## Fleet Management
 
 When you're running multiple agents, `envpkt fleet` scans a directory tree for `envpkt.toml` files and aggregates credential health across your entire fleet.
@@ -431,12 +457,35 @@ eval "$(envpkt env export --profile staging)"
 eval "$(envpkt env export -c path/to/envpkt.toml)"
 ```
 
-Add to your shell startup (e.g. `~/.zshrc` or `~/.bashrc`) for automatic secret loading. envpkt's [config discovery chain](#config-resolution) finds your config automatically — no platform-specific shell logic needed:
+Add to your shell startup (e.g. `~/.zshrc`) to load a global package once at login:
 
 ```bash
 eval "$(envpkt env export 2>/dev/null)"
 ```
 
+Secret values are emitted **only when the package sets top-level `scope = "shell"`** — the default `scope = "exec"` withholds them (use `envpkt exec`). For **per-project** credentials that load on `cd`, use [`envpkt shell-hook`](#envpkt-shell-hook) rather than a one-time startup eval.
+
+### `envpkt shell-hook`
+
+Generate a `cd` hook (zsh/bash) that loads a project's credentials when you enter its directory tree and restores your environment when you leave:
+
+```bash
+eval "$(envpkt shell-hook zsh)"   # add to ~/.zshrc (or: shell-hook bash)
+```
+
+On each directory change it resolves the **nearest `envpkt.toml`, walking up from the current directory** (like `git`/`direnv` — so it works from any subdirectory, not just the project root), injects that package via `env export --track`, and restores the previous package on leave (prior values, not a blind unset). Env defaults always load; secret values load only for `scope = "shell"` packages. Backed by `envpkt config-path` — a resolve-only command that prints the active config path (no decryption).
+
+> **Upward-walk discovery**: config resolution now walks up the directory tree to the nearest `envpkt.toml` before falling back to the global package. This also applies to `exec`, `env export`, and `audit` — running any of them from a subdirectory finds the enclosing project.
+
+### `envpkt env github`
+
+Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each secret value (redacting it from the log) and appends assignments to `$GITHUB_ENV` — under their namespaced wire names — so later steps in the job inherit them. Env defaults are written but not masked. `--strict` exits non-zero if the pre-flight audit is unhealthy. This is the engine behind the [GitHub Action](#github-actions).
+
+```bash
+# Run as a step; later steps in the job see the resolved vars
+npx envpkt env github --strict
+```
+
 ### `envpkt shell-hook`
 
 Output a shell function that runs `envpkt audit --format minimal` whenever you `cd` into a directory. envpkt's config discovery chain automatically finds config files beyond CWD (see [Config Resolution](#config-resolution)), so the hook works even in directories without a local `envpkt.toml`.

package/dist/cli.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { $, Cond, Do, Either, Left, List, Map as Map$1, Option, Right, Set as Set$1, Try } from "functype";
+import { $, Cond, Do, Either, Left, List, Map as Map$1, None, Option, Right, Set as Set$1, Some, Try } from "functype";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
 import { FormatRegistry, Type } from "@sinclair/typebox";
+import { randomBytes } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
 import { directSilentLogger } from "functype-log/direct";
 import { execFileSync } from "node:child_process";
-import { homedir } from "node:os";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -302,6 +303,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	scope: Type.Optional(Type.Union([Type.Literal("shell"), Type.Literal("exec")], { description: "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything." })),
 	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
@@ -368,11 +370,24 @@ const buildSearchPaths = () => {
 	const cloudPaths = Platform.cloudStorageDirs().toArray().map((cloud) => join(cloud.path, ".envpkt", CONFIG_FILENAME$2));
 	return [...homePaths, ...cloudPaths];
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/**
+* Walk up from `dir` to the filesystem root, returning the nearest `envpkt.toml`.
+* Makes a project's config apply throughout its subtree (like git/.env/direnv finding
+* their root file), not only in the directory that literally contains the file.
+* The global package lives in `~/.envpkt/` (a subdir), so it is not matched by this
+* walk — it is resolved by the search-path/Platform fallback below.
+*/
+const walkUpForConfig = (dir) => {
+	const candidate = join(dir, CONFIG_FILENAME$2);
+	if (Fs.existsSync(candidate)) return Option(candidate);
+	const parent = dirname(dir);
+	return parent === dir ? Option(void 0) : walkUpForConfig(parent);
+};
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 const discoverConfig = (cwd) => {
-	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$2);
-	if (Fs.existsSync(cwdCandidate)) return Option({
-		path: cwdCandidate,
+	const walked = walkUpForConfig(cwd ?? process.cwd()).orUndefined();
+	if (walked) return Option({
+		path: walked,
 		source: "cwd"
 	});
 	const customMatch = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean)).map((template) => ({
@@ -834,6 +849,19 @@ const runAuditOnConfig = (config, options) => {
 	process.exit(code);
 };
 //#endregion
+//#region src/cli/commands/config-path.ts
+/**
+* Print the `envpkt.toml` path resolved for the current directory, or nothing if none
+* is found. Resolve-only: no config load, no boot, no decryption — cheap enough for a
+* per-`cd` shell hook to gate on. Always exits 0; a missing config means "no package
+* here", not an error.
+*/
+const runConfigPath = (options) => {
+	resolveConfigPath(options.config).fold(() => {}, ({ path }) => {
+		console.log(path);
+	});
+};
+//#endregion
 //#region src/fnox/cli.ts
 /** Export all secrets from fnox as key=value pairs for a given profile */
 const fnoxExport = (profile, agentKey) => {
@@ -1062,6 +1090,11 @@ const formatAliasError = (error) => {
 //#region src/core/keygen.ts
 /** Resolve the age identity file path: ENVPKT_AGE_KEY_FILE env var > ~/.envpkt/age-key.txt */
 const resolveKeyPath = () => process.env["ENVPKT_AGE_KEY_FILE"] ?? join(homedir(), ".envpkt", "age-key.txt");
+/** Resolve an inline age key from ENVPKT_AGE_KEY env var (for CI) */
+const resolveInlineKey = () => {
+	const key = process.env["ENVPKT_AGE_KEY"];
+	return key ? Some(key) : None();
+};
 /** Generate an age keypair and write to disk. Refuses to overwrite if the file already exists. */
 const generateKeypair = (options) => {
 	if (!ageAvailable()) return Left({
@@ -1297,6 +1330,65 @@ const resolveIdentityFilePath = (config, configDir, useDefaultFallback) => {
 	const defaultPath = resolveKeyPath();
 	return existsSync(defaultPath) ? Option(defaultPath) : Option(void 0);
 };
+const noop = () => {};
+/** Write an inline age key to a private temp file so the `age` CLI (file-based) can use it. */
+const materializeInlineKey = (key) => {
+	const dir = mkdtempSync(join(tmpdir(), "envpkt-age-"));
+	const keyPath = join(dir, "age-key.txt");
+	writeFileSync(keyPath, key.endsWith("\n") ? key : `${key}\n`);
+	chmodSync(keyPath, 384);
+	return {
+		path: keyPath,
+		dispose: () => rmSync(dir, {
+			recursive: true,
+			force: true
+		})
+	};
+};
+/**
+* Resolve an age identity for unsealing sealed packets. Precedence:
+*   config.identity.key_file > ENVPKT_AGE_KEY_FILE > ENVPKT_AGE_KEY (inline) > ~/.envpkt/age-key.txt
+* The inline key (CI secret) ranks above the homedir default so an explicit
+* env var beats a stray local key. Inline keys are written to a 0600 temp file
+* the caller must dispose().
+*/
+const resolveSealIdentity = (config, configDir) => {
+	if (config.identity?.key_file) {
+		const keyFilePath = resolve(configDir, expandPath(config.identity.key_file));
+		if (existsSync(keyFilePath)) return Option({
+			path: keyFilePath,
+			dispose: noop
+		});
+	}
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	if (envFile && existsSync(envFile)) return Option({
+		path: envFile,
+		dispose: noop
+	});
+	const inlineKey = resolveInlineKey().orUndefined();
+	if (inlineKey) return Option(materializeInlineKey(inlineKey));
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	if (existsSync(defaultPath)) return Option({
+		path: defaultPath,
+		dispose: noop
+	});
+	return Option(void 0);
+};
+/** Describe the seal-identity precedence chain with per-entry status, for a clear no-key error. */
+const describeSealKeySearch = (config, configDir) => {
+	const keyFile = config.identity?.key_file;
+	const keyFileLine = keyFile ? `identity.key_file → ${resolve(configDir, expandPath(keyFile))} (${existsSync(resolve(configDir, expandPath(keyFile))) ? "found" : "missing"})` : `identity.key_file (not set)`;
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	const envFileLine = envFile ? `ENVPKT_AGE_KEY_FILE → ${envFile} (${existsSync(envFile) ? "found" : "missing"})` : `ENVPKT_AGE_KEY_FILE (unset)`;
+	const inlineLine = resolveInlineKey().isEmpty ? `ENVPKT_AGE_KEY (unset)` : `ENVPKT_AGE_KEY (set, inline)`;
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	return [
+		keyFileLine,
+		envFileLine,
+		inlineLine,
+		`${defaultPath} (${existsSync(defaultPath) ? "found" : "missing"})`
+	];
+};
 const resolveIdentityKey = (config, configDir) => {
 	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (key) => Right(Option(key))));
 };
@@ -1366,6 +1458,12 @@ const bootSafe = (options) => {
 			message: "unexpected"
 		}));
 		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
+		if (hasSealedValues && sealIdentity.isEmpty) return Left({
+			_tag: "SealKeyUnavailable",
+			sealedKeys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value),
+			searched: describeSealKeySearch(config, configDir)
+		});
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
 			const injected = [];
@@ -1379,23 +1477,25 @@ const bootSafe = (options) => {
 				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
-			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
-			if (hasSealedValues) identityFilePath.fold(() => {
+			if (hasSealedValues) sealIdentity.fold(() => {
 				log.warn("phase.sealed.no_identity_file", { sealed_keys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value).length });
-				warnings.push("Sealed values found but no identity file available for decryption");
-			}, (idPath) => {
-				unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
-					log.warn("phase.sealed.decrypt_failed", { message: err.message });
-					warnings.push(`Sealed value decryption failed: ${err.message}`);
-				}, (unsealed) => {
-					const unsealedEntries = Object.entries(unsealed);
-					Object.assign(secrets, unsealed);
-					injected.push(...unsealedEntries.map(([key]) => key));
-					unsealedEntries.forEach(([key]) => {
-						sealedKeys.add(key);
-						log.debug("phase.sealed.resolved", { key });
+			}, ({ path: idPath, dispose }) => {
+				try {
+					unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
+						log.warn("phase.sealed.decrypt_failed", { message: err.message });
+						warnings.push(`Sealed value decryption failed: ${err.message}`);
+					}, (unsealed) => {
+						const unsealedEntries = Object.entries(unsealed);
+						Object.assign(secrets, unsealed);
+						injected.push(...unsealedEntries.map(([key]) => key));
+						unsealedEntries.forEach(([key]) => {
+							sealedKeys.add(key);
+							log.debug("phase.sealed.resolved", { key });
+						});
 					});
-				});
+				} finally {
+					dispose();
+				}
 			});
 			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
 			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
@@ -1483,6 +1583,30 @@ const bootSafe = (options) => {
 	}));
 };
 //#endregion
+//#region src/core/dotenv.ts
+const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+* Quote a single value for dotenv output. Returns the value bare when safe,
+* otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+* whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+*/
+const quoteDotenvValue = (value) => {
+	if (value === "") return "";
+	if (BARE_SAFE.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+};
+const formatEntry = (entry, includeSecrets) => {
+	if (entry.secret && !includeSecrets) return `# (secret value omitted — re-run without --no-secrets to include)\n${entry.name}=`;
+	return `${entry.name}=${quoteDotenvValue(entry.value)}`;
+};
+/** Serialize entries to dotenv text (no trailing newline). */
+const formatDotenv = (entries, options) => {
+	const includeSecrets = options?.includeSecrets ?? true;
+	const body = entries.map((e) => formatEntry(e, includeSecrets)).join("\n");
+	const header = options?.header;
+	return header ? `${header}\n\n${body}` : body;
+};
+//#endregion
 //#region src/core/patterns.ts
 const EXCLUDED_VARS = Set$1([
 	"PATH",
@@ -2615,6 +2739,20 @@ const writeIfValid = (configPath, updated, successMsg) => {
 	writeFileSync(configPath, updated, "utf-8");
 	console.log(successMsg);
 };
+/**
+* Validate then preview (no write) — the `--dry-run` counterpart of `writeIfValid`.
+* Runs the same structural validation the real write would, so a dry-run can never
+* show a result that the actual write would reject. On invalid output it prints the
+* same error and exits 1, exactly as the write path does.
+*
+* `display` lets callers preview a focused slice (e.g. just the new block for `add`)
+* while still validating the full resulting config.
+*/
+const previewIfValid = (updated, display) => {
+	validateOrExit(updated);
+	console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+	console.log(display ?? updated);
+};
 //#endregion
 //#region src/cli/commands/env.ts
 const printPostWriteGuidance = () => {
@@ -2693,37 +2831,118 @@ const runEnvCheck = (options) => {
 	});
 };
 const shellEscape = (value) => value.replace(/'/g, "'\\''");
+/** Shared resolution for the emit commands (`export`, `github`): resolve without injecting. */
+const resolveForEmit = (options) => bootSafe({
+	inject: false,
+	configPath: options.config,
+	profile: options.profile,
+	warnOnly: true
+});
+/**
+* Flatten a resolved BootResult into the ordered (wire-name, value) pairs to emit:
+* env defaults, then overridden env entries (value from config), then secrets (which
+* override). `secret` marks values that consumers must redact (e.g. GitHub masking).
+*/
+const collectEmitEntries = (boot) => {
+	const wireName = (key) => boot.envNames[key] ?? key;
+	const defaults = Object.entries(boot.envDefaults).map(([key, value]) => ({
+		name: wireName(key),
+		value,
+		secret: false
+	}));
+	const overridden = boot.overridden.length === 0 ? [] : loadConfig(boot.configPath).fold(() => [], (config) => {
+		const envEntries = config.env ?? {};
+		return boot.overridden.flatMap((key) => {
+			const entry = envEntries[key];
+			if (!entry) return [];
+			const name = wireName(key);
+			return [{
+				name,
+				value: entry.value ?? process.env[name] ?? "",
+				secret: false
+			}];
+		});
+	});
+	const secrets = Object.entries(boot.secrets).map(([key, value]) => ({
+		name: wireName(key),
+		value,
+		secret: true
+	}));
+	return [
+		...defaults,
+		...overridden,
+		...secrets
+	];
+};
+const emitWarnings = (boot) => {
+	const sourceMsg = formatConfigSource(boot.configPath, boot.configSource);
+	if (sourceMsg) console.error(sourceMsg);
+	boot.warnings.forEach((warning) => {
+		console.error(`${YELLOW}Warning:${RESET} ${warning}`);
+	});
+};
 const runEnvExport = (options) => {
-	bootSafe({
-		inject: false,
-		configPath: options.config,
-		profile: options.profile,
-		warnOnly: true
-	}).fold((err) => {
+	resolveForEmit(options).fold((err) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
-		const sourceMsg = formatConfigSource(boot.configPath, boot.configSource);
-		if (sourceMsg) console.error(sourceMsg);
-		boot.warnings.forEach((warning) => {
-			console.error(`${YELLOW}Warning:${RESET} ${warning}`);
+		emitWarnings(boot);
+		const scope = loadConfig(boot.configPath).fold(() => "exec", (config) => config.scope ?? "exec");
+		const entries = collectEmitEntries(boot);
+		const emit = scope === "shell" ? entries : entries.filter((e) => !e.secret);
+		const withheld = entries.length - emit.length;
+		if (withheld > 0) console.error(`${DIM}${withheld} secret(s) withheld (scope="${scope}") — use \`envpkt exec\` or set top-level scope="shell".${RESET}`);
+		emit.forEach(({ name, value }) => {
+			console.log(options.track ? `_ENVPKT_HAD_${name}=\${${name}+1}; _ENVPKT_PREV_${name}="\${${name}-}"; export ${name}='${shellEscape(value)}'` : `export ${name}='${shellEscape(value)}'`);
 		});
-		const wireName = (key) => boot.envNames[key] ?? key;
-		Object.entries(boot.envDefaults).forEach(([key, value]) => {
-			console.log(`export ${wireName(key)}='${shellEscape(value)}'`);
+		if (options.track) console.log(`_ENVPKT_INJECTED='${emit.map((e) => e.name).join(" ")}'`);
+	});
+};
+const runEnvGithub = (options) => {
+	resolveForEmit(options).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, (boot) => {
+		emitWarnings(boot);
+		const entries = collectEmitEntries(boot);
+		entries.filter((e) => e.secret).forEach((e) => console.log(`::add-mask::${e.value}`));
+		const lines = entries.map(({ name, value }) => {
+			const delim = `__ENVPKT_${randomBytes(9).toString("hex")}__`;
+			return `${name}<<${delim}\n${value}\n${delim}`;
 		});
-		if (boot.overridden.length > 0) loadConfig(boot.configPath).fold(() => {}, (config) => {
-			const envEntries = config.env ?? {};
-			boot.overridden.forEach((key) => {
-				if (!(key in envEntries)) return;
-				const entry = envEntries[key];
-				const name = wireName(key);
-				const value = entry.value ?? process.env[name] ?? "";
-				console.log(`export ${name}='${shellEscape(value)}'`);
-			});
+		const githubEnv = process.env["GITHUB_ENV"];
+		if (githubEnv) appendFileSync(githubEnv, lines.length > 0 ? `${lines.join("\n")}\n` : "");
+		else {
+			console.error(`${YELLOW}Warning:${RESET} GITHUB_ENV not set — printing assignments to stdout (not a GitHub Actions runner)`);
+			lines.forEach((l) => console.log(l));
+		}
+		if (options.strict) process.exit(exitCodeForAudit(boot.audit));
+	});
+};
+const buildDotenvHeader = (configPath) => `# Generated by envpkt — regenerate with: envpkt env dotenv\n# Source: ${configPath}. Do not edit by hand.`;
+const runEnvDotenv = (options) => {
+	resolveForEmit(options).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, (boot) => {
+		emitWarnings(boot);
+		const entries = collectEmitEntries(boot);
+		const includeSecrets = options.secrets !== false;
+		const text = formatDotenv(entries, {
+			includeSecrets,
+			header: buildDotenvHeader(boot.configPath)
 		});
-		Object.entries(boot.secrets).forEach(([key, value]) => {
-			console.log(`export ${wireName(key)}='${shellEscape(value)}'`);
+		if (!options.output) {
+			console.log(text);
+			return;
+		}
+		const outPath = resolve(options.output);
+		Try(() => writeFileSync(outPath, `${text}\n`, "utf-8")).fold((writeErr) => {
+			console.error(`${RED}Error:${RESET} Failed to write ${outPath}: ${writeErr}`);
+			process.exit(1);
+		}, () => {
+			console.error(`${GREEN}✓${RESET} Wrote ${CYAN}${outPath}${RESET}`);
+			if (includeSecrets && entries.some((e) => e.secret)) console.error(`${YELLOW}Note:${RESET} ${outPath} contains secret values — ensure it is .gitignored.`);
 		});
 	});
 };
@@ -2919,9 +3138,15 @@ const registerEnvCommands = (program) => {
 	env.command("check").description("Bidirectional drift detection between envpkt.toml and live environment").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--strict", "Exit non-zero on any drift").action((options) => {
 		runEnvCheck(options);
 	});
-	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").action((options) => {
+	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").option("--track", "Emit prior-value snapshots + an _ENVPKT_INJECTED list (for the shell hook to restore on cd)").action((options) => {
 		runEnvExport(options);
 	});
+	env.command("github").description("Inject resolved secrets into $GITHUB_ENV for GitHub Actions, masking secret values in the log (::add-mask::)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--strict", "Exit non-zero if the pre-flight audit is not healthy").action((options) => {
+		runEnvGithub(options);
+	});
+	env.command("dotenv").description("Output resolved credentials in .env format (for Wrangler, Docker --env-file, Vite, etc.)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("-o, --output <file>", "Write to a file instead of stdout").option("--no-secrets", "Omit secret values (emit KEY= with a note) — values are included by default").action((options) => {
+		runEnvDotenv(options);
+	});
 	env.command("add").description("Add a new environment default entry to envpkt.toml").argument("<name>", "Environment variable name").argument("<value>", "Default value").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this env var exists").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--dry-run", "Preview the TOML block without writing").action((name, value, options) => {
 		runEnvAdd(name, value, options);
 	});
@@ -3857,6 +4082,34 @@ const applySealedToml = (raw, sealedMeta) => {
 	};
 	return flushPending(List(lines).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]))).output.join("\n");
 };
+/** Affirmative answer to a `[y/N]` confirm prompt. */
+const isAffirmative = (answer) => /^y(es)?$/i.test(answer.trim());
+/**
+* Collect new plaintext values for the `--edit`ed keys via the injected `prompt`. Before
+* overwriting an entry that is **already sealed** (`encrypted_value` present), require an
+* explicit confirmation — replacing it discards the only ciphertext, and the prior value
+* can't be recovered without the original key. Declined or empty entries are skipped (reported
+* via `onSkip`). I/O flows only through `prompt`/`onSkip`, so the confirm/skip logic is
+* unit-testable without a TTY.
+*/
+const collectEditedValues = async (editKeys, entries, prompt, onSkip) => {
+	const values = {};
+	for (const key of editKeys) {
+		if (entries[key]?.encrypted_value) {
+			if (!isAffirmative(await prompt(`Replace the sealed value for ${key}? The previous value can't be recovered without the original key. [y/N] `))) {
+				onSkip?.(key, "declined");
+				continue;
+			}
+		}
+		const value = await prompt(`Enter new value for ${key}: `);
+		if (value === "") {
+			onSkip?.(key, "empty");
+			continue;
+		}
+		values[key] = value;
+	}
+	return values;
+};
 /** Write sealed values back into the TOML file, preserving structure. */
 const writeSealedToml = (configPath, sealedMeta) => {
 	const finalContent = applySealedToml(readFileSync(configPath, "utf-8"), sealedMeta);
@@ -3933,15 +4186,9 @@ const runSeal = async (options) => {
 		const prompt = (question) => new Promise((resolve) => {
 			rl.question(question, (answer) => resolve(answer));
 		});
-		const values = {};
-		for (const key of editKeys) {
-			const value = await prompt(`Enter new value for ${key}: `);
-			if (value === "") {
-				console.error(`${YELLOW}Skipped${RESET} ${key} (empty value)`);
-				continue;
-			}
-			values[key] = value;
-		}
+		const values = await collectEditedValues(editKeys, secretEntries, prompt, (key, reason) => {
+			console.error(`${YELLOW}Skipped${RESET} ${key} (${reason === "empty" ? "empty value" : "kept existing sealed value"})`);
+		});
 		rl.close();
 		if (Object.keys(values).length === 0) {
 			console.error(`${RED}Error:${RESET} No values provided`);
@@ -4028,6 +4275,27 @@ const runSeal = async (options) => {
 };
 //#endregion
 //#region src/cli/commands/secret.ts
+/**
+* Fields removable via `--unset` — exactly the metadata fields settable via a flag.
+* Mental model: you can unset any field you can set. Structural/managed fields
+* (`created`, `last_rotated_at`, `encrypted_value`, `from_key`, `namespace`) are
+* intentionally excluded — they're owned by `seal`/`rotate`/`alias`, not `edit`.
+* Field names are the canonical TOML keys (e.g. `rate_limit`, not `rate-limit`).
+*/
+const UNSETTABLE_FIELDS = [
+	"service",
+	"purpose",
+	"comment",
+	"expires",
+	"rotates",
+	"rate_limit",
+	"model_hint",
+	"source",
+	"rotation_url",
+	"required",
+	"capabilities",
+	"tags"
+];
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const buildSecretBlock = (name, options) => {
 	const lines = [`[secret.${name}]`];
@@ -4073,6 +4341,9 @@ const buildFieldUpdates = (options) => {
 		const [k, v] = pair.split("=").map((s) => s.trim());
 		return `${k} = "${v}"`;
 	}).join(", ")} }`;
+	options.unset?.forEach((field) => {
+		updates[field] = null;
+	});
 	return updates;
 };
 const withConfig = (configFlag, fn) => {
@@ -4105,12 +4376,12 @@ const runSecretAdd = (name, options) => {
 				process.exit(1);
 			}
 			const block = buildSecretBlock(name, options);
+			const updated = appendSection(readFileSync(configPath, "utf-8"), block);
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(block);
+				previewIfValid(updated, block);
 				return;
 			}
-			writeIfValid(configPath, appendSection(readFileSync(configPath, "utf-8"), block), `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -4119,6 +4390,12 @@ const runSecretEdit = (name, options) => {
 		console.error(`${RED}Error:${RESET} Invalid date format for --expires: "${options.expires}" (expected YYYY-MM-DD)`);
 		process.exit(1);
 	}
+	const unknownUnset = (options.unset ?? []).filter((f) => !UNSETTABLE_FIELDS.includes(f));
+	if (unknownUnset.length > 0) {
+		console.error(`${RED}Error:${RESET} Cannot --unset unknown field(s): ${unknownUnset.join(", ")}`);
+		console.error(`${DIM}Unsettable fields: ${UNSETTABLE_FIELDS.join(", ")}${RESET}`);
+		process.exit(1);
+	}
 	withConfig(Option(options.config), (configPath, raw) => {
 		loadConfig(configPath).fold((err) => {
 			console.error(formatError(err));
@@ -4138,8 +4415,7 @@ const runSecretEdit = (name, options) => {
 				process.exit(2);
 			}, (updated) => {
 				if (options.dryRun) {
-					console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-					console.log(updated);
+					previewIfValid(updated);
 					return;
 				}
 				writeIfValid(configPath, updated, `${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
@@ -4154,8 +4430,7 @@ const runSecretRm = (name, options) => {
 			process.exit(1);
 		}, (updated) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(updated);
+				previewIfValid(updated);
 				return;
 			}
 			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
@@ -4169,8 +4444,7 @@ const runSecretRename = (oldName, newName, options) => {
 			process.exit(1);
 		}, (updated) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(updated);
+				previewIfValid(updated);
 				return;
 			}
 			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
@@ -4303,8 +4577,7 @@ const runSecretRotate = async (name, options) => {
 			process.exit(2);
 		}, (result) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(result);
+				previewIfValid(result);
 				return;
 			}
 			writeIfValid(configPath, result, `${GREEN}✓${RESET} Stamped ${BOLD}last_rotated_at${RESET} on ${BOLD}${name}${RESET} (unsealed — no ciphertext to update)`);
@@ -4332,8 +4605,7 @@ const runSecretRotate = async (name, options) => {
 		process.exit(2);
 	}, (result) => {
 		if (options.dryRun) {
-			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-			console.log(result);
+			previewIfValid(result);
 			return;
 		}
 		writeIfValid(configPath, result, `${GREEN}✓${RESET} Rotated ${BOLD}${name}${RESET} (resealed + stamped ${CYAN}${today}${RESET})`);
@@ -4345,7 +4617,8 @@ const registerSecretCommands = (program) => {
 	addSecretFlags(secret.command("add").description("Add a new secret entry to envpkt.toml").argument("<name>", "Secret name (becomes the env var key)").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--dry-run", "Preview the TOML block without writing")).action((name, options) => {
 		runSecretAdd(name, options);
 	});
-	addSecretFlags(secret.command("edit").description("Update metadata fields on an existing secret").argument("<name>", "Secret name to edit").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--no-required", "Mark this secret as not required").option("--dry-run", "Preview the changes without writing")).action((name, options) => {
+	const collect = (value, previous) => [...previous, value];
+	addSecretFlags(secret.command("edit").description("Update metadata fields on an existing secret").argument("<name>", "Secret name to edit").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--no-required", "Mark this secret as not required").option("--unset <field>", "Remove an optional field (repeatable). Field names match TOML keys, e.g. expires, rate_limit", collect, []).option("--dry-run", "Preview the changes without writing")).action((name, options) => {
 		runSecretEdit(name, options);
 	});
 	secret.command("rm").description("Remove a secret entry from envpkt.toml").argument("<name>", "Secret name to remove").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((name, options) => {
@@ -4363,31 +4636,77 @@ const registerSecretCommands = (program) => {
 };
 //#endregion
 //#region src/cli/commands/shell-hook.ts
-const ZSH_HOOK = `# envpkt shell hook — add to your .zshrc
+const ZSH_HOOK = `# envpkt shell hook — add to ~/.zshrc:  eval "$(envpkt shell-hook zsh)"
+# Loads a project envpkt.toml on cd (secrets only for scope="shell" packages), restores the
+# prior environment on leave, and warns on credential health. Use \`envpkt exec\` for scope="exec".
+_envpkt_restore() {
+  [[ -n "$_ENVPKT_INJECTED" ]] || return
+  local k had prev
+  for k in \${(s: :)_ENVPKT_INJECTED}; do
+    had="_ENVPKT_HAD_$k"
+    prev="_ENVPKT_PREV_$k"
+    if [[ -n "\${(P)had}" ]]; then
+      export "$k=\${(P)prev}"
+    else
+      unset "$k"
+    fi
+    unset "$had" "$prev"
+  done
+  unset _ENVPKT_INJECTED
+}
+
 _envpkt_chpwd() {
+  local cfg
+  cfg="$(envpkt config-path 2>/dev/null)"
+  [[ "$cfg" == "$_ENVPKT_DIR" ]] && return
+  _envpkt_restore
+  _ENVPKT_DIR="$cfg"
+  [[ -z "$cfg" ]] && return
+  eval "$(envpkt env export --track 2>/dev/null)"
   envpkt audit --format minimal 2>/dev/null
 }
 
-if (( $+functions[add-zsh-hook] )); then
-  autoload -Uz add-zsh-hook
-  add-zsh-hook chpwd _envpkt_chpwd
-else
-  autoload -Uz add-zsh-hook
-  add-zsh-hook chpwd _envpkt_chpwd
-fi
+autoload -Uz add-zsh-hook
+add-zsh-hook chpwd _envpkt_chpwd
+_envpkt_chpwd
 `;
-const BASH_HOOK = `# envpkt shell hook — add to your .bashrc
-_envpkt_last_dir=""
+const BASH_HOOK = `# envpkt shell hook — add to ~/.bashrc:  eval "$(envpkt shell-hook bash)"
+# Loads a project envpkt.toml on cd (secrets only for scope="shell" packages), restores the
+# prior environment on leave, and warns on credential health. Use \`envpkt exec\` for scope="exec".
+_envpkt_restore() {
+  [ -n "$_ENVPKT_INJECTED" ] || return
+  local k had prev
+  for k in $_ENVPKT_INJECTED; do
+    had="_ENVPKT_HAD_$k"
+    prev="_ENVPKT_PREV_$k"
+    if [ -n "\${!had}" ]; then
+      export "$k=\${!prev}"
+    else
+      unset "$k"
+    fi
+    unset "$had" "$prev"
+  done
+  unset _ENVPKT_INJECTED
+}
+
 _envpkt_prompt() {
-  if [[ "$PWD" != "$_envpkt_last_dir" ]]; then
-    _envpkt_last_dir="$PWD"
-    envpkt audit --format minimal 2>/dev/null
-  fi
+  [ "$PWD" = "$_ENVPKT_PWD" ] && return
+  _ENVPKT_PWD="$PWD"
+  local cfg
+  cfg="$(envpkt config-path 2>/dev/null)"
+  [ "$cfg" = "$_ENVPKT_DIR" ] && return
+  _envpkt_restore
+  _ENVPKT_DIR="$cfg"
+  [ -z "$cfg" ] && return
+  eval "$(envpkt env export --track 2>/dev/null)"
+  envpkt audit --format minimal 2>/dev/null
 }
 
-if [[ ! "$PROMPT_COMMAND" == *"_envpkt_prompt"* ]]; then
-  PROMPT_COMMAND="_envpkt_prompt;$PROMPT_COMMAND"
-fi
+case "$PROMPT_COMMAND" in
+  *_envpkt_prompt*) ;;
+  *) PROMPT_COMMAND="_envpkt_prompt\${PROMPT_COMMAND:+;$PROMPT_COMMAND}" ;;
+esac
+_envpkt_prompt
 `;
 const runShellHook = (shell) => {
 	switch (shell) {
@@ -4730,6 +5049,9 @@ program.command("sort").description("Group [env.*] and [secret.*] sections and a
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });
+program.command("config-path").description("Print the envpkt.toml path resolved for the current directory (empty if none). Resolve-only — no decryption.").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
+	runConfigPath(options);
+});
 program.command("shell-hook").description("Output shell function for ambient credential warnings on cd — combine with env export for full setup").argument("<shell>", "Shell type: zsh | bash").action((shell) => {
 	runShellHook(shell);
 });

package/dist/index.d.ts

@@ -78,6 +78,7 @@ type EnvMeta = Static<typeof EnvMetaSchema>;
 declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
   version: import("@sinclair/typebox").TNumber;
   catalog: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  scope: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"shell">, import("@sinclair/typebox").TLiteral<"exec">]>>;
   namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
     prefix: import("@sinclair/typebox").TString;
     separator: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -327,6 +328,10 @@ type BootError = ConfigError | FnoxError | CatalogError | AliasError | {
   readonly _tag: "AuditFailed";
   readonly audit: AuditResult;
   readonly message: string;
+} | {
+  readonly _tag: "SealKeyUnavailable";
+  readonly sealedKeys: ReadonlyArray<string>;
+  readonly searched: ReadonlyArray<string>;
 } | IdentityError;
 type IdentityError = {
   readonly _tag: "AgeNotFound";
@@ -389,7 +394,7 @@ type DiscoveredConfig = {
   readonly path: string;
   readonly source: "cwd" | "search";
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 declare const discoverConfig: (cwd?: string) => Option<DiscoveredConfig>;
 /** Read a config file, returning Either<ConfigError, string> */
 declare const readConfigFile: (path: string) => Either<ConfigError, string>;
@@ -549,6 +554,35 @@ declare const updateConfigIdentity: (configPath: string, options: UpdateIdentity
 /** Resolve plaintext values for the given keys via cascade: fnox → env → interactive prompt */
 declare const resolveValues: (keys: ReadonlyArray<string>, profile?: string, agentKey?: string) => Promise<Record<string, string>>;
 //#endregion
+//#region src/core/dotenv.d.ts
+/**
+ * Serialize resolved credential entries to `.env` (dotenv) format.
+ *
+ * Unlike `env export` (shell `export VAR=...` for `eval`) this emits the bare
+ * `KEY=value` syntax that the broad `.env`-consuming ecosystem auto-discovers:
+ * Wrangler, Docker `--env-file`, Vite/Next/Astro, many GitHub Actions, direnv.
+ *
+ * Pure and deterministic — no I/O, no timestamps — so regenerating a file
+ * produces identical output (clean diffs, reproducible CI).
+ */
+type DotenvEntry = {
+  readonly name: string;
+  readonly value: string;
+  readonly secret: boolean;
+};
+type FormatDotenvOptions = {
+  /** Write secret values into the output. Default true (matches `env export`/`env github`). */readonly includeSecrets?: boolean; /** A pre-formatted comment block (each line `#`-prefixed) placed at the top. */
+  readonly header?: string;
+};
+/**
+ * Quote a single value for dotenv output. Returns the value bare when safe,
+ * otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+ * whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+ */
+declare const quoteDotenvValue: (value: string) => string;
+/** Serialize entries to dotenv text (no trailing newline). */
+declare const formatDotenv: (entries: ReadonlyArray<DotenvEntry>, options?: FormatDotenvOptions) => string;
+//#endregion
 //#region src/core/toml-edit.d.ts
 /**
  * Remove a TOML section (e.g. `[secret.X]`) and all its fields through the next section or EOF.
@@ -634,4 +668,4 @@ type ToolDef = {
 declare const toolDefinitions: readonly ToolDef[];
 declare const callTool: (name: string, args: Record<string, unknown>) => CallToolResult;
 //#endregion
-export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/dist/index.js

@@ -4,10 +4,10 @@ import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { $, Cond, Do, Either, Left, List, Map as Map$1, None, Option, Right, Set as Set$1, Some, Try } from "functype";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse } from "smol-toml";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { createDirectConsoleLogger, createDirectTestLogger, directSilentLogger, directSilentLogger as directSilentLogger$1 } from "functype-log/direct";
 import { execFileSync } from "node:child_process";
-import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -111,6 +111,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	scope: Type.Optional(Type.Union([Type.Literal("shell"), Type.Literal("exec")], { description: "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything." })),
 	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
@@ -182,11 +183,24 @@ const buildSearchPaths = () => {
 	const cloudPaths = Platform.cloudStorageDirs().toArray().map((cloud) => join(cloud.path, ".envpkt", CONFIG_FILENAME$1));
 	return [...homePaths, ...cloudPaths];
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/**
+* Walk up from `dir` to the filesystem root, returning the nearest `envpkt.toml`.
+* Makes a project's config apply throughout its subtree (like git/.env/direnv finding
+* their root file), not only in the directory that literally contains the file.
+* The global package lives in `~/.envpkt/` (a subdir), so it is not matched by this
+* walk — it is resolved by the search-path/Platform fallback below.
+*/
+const walkUpForConfig = (dir) => {
+	const candidate = join(dir, CONFIG_FILENAME$1);
+	if (Fs.existsSync(candidate)) return Option(candidate);
+	const parent = dirname(dir);
+	return parent === dir ? Option(void 0) : walkUpForConfig(parent);
+};
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 const discoverConfig = (cwd) => {
-	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$1);
-	if (Fs.existsSync(cwdCandidate)) return Option({
-		path: cwdCandidate,
+	const walked = walkUpForConfig(cwd ?? process.cwd()).orUndefined();
+	if (walked) return Option({
+		path: walked,
 		source: "cwd"
 	});
 	const customMatch = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean)).map((template) => ({
@@ -1926,6 +1940,65 @@ const resolveIdentityFilePath = (config, configDir, useDefaultFallback) => {
 	const defaultPath = resolveKeyPath();
 	return existsSync(defaultPath) ? Option(defaultPath) : Option(void 0);
 };
+const noop = () => {};
+/** Write an inline age key to a private temp file so the `age` CLI (file-based) can use it. */
+const materializeInlineKey = (key) => {
+	const dir = mkdtempSync(join(tmpdir(), "envpkt-age-"));
+	const keyPath = join(dir, "age-key.txt");
+	writeFileSync(keyPath, key.endsWith("\n") ? key : `${key}\n`);
+	chmodSync(keyPath, 384);
+	return {
+		path: keyPath,
+		dispose: () => rmSync(dir, {
+			recursive: true,
+			force: true
+		})
+	};
+};
+/**
+* Resolve an age identity for unsealing sealed packets. Precedence:
+*   config.identity.key_file > ENVPKT_AGE_KEY_FILE > ENVPKT_AGE_KEY (inline) > ~/.envpkt/age-key.txt
+* The inline key (CI secret) ranks above the homedir default so an explicit
+* env var beats a stray local key. Inline keys are written to a 0600 temp file
+* the caller must dispose().
+*/
+const resolveSealIdentity = (config, configDir) => {
+	if (config.identity?.key_file) {
+		const keyFilePath = resolve(configDir, expandPath(config.identity.key_file));
+		if (existsSync(keyFilePath)) return Option({
+			path: keyFilePath,
+			dispose: noop
+		});
+	}
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	if (envFile && existsSync(envFile)) return Option({
+		path: envFile,
+		dispose: noop
+	});
+	const inlineKey = resolveInlineKey().orUndefined();
+	if (inlineKey) return Option(materializeInlineKey(inlineKey));
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	if (existsSync(defaultPath)) return Option({
+		path: defaultPath,
+		dispose: noop
+	});
+	return Option(void 0);
+};
+/** Describe the seal-identity precedence chain with per-entry status, for a clear no-key error. */
+const describeSealKeySearch = (config, configDir) => {
+	const keyFile = config.identity?.key_file;
+	const keyFileLine = keyFile ? `identity.key_file → ${resolve(configDir, expandPath(keyFile))} (${existsSync(resolve(configDir, expandPath(keyFile))) ? "found" : "missing"})` : `identity.key_file (not set)`;
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	const envFileLine = envFile ? `ENVPKT_AGE_KEY_FILE → ${envFile} (${existsSync(envFile) ? "found" : "missing"})` : `ENVPKT_AGE_KEY_FILE (unset)`;
+	const inlineLine = resolveInlineKey().isEmpty ? `ENVPKT_AGE_KEY (unset)` : `ENVPKT_AGE_KEY (set, inline)`;
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	return [
+		keyFileLine,
+		envFileLine,
+		inlineLine,
+		`${defaultPath} (${existsSync(defaultPath) ? "found" : "missing"})`
+	];
+};
 const resolveIdentityKey = (config, configDir) => {
 	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (key) => Right(Option(key))));
 };
@@ -1995,6 +2068,12 @@ const bootSafe = (options) => {
 			message: "unexpected"
 		}));
 		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
+		if (hasSealedValues && sealIdentity.isEmpty) return Left({
+			_tag: "SealKeyUnavailable",
+			sealedKeys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value),
+			searched: describeSealKeySearch(config, configDir)
+		});
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
 			const injected = [];
@@ -2008,23 +2087,25 @@ const bootSafe = (options) => {
 				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
-			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
-			if (hasSealedValues) identityFilePath.fold(() => {
+			if (hasSealedValues) sealIdentity.fold(() => {
 				log.warn("phase.sealed.no_identity_file", { sealed_keys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value).length });
-				warnings.push("Sealed values found but no identity file available for decryption");
-			}, (idPath) => {
-				unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
-					log.warn("phase.sealed.decrypt_failed", { message: err.message });
-					warnings.push(`Sealed value decryption failed: ${err.message}`);
-				}, (unsealed) => {
-					const unsealedEntries = Object.entries(unsealed);
-					Object.assign(secrets, unsealed);
-					injected.push(...unsealedEntries.map(([key]) => key));
-					unsealedEntries.forEach(([key]) => {
-						sealedKeys.add(key);
-						log.debug("phase.sealed.resolved", { key });
+			}, ({ path: idPath, dispose }) => {
+				try {
+					unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
+						log.warn("phase.sealed.decrypt_failed", { message: err.message });
+						warnings.push(`Sealed value decryption failed: ${err.message}`);
+					}, (unsealed) => {
+						const unsealedEntries = Object.entries(unsealed);
+						Object.assign(secrets, unsealed);
+						injected.push(...unsealedEntries.map(([key]) => key));
+						unsealedEntries.forEach(([key]) => {
+							sealedKeys.add(key);
+							log.debug("phase.sealed.resolved", { key });
+						});
 					});
-				});
+				} finally {
+					dispose();
+				}
 			});
 			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
 			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
@@ -2141,6 +2222,19 @@ const formatBootError = (error) => {
 		case "AgeNotFound": return `age not found: ${error.message}`;
 		case "DecryptFailed": return `Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `Identity file not found: ${error.path}`;
+		case "SealKeyUnavailable": {
+			const keys = error.sealedKeys.length;
+			const searched = error.searched.map((line) => `  • ${line}`).join("\n");
+			return [
+				`${keys} sealed secret(s) can't be decrypted — no age key found.`,
+				`Searched (in order):`,
+				searched,
+				`Fix one:`,
+				`  • Restore your key to ~/.envpkt/age-key.txt (or set ENVPKT_AGE_KEY_FILE / ENVPKT_AGE_KEY)`,
+				`  • Re-provision from source: envpkt seal --edit <KEY>`,
+				`Refusing to inject empty values for sealed secrets.`
+			].join("\n");
+		}
 		case "AliasInvalidSyntax":
 		case "AliasTargetMissing":
 		case "AliasSelfReference":
@@ -2188,6 +2282,30 @@ const resolveValues = async (keys, profile, agentKey) => {
 	return result;
 };
 //#endregion
+//#region src/core/dotenv.ts
+const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+* Quote a single value for dotenv output. Returns the value bare when safe,
+* otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+* whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+*/
+const quoteDotenvValue = (value) => {
+	if (value === "") return "";
+	if (BARE_SAFE.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+};
+const formatEntry = (entry, includeSecrets) => {
+	if (entry.secret && !includeSecrets) return `# (secret value omitted — re-run without --no-secrets to include)\n${entry.name}=`;
+	return `${entry.name}=${quoteDotenvValue(entry.value)}`;
+};
+/** Serialize entries to dotenv text (no trailing newline). */
+const formatDotenv = (entries, options) => {
+	const includeSecrets = options?.includeSecrets ?? true;
+	const body = entries.map((e) => formatEntry(e, includeSecrets)).join("\n");
+	const header = options?.header;
+	return header ? `${header}\n\n${body}` : body;
+};
+//#endregion
 //#region src/core/toml-edit.ts
 const SECTION_RE = /^\[.+\]\s*$/;
 const MULTILINE_OPEN = "\"\"\"";
@@ -2686,4 +2804,4 @@ const startServer = async () => {
 	await server.connect(transport);
 };
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.11.9",
+  "version": "0.13.0",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",
@@ -42,14 +42,14 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.49",
     "commander": "^15.0.0",
-    "functype": "^1.3.0",
-    "functype-log": "^1.3.0",
-    "functype-os": "^1.3.0",
+    "functype": "^1.3.1",
+    "functype-log": "^1.3.1",
+    "functype-os": "^1.3.1",
     "smol-toml": "^1.6.1"
   },
   "devDependencies": {
     "@types/node": "^24.13.1",
-    "ts-builds": "^3.0.0",
+    "ts-builds": "^3.0.1",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4"
   },

package/schemas/envpkt.schema.json

@@ -17,6 +17,19 @@
       "description": "Path to shared secret catalog (relative to this config file)",
       "type": "string"
     },
+    "scope": {
+      "description": "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything.",
+      "anyOf": [
+        {
+          "const": "shell",
+          "type": "string"
+        },
+        {
+          "const": "exec",
+          "type": "string"
+        }
+      ]
+    },
     "namespace": {
       "description": "Optional namespace/package prefix for injected environment variable names",
       "type": "object",