@honeydeck/honeydeck 0.1.0

package/src/cli/build.ts

@@ -0,0 +1,229 @@
+/**
+ * `honeydeck build` — build the presentation as a deployable static SPA.
+ *
+ * ### Architecture
+ *
+ * Vite root is set to `src/runtime/app-shell/` so that `index.html` lives
+ * at the root and Vite outputs it as `dist/index.html`.
+ *
+ *   Why APP_SHELL_DIR as root?
+ *   Vite's default HTML entry resolution uses `<root>/index.html`. By setting
+ *   root to the directory that *owns* our shell HTML we get clean output paths
+ *   without having to configure `rollupOptions.input` to an unusual path.
+ *
+ * The `__HONEYDECK_MAIN_ENTRY__` placeholder in index.html is replaced with
+ * `./main.tsx` by the `buildHtmlPlugin`. Vite resolves this relative to the
+ * HTML file's location (APP_SHELL_DIR), finding `app-shell/main.tsx`. ✓
+ *
+ * User project files (deck entry, CSS, components) are outside APP_SHELL_DIR
+ * but are accessed via absolute paths by `honeydeckPlugin`'s virtual module
+ * resolver and resolveId hooks. Rollup (used by Vite during build) has no
+ * file-system restrictions — all absolute paths are accessible.
+ *
+ * `outDir` points to `<userRoot>/dist` (outside the Vite root). Vite 5+
+ * allows this when `emptyOutDir: true` is set explicitly.
+ *
+ * ### Output structure
+ * ```
+ * dist/
+ *   index.html
+ *   assets/
+ *     honeydeck-[hash].js
+ *     honeydeck-[hash].css
+ *   public/       ← copied from project's public/ (if present)
+ * ```
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin } from "vite";
+import { build } from "vite";
+import { loadDeck } from "#vite-plugin/deck-loader.ts";
+import { honeydeckPlugin } from "#vite-plugin/index.ts";
+import { hasHelpFlag } from "./args.ts";
+import { formatCommandBanner } from "./banner.ts";
+import {
+	type DeckPathOptions,
+	rejectRootOption,
+	resolveDeckPath,
+	validateDeckPath,
+} from "./deck-path.ts";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/** Absolute path to src/runtime/app-shell/ — used as Vite root for build. */
+export const APP_SHELL_DIR = resolve(__dirname, "../runtime/app-shell");
+
+// ---------------------------------------------------------------------------
+// HTML fix plugin — shared with pdf.ts via the export below
+// ---------------------------------------------------------------------------
+
+/**
+ * Replaces `__HONEYDECK_MAIN_ENTRY__` in index.html with `./main.tsx`.
+ *
+ * During build (root = APP_SHELL_DIR), `./main.tsx` is resolved relative to
+ * the HTML file's directory, which is APP_SHELL_DIR — exactly where main.tsx
+ * lives. This allows the same index.html template to be used for both the
+ * dev server (which injects an `/@fs/` absolute path) and the production
+ * build (which uses a normal relative module path).
+ */
+export function buildHtmlPlugin(): Plugin {
+	return {
+		name: "honeydeck:build-html",
+		// `order: 'pre'` ensures this hook runs before Vite's built-in
+		// `vite:build-html` plugin tries to resolve the script src as a module.
+		transformIndexHtml: {
+			order: "pre",
+			handler(html: string): string {
+				return html.replace("__HONEYDECK_MAIN_ENTRY__", "./main.tsx");
+			},
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Shared build function (also consumed by pdf.ts)
+// ---------------------------------------------------------------------------
+
+export type BuildConfig = {
+	/** User project root — where the deck entry, CSS, and components live. */
+	userRoot: string;
+	/** Entry MDX file path relative to userRoot. */
+	entry: string;
+	/** Absolute path to the output directory. */
+	outDir: string;
+	/**
+	 * Vite log level.
+	 * @default 'warn'  Use 'error' for quiet PDF sub-builds.
+	 */
+	logLevel?: "silent" | "error" | "warn" | "info";
+};
+
+/**
+ * Programmatic Vite build for Honeydeck presentations.
+ * Called by both `runBuild` (normal build) and `runPdf` (PDF sub-build).
+ */
+export async function buildPresentation(config: BuildConfig): Promise<void> {
+	const { userRoot, entry, outDir, logLevel = "warn" } = config;
+
+	// Only pass publicDir when the project actually has a public/ folder,
+	// otherwise Vite logs a harmless-but-noisy "public dir does not exist" warning.
+	const publicDir = resolve(userRoot, "public");
+
+	await build({
+		// root = APP_SHELL_DIR: index.html is here, outputs to outDir/index.html.
+		root: APP_SHELL_DIR,
+		publicDir: existsSync(publicDir) ? publicDir : false,
+		logLevel,
+
+		build: {
+			outDir,
+			// Explicit true so Vite honours it even though outDir is outside the root.
+			emptyOutDir: true,
+		},
+
+		plugins: [
+			// Replace HTML placeholder before Vite bundles the entry script.
+			buildHtmlPlugin(),
+			// Virtual slides + MDX compilation + Tailwind — user files via userRoot.
+			...honeydeckPlugin({ root: userRoot, entry }),
+		],
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+export type BuildOptions = DeckPathOptions;
+
+export function printBuildHelp(): void {
+	console.log(`
+  ✨ honeydeck build — build for production
+
+  Usage:
+    honeydeck build [options]
+
+  Options:
+    --deck <file.mdx>  Deck entry file          (default: ./deck.mdx)
+    -h, --help         Show this help page
+
+  Examples:
+    honeydeck build
+    honeydeck build --deck talk.mdx
+`);
+}
+
+function readOptionValue(
+	args: string[],
+	index: number,
+	option: string,
+): string {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) {
+		console.error(`❌  Missing value for ${option}`);
+		process.exit(1);
+	}
+	return value;
+}
+
+export function parseBuildArgs(args: string[]): BuildOptions {
+	let deckPath: string | null = null;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--deck") {
+			const value = readOptionValue(args, i, arg);
+			validateDeckPath(value, arg);
+			deckPath = value;
+			i++;
+		} else if (arg === "--root") {
+			rejectRootOption();
+		}
+	}
+
+	return resolveDeckPath(deckPath ?? undefined);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runBuild(args: string[]): Promise<void> {
+	if (hasHelpFlag(args)) {
+		printBuildHelp();
+		return;
+	}
+
+	const { root, entry, deck } = parseBuildArgs(args);
+
+	// Count slides for the summary line — non-fatal if the deck is unreadable
+	// (the Vite build step will surface the real error with full context).
+	let slideCount = 0;
+	try {
+		const { slides } = loadDeck(deck);
+		slideCount = slides.length;
+	} catch {
+		// Non-fatal — Vite build will surface the actual error.
+	}
+
+	console.log(`\n${formatCommandBanner()}\n`);
+	console.log("  📦 Building presentation…\n");
+
+	const outDir = resolve(root, "dist");
+
+	await buildPresentation({ userRoot: root, entry, outDir });
+
+	console.log("\n  ✅ Build complete!");
+	console.log("  📁 Output: dist/");
+	if (slideCount > 0) {
+		console.log(`  📄 ${slideCount} slide${slideCount !== 1 ? "s" : ""}`);
+	}
+	console.log();
+}

package/src/cli/deck-path.ts

@@ -0,0 +1,32 @@
+import { basename, dirname, extname, resolve } from "node:path";
+import { DEFAULT_DECK_ENTRY } from "../defaults.ts";
+
+export type DeckPathOptions = {
+	deck: string;
+	root: string;
+	entry: string;
+};
+
+export function resolveDeckPath(
+	deckPath = DEFAULT_DECK_ENTRY,
+): DeckPathOptions {
+	const deck = resolve(process.cwd(), deckPath);
+
+	return {
+		deck,
+		root: dirname(deck),
+		entry: basename(deck),
+	};
+}
+
+export function validateDeckPath(deckPath: string, option: string): void {
+	if (extname(deckPath) !== ".mdx") {
+		console.error(`❌  ${option} must point to an .mdx file: ${deckPath}`);
+		process.exit(1);
+	}
+}
+
+export function rejectRootOption(): never {
+	console.error("❌  --root is no longer supported. Use --deck <file.mdx>.");
+	process.exit(1);
+}

package/src/cli/dev.ts

@@ -0,0 +1,263 @@
+/**
+ * `honeydeck dev` — start the Vite development server.
+ *
+ * Architecture summary:
+ *
+ *   Vite root = <deck dir>
+ *     → deck-local files (CSS, images, components) resolve naturally
+ *
+ *   `honeydeck:app-shell` plugin
+ *     → intercepts GET / and serves src/runtime/app-shell/index.html
+ *     → replaces the MAIN_ENTRY placeholder with `/@fs/<abs-path>/main.tsx`
+ *     → Vite's /@fs/ handler serves files outside the configured root
+ *
+ *   `honeydeckPlugin()` (virtual modules + MDX + Tailwind)
+ *     → splits the selected deck entry, serves virtual:honeydeck/* modules, compiles MDX
+ *
+ * Why this approach?
+ *   Vite root controls where CSS/assets/components resolve. Setting it to
+ *   the deck dir lets users `@import './styles.css'` etc. normally.
+ *   The app shell (main.tsx, Deck.tsx) lives inside the honeydeck package and
+ *   is accessed via /@fs/ — Vite's escape hatch for files outside the root.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer, type Plugin } from "vite";
+import { honeydeckPlugin } from "#vite-plugin/index.ts";
+import { hasHelpFlag } from "./args.ts";
+import { formatCommandBanner } from "./banner.ts";
+import {
+	type DeckPathOptions,
+	rejectRootOption,
+	resolveDeckPath,
+	validateDeckPath,
+} from "./deck-path.ts";
+
+// ---------------------------------------------------------------------------
+// Paths (all resolved at module load time, before any async work)
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Absolute path to src/runtime/app-shell/ */
+const APP_SHELL_DIR = resolve(__dirname, "../runtime/app-shell");
+
+/** Absolute path to src/runtime/app-shell/main.tsx */
+const MAIN_TSX_PATH = resolve(APP_SHELL_DIR, "main.tsx");
+
+/** Absolute path to src/runtime/app-shell/index.html (the template) */
+const INDEX_HTML_PATH = resolve(APP_SHELL_DIR, "index.html");
+
+/**
+ * Absolute path to the honeydeck package root (the directory that contains src/).
+ * Passed to `server.fs.allow` so that Vite's /@fs/ handler can serve
+ * files under src/ even when the Vite root is set to the deck dir.
+ */
+const PACKAGE_ROOT = resolve(__dirname, "../..");
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+export type DevOptions = {
+	port: number;
+	open: boolean;
+} & DeckPathOptions;
+
+export function createDevServerConfig(port: number, open: boolean) {
+	return {
+		port,
+		open,
+		strictPort: false,
+		// Bind to all interfaces so phones/tablets on the same local network can
+		// open the printed Network URL.
+		host: "0.0.0.0",
+	} as const;
+}
+
+export function printDevHelp(): void {
+	console.log(`
+  ✨ honeydeck dev — start the development server
+
+  Usage:
+    honeydeck dev [options]
+
+  Options:
+    --deck <file.mdx>  Deck entry file          (default: ./deck.mdx)
+    -p, --port <n>     Dev server port          (default: 4200)
+    -o, --open         Open browser on start
+    -h, --help         Show this help page
+
+  Examples:
+    honeydeck dev
+    honeydeck dev --open
+    honeydeck dev --deck talk.mdx --port 8080
+`);
+}
+
+function readOptionValue(
+	args: string[],
+	index: number,
+	option: string,
+): string {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) {
+		console.error(`❌  Missing value for ${option}`);
+		process.exit(1);
+	}
+	return value;
+}
+
+export function parseDevArgs(args: string[]): DevOptions {
+	let port = 4200;
+	let open = false;
+	let deckPath: string | null = null;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--port" || arg === "-p") {
+			const value = readOptionValue(args, i, arg);
+			port = parseInt(value, 10);
+			i++;
+			if (Number.isNaN(port)) {
+				console.error(`❌  Invalid --port value: ${value}`);
+				process.exit(1);
+			}
+		} else if (arg === "--open" || arg === "-o") {
+			open = true;
+		} else if (arg === "--deck") {
+			const value = readOptionValue(args, i, arg);
+			validateDeckPath(value, arg);
+			deckPath = value;
+			i++;
+		} else if (arg === "--root") {
+			rejectRootOption();
+		}
+	}
+
+	return { port, open, ...resolveDeckPath(deckPath ?? undefined) };
+}
+
+// ---------------------------------------------------------------------------
+// App shell Vite plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * `honeydeck:app-shell` — serves the Honeydeck index.html for the root route.
+ *
+ * Handles two concerns:
+ *  1. `config` hook: broadens `server.fs.allow` so /@fs/ can reach the
+ *     app shell files which live outside the user's project root.
+ *  2. `configureServer` hook: registers a connect middleware that intercepts
+ *     GET / (and /index.html), reads the HTML template, injects the correct
+ *     /@fs/ script src, and lets Vite's `transformIndexHtml` pipeline apply
+ *     any further HTML transforms (e.g. inject the HMR client).
+ */
+function appShellPlugin(): Plugin {
+	return {
+		name: "honeydeck:app-shell",
+
+		config() {
+			return {
+				server: {
+					fs: {
+						// Allow Vite's /@fs/ handler to serve any file under the honeydeck
+						// package root (so src/runtime/app-shell/main.tsx is accessible).
+						allow: [PACKAGE_ROOT],
+					},
+				},
+			};
+		},
+
+		configureServer(server) {
+			server.middlewares.use(async (req, res, next) => {
+				const url = req.url ?? "/";
+
+				// Only handle the root HTML request; let everything else pass through.
+				if (url !== "/" && url !== "/index.html") {
+					next();
+					return;
+				}
+
+				try {
+					// Read the template and replace the placeholder script src.
+					// The /@fs/ prefix tells Vite to serve the file by absolute path,
+					// bypassing the root restriction for this single module.
+					let html = readFileSync(INDEX_HTML_PATH, "utf-8");
+					html = html.replace(
+						"__HONEYDECK_MAIN_ENTRY__",
+						`/@fs${MAIN_TSX_PATH}`,
+					);
+
+					// Let Vite's HTML transform pipeline run (injects HMR client, etc.)
+					const transformed = await server.transformIndexHtml(url, html);
+
+					res.setHeader("Content-Type", "text/html; charset=utf-8");
+					res.end(transformed);
+				} catch (err) {
+					next(err);
+				}
+			});
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runDev(args: string[]): Promise<void> {
+	if (hasHelpFlag(args)) {
+		printDevHelp();
+		return;
+	}
+
+	const { port, open, root, entry, deck } = parseDevArgs(args);
+
+	console.log("\n  ✨ Honeydeck dev starting...\n");
+	console.log(`  Root   → ${root}`);
+	console.log(`  Deck   → ${deck}`);
+	console.log(`  Port   → ${port}`);
+
+	const server = await createServer({
+		// Set root to the deck dir so local CSS/assets resolve naturally.
+		root,
+
+		// `custom` appType: we serve our own index.html; Vite doesn't look for
+		// one in the root dir.
+		appType: "custom",
+
+		server: createDevServerConfig(port, open),
+
+		plugins: [
+			// 1. App shell: serve our index.html + configure fs.allow
+			appShellPlugin(),
+			// 2. Virtual modules + MDX compilation + Tailwind
+			...honeydeckPlugin({ root, entry }),
+		],
+	});
+
+	await server.listen();
+
+	const resolvedPort = server.config.server.port ?? port;
+	// Try to get the network address
+	const networkAddresses = server.resolvedUrls?.network ?? [];
+	const networkUrl =
+		networkAddresses[0] ?? `http://192.168.x.x:${resolvedPort}/`;
+
+	console.log(`\n${formatCommandBanner()}\n`);
+	console.log(`  🚀 Local:   http://localhost:${resolvedPort}/`);
+	console.log(`  🌐 Network: ${networkUrl}`);
+	console.log(`  🎨 Theme:   http://localhost:${resolvedPort}/#/theme`);
+	console.log(`\n  👀 Watching for changes...\n`);
+
+	// Keep the process alive (Vite does this, but be explicit).
+	process.on("SIGINT", async () => {
+		console.log("\n  👋  Shutting down honeydeck dev server…\n");
+		await server.close();
+		process.exit(0);
+	});
+}

package/src/cli/index.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * honeydeck CLI — entry point.
+ *
+ * Dispatches to sub-commands based on process.argv.
+ * Uses dynamic `import()` for each sub-command so that only the required
+ * code is loaded (avoids pulling in Vite at startup just to print --help).
+ *
+ * Usage:
+ *   honeydeck                           — show help
+ *   honeydeck help <command>            — show sub-command help
+ *   honeydeck init [--name <n>] [--skip-skill|--install-skill]
+ *                                   — scaffold a new project
+ *   honeydeck skill                    — install Honeydeck agent skills
+ *   honeydeck dev  [--deck <file.mdx>] [--port <n>] [--open]
+ *   honeydeck build [--deck <file.mdx>]
+ *   honeydeck pdf  [--deck <file.mdx>] [-o <file>] [--steps all|final] [--mode light|dark]
+ */
+
+import { formatTopLevelBanner } from "./banner.ts";
+
+const [, , command, ...args] = process.argv;
+
+async function main(): Promise<void> {
+	if (!command || isHelpFlag(command)) {
+		printHelp();
+		process.exit(0);
+	}
+
+	if (command === "help") {
+		const target = args[0];
+		if (!target || isHelpFlag(target)) {
+			printHelp();
+			process.exit(0);
+		}
+
+		const handled = await runCommand(target, ["--help"]);
+		if (!handled) {
+			console.error(`  ❌ Unknown command "${target}".`);
+			printHelp();
+			process.exit(1);
+		}
+		return;
+	}
+
+	const handled = await runCommand(command, args);
+	if (!handled) {
+		printHelp();
+		process.exit(1);
+	}
+}
+
+async function runCommand(command: string, args: string[]): Promise<boolean> {
+	switch (command) {
+		case "dev": {
+			const { runDev } = await import("./dev.ts");
+			await runDev(args);
+			return true;
+		}
+
+		case "build": {
+			const { runBuild } = await import("./build.ts");
+			await runBuild(args);
+			return true;
+		}
+
+		case "pdf": {
+			const { runPdf } = await import("./pdf.ts");
+			await runPdf(args);
+			return true;
+		}
+
+		case "init": {
+			const { runInit } = await import("./init.ts");
+			await runInit(args);
+			return true;
+		}
+
+		case "skill": {
+			const { runSkill } = await import("./skill.ts");
+			await runSkill(args);
+			return true;
+		}
+
+		default:
+			return false;
+	}
+}
+
+function isHelpFlag(value: string): boolean {
+	return value === "--help" || value === "-h";
+}
+
+function printHelp(): void {
+	console.log(`
+${formatTopLevelBanner()}
+
+  Usage:
+    honeydeck <command> [options]
+    honeydeck help <command>
+
+  Commands:
+    init    Scaffold a new presentation project
+    skill   Install Honeydeck agent skills
+    dev     Start the development server
+    build   Build for production (static SPA)
+    pdf     Export slides to a PDF file
+    help    Show top-level or command-specific help
+
+  Options:
+    -h, --help  Show help
+
+  Examples:
+    honeydeck init --name my-talk
+    honeydeck help dev
+    honeydeck dev --open
+    honeydeck pdf --steps all --mode dark -o slides.pdf
+
+  🎞  Happy presenting!
+`);
+}
+
+main().catch((err: unknown) => {
+	console.error("❌  honeydeck error:", err);
+	process.exit(1);
+});