envpkt 0.13.1 → 0.13.2

package/README.md

@@ -5,43 +5,38 @@
 
 **Credentials your agents actually understand.**
 
-Structured metadata for every secret — capabilities, constraints, expiration, and fleet health — so agents operate within their boundaries instead of flying blind.
+envpkt gives every credential an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_ — while the secret values stay in your secrets manager, encrypted at rest, or injected at runtime, never committed in plaintext.
 
-Every credential in your system gets an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_. Your agents query this metadata via MCP to understand their operating constraints. Your operators audit credential health across entire agent fleets. The secrets themselves stay where they belong — in your secrets manager, encrypted at rest, or injected at runtime — never in the agent's conversation context.
+**Day one, with zero agents,** it's an encrypted-at-rest `.env` replacement with scoped loading: scan the credentials already in your shell, seal them into a file that's safe to commit, and load them automatically on `cd`, into a single command, or as a plain `.env` for any tool that wants one.
 
-## MCP Integration
+**As you add agents,** the same metadata gives them structured awareness of their own credentials over [MCP](#for-agents-and-fleets) — capabilities, expiry, drift, fleet health — without any secret value ever entering the model's context window.
 
-envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+## Quick Start
 
-```json
-{
-  "mcpServers": {
-    "envpkt": {
-      "command": "envpkt",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+The whole loop for a single project — discover, seal, load — with zero agents involved:
 
-### Tools
+```bash
+npm install -g envpkt
 
-| Tool               | Description                                             |
-| ------------------ | ------------------------------------------------------- |
-| `getPacketHealth`  | Get overall health status with per-secret audit results |
-| `listCapabilities` | List agent and per-secret capabilities                  |
-| `getSecretMeta`    | Get metadata for a specific secret by key               |
-| `checkExpiration`  | Check expiration status and days remaining              |
-| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+# 1. Discover the credentials already in your shell, and scaffold envpkt.toml from them
+envpkt env scan
+envpkt env scan --write
 
-### Resources
+# 2. Generate an age key and seal the secret values into envpkt.toml (the file is safe to commit)
+envpkt keygen
+envpkt seal
 
-| URI                     | Description                       |
-| ----------------------- | --------------------------------- |
-| `envpkt://health`       | Current credential health summary |
-| `envpkt://capabilities` | Agent and secret capabilities     |
+# 3. Load them — pick whatever fits the moment:
+envpkt exec -- your-tool            # run one command with the secrets injected, scoped to it
+eval "$(envpkt shell-hook zsh)"     # add to ~/.zshrc: auto-load on cd into a project, restore on leave
+envpkt env dotenv -o .env           # materialize a .env for Docker / Wrangler / Vite / …
+
+# Anytime: check health and drift
+envpkt audit
+envpkt env check
+```
 
-The MCP server exposes metadata only — it does not have access to secret values. See [Security Model](#security-model) for details.
+Encrypted secrets committed to git, loaded where you need them, with health you can audit — and not an agent in sight. Scaling the same metadata to agents and fleets is [act two](#for-agents-and-fleets).
 
 ## Security Model
 
@@ -53,30 +48,6 @@ envpkt operates a three-tier trust model. Each tier has different guarantees, an
 
 **Tier 3: Shell-level agents** — Agents with shell access (Claude Code, Devin, etc.) can read environment variables directly. Prevention isn't possible at this tier. envpkt provides encrypted storage, scoped access, and audit trails — because when prevention isn't possible, visibility is what matters.
 
-## Quick Start
-
-Start where your credentials already are — environment variables — and graduate to encrypted, per-agent-scoped metadata.
-
-```bash
-# Install
-npm install -g envpkt
-
-# Auto-discover credentials from your shell environment
-envpkt env scan
-
-# Scaffold envpkt.toml from discovered credentials
-envpkt env scan --write
-
-# Audit credential health
-envpkt audit
-
-# Check for drift between envpkt.toml and live environment
-envpkt env check
-
-# Scan a directory tree of agents
-envpkt fleet
-```
-
 ## The envpkt.toml File
 
 Every project gets one `envpkt.toml` that describes its credentials. Here's a minimal example:
@@ -236,6 +207,44 @@ A composite action resolves the credentials in `envpkt.toml` into the CI job —
 
 > 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.
 
+## For agents and fleets
+
+Everything above stands on its own with no agents involved. Once you _do_ have them, the same `envpkt.toml` metadata powers three more capabilities: agents reading their own constraints over MCP, fleet-wide health monitoring, and shared catalogs across many agents.
+
+### MCP server
+
+envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "envpkt": {
+      "command": "envpkt",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tools**
+
+| Tool               | Description                                             |
+| ------------------ | ------------------------------------------------------- |
+| `getPacketHealth`  | Get overall health status with per-secret audit results |
+| `listCapabilities` | List agent and per-secret capabilities                  |
+| `getSecretMeta`    | Get metadata for a specific secret by key               |
+| `checkExpiration`  | Check expiration status and days remaining              |
+| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+
+**Resources**
+
+| URI                     | Description                       |
+| ----------------------- | --------------------------------- |
+| `envpkt://health`       | Current credential health summary |
+| `envpkt://capabilities` | Agent and secret capabilities     |
+
+The MCP server exposes metadata only — it reads `envpkt.toml` and strips any `encrypted_value` ciphertext from responses, so prompt injection cannot leak what isn't there. See [Security Model](#security-model) for the full trust model.
+
 ## 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.
@@ -355,6 +364,19 @@ envpkt audit -c path/to/envpkt.toml # Specify config path
 
 Exit codes: `0` = healthy, `1` = degraded, `2` = critical.
 
+### `envpkt doctor`
+
+One-shot environment check: is the `age` CLI installed, is a config resolvable here, and do its sealed secrets decrypt with an available key?
+
+```bash
+envpkt doctor
+# ✓ age      v1.2.0
+# ✓ config   /path/to/envpkt.toml
+# ✓ secrets  5 resolved, 0 skipped
+```
+
+If `age` is missing it prints the platform-specific install command; if a sealed packet has no key, it lists the paths it searched. Exits non-zero when a check fails.
+
 ### `envpkt resolve`
 
 Resolve catalog references and output a flat, self-contained config.
@@ -470,7 +492,8 @@ Secret values are emitted **only when the package sets top-level `scope = "shell
 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)
+eval "$(envpkt shell-hook zsh)"             # add to ~/.zshrc (or: shell-hook bash)
+eval "$(envpkt shell-hook zsh --no-audit)"  # …without the per-cd health-check line
 ```
 
 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).
