emdash 0.7.0 → 0.9.0

package/src/bylines/index.ts

@@ -12,7 +12,6 @@ import { BylineRepository } from "../database/repositories/byline.js";
 import type { BylineSummary, ContentBylineCredit } from "../database/repositories/types.js";
 import { validateIdentifier } from "../database/validate.js";
 import { getDb } from "../loader.js";
-import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { isMissingTableError } from "../utils/db-errors.js";
 
 /**
@@ -73,15 +72,11 @@ export async function getBylineBySlug(slug: string): Promise<BylineSummary | nul
  * but the entry has an `authorId`, falls back to the user-linked byline
  * (marked as source: "inferred").
  *
- * @example
- * ```ts
- * import { getEntryBylines } from "emdash";
- *
- * const bylines = await getEntryBylines("posts", post.data.id);
- * for (const credit of bylines) {
- *   console.log(credit.byline.displayName, credit.roleLabel);
- * }
- * ```
+ * Internal: not re-exported from the `emdash` package entry point. Every
+ * entry returned by `getEmDashCollection` / `getEmDashEntry` already has
+ * `data.bylines` populated by `hydrateEntryBylines` (which uses the batch
+ * helper `getBylinesForEntries` directly). Site code should read those
+ * fields rather than calling this function.
  */
 export async function getEntryBylines(
 	collection: string,
@@ -108,55 +103,55 @@ export async function getEntryBylines(
 	return [];
 }
 
+/**
+ * An entry reference for batch byline lookups.
+ *
+ * `authorId` is read directly from the row when computing the inferred-byline
+ * fallback — passing it in avoids a redundant `SELECT id, author_id` against
+ * the content table after every list/entry fetch.
+ */
+export interface BylineEntry {
+	id: string;
+	authorId: string | null;
+}
+
 /**
  * Batch-fetch byline credits for multiple content entries in a single query.
  *
- * This is more efficient than calling getEntryBylines for each entry
- * when you need bylines for a list of entries (e.g., a blog index page).
+ * Internal: consumed by `hydrateEntryBylines` in `query.ts` so that every
+ * entry returned from `getEmDashCollection` / `getEmDashEntry` already has
+ * `data.bylines` populated. Site code should rely on that eager hydration
+ * rather than calling this directly -- this function is not re-exported
+ * from the `emdash` package entry point.
  *
  * @param collection - The collection slug (e.g., "posts")
- * @param entryIds - Array of entry IDs
+ * @param entries - Entry id + authorId pairs (authorId is already on the row)
  * @returns Map from entry ID to array of byline credits
- *
- * @example
- * ```ts
- * import { getBylinesForEntries, getEmDashCollection } from "emdash";
- *
- * const { entries } = await getEmDashCollection("posts");
- * const ids = entries.map(e => e.data.id);
- * const bylinesMap = await getBylinesForEntries("posts", ids);
- *
- * for (const entry of entries) {
- *   const bylines = bylinesMap.get(entry.data.id) ?? [];
- *   // render bylines
- * }
- * ```
  */
 export async function getBylinesForEntries(
 	collection: string,
-	entryIds: string[],
+	entries: BylineEntry[],
 ): Promise<Map<string, ContentBylineCredit[]>> {
 	validateIdentifier(collection, "collection");
 	const result = new Map<string, ContentBylineCredit[]>();
 
-	// Initialize all entry IDs with empty arrays
-	for (const id of entryIds) {
+	for (const { id } of entries) {
 		result.set(id, []);
 	}
 
-	if (entryIds.length === 0) {
+	if (entries.length === 0) {
 		return result;
 	}
 
 	const db = await getDb();
 	const repo = new BylineRepository(db);
+	const entryIds = entries.map((e) => e.id);
 
-	// 1. Batch fetch all explicit byline credits. Sites with no bylines
-	// get an empty map back for one query — the previous "has any bylines"
-	// probe traded an extra round-trip on every request to save that one
-	// query on empty sites, which is exactly backwards for the common case.
-	// Pre-migration databases (bylines table missing) fall through to the
-	// `isMissingTableError` catch below and return empty results.
+	// Sites with no bylines get an empty map back for one query — the previous
+	// "has any bylines" probe traded an extra round-trip on every request to
+	// save that one query on empty sites, which is exactly backwards for the
+	// common case. Pre-migration databases (bylines table missing) fall
+	// through to the `isMissingTableError` catch below and return empty.
 	let bylinesMap;
 	try {
 		bylinesMap = await repo.getContentBylinesMany(collection, entryIds);
@@ -165,32 +160,17 @@ export async function getBylinesForEntries(
 		throw error;
 	}
 
-	// 2. Collect entry IDs that need fallback lookup
-	const fallbackEntryIds: string[] = [];
-	const needsFallback: Map<string, string> = new Map(); // entryId -> authorId
-
-	for (const id of entryIds) {
-		if (!bylinesMap.has(id)) {
-			// Need to check author_id for this entry — but we only have the IDs,
-			// so batch-fetch them from the content table
-			fallbackEntryIds.push(id);
+	const needsFallback = new Map<string, string>();
+	for (const { id, authorId } of entries) {
+		if (!bylinesMap.has(id) && authorId) {
+			needsFallback.set(id, authorId);
 		}
 	}
 
-	// Batch-fetch author_ids for entries that need fallback
-	if (fallbackEntryIds.length > 0) {
-		const authorMap = await getAuthorIds(db, collection, fallbackEntryIds);
-		for (const [entryId, authorId] of authorMap) {
-			needsFallback.set(entryId, authorId);
-		}
-	}
-
-	// 3. Batch fetch user-linked bylines for fallback
 	const uniqueAuthorIds = [...new Set(needsFallback.values())];
 	const authorBylineMap = await repo.findByUserIds(uniqueAuthorIds);
 
-	// 4. Assign results
-	for (const id of entryIds) {
+	for (const { id } of entries) {
 		const explicit = bylinesMap.get(id);
 		if (explicit && explicit.length > 0) {
 			result.set(
@@ -205,11 +185,8 @@ export async function getBylinesForEntries(
 			const fallback = authorBylineMap.get(authorId);
 			if (fallback) {
 				result.set(id, [{ byline: fallback, sortOrder: 0, roleLabel: null, source: "inferred" }]);
-				continue;
 			}
 		}
-
-		// Already initialized with empty array
 	}
 
 	return result;
@@ -235,31 +212,3 @@ async function getAuthorId(
 
 	return result.rows[0]?.author_id ?? null;
 }
-
-/**
- * Batch-fetch author_ids for multiple content entries.
- * Returns Map<entryId, authorId> (only entries with non-null author_id).
- */
-async function getAuthorIds(
-	db: Awaited<ReturnType<typeof getDb>>,
-	collection: string,
-	entryIds: string[],
-): Promise<Map<string, string>> {
-	validateIdentifier(collection, "collection");
-	const tableName = `ec_${collection}`;
-
-	const map = new Map<string, string>();
-	for (const chunk of chunks(entryIds, SQL_BATCH_SIZE)) {
-		const result = await sql<{ id: string; author_id: string | null }>`
-			SELECT id, author_id FROM ${sql.ref(tableName)}
-			WHERE id IN (${sql.join(chunk.map((id) => sql`${id}`))})
-		`.execute(db);
-
-		for (const row of result.rows) {
-			if (row.author_id) {
-				map.set(row.id, row.author_id);
-			}
-		}
-	}
-	return map;
-}

package/src/cli/commands/auth.ts

@@ -1,5 +1,22 @@
 /**
- * Auth CLI commands
+ * Auth CLI commands (deprecated)
+ *
+ * Kept as a deprecated alias for backwards compatibility. The original
+ * `emdash auth secret` was documented in published docs and is plausibly
+ * scripted in user CI (e.g. `npx emdash auth secret >> .env`). Removing
+ * it outright would break those scripts on minor-version upgrade.
+ *
+ * The command still emits an `EMDASH_AUTH_SECRET=<32-byte-base64url>`
+ * line, unchanged. `EMDASH_AUTH_SECRET` itself is now legacy: it's only
+ * read as a fallback source for the commenter-IP hash salt so installs
+ * upgrading from a prior version keep stable IP hashes (and therefore
+ * stable rate-limit buckets). New installs don't need to set it.
+ *
+ * The deprecation note steers users toward `emdash secrets generate`
+ * (which emits a different, versioned `emdash_enc_v1_*` value for
+ * `EMDASH_ENCRYPTION_KEY` — used to encrypt plugin secrets at rest).
+ *
+ * Will be removed in a future minor.
  */
 
 import { defineCommand } from "citty";
@@ -8,9 +25,6 @@ import pc from "picocolors";
 
 import { encodeBase64url } from "../../utils/base64.js";
 
-/**
- * Generate a cryptographically secure auth secret
- */
 function generateAuthSecret(): string {
 	const bytes = new Uint8Array(32);
 	crypto.getRandomValues(bytes);
@@ -20,11 +34,13 @@ function generateAuthSecret(): string {
 const secretCommand = defineCommand({
 	meta: {
 		name: "secret",
-		description: "Generate a secure auth secret",
+		description: "[DEPRECATED] Generate a value for legacy EMDASH_AUTH_SECRET",
 	},
 	run() {
 		const secret = generateAuthSecret();
 
+		// Match the original behavior verbatim: pretty-printed name=value
+		// on stdout (most scripts piped this to a file expecting that shape).
 		consola.log("");
 		consola.log(pc.bold("Generated auth secret:"));
 		consola.log("");
@@ -32,13 +48,19 @@ const secretCommand = defineCommand({
 		consola.log("");
 		consola.log(pc.dim("Add this to your environment variables."));
 		consola.log("");
+		// Deprecation note on stderr so it doesn't break stdout consumers.
+		process.stderr.write(
+			`${pc.yellow("Note:")} ${pc.bold("emdash auth secret")} is deprecated and will be removed in a future minor. ` +
+				`${pc.cyan("EMDASH_AUTH_SECRET")} itself is now optional — it's only used as a legacy fallback for the commenter-IP hash salt. ` +
+				`For encrypting plugin secrets at rest, use ${pc.bold("emdash secrets generate")} (a different secret: ${pc.cyan("EMDASH_ENCRYPTION_KEY")}).\n`,
+		);
 	},
 });
 
 export const authCommand = defineCommand({
 	meta: {
 		name: "auth",
-		description: "Authentication utilities",
+		description: "[DEPRECATED] Authentication utilities (use `emdash secrets` for new flows)",
 	},
 	subCommands: {
 		secret: secretCommand,

package/src/cli/commands/bundle-utils.ts

@@ -30,8 +30,17 @@ export const ICON_SIZE = 256;
 
 // ── Regex patterns (module-scope to avoid re-compilation) ────────────────────
 
-/** Matches require("node:xxx") / require("xxx") / import("node:xxx") in bundled output */
-const NODE_BUILTIN_IMPORT_RE = /(?:import|require)\s*\(?["'](?:node:)?([a-z_]+)["']\)?/g;
+/**
+ * Matches Node.js built-in imports in bundled output:
+ * - require("node:xxx") / require("xxx")
+ * - import("node:xxx") / import("xxx")
+ * - import X from "node:xxx" / import { X } from "node:xxx"
+ * - import * as X from "node:xxx"
+ * - export { X } from "node:xxx"
+ * Captures the base module name (e.g. "fs" from "node:fs/promises").
+ */
+const NODE_BUILTIN_IMPORT_RE =
+	/(?:import|export|require)\s*(?:\(|[^(]*?\bfrom\s+)["'](?:node:)?([a-z_]+)(?:\/[^"']*)?\s*["']\)?/g;
 const LEADING_DOT_SLASH_RE = /^\.\//;
 const DIST_PREFIX_RE = /^dist\//;
 const MJS_EXT_RE = /\.m?js$/;

package/src/cli/commands/bundle.ts

@@ -20,6 +20,7 @@ import { resolve, join, extname, basename } from "node:path";
 import { defineCommand } from "citty";
 import consola from "consola";
 
+import { CAPABILITY_RENAMES, isDeprecatedCapability } from "../../plugins/types.js";
 import type { ResolvedPlugin } from "../../plugins/types.js";
 import {
 	fileExists,
@@ -38,7 +39,7 @@ import {
 	ICON_SIZE,
 } from "./bundle-utils.js";
 
-const TS_EXT_RE = /\.tsx?$/;
+const TS_EXT_RE = /\.(tsx?|[mc]?js)$/;
 const SLASH_RE = /\//g;
 const LEADING_AT_RE = /^@/;
 const emdash_SCOPE_RE = /^@emdash-cms\//;
@@ -163,6 +164,8 @@ export const bundleCommand = defineCommand({
 		const tmpDir = join(pluginDir, ".emdash-bundle-tmp");
 
 		try {
+			// Clean up any stale temp directory from a previous failed run
+			await rm(tmpDir, { recursive: true, force: true });
 			await mkdir(tmpDir, { recursive: true });
 
 			// Build main entry to extract manifest.
@@ -522,20 +525,39 @@ export const bundleCommand = defineCommand({
 				}
 			}
 
-			// Check capabilities warnings
-			if (manifest.capabilities.includes("network:fetch:any")) {
+			// Check capabilities warnings — use canonical names. Deprecated
+			// names are accepted (and warned about separately below) so we
+			// also check the legacy aliases here for the duration of the
+			// deprecation window.
+			const declaresUnrestricted =
+				manifest.capabilities.includes("network:request:unrestricted") ||
+				manifest.capabilities.includes("network:fetch:any");
+			const declaresHostRestricted =
+				manifest.capabilities.includes("network:request") ||
+				manifest.capabilities.includes("network:fetch");
+			if (declaresUnrestricted) {
 				consola.warn(
-					"Plugin declares unrestricted network access (network:fetch:any) — it can make requests to any host",
+					"Plugin declares unrestricted network access (network:request:unrestricted) — it can make requests to any host",
 				);
-			} else if (
-				manifest.capabilities.includes("network:fetch") &&
-				manifest.allowedHosts.length === 0
-			) {
+			} else if (declaresHostRestricted && manifest.allowedHosts.length === 0) {
 				consola.warn(
-					"Plugin declares network:fetch capability but no allowedHosts — all fetch requests will be blocked",
+					"Plugin declares network:request capability but no allowedHosts — all requests will be blocked",
 				);
 			}
 
+			// Warn for each deprecated capability used. The warning points
+			// to the new name so the fix is mechanical. We continue (not
+			// error) here — the hard fail lives in `publish` so authors
+			// can still build and test locally.
+			const deprecatedCaps = manifest.capabilities.filter(isDeprecatedCapability);
+			if (deprecatedCaps.length > 0) {
+				consola.warn("Plugin uses deprecated capability names. Rename them before publishing:");
+				for (const cap of deprecatedCaps) {
+					const replacement = CAPABILITY_RENAMES[cap];
+					consola.warn(`  ${cap} → ${replacement}`);
+				}
+			}
+
 			// Check for features that won't work in sandboxed mode
 			if (
 				resolvedPlugin.admin?.portableTextBlocks &&

package/src/cli/commands/content.ts

@@ -9,6 +9,7 @@ import { readFile } from "node:fs/promises";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 
+import { convertDataForRead } from "../../client/portable-text.js";
 import { connectionArgs, createClientFromArgs } from "../client-factory.js";
 import { configureOutputMode, output } from "../output.js";
 
@@ -144,6 +145,13 @@ const getCommand = defineCommand({
 				const comparison = await client.compare(args.collection, args.id);
 				if (comparison.hasChanges && comparison.draft) {
 					item.data = comparison.draft;
+					// The comparison endpoint returns raw PT data. Apply the same
+					// PT-to-markdown conversion that `client.get` does, unless --raw.
+					if (!args.raw && item.data) {
+						const col = await client.collection(args.collection);
+						const fields = col.fields.map((f) => ({ slug: f.slug, type: f.type }));
+						item.data = convertDataForRead(item.data, fields, false);
+					}
 				}
 			}
 
@@ -278,6 +286,7 @@ const deleteCommand = defineCommand({
 		try {
 			const client = createClientFromArgs(args);
 			await client.delete(args.collection, args.id);
+			output({ success: true }, args);
 			consola.success(`Deleted ${args.collection}/${args.id}`);
 		} catch (error) {
 			consola.error(error instanceof Error ? error.message : "Unknown error");
@@ -306,6 +315,7 @@ const publishCommand = defineCommand({
 		try {
 			const client = createClientFromArgs(args);
 			await client.publish(args.collection, args.id);
+			output({ success: true }, args);
 			consola.success(`Published ${args.collection}/${args.id}`);
 		} catch (error) {
 			consola.error(error instanceof Error ? error.message : "Unknown error");
@@ -334,6 +344,7 @@ const unpublishCommand = defineCommand({
 		try {
 			const client = createClientFromArgs(args);
 			await client.unpublish(args.collection, args.id);
+			output({ success: true }, args);
 			consola.success(`Unpublished ${args.collection}/${args.id}`);
 		} catch (error) {
 			consola.error(error instanceof Error ? error.message : "Unknown error");
@@ -367,6 +378,7 @@ const scheduleCommand = defineCommand({
 		try {
 			const client = createClientFromArgs(args);
 			await client.schedule(args.collection, args.id, { at: args.at });
+			output({ success: true }, args);
 			consola.success(`Scheduled ${args.collection}/${args.id} for ${args.at}`);
 		} catch (error) {
 			consola.error(error instanceof Error ? error.message : "Unknown error");
@@ -395,6 +407,7 @@ const restoreCommand = defineCommand({
 		try {
 			const client = createClientFromArgs(args);
 			await client.restore(args.collection, args.id);
+			output({ success: true }, args);
 			consola.success(`Restored ${args.collection}/${args.id}`);
 		} catch (error) {
 			consola.error(error instanceof Error ? error.message : "Unknown error");

package/src/cli/commands/login.ts

@@ -459,7 +459,14 @@ export const whoamiCommand = defineCommand({
 							},
 						);
 						if (refreshRes.ok) {
-							const refreshed = (await refreshRes.json()) as TokenResponse;
+							const json = (await refreshRes.json()) as Record<string, unknown>;
+							// Token endpoint wraps response in { data: ... } via apiSuccess.
+							// Handle both wrapped and bare shapes for robustness.
+							const refreshed = (
+								json.data && typeof json.data === "object" && "access_token" in json.data
+									? json.data
+									: json
+							) as TokenResponse;
 							token = refreshed.access_token;
 							saveCredentials(baseUrl, {
 								...cred,

package/src/cli/commands/publish.ts

@@ -21,6 +21,7 @@ import { createGzipDecoder, unpackTar } from "modern-tar";
 import pc from "picocolors";
 
 import { pluginManifestSchema } from "../../plugins/manifest-schema.js";
+import { CAPABILITY_RENAMES, isDeprecatedCapability } from "../../plugins/types.js";
 import {
 	getMarketplaceCredential,
 	saveMarketplaceCredential,
@@ -440,6 +441,29 @@ export const publishCommand = defineCommand({
 		}
 		console.log();
 
+		// ── Step 2.5: Hard-fail on deprecated capability names ──
+		//
+		// Refusing to publish manifests that use deprecated capability names
+		// keeps the marketplace clean while the deprecation window is open.
+		// The fix is mechanical and entirely in the author's hands — they
+		// rename, re-bundle, and republish. Better to refuse 5 publishes
+		// than ship 500 deprecated manifests. We check before authentication
+		// so authors don't burn a device-flow login on a doomed publish.
+		const deprecatedCaps = manifest.capabilities.filter(isDeprecatedCapability);
+		if (deprecatedCaps.length > 0) {
+			consola.error(
+				"Plugin declares deprecated capability names. Rename them and re-bundle before publishing:",
+			);
+			for (const cap of deprecatedCaps) {
+				const replacement = CAPABILITY_RENAMES[cap];
+				consola.error(`  ${cap} → ${replacement}`);
+			}
+			consola.error(
+				"See https://emdashcms.com/docs/plugins/overview#capabilities for the full rename table.",
+			);
+			process.exit(1);
+		}
+
 		// ── Step 3: Authenticate ──
 		//
 		// Priority: EMDASH_MARKETPLACE_TOKEN env var > stored credential > interactive device flow.

package/src/cli/commands/secrets.ts

@@ -0,0 +1,183 @@
+/**
+ * Secrets CLI commands
+ *
+ * Pure (no-DB) commands for working with EmDash secrets:
+ *
+ * - `emdash secrets generate` — emits a fresh `EMDASH_ENCRYPTION_KEY`.
+ *   Optionally writes it to `.dev.vars` (Workers) or `.env` (Node).
+ * - `emdash secrets fingerprint <key>` — prints the kid for a key,
+ *   useful in CI for verifying what's been deployed without exposing
+ *   the raw value.
+ *
+ * DB-touching commands (`status`, `migrate`, `rotate`) live elsewhere:
+ * the CLI process can't open the production D1/Postgres binding from
+ * the operator's machine, so those operations ship as admin HTTP
+ * endpoints in a later PR. A thin `--site <url>` wrapper for those
+ * endpoints can land alongside.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { defineCommand } from "citty";
+import { consola } from "consola";
+import pc from "picocolors";
+
+import { EmDashSecretsError, fingerprintKey, generateEncryptionKey } from "../../config/secrets.js";
+
+const KEY_VAR_NAME = "EMDASH_ENCRYPTION_KEY";
+/** Matches a populated entry — `KEY=<at least one char>`. */
+const POPULATED_KEY_LINE_PATTERN = /^EMDASH_ENCRYPTION_KEY=.+$/m;
+/**
+ * Matches any line starting `KEY=` including `KEY=` with empty value.
+ * Used for in-place replacement when the entry exists but has no value.
+ */
+const ANY_KEY_LINE_PATTERN = /^EMDASH_ENCRYPTION_KEY=.*$/m;
+
+/**
+ * Append (or replace) `EMDASH_ENCRYPTION_KEY` in a dotenv-style file.
+ *
+ * Idempotent: if the entry exists with a populated value, leaves it alone
+ * (returns `"skipped"`) unless `force` is set. An entry with an empty
+ * value (`EMDASH_ENCRYPTION_KEY=`) is treated as "not set" and gets
+ * replaced — placeholder lines aren't a reason to refuse.
+ *
+ * Always ends the resulting file with a trailing newline. Doesn't touch
+ * other variables.
+ *
+ * Exported for tests.
+ */
+export function writeEncryptionKeyToFile(
+	targetPath: string,
+	value: string,
+	force: boolean,
+): "wrote" | "skipped" {
+	const exists = existsSync(targetPath);
+	const existing = exists ? readFileSync(targetPath, "utf-8") : "";
+
+	const hasPopulatedKey = POPULATED_KEY_LINE_PATTERN.test(existing);
+	if (hasPopulatedKey && !force) {
+		return "skipped";
+	}
+
+	const newLine = `${KEY_VAR_NAME}=${value}`;
+	let next: string;
+	if (ANY_KEY_LINE_PATTERN.test(existing)) {
+		// In-place replace handles both populated-and-forced and empty-value
+		// cases. Then ensure trailing newline.
+		next = existing.replace(ANY_KEY_LINE_PATTERN, newLine);
+		if (!next.endsWith("\n")) next += "\n";
+	} else {
+		// Append. Insert a separating newline only if the file has content
+		// not already ending in one.
+		const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "" : "\n";
+		next = `${existing}${sep}${newLine}\n`;
+	}
+
+	writeFileSync(targetPath, next);
+	return "wrote";
+}
+
+const generateCommand = defineCommand({
+	meta: {
+		name: "generate",
+		description: "Generate a new EmDash encryption key",
+	},
+	args: {
+		write: {
+			type: "string",
+			description:
+				"Optional path to write the key to (e.g. .dev.vars or .env). " +
+				"Won't overwrite an existing entry without --force.",
+		},
+		force: {
+			type: "boolean",
+			description: "When used with --write, overwrite an existing entry",
+			default: false,
+		},
+	},
+	run({ args }) {
+		const value = generateEncryptionKey();
+
+		if (args.write) {
+			const targetPath = resolve(process.cwd(), args.write);
+			const result = writeEncryptionKeyToFile(targetPath, value, args.force);
+			if (result === "skipped") {
+				// Idempotent no-op: entry already populated. Exit 0 so chained
+				// scripts (`emdash secrets generate --write && pnpm dev`) don't
+				// break. Pass --force to replace, with full awareness that
+				// existing encrypted secrets become unreadable.
+				consola.info(
+					`${KEY_VAR_NAME} already set in ${pc.cyan(args.write)}; leaving it alone. ` +
+						`Pass ${pc.bold("--force")} to replace it.`,
+				);
+				return;
+			}
+			consola.log("");
+			consola.log(`${pc.bold("Wrote")} ${pc.cyan(KEY_VAR_NAME)} to ${pc.cyan(args.write)}`);
+			consola.log("");
+			consola.log(
+				pc.yellow(
+					"Keep this file out of version control. Losing the key means losing every secret encrypted with it.",
+				),
+			);
+			consola.log("");
+			return;
+		}
+
+		// Print the key to stdout (one line, no decoration) so it can be
+		// piped into env files or secret-management tools without scraping.
+		// Explanatory text goes to stderr so it doesn't pollute the pipe.
+		process.stdout.write(`${value}\n`);
+		const guidance = [
+			"",
+			pc.bold("EmDash encryption key generated."),
+			"",
+			`Set ${pc.cyan(KEY_VAR_NAME)} in your environment.`,
+			"For Cloudflare deployments, push it to your Worker's secrets.",
+			"For Node deployments, add it to your process environment or .env file.",
+			"",
+			pc.yellow("Keep this value secret. Losing it means losing every secret encrypted with it."),
+			"",
+		].join("\n");
+		process.stderr.write(`${guidance}\n`);
+	},
+});
+
+const fingerprintCommand = defineCommand({
+	meta: {
+		name: "fingerprint",
+		description: "Print the kid (8-char fingerprint) for an encryption key",
+	},
+	args: {
+		key: {
+			type: "positional",
+			description: "The full key value (with the emdash_enc_v1_ prefix)",
+			required: true,
+		},
+	},
+	async run({ args }) {
+		try {
+			const kid = await fingerprintKey(args.key);
+			// Newline-only on stdout so it pipes cleanly into env/CI logs
+			// without leaking the raw key.
+			process.stdout.write(`${kid}\n`);
+		} catch (error) {
+			consola.error(
+				error instanceof EmDashSecretsError ? error.message : "Failed to fingerprint key",
+			);
+			process.exit(1);
+		}
+	},
+});
+
+export const secretsCommand = defineCommand({
+	meta: {
+		name: "secrets",
+		description: "Manage EmDash secrets (generate, inspect)",
+	},
+	subCommands: {
+		generate: generateCommand,
+		fingerprint: fingerprintCommand,
+	},
+});

package/src/cli/credentials.ts

@@ -130,7 +130,7 @@ function readStore(): CredentialStore {
 
 function writeStore(store: CredentialStore): void {
 	const dir = getConfigDir();
-	mkdirSync(dir, { recursive: true });
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
 
 	const path = getCredentialPath();
 	writeFileSync(path, JSON.stringify(store, null, "\t"), {