emdash 0.8.0 → 0.10.0

package/src/cli/commands/plugin-init.ts

@@ -1,13 +1,15 @@
 /**
  * emdash plugin init
  *
- * Scaffold a new EmDash plugin. Generates the standard-format boilerplate:
+ * Scaffold a new EmDash plugin. Generates the sandboxed-format boilerplate:
  *   src/index.ts         -- descriptor factory
  *   src/sandbox-entry.ts -- definePlugin({ hooks, routes })
  *   package.json
  *   tsconfig.json
  *
- * Use --native to generate native-format boilerplate instead (createPlugin + React admin).
+ * Use --format=native (or --native) to generate native-format boilerplate
+ * instead (createPlugin + React admin). When neither is passed and stdout
+ * is a TTY, the user is prompted to choose.
  *
  */
 
@@ -22,6 +24,8 @@ import { fileExists } from "./bundle-utils.js";
 const SLUG_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const SCOPE_RE = /^@[^/]+\//;
 
+type PluginFormat = "standard" | "native";
+
 export const pluginInitCommand = defineCommand({
 	meta: {
 		name: "init",
@@ -37,15 +41,27 @@ export const pluginInitCommand = defineCommand({
 			type: "string",
 			description: "Plugin name/id (e.g. my-plugin or @org/my-plugin)",
 		},
+		format: {
+			type: "string",
+			description:
+				"Plugin format: sandboxed or native. Prompts when running interactively if not set.",
+			valueHint: "sandboxed|native",
+		},
 		native: {
 			type: "boolean",
-			description: "Generate native-format plugin (createPlugin + React admin)",
+			description: "Shortcut for --format=native",
 			default: false,
 		},
 	},
 	async run({ args }) {
 		const targetDir = resolve(args.dir);
-		const isNative = args.native;
+
+		const format = await resolveFormat(args.format, args.native);
+		if (!format) {
+			consola.info("Cancelled");
+			return;
+		}
+		const isNative = format === "native";
 
 		// Derive plugin name from --name or directory name
 		let pluginName = args.name || basename(targetDir);
@@ -71,7 +87,7 @@ export const pluginInitCommand = defineCommand({
 			process.exit(1);
 		}
 
-		consola.start(`Scaffolding ${isNative ? "native" : "standard"} plugin: ${pluginName}`);
+		consola.start(`Scaffolding ${isNative ? "native" : "sandboxed"} plugin: ${pluginName}`);
 
 		await mkdir(srcDir, { recursive: true });
 
@@ -83,22 +99,99 @@ export const pluginInitCommand = defineCommand({
 
 		consola.success(`Plugin scaffolded in ${targetDir}`);
 		consola.info("Next steps:");
-		if (args.dir !== ".") {
-			consola.info(`  1. cd ${args.dir}`);
-		}
-		consola.info(`  ${args.dir !== "." ? "2" : "1"}. pnpm install`);
-		if (isNative) {
-			consola.info(`  ${args.dir !== "." ? "3" : "2"}. Edit src/index.ts to add hooks and routes`);
+		const steps: string[] = [];
+		if (args.dir !== ".") steps.push(`cd ${args.dir}`);
+		steps.push("pnpm install");
+		steps.push(
+			isNative
+				? "Edit src/index.ts to add hooks and routes"
+				: "Edit src/sandbox-entry.ts to add hooks and routes",
+		);
+		steps.push("pnpm build");
+		if (!isNative) steps.push("emdash plugin validate --dir .");
+		steps.forEach((step, i) => consola.info(`  ${i + 1}. ${step}`));
+	},
+});
+
+async function resolveFormat(
+	formatArg: string | undefined,
+	nativeFlag: boolean,
+): Promise<PluginFormat | null> {
+	if (formatArg) {
+		const normalized = formatArg.toLowerCase();
+		let parsed: PluginFormat;
+		if (normalized === "native") {
+			parsed = "native";
+		} else if (normalized === "sandboxed" || normalized === "standard") {
+			parsed = "standard";
 		} else {
-			consola.info(
-				`  ${args.dir !== "." ? "3" : "2"}. Edit src/sandbox-entry.ts to add hooks and routes`,
-			);
+			consola.error(`Invalid --format "${formatArg}". Use "sandboxed" or "native".`);
+			process.exit(1);
+		}
+		if (nativeFlag && parsed !== "native") {
+			consola.error(`Conflicting flags: --native and --format=${formatArg}. Pass only one.`);
+			process.exit(1);
 		}
-		consola.info(`  ${args.dir !== "." ? "4" : "3"}. emdash plugin validate --dir .`);
+		return parsed;
+	}
+	if (nativeFlag) return "native";
+
+	if (!process.stdout.isTTY) return "standard";
+
+	const choice = await consola.prompt("Which plugin format?", {
+		type: "select",
+		initial: "standard",
+		options: [
+			{
+				label: "Sandboxed",
+				value: "standard",
+				hint: "runs in an isolated sandbox; safe to install from the marketplace",
+			},
+			{
+				label: "Native",
+				value: "native",
+				hint: "full runtime access; install from npm",
+			},
+		],
+		cancel: "null",
+	});
+	if (choice === null) return null;
+	return choice as PluginFormat;
+}
+
+function camelCase(slug: string): string {
+	return slug
+		.split("-")
+		.map((s, i) => (i === 0 ? s : s[0].toUpperCase() + s.slice(1)))
+		.join("");
+}
+
+function pascalCase(slug: string): string {
+	return slug
+		.split("-")
+		.map((s) => s[0].toUpperCase() + s.slice(1))
+		.join("");
+}
+
+const TSCONFIG = {
+	compilerOptions: {
+		target: "ES2022",
+		module: "preserve",
+		moduleResolution: "bundler",
+		strict: true,
+		esModuleInterop: true,
+		declaration: true,
+		outDir: "./dist",
+		rootDir: "./src",
 	},
-});
+	include: ["src/**/*"],
+	exclude: ["node_modules", "dist"],
+} as const;
+
+const TSDOWN_VERSION = "^0.20.0";
+const TYPESCRIPT_VERSION = "^5.9.0";
 
-// ── Standard format scaffolding ──────────────────────────────────
+// ── Sandboxed format scaffolding ─────────────────────────────────
 
 async function scaffoldStandard(
 	targetDir: string,
@@ -106,13 +199,8 @@ async function scaffoldStandard(
 	pluginName: string,
 	slug: string,
 ): Promise<void> {
-	// Derive the camelCase function name from slug
-	const fnName = slug
-		.split("-")
-		.map((s, i) => (i === 0 ? s : s[0].toUpperCase() + s.slice(1)))
-		.join("");
+	const fnName = camelCase(slug);
 
-	// package.json
 	await writeFile(
 		join(targetDir, "package.json"),
 		JSON.stringify(
@@ -120,74 +208,98 @@ async function scaffoldStandard(
 				name: pluginName,
 				version: "0.1.0",
 				type: "module",
+				main: "./dist/index.mjs",
 				exports: {
-					".": "./src/index.ts",
-					"./sandbox": "./src/sandbox-entry.ts",
+					".": {
+						types: "./dist/index.d.mts",
+						import: "./dist/index.mjs",
+					},
+					"./sandbox": {
+						types: "./dist/sandbox-entry.d.mts",
+						import: "./dist/sandbox-entry.mjs",
+					},
 				},
-				files: ["src"],
+				files: ["dist"],
+				scripts: {
+					build: "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean",
+					dev: "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --watch",
+					typecheck: "tsc --noEmit",
+				},
+				keywords: ["emdash", "emdash-plugin"],
+				license: "MIT",
 				peerDependencies: {
 					emdash: "*",
 				},
-			},
-			null,
-			"\t",
-		) + "\n",
-	);
-
-	// tsconfig.json
-	await writeFile(
-		join(targetDir, "tsconfig.json"),
-		JSON.stringify(
-			{
-				compilerOptions: {
-					target: "ES2022",
-					module: "preserve",
-					moduleResolution: "bundler",
-					strict: true,
-					esModuleInterop: true,
-					declaration: true,
-					outDir: "./dist",
-					rootDir: "./src",
+				devDependencies: {
+					emdash: "*",
+					tsdown: TSDOWN_VERSION,
+					typescript: TYPESCRIPT_VERSION,
 				},
-				include: ["src/**/*"],
-				exclude: ["node_modules", "dist"],
 			},
 			null,
 			"\t",
 		) + "\n",
 	);
 
-	// src/index.ts -- descriptor factory
+	await writeFile(join(targetDir, "tsconfig.json"), JSON.stringify(TSCONFIG, null, "\t") + "\n");
+
 	await writeFile(
 		join(srcDir, "index.ts"),
 		`import type { PluginDescriptor } from "emdash";
 
 export function ${fnName}Plugin(): PluginDescriptor {
 \treturn {
-\t\tid: "${pluginName}",
+\t\tid: "${slug}",
 \t\tversion: "0.1.0",
 \t\tformat: "standard",
 \t\tentrypoint: "${pluginName}/sandbox",
-\t\tcapabilities: [],
+
+\t\tcapabilities: ["content:read"],
+\t\tstorage: {
+\t\t\tevents: { indexes: ["timestamp"] },
+\t\t},
 \t};
 }
 `,
 	);
 
-	// src/sandbox-entry.ts -- plugin definition
 	await writeFile(
 		join(srcDir, "sandbox-entry.ts"),
 		`import { definePlugin } from "emdash";
 import type { PluginContext } from "emdash";
 
+interface ContentSaveEvent {
+\tcollection: string;
+\tcontent: { id: string };
+\tisNew: boolean;
+}
+
 export default definePlugin({
 \thooks: {
 \t\t"content:afterSave": {
-\t\t\thandler: async (event: any, ctx: PluginContext) => {
+\t\t\thandler: async (event: ContentSaveEvent, ctx: PluginContext) => {
 \t\t\t\tctx.log.info("Content saved", {
 \t\t\t\t\tcollection: event.collection,
 \t\t\t\t\tid: event.content.id,
 \t\t\t\t});
+
+\t\t\t\tawait ctx.storage.events.put(\`save-\${Date.now()}\`, {
+\t\t\t\t\ttimestamp: new Date().toISOString(),
+\t\t\t\t\tcollection: event.collection,
+\t\t\t\t\tcontentId: event.content.id,
+\t\t\t\t});
+\t\t\t},
+\t\t},
+\t},
+
+\troutes: {
+\t\trecent: {
+\t\t\thandler: async (_routeCtx, ctx: PluginContext) => {
+\t\t\t\tconst result = await ctx.storage.events.query({
+\t\t\t\t\torderBy: { timestamp: "desc" },
+\t\t\t\t\tlimit: 10,
+\t\t\t\t});
+\t\t\t\treturn { events: result.items };
 \t\t\t},
 \t\t},
 \t},
@@ -204,12 +316,9 @@ async function scaffoldNative(
 	pluginName: string,
 	slug: string,
 ): Promise<void> {
-	const fnName = slug
-		.split("-")
-		.map((s, i) => (i === 0 ? s : s[0].toUpperCase() + s.slice(1)))
-		.join("");
+	const fnName = camelCase(slug);
+	const typeName = pascalCase(slug);
 
-	// package.json
 	await writeFile(
 		join(targetDir, "package.json"),
 		JSON.stringify(
@@ -217,71 +326,88 @@ async function scaffoldNative(
 				name: pluginName,
 				version: "0.1.0",
 				type: "module",
+				main: "./dist/index.mjs",
 				exports: {
-					".": "./src/index.ts",
+					".": {
+						types: "./dist/index.d.mts",
+						import: "./dist/index.mjs",
+					},
+				},
+				files: ["dist"],
+				scripts: {
+					build: "tsdown src/index.ts --format esm --dts --clean",
+					dev: "tsdown src/index.ts --format esm --dts --watch",
+					typecheck: "tsc --noEmit",
 				},
-				files: ["src"],
+				keywords: ["emdash", "emdash-plugin"],
+				license: "MIT",
 				peerDependencies: {
 					emdash: "*",
 				},
-			},
-			null,
-			"\t",
-		) + "\n",
-	);
-
-	// tsconfig.json
-	await writeFile(
-		join(targetDir, "tsconfig.json"),
-		JSON.stringify(
-			{
-				compilerOptions: {
-					target: "ES2022",
-					module: "preserve",
-					moduleResolution: "bundler",
-					strict: true,
-					esModuleInterop: true,
-					declaration: true,
-					outDir: "./dist",
-					rootDir: "./src",
+				devDependencies: {
+					emdash: "*",
+					tsdown: TSDOWN_VERSION,
+					typescript: TYPESCRIPT_VERSION,
 				},
-				include: ["src/**/*"],
-				exclude: ["node_modules", "dist"],
 			},
 			null,
 			"\t",
 		) + "\n",
 	);
 
-	// src/index.ts -- descriptor + createPlugin
+	await writeFile(join(targetDir, "tsconfig.json"), JSON.stringify(TSCONFIG, null, "\t") + "\n");
+
 	await writeFile(
 		join(srcDir, "index.ts"),
 		`import { definePlugin } from "emdash";
 import type { PluginDescriptor } from "emdash";
 
-export function ${fnName}Plugin(): PluginDescriptor {
+export interface ${typeName}Options {
+\tenabled?: boolean;
+}
+
+export function ${fnName}Plugin(options: ${typeName}Options = {}): PluginDescriptor<${typeName}Options> {
 \treturn {
-\t\tid: "${pluginName}",
+\t\tid: "${slug}",
 \t\tversion: "0.1.0",
 \t\tformat: "native",
 \t\tentrypoint: "${pluginName}",
-\t\toptions: {},
+\t\toptions,
 \t};
 }
 
-export function createPlugin() {
+export function createPlugin(options: ${typeName}Options = {}) {
 \treturn definePlugin({
-\t\tid: "${pluginName}",
+\t\tid: "${slug}",
 \t\tversion: "0.1.0",
 
+\t\tcapabilities: ["content:read"],
+\t\tstorage: {
+\t\t\tevents: { indexes: ["createdAt"] },
+\t\t},
+
 \t\thooks: {
 \t\t\t"content:afterSave": async (event, ctx) => {
-\t\t\t\tctx.log.info("Content saved", {
+\t\t\t\tif (options.enabled === false) return;
+\t\t\t\tawait ctx.storage.events.put(\`evt_\${Date.now()}\`, {
 \t\t\t\t\tcollection: event.collection,
-\t\t\t\t\tid: event.content.id,
+\t\t\t\t\tcontentId: event.content.id,
+\t\t\t\t\tcreatedAt: new Date().toISOString(),
 \t\t\t\t});
 \t\t\t},
 \t\t},
+
+\t\troutes: {
+\t\t\trecent: {
+\t\t\t\thandler: async (ctx) => {
+\t\t\t\t\tconst result = await ctx.storage.events.query({
+\t\t\t\t\t\torderBy: { createdAt: "desc" },
+\t\t\t\t\t\tlimit: 10,
+\t\t\t\t\t});
+\t\t\t\t\treturn { events: result.items };
+\t\t\t\t},
+\t\t\t},
+\t\t},
 \t});
 }
 

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"), {