envpkt 0.11.3 → 0.11.4

package/dist/cli.js

@@ -778,9 +778,13 @@ const runAuditOnConfig = (config, options) => {
 		...afterStatus,
 		secrets: afterStatus.secrets.filter((s) => s.days_remaining.fold(() => false, (d) => d >= 0 && d <= expiring))
 	}));
-	if (options.format === "json") console.log(formatAuditJson(filtered));
-	else if (options.format === "minimal") console.log(formatAuditMinimal(filtered));
-	else console.log(formatAudit(filtered));
+	const sorted = options.sort ? {
+		...filtered,
+		secrets: filtered.secrets.sortBy((s) => s.key)
+	} : filtered;
+	if (options.format === "json") console.log(formatAuditJson(sorted));
+	else if (options.format === "minimal") console.log(formatAuditMinimal(sorted));
+	else console.log(formatAudit(sorted));
 	if (options.all) if (options.format === "json") console.log(formatEnvAuditJson(config));
 	else formatEnvAuditTable(config);
 	const code = options.strict ? exitCodeForAudit(audit) : audit.status === "critical" ? 2 : 0;
@@ -2360,6 +2364,145 @@ const updateSectionFields = (raw, sectionHeader, updates) => {
 * Ensures proper spacing (double newline before the block).
 */
 const appendSection = (raw, block) => `${raw.trimEnd()}\n\n${block}`;
+const ENV_HEADER_RE = /^\[env\.(.+)\]\s*$/;
+const SECRET_HEADER_RE = /^\[secret\.(.+)\]\s*$/;
+const ANY_HEADER_RE = /^\[.+\]\s*$/;
+/**
+* Find the end (exclusive) of a section starting at `start`, respecting
+* multiline `"""..."""` values so the scanner does not mistake content inside
+* a multiline string for a section header.
+*/
+const findSectionEnd = (lines, start) => {
+	const initial = {
+		end: lines.length,
+		inMultiline: false,
+		done: false
+	};
+	return List(lines.slice(start + 1)).zipWithIndex().foldLeft(initial)((state, entry) => scanSectionBoundary(state, entry[0], start + 1 + entry[1])).end;
+};
+/**
+* Walking backwards from `headerIdx`, return the index of the first line of the
+* "doc block" that should travel with this section. A doc block is a contiguous
+* run of `#`-comment lines *immediately* above the header (no blank line
+* between). A blank line acts as a paragraph break and stops the walk — so
+* `# Some heading\n\n[secret.X]` does NOT attach the heading to `[secret.X]`.
+*/
+const findPreambleStart = (lines, headerIdx) => {
+	const stopOffset = [...lines.slice(0, headerIdx)].reverse().findIndex((l) => !l.trim().startsWith("#"));
+	return stopOffset === -1 ? 0 : headerIdx - stopOffset;
+};
+const classifyHeader = (line, idx) => {
+	if (!ANY_HEADER_RE.test(line)) return Option.none();
+	const envMatch = line.match(ENV_HEADER_RE);
+	if (envMatch) return Option({
+		idx,
+		kind: "env",
+		key: envMatch[1]
+	});
+	const secretMatch = line.match(SECRET_HEADER_RE);
+	if (secretMatch) return Option({
+		idx,
+		kind: "secret",
+		key: secretMatch[1]
+	});
+	return Option({
+		idx,
+		kind: "other",
+		key: ""
+	});
+};
+const scanHeader = (state, line, idx) => {
+	if (state.inMultiline) return line.includes(MULTILINE_OPEN) ? {
+		...state,
+		inMultiline: false
+	} : state;
+	if (line.includes(MULTILINE_OPEN)) return (line.slice(line.indexOf("=") + 1).trim().match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1 ? {
+		...state,
+		inMultiline: true
+	} : state;
+	return classifyHeader(line, idx).fold(() => state, (header) => ({
+		...state,
+		headers: [...state.headers, header]
+	}));
+};
+const partitionSections = (raw) => {
+	const lines = raw.split("\n");
+	const { headers } = List(lines).zipWithIndex().foldLeft({
+		headers: [],
+		inMultiline: false
+	})((state, entry) => scanHeader(state, entry[0], entry[1]));
+	const envSecretHeaders = headers.filter((h) => h.kind === "env" || h.kind === "secret");
+	const trueBodyRange = (headerIdx) => {
+		const naiveEnd = findSectionEnd(lines, headerIdx);
+		const lastContent = lines.slice(headerIdx, naiveEnd).findLastIndex((l) => {
+			const t = l.trim();
+			return t !== "" && !t.startsWith("#");
+		});
+		return {
+			start: headerIdx,
+			end: lastContent === -1 ? headerIdx + 1 : headerIdx + lastContent + 1
+		};
+	};
+	const sections = envSecretHeaders.map((h) => {
+		const headerIdx = h.idx;
+		const preambleStart = findPreambleStart(lines, headerIdx);
+		const body = lines.slice(headerIdx, trueBodyRange(headerIdx).end);
+		const preamble = lines.slice(preambleStart, headerIdx);
+		return {
+			kind: h.kind,
+			key: h.key,
+			body,
+			preamble
+		};
+	});
+	const claimedRanges = envSecretHeaders.map((h) => {
+		const headerIdx = h.idx;
+		return {
+			start: findPreambleStart(lines, headerIdx),
+			end: trueBodyRange(headerIdx).end
+		};
+	});
+	const isClaimed = (idx) => claimedRanges.some((r) => idx >= r.start && idx < r.end);
+	return {
+		preambleLines: lines.map((l, idx) => isClaimed(idx) ? null : l).filter((l) => l !== null),
+		envSections: sections.filter((s) => s.kind === "env"),
+		secretSections: sections.filter((s) => s.kind === "secret")
+	};
+};
+const emitSection = (s) => {
+	return `${s.preamble.length > 0 ? `${s.preamble.join("\n")}\n` : ""}${s.body.join("\n")}`;
+};
+/**
+* Reformat a TOML config with `[env.*]` and `[secret.*]` sections grouped and
+* alphabetized. Top-level content (version key, `[identity]`, `[lifecycle]`,
+* `[callbacks]`, `[tools]`, etc.) stays in its original position. Comment
+* doc-blocks immediately above a section header travel with that section.
+*
+* Pure — no I/O. Returns the raw input unchanged when there is no env or
+* secret content to reorder.
+*/
+const sortConfigToml = (raw) => {
+	const { preambleLines, envSections, secretSections } = partitionSections(raw);
+	if (envSections.length === 0 && secretSections.length === 0) return raw;
+	const sortedEnv = [...envSections].sort((a, b) => a.key.localeCompare(b.key));
+	const sortedSecret = [...secretSections].sort((a, b) => a.key.localeCompare(b.key));
+	const trimTrailing = (xs) => {
+		const lastNonBlank = xs.findLastIndex((l) => l.trim() !== "");
+		return lastNonBlank === -1 ? [] : xs.slice(0, lastNonBlank + 1);
+	};
+	const collapseBlanks = (xs) => xs.reduce((acc, line) => {
+		const isBlank = line.trim() === "";
+		const prevBlank = acc.length > 0 && acc[acc.length - 1].trim() === "";
+		if (isBlank && prevBlank) return acc;
+		return [...acc, line];
+	}, []);
+	const preambleTrimmed = collapseBlanks(trimTrailing(preambleLines));
+	const parts = [];
+	if (preambleTrimmed.length > 0) parts.push(preambleTrimmed.join("\n"));
+	if (sortedEnv.length > 0) parts.push(sortedEnv.map(emitSection).join("\n\n"));
+	if (sortedSecret.length > 0) parts.push(sortedSecret.map(emitSection).join("\n\n"));
+	return `${parts.join("\n\n")}\n`;
+};
 //#endregion
 //#region src/core/validate.ts
 /**
@@ -3000,6 +3143,7 @@ const printSecretMeta = (meta, indent) => {
 		console.log(`${indent}${DIM}tags:${RESET} ${tagStr}`);
 	}
 };
+const sortedIfRequested = (entries, sort) => sort ? [...entries].sort((a, b) => a[0].localeCompare(b[0])) : entries;
 const printConfig = (config, path, resolveResult, opts) => {
 	console.log(`${BOLD}envpkt.toml${RESET} ${DIM}(${path})${RESET}`);
 	if (resolveResult?.catalogPath) console.log(`${DIM}Catalog: ${CYAN}${resolveResult.catalogPath}${RESET}`);
@@ -3017,7 +3161,7 @@ const printConfig = (config, path, resolveResult, opts) => {
 	}
 	const secretEntries = config.secret ?? {};
 	console.log(`${BOLD}Secrets:${RESET} ${Object.keys(secretEntries).length}`);
-	Object.entries(secretEntries).forEach(([key, meta]) => {
+	sortedIfRequested(Object.entries(secretEntries), opts?.sort).forEach(([key, meta]) => {
 		const valueSuffix = Option(opts?.secrets?.[key]).fold(() => "", (secretValue) => ` = ${YELLOW}${(opts?.secretDisplay ?? "encrypted") === "plaintext" ? secretValue : maskValue(secretValue)}${RESET}`);
 		const sealedTag = meta.encrypted_value ? ` ${CYAN}[sealed]${RESET}` : "";
 		console.log(`  ${BOLD}${key}${RESET} → ${meta.service ?? key}${sealedTag}${valueSuffix}`);
@@ -3028,7 +3172,7 @@ const printConfig = (config, path, resolveResult, opts) => {
 	if (envKeys.length > 0) {
 		console.log("");
 		console.log(`${BOLD}Environment Defaults:${RESET} ${envKeys.length}`);
-		Object.entries(envEntries).forEach(([key, entry]) => {
+		sortedIfRequested(Object.entries(envEntries), opts?.sort).forEach(([key, entry]) => {
 			console.log(`  ${BOLD}${key}${RESET} = ${GREEN}"${entry.value}"${RESET}`);
 			if (entry.purpose) console.log(`    ${DIM}purpose:${RESET} ${entry.purpose}`);
 			if (entry.comment) console.log(`    ${DIM}comment:${RESET} ${DIM}${entry.comment}${RESET}`);
@@ -3092,7 +3236,10 @@ const runInspect = (options) => {
 						secretDisplay: options.plaintext ? "plaintext" : "encrypted"
 					};
 				})() : void 0;
-				printConfig(showConfig, path, showResolved ? resolveResult : void 0, printOpts);
+				printConfig(showConfig, path, showResolved ? resolveResult : void 0, {
+					...printOpts ?? {},
+					sort: options.sort
+				});
 			});
 		});
 	});
@@ -4182,6 +4329,45 @@ const runShellHook = (shell) => {
 	}
 };
 //#endregion
+//#region src/cli/commands/sort.ts
+const SECTION_HEADER_RE = /^\[(env|secret)\.(.+)\]\s*$/;
+const countSections = (raw) => raw.split("\n").reduce((acc, line) => {
+	const m = SECTION_HEADER_RE.exec(line);
+	if (!m) return acc;
+	return m[1] === "env" ? {
+		...acc,
+		env: acc.env + 1
+	} : {
+		...acc,
+		secret: acc.secret + 1
+	};
+}, {
+	env: 0,
+	secret: 0
+});
+const runSort = (options) => {
+	resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, ({ path: configPath, source }) => {
+		const sourceMsg = formatConfigSource(configPath, source);
+		if (sourceMsg) console.error(sourceMsg);
+		const raw = readFileSync(configPath, "utf-8");
+		const sorted = sortConfigToml(raw);
+		const counts = countSections(sorted);
+		if (sorted === raw) {
+			console.log(`${GREEN}✓${RESET} ${BOLD}Already sorted${RESET} — ${counts.env} env, ${counts.secret} secret`);
+			return;
+		}
+		if (options.dryRun) {
+			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+			console.log(sorted);
+			return;
+		}
+		writeIfValid(configPath, sorted, `${GREEN}✓${RESET} Sorted ${BOLD}${counts.env}${RESET} env and ${BOLD}${counts.secret}${RESET} secret entries in ${CYAN}${configPath}${RESET}`);
+	});
+};
+//#endregion
 //#region src/cli/commands/upgrade.ts
 const getCurrentVersion = () => Try(() => execFileSync("npm", [
 	"list",
@@ -4438,7 +4624,7 @@ program.command("init").description("Initialize a new envpkt.toml in the current
 program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates identity.recipient if found)").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/<project>-key.txt)").option("--global", "Write key to the shared default path (~/.envpkt/age-key.txt) instead of a project-specific one").action((options) => {
 	runKeygen(options);
 });
-program.command("audit").description("Audit credential health from envpkt.toml (use --strict in CI pipelines to gate deploys)").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json | minimal", "table").option("--expiring <days>", "Show secrets expiring within N days", parseInt).option("--status <status>", "Filter by status: healthy | expiring_soon | expired | stale | missing").option("--strict", "Exit non-zero on any non-healthy secret").option("--all", "Show both secrets and env defaults").option("--env-only", "Show only env defaults (drift detection)").option("--sealed", "Show only secrets with encrypted_value").option("--external", "Show only secrets without encrypted_value").action((options) => {
+program.command("audit").description("Audit credential health from envpkt.toml (use --strict in CI pipelines to gate deploys)").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json | minimal", "table").option("--expiring <days>", "Show secrets expiring within N days", parseInt).option("--status <status>", "Filter by status: healthy | expiring_soon | expired | stale | missing").option("--strict", "Exit non-zero on any non-healthy secret").option("--all", "Show both secrets and env defaults").option("--env-only", "Show only env defaults (drift detection)").option("--sealed", "Show only secrets with encrypted_value").option("--external", "Show only secrets without encrypted_value").option("--sort", "Sort secrets alphabetically within each status bucket (no file mutation)").action((options) => {
 	runAudit(options);
 });
 program.command("fleet").description("Scan directory tree for envpkt.toml files and aggregate health (use in CI for fleet-wide monitoring)").option("-d, --dir <path>", "Root directory to scan", ".").option("--depth <n>", "Max directory depth", parseInt).option("--format <format>", "Output format: table | json", "table").option("--status <status>", "Filter agents by health status").action((options) => {
@@ -4447,7 +4633,7 @@ program.command("fleet").description("Scan directory tree for envpkt.toml files
 program.command("validate").description("Verify envpkt.toml integrity — runs TOML syntax, schema, catalog, alias, and sealed-block structural checks").option("-c, --config <path>", "Path to envpkt.toml").option("--json", "Output structured JSON instead of human-readable text").action((options) => {
 	runValidate(options);
 });
-program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").action((options) => {
+program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").option("--sort", "Display secrets and env entries in alphabetical order (no file mutation)").action((options) => {
 	runInspect(options);
 });
 program.command("exec").description("Run pre-flight audit then execute a command with injected secrets (sealed → fnox → env cascade)").argument("<command...>", "Command to execute").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit (alias: --no-check)").option("--no-check", "Skip the pre-flight audit").option("--warn-only", "Warn on critical audit but do not abort").option("--strict", "Abort on any non-healthy secret").action((args, options) => {
@@ -4464,6 +4650,9 @@ program.command("mcp").description("Start the envpkt MCP server (stdio transport
 });
 registerSecretCommands(program);
 registerEnvCommands(program);
+program.command("sort").description("Group [env.*] and [secret.*] sections and alphabetize within each region").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((options) => {
+	runSort(options);
+});
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });

package/package.json

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