kitfly 0.2.3 → 0.2.4

package/scripts/build-all.ts

@@ -70,6 +70,11 @@ function getVersion(): string {
 function main(): void {
 	const version = getVersion();
 
+	// Generate embedded docs before compiling binaries
+	console.log("Generating embedded documentation...");
+	execSync("bun scripts/embed-docs.ts", { stdio: "inherit" });
+	console.log();
+
 	console.log(`Building ${TARGETS.length} binaries for '${BINARY_NAME}' v${version}`);
 	console.log(`  Entry point: ${ENTRY_POINT}`);
 	console.log(`  Output dir:  ${OUT_DIR}`);

package/scripts/build.ts

@@ -29,6 +29,7 @@ import {
 	type ContentFile,
 	collectFiles,
 	// Navigation/template building
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	// Config helpers
@@ -38,6 +39,7 @@ import {
 	// File utilities
 	exists,
 	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	// Provenance
 	generateProvenance,
@@ -59,6 +61,7 @@ import {
 	type SiteConfig,
 	slugify,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme, type Theme } from "../src/theme.ts";
@@ -154,6 +157,27 @@ async function resolveSiteAssetsDir(siteRoot: string): Promise<string | null> {
 	return null;
 }
 
+type FenceValidationFlags = {
+	slidesVisuals: boolean;
+	planningVisuals: boolean;
+};
+
+async function getFenceValidationFlags(root: string): Promise<FenceValidationFlags> {
+	try {
+		const raw = await readFile(join(root, "kitfly.plugins.yaml"), "utf-8");
+		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
+		const enabled = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
+		return {
+			slidesVisuals: enabled.some((p) => typeof p === "string" && p.startsWith("slides-visuals@")),
+			planningVisuals: enabled.some(
+				(p) => typeof p === "string" && p.startsWith("planning-visuals@"),
+			),
+		};
+	} catch {
+		return { slidesVisuals: false, planningVisuals: false };
+	}
+}
+
 function computePathPrefix(urlKey: string): string {
 	const clean = urlKey.replace(/^\/+/, "").replace(/\.html$/, "");
 	if (!clean) return "./";
@@ -217,6 +241,7 @@ async function renderFile(
 	config: SiteConfig,
 	theme: Theme,
 	plugins: PluginInjections,
+	fenceValidation: FenceValidationFlags,
 ): Promise<string> {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const content = await readFile(filePath, "utf-8");
@@ -242,6 +267,22 @@ async function renderFile(
 			title = frontmatter.title as string;
 		}
 		pageMeta = buildPageMeta(frontmatter);
+		if (fenceValidation.planningVisuals) {
+			const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+				validatePlanningVisualsFences(body),
+			);
+			if (diagnostics.length) {
+				const msg = diagnostics
+					.slice(0, 12)
+					.map((d) => `  - ${filePath}:${d.line} ${d.message}`)
+					.join("\n");
+				throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+			}
+			const warnings = collectPlanningVisualsContainmentWarnings(body);
+			for (const warning of warnings.slice(0, 12)) {
+				console.warn(`  ⚠ ${filePath}:${warning.line} ${warning.message}`);
+			}
+		}
 		htmlContent = marked.parse(body) as string;
 	}
 
@@ -394,26 +435,18 @@ async function renderSlidesIndex(
 	config: SiteConfig,
 	theme: Theme,
 	plugins: PluginInjections,
+	fenceValidation: FenceValidationFlags,
 ): Promise<string> {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const pathPrefix = "./";
 	const slides = await collectSlides(files, {
 		markdownTransform: (raw, file) => applyDataBindingsForSlides(raw, file.path, config),
 	});
-	let validateFences = false;
-	try {
-		const raw = await readFile(join(ROOT, "kitfly.plugins.yaml"), "utf-8");
-		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
-		const enabled = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
-		validateFences = enabled.some((p) => typeof p === "string" && p.startsWith("slides-visuals@"));
-	} catch {
-		// no config, skip
-	}
 	const renderedSlides = await Promise.all(
 		slides.map(async (slide, i) => {
 			let inner = "";
 			if (slide.kind === "markdown") {
-				if (validateFences) {
+				if (fenceValidation.slidesVisuals) {
 					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
 						validateSlidesVisualsFences(slide.body),
 					);
@@ -425,6 +458,22 @@ async function renderSlidesIndex(
 						throw new Error(`slides-visuals fence contract violations:\n${msg}`);
 					}
 				}
+				if (fenceValidation.planningVisuals) {
+					const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+						validatePlanningVisualsFences(slide.body),
+					);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${slide.sourcePath}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+					}
+					const warnings = collectPlanningVisualsContainmentWarnings(slide.body);
+					for (const warning of warnings.slice(0, 12)) {
+						console.warn(`  ⚠ ${slide.sourcePath}:${warning.line} ${warning.message}`);
+					}
+				}
 				inner = marked.parse(slide.body) as string;
 			} else if (slide.kind === "yaml") {
 				inner = `<pre><code class="language-yaml">${escapeHtml(slide.body)}</code></pre>`;
@@ -581,6 +630,7 @@ async function buildSite() {
 		root: ROOT,
 		mode: config.mode === "slides" ? "slides" : "docs",
 	});
+	const fenceValidation = await getFenceValidationFlags(ROOT);
 
 	// Copy CSS
 	const css = await readFile(await resolveStylesPath(ROOT), "utf-8");
@@ -631,7 +681,15 @@ async function buildSite() {
 	}
 
 	if (config.mode === "slides") {
-		const html = await renderSlidesIndex(template, files, provenance, config, theme, plugins);
+		const html = await renderSlidesIndex(
+			template,
+			files,
+			provenance,
+			config,
+			theme,
+			plugins,
+			fenceValidation,
+		);
 		await writeFile(join(DIST, "index.html"), html);
 		console.log(`  ✓ index.html (slides mode, ${files.length} source files)`);
 		await generateAIAccessibility(DIST, files, config, provenance);
@@ -650,6 +708,7 @@ async function buildSite() {
 			config,
 			theme,
 			plugins,
+			fenceValidation,
 		);
 
 		// Create output path
@@ -676,6 +735,7 @@ async function buildSite() {
 					config,
 					theme,
 					plugins,
+					fenceValidation,
 				);
 				await writeFile(join(DIST, "index.html"), homeHtml);
 				console.log(`  ✓ index.html (from ${config.home})`);
@@ -691,6 +751,7 @@ async function buildSite() {
 					config,
 					theme,
 					plugins,
+					fenceValidation,
 				);
 				await writeFile(join(DIST, "index.html"), indexHtml);
 				console.log("  ✓ index.html");
@@ -708,6 +769,7 @@ async function buildSite() {
 			config,
 			theme,
 			plugins,
+			fenceValidation,
 		);
 		await writeFile(join(DIST, "index.html"), indexHtml);
 		console.log("  ✓ index.html");

package/scripts/bundle.ts

@@ -26,9 +26,10 @@ import {
 	buildSectionNav,
 	// Navigation/template building
 	buildSlideNavHierarchical,
-	// Types
 	type ContentFile,
 	collectFiles,
+	// Types
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	// Config helpers
@@ -36,6 +37,7 @@ import {
 	// Formatting
 	escapeHtml,
 	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	// YAML/Config parsing
 	loadDataBindings,
@@ -52,6 +54,7 @@ import {
 	type SiteConfig,
 	slugify,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme } from "../src/theme.ts";
@@ -354,24 +357,35 @@ function buildBundleNav(files: ContentFile[], config: SiteConfig): string {
 	return html;
 }
 
-async function buildSlidesBundleContent(files: ContentFile[], config: SiteConfig): Promise<string> {
-	const slides = await collectSlides(files, {
-		markdownTransform: (raw, file) => applyDataBindingsForSlides(raw, file.path, config),
-	});
-	let validateFences = false;
+async function getFenceValidationFlags(root: string): Promise<{
+	slidesVisuals: boolean;
+	planningVisuals: boolean;
+}> {
 	try {
-		const raw = await readFile(join(ROOT, "kitfly.plugins.yaml"), "utf-8");
+		const raw = await readFile(join(root, "kitfly.plugins.yaml"), "utf-8");
 		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
 		const enabled = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
-		validateFences = enabled.some((p) => typeof p === "string" && p.startsWith("slides-visuals@"));
+		return {
+			slidesVisuals: enabled.some((p) => typeof p === "string" && p.startsWith("slides-visuals@")),
+			planningVisuals: enabled.some(
+				(p) => typeof p === "string" && p.startsWith("planning-visuals@"),
+			),
+		};
 	} catch {
-		// no config, skip
+		return { slidesVisuals: false, planningVisuals: false };
 	}
+}
+
+async function buildSlidesBundleContent(files: ContentFile[], config: SiteConfig): Promise<string> {
+	const slides = await collectSlides(files, {
+		markdownTransform: (raw, file) => applyDataBindingsForSlides(raw, file.path, config),
+	});
+	const fenceValidation = await getFenceValidationFlags(ROOT);
 	const renderedSlides = await Promise.all(
 		slides.map(async (slide, i) => {
 			let inner = "";
 			if (slide.kind === "markdown") {
-				if (validateFences) {
+				if (fenceValidation.slidesVisuals) {
 					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
 						validateSlidesVisualsFences(slide.body),
 					);
@@ -383,6 +397,22 @@ async function buildSlidesBundleContent(files: ContentFile[], config: SiteConfig
 						throw new Error(`slides-visuals fence contract violations:\n${msg}`);
 					}
 				}
+				if (fenceValidation.planningVisuals) {
+					const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+						validatePlanningVisualsFences(slide.body),
+					);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${slide.sourcePath}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+					}
+					const warnings = collectPlanningVisualsContainmentWarnings(slide.body);
+					for (const warning of warnings.slice(0, 12)) {
+						console.warn(`  ⚠ ${slide.sourcePath}:${warning.line} ${warning.message}`);
+					}
+				}
 				inner = marked.parse(slide.body) as string;
 			} else if (slide.kind === "yaml") {
 				inner = `<pre><code class="language-yaml">${escapeHtml(slide.body)}</code></pre>`;
@@ -602,6 +632,7 @@ async function bundle() {
 		navHtml = buildSlideNavHierarchical(slides, config, "slide-1");
 		contentHtml = await buildSlidesBundleContent(files, config);
 	} else {
+		const fenceValidation = await getFenceValidationFlags(ROOT);
 		// Build navigation and content sections
 		const sections: Map<string, { id: string; title: string; html: string }[]> = new Map();
 
@@ -617,6 +648,22 @@ async function bundle() {
 						homePath,
 						config,
 					);
+					if (fenceValidation.planningVisuals) {
+						const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+							validatePlanningVisualsFences(body),
+						);
+						if (diagnostics.length) {
+							const msg = diagnostics
+								.slice(0, 12)
+								.map((d) => `  - ${homePath}:${d.line} ${d.message}`)
+								.join("\n");
+							throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+						}
+						const warnings = collectPlanningVisualsContainmentWarnings(body);
+						for (const warning of warnings.slice(0, 12)) {
+							console.warn(`  ⚠ ${homePath}:${warning.line} ${warning.message}`);
+						}
+					}
 					const title = (frontmatter.title as string) || "Home";
 					let htmlContent = marked.parse(body) as string;
 					htmlContent = await inlineLocalImages(htmlContent, config);
@@ -654,6 +701,22 @@ async function bundle() {
 				if (frontmatter.description) {
 					description = frontmatter.description as string;
 				}
+				if (fenceValidation.planningVisuals) {
+					const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+						validatePlanningVisualsFences(body),
+					);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${file.path}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+					}
+					const warnings = collectPlanningVisualsContainmentWarnings(body);
+					for (const warning of warnings.slice(0, 12)) {
+						console.warn(`  ⚠ ${file.path}:${warning.line} ${warning.message}`);
+					}
+				}
 				htmlContent = marked.parse(body) as string;
 
 				// Collect raw markdown for AI accessibility

package/scripts/dev.ts

@@ -40,6 +40,7 @@ import {
 	checkPortOrExit,
 	// Navigation/template building
 	collectFiles,
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	envInt,
@@ -48,6 +49,7 @@ import {
 	// Formatting
 	escapeHtml,
 	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	// Provenance
 	generateProvenance,
@@ -68,6 +70,7 @@ import {
 	type SiteConfig,
 	slugify,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme, type Theme } from "../src/theme.ts";
@@ -302,15 +305,23 @@ const clients: Set<ReadableStreamDefaultController> = new Set();
 
 let pluginCache: { key: string; head: string; bodyEnd: string } | null = null;
 
-async function isSlidesVisualsEnabled(): Promise<boolean> {
+async function getFenceValidationFlags(): Promise<{
+	slidesVisuals: boolean;
+	planningVisuals: boolean;
+}> {
 	const configPath = join(ROOT, "kitfly.plugins.yaml");
 	try {
 		const raw = await readFile(configPath, "utf-8");
 		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
 		const plugins = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
-		return plugins.some((p) => typeof p === "string" && p.startsWith("slides-visuals@"));
+		return {
+			slidesVisuals: plugins.some((p) => typeof p === "string" && p.startsWith("slides-visuals@")),
+			planningVisuals: plugins.some(
+				(p) => typeof p === "string" && p.startsWith("planning-visuals@"),
+			),
+		};
 	} catch {
-		return false;
+		return { slidesVisuals: false, planningVisuals: false };
 	}
 }
 
@@ -400,6 +411,23 @@ async function renderPage(
 			title = frontmatter.title as string;
 		}
 		pageMeta = buildPageMeta(frontmatter);
+		const fenceValidation = await getFenceValidationFlags();
+		if (fenceValidation.planningVisuals) {
+			const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+				validatePlanningVisualsFences(body),
+			);
+			if (diagnostics.length) {
+				const msg = diagnostics
+					.slice(0, 12)
+					.map((d) => `  - ${filePath}:${d.line} ${d.message}`)
+					.join("\n");
+				throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+			}
+			const warnings = collectPlanningVisualsContainmentWarnings(body);
+			for (const warning of warnings.slice(0, 12)) {
+				logWarn(`${filePath}:${warning.line} ${warning.message}`);
+			}
+		}
 		htmlContent = marked.parse(body) as string;
 	}
 
@@ -487,13 +515,13 @@ async function renderSlidesPage(
 		return renderGettingStarted(provenance, config, theme);
 	}
 	const pathPrefix = "/";
-	const validateFences = await isSlidesVisualsEnabled();
+	const fenceValidation = await getFenceValidationFlags();
 
 	const sections = await Promise.all(
 		slides.map(async (slide, i) => {
 			let inner = "";
 			if (slide.kind === "markdown") {
-				if (validateFences) {
+				if (fenceValidation.slidesVisuals) {
 					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
 						validateSlidesVisualsFences(slide.body),
 					);
@@ -505,6 +533,22 @@ async function renderSlidesPage(
 						throw new Error(`slides-visuals fence contract violations:\n${msg}`);
 					}
 				}
+				if (fenceValidation.planningVisuals) {
+					const diagnostics = filterUnknownPlanningVisualsTypeDiagnostics(
+						validatePlanningVisualsFences(slide.body),
+					);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${slide.sourcePath}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`planning-visuals fence contract violations:\n${msg}`);
+					}
+					const warnings = collectPlanningVisualsContainmentWarnings(slide.body);
+					for (const warning of warnings.slice(0, 12)) {
+						logWarn(`${slide.sourcePath}:${warning.line} ${warning.message}`);
+					}
+				}
 				inner = marked.parse(slide.body) as string;
 			} else if (slide.kind === "yaml") {
 				inner = `<pre><code class="language-yaml">${escapeHtml(slide.body)}</code></pre>`;

package/scripts/embed-docs.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+
+/**
+ * Build-time codegen: reads docs/embed-manifest.yaml, resolves globs,
+ * and generates src/generated/embedded-docs.ts with all matched content.
+ *
+ * Usage:
+ *   bun scripts/embed-docs.ts
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { Glob } from "bun";
+import { parseFrontmatter, parseYaml } from "../src/shared.ts";
+
+const MANIFEST_PATH = "docs/embed-manifest.yaml";
+const OUTPUT_PATH = "src/generated/embedded-docs.ts";
+
+function toSlug(filePath: string): string {
+	// Normalize path separators first (Windows compat: Bun.Glob returns backslashes)
+	const normalized = filePath.replace(/\\/g, "/");
+	// Strip first segment (docs/ or content/) and .md extension
+	const withoutPrefix = normalized.replace(/^[^/]+\//, "");
+	const withoutExt = withoutPrefix.replace(/\.md$/, "");
+	const base = basename(withoutExt).toLowerCase();
+	if (base === "readme" || base === "index") {
+		return dirname(withoutPrefix).replace(/\\/g, "/");
+	}
+	return withoutExt;
+}
+
+function extractTitle(body: string): string {
+	for (const line of body.split("\n")) {
+		const m = line.match(/^#\s+(.+)/);
+		if (m) return m[1].trim();
+	}
+	return "(untitled)";
+}
+
+async function resolveGlobs(includes: string[], excludes: string[]): Promise<string[]> {
+	const matched = new Set<string>();
+
+	for (const pattern of includes) {
+		const glob = new Glob(pattern);
+		for await (const path of glob.scan({ cwd: ".", dot: false })) {
+			matched.add(path);
+		}
+	}
+
+	for (const pattern of excludes) {
+		const glob = new Glob(pattern);
+		for await (const path of glob.scan({ cwd: ".", dot: false })) {
+			matched.delete(path);
+		}
+	}
+
+	return [...matched].sort();
+}
+
+function escapeForTemplate(s: string): string {
+	return s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+
+async function main(): Promise<void> {
+	const raw = readFileSync(MANIFEST_PATH, "utf-8");
+	const manifest = parseYaml(raw);
+	const includes = manifest.include as string[];
+	const excludes = (manifest.exclude as string[]) ?? [];
+
+	if (!includes?.length) {
+		console.error(`Error: no include patterns in ${MANIFEST_PATH}`);
+		process.exit(1);
+	}
+
+	const files = await resolveGlobs(includes, excludes);
+
+	if (files.length === 0) {
+		console.error("Error: no files matched the manifest patterns");
+		process.exit(1);
+	}
+
+	const entries: Array<[string, string, string]> = [];
+
+	for (const file of files) {
+		const content = readFileSync(file, "utf-8");
+		const { body } = parseFrontmatter(content);
+		const trimmed = body.trim();
+		const slug = toSlug(file);
+		const title = extractTitle(trimmed);
+		entries.push([slug, title, trimmed]);
+	}
+
+	// Sort by slug for deterministic output
+	entries.sort((a, b) => a[0].localeCompare(b[0]));
+
+	const lines = [
+		"// AUTO-GENERATED by scripts/embed-docs.ts — do not edit",
+		"export const EMBEDDED_DOCS: ReadonlyArray<readonly [string, string, string]> = [",
+	];
+
+	for (const [slug, title, content] of entries) {
+		lines.push(
+			`\t[${JSON.stringify(slug)}, ${JSON.stringify(title)}, \`${escapeForTemplate(content)}\`],`,
+		);
+	}
+
+	lines.push("];");
+	lines.push("");
+
+	mkdirSync(dirname(OUTPUT_PATH), { recursive: true });
+	writeFileSync(OUTPUT_PATH, lines.join("\n"));
+
+	console.log(`Embedded ${entries.length} docs into ${OUTPUT_PATH}`);
+	for (const [slug, title] of entries) {
+		console.log(`  ${slug} — ${title}`);
+	}
+}
+
+main();