kitfly 0.2.1 → 0.2.4

package/scripts/bundle.ts

@@ -6,6 +6,7 @@
  * Options:
  *   -o, --out <dir>    Output directory [env: KITFLY_BUNDLE_OUT] [default: bundles]
  *   -n, --name <file>  Bundle filename [env: KITFLY_BUNDLE_NAME] [default: bundle.html]
+ *   --profile <name>   Active content profile [env: KITFLY_PROFILE]
  *   --raw              Include raw markdown in bundle [env: KITFLY_BUNDLE_RAW] [default: true]
  *   --no-raw           Don't include raw markdown
  *   --help             Show help message
@@ -21,29 +22,39 @@ import { ENGINE_ASSETS_DIR } from "../src/engine.ts";
 import { loadPluginInjections } from "../src/plugin-loader.ts";
 import {
 	buildBundleFooter,
+	buildLogoImgHtml,
 	buildSectionNav,
 	// Navigation/template building
-	buildSlideNav,
-	// Types
+	buildSlideNavHierarchical,
 	type ContentFile,
 	collectFiles,
+	// Types
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	// Config helpers
 	envString,
 	// Formatting
 	escapeHtml,
+	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	// YAML/Config parsing
+	loadDataBindings,
 	loadSiteConfig,
+	mergeFrontmatterWithBody,
 	// Markdown utilities
+	pagePathForData,
 	parseFrontmatter,
 	parseYaml,
+	resolveBindings,
 	resolveSiteVersion,
 	resolveStylesPath,
+	runPrebuildHooks,
 	type SiteConfig,
 	slugify,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme } from "../src/theme.ts";
@@ -55,6 +66,41 @@ const DEFAULT_NAME = "bundle.html";
 let ROOT = process.cwd();
 let OUT_DIR = DEFAULT_OUT;
 let BUNDLE_NAME = DEFAULT_NAME;
+let ACTIVE_PROFILE: string | undefined;
+
+async function applyDataBindingsToMarkdown(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<{ frontmatter: Record<string, unknown>; body: string }> {
+	const parsed = parseFrontmatter(rawMarkdown);
+	const dataRef = typeof parsed.frontmatter.data === "string" ? parsed.frontmatter.data.trim() : "";
+	if (!dataRef) return parsed;
+
+	const pagePath = pagePathForData(ROOT, config.docroot, filePath);
+	const bindings = await loadDataBindings(dataRef, pagePath, ROOT, config.docroot, config.dataroot);
+	return {
+		frontmatter: parsed.frontmatter,
+		body: resolveBindings(parsed.body, bindings, pagePath),
+	};
+}
+
+async function applyDataBindingsForSlides(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<string> {
+	const resolved = await applyDataBindingsToMarkdown(rawMarkdown, filePath, config);
+	return mergeFrontmatterWithBody(rawMarkdown, resolved.body);
+}
+
+function normalizeMsysPath(p: string): string {
+	// Git Bash / MSYS-style paths: /c/Users/... -> C:\Users\...
+	if (process.platform !== "win32") return p;
+	const m = p.match(/^\/([a-zA-Z])\/(.*)$/);
+	if (!m) return p;
+	return `${m[1].toUpperCase()}:\\${m[2].replaceAll("/", "\\")}`;
+}
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -65,6 +111,7 @@ interface ParsedArgs {
 	out?: string;
 	name?: string;
 	raw?: boolean;
+	profile?: string;
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
@@ -79,6 +126,9 @@ function parseArgs(argv: string[]): ParsedArgs {
 		} else if ((arg === "--name" || arg === "-n") && next && !next.startsWith("-")) {
 			result.name = next;
 			i++;
+		} else if (arg === "--profile" && next && !next.startsWith("-")) {
+			result.profile = next;
+			i++;
 		} else if (arg === "--raw") {
 			result.raw = true;
 		} else if (arg === "--no-raw") {
@@ -95,6 +145,7 @@ function getConfig(): {
 	out: string;
 	name: string;
 	raw: boolean;
+	profile?: string;
 } {
 	const args = parseArgs(process.argv.slice(2));
 	const legacyOut = envString("KITFLY_BUILD_OUT", DEFAULT_OUT);
@@ -106,6 +157,7 @@ function getConfig(): {
 		out,
 		name: args.name ?? envString("KITFLY_BUNDLE_NAME", DEFAULT_NAME),
 		raw,
+		profile: args.profile ?? process.env.KITFLY_PROFILE,
 	};
 }
 
@@ -305,22 +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);
-	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),
 					);
@@ -332,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>`;
@@ -376,18 +457,26 @@ function buildBundleSidebarHeader(
 	config: SiteConfig,
 	version: string | undefined,
 	brandLogo: string,
+	brandLogoDark?: string,
 ): string {
 	const brandTarget = config.brand.external ? ' target="_blank" rel="noopener"' : "";
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const productHref = config.home ? "#home" : "#";
 	const versionLabel = version ? `v${version}` : "unversioned";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const brandLogoHtml = buildLogoImgHtml({
+		logo: brandLogo,
+		logoDark: brandLogoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		onerrorFallback: true,
+	});
 
 	return `
       <div class="sidebar-header">
         <div class="logo ${logoClass}">
           <a href="${config.brand.url}" class="logo-icon" data-initial="${brandInitial}"${brandTarget}>
-            <img src="${brandLogo}" alt="${config.brand.name}" class="logo-img" onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')">
+            ${brandLogoHtml}
           </a>
           <span class="logo-text">
             <a href="${config.brand.url}" class="brand"${brandTarget}>${config.brand.name}</a>
@@ -427,6 +516,18 @@ async function inlineBrandAsset(assetPath: string): Promise<string> {
 			/* continue */
 		}
 	}
