kitfly 0.2.1 → 0.2.4

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();

package/src/__tests__/brief.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for the Brief template definition
+ *
+ * Covers: src/templates/brief.ts
+ * Strategy: import the template directly, verify structure and generated content
+ */
+
+import { describe, expect, it } from "vitest";
+import { brief } from "../templates/brief.ts";
+import type { BrandingConfig, TemplateContext, TemplateFile } from "../templates/schema.ts";
+
+function makeCtx(overrides?: Partial<TemplateContext>): TemplateContext {
+	const branding: BrandingConfig = {
+		siteName: "Test Brief",
+		brandName: "Acme Corp",
+		brandUrl: "https://acme.example.com",
+		primaryColor: "#2563eb",
+		footerText: "Footer text",
+	};
+	return {
+		name: "test-brief",
+		branding,
+		template: brief,
+		year: 2026,
+		...overrides,
+	};
+}
+
+function resolveContent(file: TemplateFile, ctx: TemplateContext): string {
+	return typeof file.content === "function" ? file.content(ctx) : file.content;
+}
+
+function findFile(path: string): TemplateFile {
+	const f = brief.files.find((entry) => entry.path === path);
+	if (!f) throw new Error(`Template file not found: ${path}`);
+	return f;
+}
+
+describe("brief template definition", () => {
+	it("has correct identity metadata", () => {
+		expect(brief.id).toBe("brief");
+		expect(brief.name).toBe("Brief");
+		expect(brief.version).toBe(1);
+		expect(brief.extends).toBe("minimal");
+	});
+
+	it("defines exactly four sections", () => {
+		expect(brief.sections).toHaveLength(4);
+		expect(brief.sections.map((s) => s.name)).toEqual([
+			"Product",
+			"Use Cases",
+			"Getting Started",
+			"Reference",
+		]);
+		expect(brief.sections.map((s) => s.path)).toEqual([
+			"content/product",
+			"content/use-cases",
+			"content/getting-started",
+			"content/reference",
+		]);
+	});
+
+	it("defines unique file paths", () => {
+		const paths = brief.files.map((f) => f.path);
+		expect(new Set(paths).size).toBe(paths.length);
+	});
+});
+
+describe("brief site.yaml", () => {
+	const ctx = makeCtx();
+	const file = findFile("site.yaml");
+
+	it("includes branding and all four section paths", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain('title: "Test Brief"');
+		expect(content).toContain('name: "Acme Corp"');
+		expect(content).toContain('url: "https://acme.example.com"');
+		expect(content).toContain('"content/product"');
+		expect(content).toContain('"content/use-cases"');
+		expect(content).toContain('"content/getting-started"');
+		expect(content).toContain('"content/reference"');
+		expect(content).toContain('home: "index.md"');
+	});
+});
+
+describe("brief starter files", () => {
+	const ctx = makeCtx();
+	const starterFiles = [
+		"index.md",
+		"content/product/overview.md",
+		"content/product/capabilities.md",
+		"content/use-cases/overview.md",
+		"content/use-cases/example-use-case.md",
+		"content/getting-started/overview.md",
+		"content/getting-started/requirements.md",
+		"content/reference/architecture.md",
+		"content/reference/faq.md",
+		"content/reference/contacts.md",
+	];
+
+	it("ships all 10 starter files", () => {
+		expect(starterFiles).toHaveLength(10);
+		for (const path of starterFiles) {
+			expect(brief.files.some((f) => f.path === path)).toBe(true);
+		}
+	});
+
+	it("includes frontmatter in markdown starter files", () => {
+		for (const path of starterFiles) {
+			const content = resolveContent(findFile(path), ctx);
+			expect(content).toMatch(/^---\n/);
+		}
+	});
+
+	it("includes customize markers in starter files", () => {
+		for (const path of starterFiles) {
+			const content = resolveContent(findFile(path), ctx);
+			expect(content).toContain("<!-- ← CUSTOMIZE");
+		}
+	});
+
+	it("uses professional framing in index and use cases", () => {
+		const index = resolveContent(findFile("index.md"), ctx);
+		expect(index).toContain("At a Glance");
+		expect(index).toContain("[Use Cases](/content/use-cases/overview)");
+
+		const useCases = resolveContent(findFile("content/use-cases/example-use-case.md"), ctx);
+		expect(useCases).toContain("## Scenario");
+		expect(useCases).toContain("## Outcome");
+		expect(useCases).toContain("| Metric | Before | After |");
+	});
+});
+
+describe("brief CUSTOMIZING.md", () => {
+	const ctx = makeCtx();
+	const file = findFile("CUSTOMIZING.md");
+
+	it("documents template identity and external-audience tone", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain("template: brief");
+		expect(content).toContain("clients, prospects, and partners");
+		expect(content).toContain("Informational and professional");
+		expect(content).toContain("Not sales copy");
+	});
+
+	it("guides use-case duplication workflow", () => {
+		const content = resolveContent(file, ctx);
+		expect(content).toContain("Duplicate `content/use-cases/example-use-case.md`");
+		expect(content).toContain("problem -> solution -> outcome");
+	});
+});

package/src/__tests__/build.test.ts

@@ -35,7 +35,8 @@ async function writeSiteYaml(dir: string, extra: Record<string, unknown> = {}):
 	const mode = extra.mode ? `mode: ${extra.mode}\n` : "";
 	const aspect = extra.aspect ? `aspect: ${extra.aspect}\n` : "";
 	const home = extra.home ? `home: ${extra.home}\n` : "";