@@ -486,18 +509,6 @@ Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each
 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`.
-
-```bash
-# Add to your .zshrc
-eval "$(envpkt shell-hook zsh)"
-
-# Add to your .bashrc
-eval "$(envpkt shell-hook bash)"
-```
-
 ### `envpkt mcp`
 
 Start the envpkt MCP server (stdio transport) for AI agent integration.

package/dist/cli.js

@@ -8,10 +8,10 @@ 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 { execFileSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { directSilentLogger } from "functype-log/direct";
-import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 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";
@@ -557,6 +557,63 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 	}));
 };
 //#endregion
+//#region src/fnox/identity.ts
+/** Check if the age CLI is available on PATH */
+const ageAvailable = () => Try(() => {
+	execFileSync("age", ["--version"], { stdio: "pipe" });
+	return true;
+}).fold(() => false, (v) => v);
+/** The age CLI version string (e.g. "v1.2.0"), or None if age isn't on PATH. */
+const ageVersion = () => Try(() => execFileSync("age", ["--version"], {
+	stdio: [
+		"pipe",
+		"pipe",
+		"pipe"
+	],
+	encoding: "utf-8"
+}).trim()).fold(() => Option.none(), (v) => Option(v));
+/** Platform-aware instructions for installing the age CLI. */
+const ageInstallHint = () => {
+	return `Install age:\n    ${{
+		darwin: "brew install age",
+		linux: "apt install age   (or: apk add age · dnf install age · nix-env -iA nixpkgs.age)",
+		win32: "scoop install age   (or: winget install FiloSottile.age)"
+	}[process.platform] ?? "see the install guide"}\n    https://github.com/FiloSottile/age#installation`;
+};
+/**
+* Extract the secret key from an age identity file (plain or encrypted).
+* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
+* - Encrypted identity files need `age --decrypt` to unwrap
+*/
+const unwrapAgentKey = (identityPath) => {
+	if (!existsSync(identityPath)) return Left({
+		_tag: "IdentityNotFound",
+		path: identityPath
+	});
+	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
+		_tag: "DecryptFailed",
+		message: `Failed to read identity file: ${err}`
+	}), (content) => {
+		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
+		if (secretKeyLine) return Right(secretKeyLine.trim());
+		if (!ageAvailable()) return Left({
+			_tag: "AgeNotFound",
+			message: "age CLI not found on PATH"
+		});
+		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			encoding: "utf-8"
+		})).fold((err) => Left({
+			_tag: "DecryptFailed",
+			message: `age decrypt failed: ${err}`
+		}), (output) => Right(output.trim()));
+	});
+};
+//#endregion
 //#region src/cli/output.ts
 const RESET = "\x1B[0m";
 const BOLD = "\x1B[1m";