+
+	// Support any safe site-root-relative path (e.g., logos/footer.png).
+	const siteRootPath = validatePath(ROOT, ".", clean, false);
+	if (siteRootPath) {
+		try {
+			await stat(siteRootPath);
+			const uri = await fileToDataUri(siteRootPath);
+			if (uri) return uri;
+		} catch {
+			/* continue */
+		}
+	}
 	return assetPath;
 }
 
@@ -466,12 +567,26 @@ async function bundle() {
 
 	const config = await loadSiteConfig(ROOT, "Documentation");
 	console.log(`  ✓ Loaded config: "${config.title}" (${config.sections.length} sections)`);
+	if (config.prebuild?.length) {
+		await runPrebuildHooks(
+			config.prebuild,
+			ROOT,
+			"bundle",
+			ACTIVE_PROFILE,
+			config.dataroot || "data",
+		);
+		console.log(`  ✓ prebuild hooks (${config.prebuild.length})`);
+	}
 
 	const theme = await loadTheme(ROOT);
 	console.log(`  ✓ Loaded theme: "${theme.name || "default"}"`);
 	const prismUrls = getPrismUrls(theme);
 
-	const files = await collectFiles(ROOT, config);
+	const files = await filterByProfile(
+		await collectFiles(ROOT, config),
+		ACTIVE_PROFILE,
+		config.profiles,
+	);
 	if (files.length === 0) {
 		console.error("No content files found. Cannot create bundle.");
 		process.exit(1);
@@ -514,9 +629,10 @@ async function bundle() {
 				section: slide.section,
 			});
 		}
-		navHtml = buildSlideNav(slides, config, "slide-1");
+		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();
 