-	const yaml = `title: ${title}\n${version}${mode}${aspect}brand:\n${brand}\n${home}sections:\n${sections}\n`;
+	const footer = extra.footer ? `footer:\n${extra.footer}\n` : "";
+	const yaml = `title: ${title}\n${version}${mode}${aspect}brand:\n${brand}\n${home}${footer}sections:\n${sections}\n`;
 	await writeFile(join(dir, "site.yaml"), yaml);
 }
 
@@ -216,6 +217,45 @@ describe("build", () => {
 		expect(html).toContain("unversioned");
 	});
 
+	it("renders footer logo with static path prefix in built output", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, {
+			footer: '  logo: "assets/brand/footer-logo.png"\n  logoAlt: "Footer Brand"\n  logoHeight: 24',
+		});
+		await writeMd(siteDir, "docs/page.md", "# Page");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="./assets/brand/footer-logo.png"');
+		expect(html).toContain('alt="Footer Brand"');
+		expect(html).toContain("max-height: 24px");
+	});
+
+	it("renders light/dark variants for header and footer logos when configured", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, {
+			brand:
+				'  name: Test\n  url: /\n  logo: "assets/brand/logo.png"\n  logoDark: "assets/brand/logo-dark.png"',
+			footer:
+				'  logo: "assets/brand/footer-logo.png"\n  logoDark: "assets/brand/footer-logo-dark.png"',
+		});
+		await writeMd(siteDir, "docs/page.md", "# Page");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("logo-img logo-light");
+		expect(html).toContain("logo-img logo-dark");
+		expect(html).toContain("./assets/brand/logo-dark.png");
+		expect(html).toContain("footer-logo-img logo-light");
+		expect(html).toContain("footer-logo-img logo-dark");
+		expect(html).toContain("./assets/brand/footer-logo-dark.png");
+	});
+
 	it("builds a single-page hash-routed deck when mode is slides", async () => {
 		const siteDir = await makeTempDir();
 		const outDir = "out";
@@ -332,6 +372,87 @@ plugins:
 		expect(html).toContain(js);
 	});
 
+	it("preserves dollar-sign replacement patterns in injected plugin JS", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(siteDir, "docs/page.md", "# Test");
+
+		const js = "const expr='x'; const sample = `$${expr}$`; const marker = '$`';";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "literal.js"), js, "utf-8");
+
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-02-16"
+baseUrl: ""
+plugins:
+  literal:
+    name: "Literal"
+    description: "Replacement pattern regression"
+    version: "1.0.0"
+    contract: "1"
+    kitfly: ">=0.2.0 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/literal.js"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+`,
+			"utf-8",
+		);
+
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - literal@1.0.0\n", "utf-8");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("const sample = `$${expr}$`;");
+		expect(html).toContain("const marker = '$`';");
+		expect(html).not.toContain("<!DOCTYPE html><html");
+	});
+
+	it("preserves dollar-sign replacement patterns in markdown content", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(
+			siteDir,
+			"docs/dollars.md",
+			"# Dollars\n\nLiteral dollars: $$ and $` and $' and $&\n\nMath style: $$x^2$$",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain("Literal dollars: $$ and $` and $&#39; and $&amp;");
+		expect(html).toContain("Math style: $$x^2$$");
+		expect(html.match(/<!DOCTYPE html>/g)?.length ?? 0).toBe(1);
+	});
+
+	it("injects latex plugin in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir);
+		await writeMd(
+			siteDir,
+			"docs/math.md",
+			"# Math\n\nInline: $x^2$.\n\n$$\n\\\\int_0^1 x^2 dx\n$$\n\n```math\n\\\\sum_{i=1}^{n} i\n```",
+		);
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - latex@0.2.2\n", "utf-8");
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="latex@0.2.2"');
+		expect(html).toContain("const KATEX_JS_URL =");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css");
+	});
+
 	it("injects slides-only plugins when mode=slides", async () => {
 		const siteDir = await makeTempDir();
 		const outDir = "out";
@@ -395,6 +516,53 @@ plugins:
 		expect(html).toContain(js);
 	});
 
+	it("injects slides-charts-lite plugin in slides mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "slides" });
+		await writeMd(
+			siteDir,
+			"docs/deck.md",
+			`# Chart
+
+\`\`\`chart
+kind: bar
+title: Revenue
+labels: ["Q1", "Q2"]
+data: [10, 12]
+\`\`\`
+`,
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+		expect(html).toContain("kitfly-chart-wrapper");
+	});
+
+	it("does not inject slides-charts-lite in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(siteDir, "docs/page.md", "# Page");
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await build({ folder: siteDir, out: outDir });
+
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).not.toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+	});
+
 	it("ignores unknown slides-visuals block types while enforcing known contracts", async () => {
 		const siteDir = await makeTempDir();
 		const outDir = "out";
@@ -456,4 +624,128 @@ plugins:
 		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.1"');
 		expect(html).toContain("future-thing");
 	});
+
+	it("enforces planning-visuals fence contract in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(
+			siteDir,
+			"docs/plan.md",
+			`# Plan
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::
+`,
+		);
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(build({ folder: siteDir, out: outDir })).rejects.toThrow(
+			/planning-visuals fence contract violations/i,
+		);
+	});
+
+	it("ignores unknown planning-visuals block types while enforcing known contracts", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(
+			siteDir,
+			"docs/plan.md",
+			`# Plan
+
+:::future-plan
+note: pass-through
+:::
+
+:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-08
+tracks:
+  - label: Wave 1
+    depth: 1
+    start: 2026-04
+    end: 2026-06
+:::
+`,
+		);
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(build({ folder: siteDir, out: outDir })).resolves.toBeUndefined();
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="planning-visuals@0.2.4"');
+		expect(html).toContain("future-plan");
+	});
 });