@@ -659,7 +716,7 @@ const formatError = (error) => {
 		case "ParseError": return `${RED}Error:${RESET} Failed to parse TOML: ${error.message}`;
 		case "ValidationError": return `${RED}Error:${RESET} Config validation failed:\n${String(error.errors)}`;
 		case "ReadError": return `${RED}Error:${RESET} Could not read file: ${error.message}`;
-		case "AgeNotFound": return `${RED}Error:${RESET} age CLI not found: ${error.message}`;
+		case "AgeNotFound": return `${RED}Error:${RESET} age is required for this operation but was not found on PATH.\n${DIM}${ageInstallHint()}${RESET}`;
 		case "DecryptFailed": return `${RED}Error:${RESET} Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `${RED}Error:${RESET} Identity file not found: ${error.path}`;
 		case "SealKeyUnavailable": {
@@ -918,46 +975,6 @@ const fnoxAvailable = () => Try(() => {
 	return true;
 }).fold(() => false, (v) => v);
 //#endregion
-//#region src/fnox/identity.ts
-/** Check if the age CLI is available on PATH */
-const ageAvailable = () => Try(() => {
-	execFileSync("age", ["--version"], { stdio: "pipe" });
-	return true;
-}).fold(() => false, (v) => v);
-/**
-* Extract the secret key from an age identity file (plain or encrypted).
-* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
-* - Encrypted identity files need `age --decrypt` to unwrap
-*/
-const unwrapAgentKey = (identityPath) => {
-	if (!existsSync(identityPath)) return Left({
-		_tag: "IdentityNotFound",
-		path: identityPath
-	});
-	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
-		_tag: "DecryptFailed",
-		message: `Failed to read identity file: ${err}`
-	}), (content) => {
-		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
-		if (secretKeyLine) return Right(secretKeyLine.trim());
-		if (!ageAvailable()) return Left({
-			_tag: "AgeNotFound",
-			message: "age CLI not found on PATH"
-		});
-		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			],
-			encoding: "utf-8"
-		})).fold((err) => Left({
-			_tag: "DecryptFailed",
-			message: `age decrypt failed: ${err}`
-		}), (output) => Right(output.trim()));
-	});
-};
-//#endregion
 //#region src/fnox/parse.ts
 /** Read and parse fnox.toml, extracting secret keys and profiles */
 const readFnoxConfig = (path) => Try(() => readFileSync(path, "utf-8")).fold((err) => Left({
@@ -1594,6 +1611,57 @@ const bootSafe = (options) => {
 	}));
 };
 //#endregion
+//#region src/cli/commands/doctor.ts
+const ok = (label, detail) => console.log(`  ${GREEN}✓${RESET} ${label}  ${DIM}${detail}${RESET}`);
+const warn = (label, detail) => console.log(`  ${YELLOW}—${RESET} ${label}  ${detail}`);
+const bad = (label, detail) => console.log(`  ${RED}✗${RESET} ${label}  ${detail}`);
+/** Print the resolution/key check, returning whether it passed. */
+const reportResolution = (configPath) => bootSafe({
+	configPath,
+	inject: false,
+	warnOnly: true
+}).fold((err) => {
+	if (err._tag === "SealKeyUnavailable") {
+		bad("key   ", `${err.sealedKeys.length} sealed secret(s) but no decryption key`);
+		err.searched.forEach((line) => console.log(`${DIM}        ${line}${RESET}`));
+	} else bad("config", `${err._tag}`);
+	return false;
+}, (boot) => {
+	const resolved = Object.keys(boot.secrets).length;
+	ok("secrets", `${resolved} resolved, ${boot.skipped.length} skipped`);
+	const auditColor = boot.audit.status === "healthy" ? GREEN : YELLOW;
+	console.log(`  ${auditColor}•${RESET} audit   ${DIM}${boot.audit.status}${RESET}`);
+	return true;
+});
+/**
+* One-shot environment check: is age installed, is a config resolvable, and do its sealed
+* secrets decrypt with an available key? Read-only; exits non-zero if any check fails.
+*/
+const runDoctor = (options) => {
+	console.log(`${BOLD}envpkt doctor${RESET}\n`);
+	const ageOk = ageVersion().fold(() => {
+		bad("age   ", "not found on PATH");
+		console.log(`${DIM}        ${ageInstallHint().split("\n").join("\n        ")}${RESET}`);
+		return false;
+	}, (version) => {
+		ok("age   ", version);
+		return true;
+	});
+	const resolveOk = resolveConfigPath(options.config).fold(() => {
+		warn("config", "no envpkt.toml found for this directory");
+		return true;
+	}, ({ path }) => {
+		ok("config", path);
+		return reportResolution(path);
+	});
+	console.log("");
+	if (ageOk && resolveOk) console.log(`${GREEN}✓ no issues${RESET}`);
+	else {
+		console.log(`${RED}✗ ${[!ageOk, !resolveOk].filter(Boolean).length} issue(s) found${RESET} ${CYAN}(see above)${RESET}`);
+		process.exit(1);
+	}
+};
+//#endregion
 //#region src/core/dotenv.ts
 const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 /**
@@ -5078,6 +5146,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("doctor").description("Check that age is installed and that the resolved config's sealed secrets can be decrypted").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
+	runDoctor(options);
+});
 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);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",