@@ -527,7 +643,27 @@ async function bundle() {
 				try {
 					await stat(homePath);
 					const content = await readFile(homePath, "utf-8");
-					const { frontmatter, body } = parseFrontmatter(content);
+					const { frontmatter, body } = await applyDataBindingsToMarkdown(
+						content,
+						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);
@@ -558,13 +694,29 @@ async function bundle() {
 				}
 				htmlContent = `<pre><code class="language-json">${escapeHtml(prettyJson)}</code></pre>`;
 			} else {
-				const { frontmatter, body } = parseFrontmatter(content);
+				const { frontmatter, body } = await applyDataBindingsToMarkdown(content, file.path, config);
 				if (frontmatter.title) {
 					title = frontmatter.title as string;
 				}
 				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
@@ -617,7 +769,19 @@ async function bundle() {
 
 	// Inline brand assets for self-contained bundle
 	const brandLogo = await inlineBrandAsset(config.brand.logo || "assets/brand/logo.png");
+	const brandLogoDark =
+		typeof config.brand.logoDark === "string"
+			? await inlineBrandAsset(config.brand.logoDark)
+			: undefined;
 	const brandFavicon = await inlineBrandAsset(config.brand.favicon || "assets/brand/favicon.png");
+	const footerLogo =
+		typeof config.footer?.logo === "string"
+			? await inlineBrandAsset(config.footer.logo)
+			: undefined;
+	const footerLogoDark =
+		typeof config.footer?.logoDark === "string"
+			? await inlineBrandAsset(config.footer.logoDark)
+			: undefined;
 
 	// Build the complete HTML document
 	const html = `<!DOCTYPE html>
@@ -672,7 +836,7 @@ ${assets.prismCssDark}
 <body class="${config.mode === "slides" ? "mode-slides" : "mode-docs"}">
   <div class="layout">
     <nav class="sidebar">
-${buildBundleSidebarHeader(config, version, brandLogo)}
+${buildBundleSidebarHeader(config, version, brandLogo, brandLogoDark)}
       <div class="sidebar-nav">
         ${navHtml}
       </div>
@@ -683,7 +847,7 @@ ${buildBundleSidebarHeader(config, version, brandLogo)}
       </article>
     </main>
   </div>
-  ${buildBundleFooter(version, config)}
+  ${buildBundleFooter(version, config, footerLogo, footerLogoDark)}
   <script>
 ${assets.prismCore}
   </script>
@@ -749,6 +913,9 @@ ${assets.mermaid}
       if (window.reinitMermaid) {
         window.reinitMermaid();
       }
+      if (window.reinitCharts) {
+        window.reinitCharts();
+      }
     }
 
     // Slides mode hash routing
@@ -864,7 +1031,7 @@ ${JSON.stringify(
 </html>`;
 
 	// Write the bundle
-	const outDir = join(ROOT, OUT_DIR);
+	const outDir = resolve(ROOT, normalizeMsysPath(OUT_DIR));
 	await mkdir(outDir, { recursive: true });
 	const bundlePath = join(outDir, BUNDLE_NAME);
 	await writeFile(bundlePath, html);
@@ -881,6 +1048,7 @@ export interface BundleOptions {
 	out?: string;
 	name?: string;
 	raw?: boolean; // Include raw markdown in bundle (default: true)
+	profile?: string;
 }
 
 let INCLUDE_RAW = true;
@@ -910,6 +1078,7 @@ export async function bundleSite(options: BundleOptions = {}) {
 	if (options.raw === false) {
 		INCLUDE_RAW = false;
 	}
+	ACTIVE_PROFILE = options.profile;
 	await bundle();
 }
 
@@ -922,6 +1091,7 @@ Usage: bun run bundle [folder] [options]
 Options:
   -o, --out <dir>       Output directory [env: KITFLY_BUNDLE_OUT] [default: ${DEFAULT_OUT}]
   -n, --name <file>     Bundle filename [env: KITFLY_BUNDLE_NAME] [default: ${DEFAULT_NAME}]
+  --profile <name>      Active content profile [env: KITFLY_PROFILE]
   --raw                 Include raw markdown in bundle [env: KITFLY_BUNDLE_RAW] [default: true]
   --no-raw              Don't include raw markdown
   --help                Show this help message
@@ -943,5 +1113,6 @@ Examples:
 		out: cfg.out,
 		name: cfg.name,
 		raw: cfg.raw,
+		profile: cfg.profile,
 	}).catch(console.error);
 }