npm - kitfly - Versions diffs - 0.2.0 → 0.2.1 - Mend

kitfly 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/scripts/dev.ts CHANGED Viewed

@@ -18,7 +18,13 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
 import { marked, Renderer } from "marked";
 import { ENGINE_ASSETS_DIR, ENGINE_SITE_DIR } from "../src/engine.ts";
-import { loadPluginInjections } from "../src/plugin-loader.ts";
+import {
+	loadPluginInjections,
+	PluginConfigError,
+	PluginIntegrityError,
+	PluginNetworkError,
+	PluginPolicyError,
+} from "../src/plugin-loader.ts";
 import {
 	buildBreadcrumbsSimple,
 	buildFooter,
@@ -37,6 +43,7 @@ import {
 	envString,
 	// Formatting
 	escapeHtml,
+	filterUnknownSlidesVisualsTypeDiagnostics,
 	// Provenance
 	generateProvenance,
 	// YAML/Config parsing
@@ -75,6 +82,60 @@ let daemonLog: {
 	error: (msg: string) => void;
 } | null = null;
+function isPluginLoaderError(error: unknown): error is Error {
+	return (
+		error instanceof PluginConfigError ||
+		error instanceof PluginIntegrityError ||
+		error instanceof PluginPolicyError ||
+		error instanceof PluginNetworkError
+	);
+}
+function pluginVersionMismatchHint(message: string): string {
+	const m = message.match(/^Plugin ([a-z0-9-]+) version mismatch: ([^ ]+) != ([^ ]+)$/i);
+	if (!m) return "";
+	const pluginId = m[1];
+	const expected = m[3];
+	return `Update <code>kitfly.plugins.yaml</code> to <code>${pluginId}@${expected}</code>, then refresh.`;
+}
+export function buildDevPluginErrorHtml(message: string): string {
+	const hint = pluginVersionMismatchHint(message);
+	const safeMessage = escapeHtml(message);
+	const hintBlock = hint
+		? `<p>${hint}</p>`
+		: "<p>Check <code>kitfly.plugins.yaml</code> and <code>registry/plugins.yaml</code>, then refresh.</p>";
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Plugin Configuration Error</title>
+  <style>
+    body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; margin: 0; background: #0b1020; color: #e8ecf3; }
+    main { max-width: 820px; margin: 8vh auto; padding: 1.25rem; }
+    .card { background: #131a2e; border: 1px solid #2a3557; border-radius: 12px; padding: 1rem 1.1rem; }
+    h1 { margin: 0 0 0.75rem; font-size: 1.25rem; }
+    p, li { line-height: 1.5; }
+    code { background: #0e1528; padding: 0.08rem 0.3rem; border-radius: 6px; border: 1px solid #2a3557; }
+    pre { margin: 0.8rem 0 0; padding: 0.75rem; background: #0e1528; border: 1px solid #2a3557; border-radius: 8px; overflow: auto; }
+    .muted { color: #b5bfd2; font-size: 0.92rem; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="card">
+      <h1>Plugin setup error</h1>
+      <p>Kitfly could not load one or more plugins for dev preview.</p>
+      ${hintBlock}
+      <pre><code>${safeMessage}</code></pre>
+      <p class="muted">After updating config, refresh this page. No dev server restart required.</p>
+    </div>
+  </main>
+</body>
+</html>`;
+}
 /** Log info — uses structured logger in daemon mode, console.log otherwise */
 function logInfo(msg: string): void {
 	if (daemonLog) daemonLog.info(msg);
@@ -367,7 +428,9 @@ async function renderSlidesPage(
 			let inner = "";
 			if (slide.kind === "markdown") {
 				if (validateFences) {
-					const diagnostics = validateSlidesVisualsFences(slide.body);
+					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
+						validateSlidesVisualsFences(slide.body),
+					);
 					if (diagnostics.length) {
 						const msg = diagnostics
 							.slice(0, 12)
@@ -854,19 +917,44 @@ async function main() {
 		return new Response("Not found", { status: 404 });
 	}
-	// Wrap with request logging middleware when in structured log mode
-	const fetch = daemonLog
-		? async (req: Request) => {
-				const start = performance.now();
-				const response = await handleRequest(req);
+	// Wrap with request logging + friendly plugin errors.
+	const fetch = async (req: Request) => {
+		const start = performance.now();
+		const url = new URL(req.url);
+		try {
+			const response = await handleRequest(req);
+			if (daemonLog && url.pathname !== "/__reload") {
 				const duration = (performance.now() - start).toFixed(0);
-				const url = new URL(req.url);
-				if (url.pathname !== "/__reload") {
-					daemonLog?.info(`${req.method} ${url.pathname} ${response.status} ${duration}ms`);
+				daemonLog.info(`${req.method} ${url.pathname} ${response.status} ${duration}ms`);
+			}
+			return response;
+		} catch (error) {
+			const duration = (performance.now() - start).toFixed(0);
+			const message = error instanceof Error ? error.message : String(error);
+			if (isPluginLoaderError(error)) {
+				if (daemonLog && url.pathname !== "/__reload") {
+					daemonLog.warn(
+						`${req.method} ${url.pathname} 500 ${duration}ms plugin error: ${message}`,
+					);
+				} else if (!daemonLog) {
+					logWarn(`Plugin error: ${message}`);
 				}
-				return response;
+				return new Response(buildDevPluginErrorHtml(message), {
+					status: 500,
+					headers: { "Content-Type": "text/html; charset=utf-8" },
+				});
 			}
-		: handleRequest;
+			if (daemonLog && url.pathname !== "/__reload") {
+				daemonLog.error(`${req.method} ${url.pathname} 500 ${duration}ms ${message}`);
+			} else if (!daemonLog) {
+				console.error(error);
+			}
+			return new Response("Internal server error", {
+				status: 500,
+				headers: { "Content-Type": "text/plain; charset=utf-8" },
+			});
+		}
+	};
 	// Create server
 	Bun.serve({

package/src/__tests__/build.test.ts CHANGED Viewed

@@ -365,7 +365,7 @@ plugins:
   slides-visuals:
     name: "Slides Visuals"
     description: "Test visuals"
-    version: "0.2.0"
+    version: "0.2.1"
     contract: "1"
     kitfly: ">=0.2.0 <1.0.0"
     license: MIT
@@ -383,15 +383,77 @@ plugins:
 		await writeFile(
 			join(siteDir, "kitfly.plugins.yaml"),
-			"plugins:\n  - slides-visuals@0.2.0\n",
+			"plugins:\n  - slides-visuals@0.2.1\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-visuals@0.2.0"');
+		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.1"');
 		expect(html).toContain(css);
 		expect(html).toContain(js);
 	});
+	it("ignores unknown slides-visuals block types while enforcing known contracts", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "slides" });
+		await writeMd(
+			siteDir,
+			"docs/deck.md",
+			`# Title
+:::future-thing
+note: this should pass through
+:::
+:::kpi
+label: Uptime
+value: 99.95%
+:::
+`,
+		);
+		const js = "console.log('slides visuals');";
+		const css = ".kitfly-visual{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "slides-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "slides-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-02-15"
+baseUrl: ""
+plugins:
+  slides-visuals:
+    name: "Slides Visuals"
+    description: "Test visuals"
+    version: "0.2.1"
+    contract: "1"
+    kitfly: ">=0.2.0 <1.0.0"
+    license: MIT
+    verified: true
+    modes: ["slides"]
+    assets:
+      js: "plugins-dist/slides-visuals.js"
+      css: "plugins-dist/slides-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-visuals@0.2.1\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="slides-visuals@0.2.1"');
+		expect(html).toContain("future-thing");
+	});
 });

package/src/__tests__/dev-plugin-errors.test.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { buildDevPluginErrorHtml } from "../../scripts/dev.ts";
+describe("dev plugin error page", () => {
+	it("shows actionable update hint for plugin version mismatch", () => {
+		const html = buildDevPluginErrorHtml("Plugin slides-visuals version mismatch: 0.2.0 != 0.2.1");
+		expect(html).toContain("Plugin setup error");
+		expect(html).toContain("kitfly.plugins.yaml");
+		expect(html).toContain("slides-visuals@0.2.1");
+	});
+	it("escapes error text and falls back to generic guidance", () => {
+		const html = buildDevPluginErrorHtml('Invalid plugin ref: bad"@1.0.0 <x>');
+		expect(html).toContain(
+			"Check <code>kitfly.plugins.yaml</code> and <code>registry/plugins.yaml</code>",
+		);
+		expect(html).toContain("bad&quot;@1.0.0 &lt;x&gt;");
+		expect(html).not.toContain('bad"@1.0.0 <x>');
+	});
+});

package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md ADDED Viewed

@@ -0,0 +1,5 @@
+:::flow-branching
+branches:
+  - "API Handler"
+  - "Static Files"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md ADDED Viewed

@@ -0,0 +1,6 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+merge: "Aggregator"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md ADDED Viewed

@@ -0,0 +1,3 @@
+:::staircase
+steps:
+:::

package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ :::timeline-horizontal
2	+ :::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md ADDED Viewed

@@ -0,0 +1,7 @@
+:::flow-branching
+source: "Incoming Request"
+branches:
+  - "API Handler"
+  - "Static Files"
+  - "WebSocket"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md ADDED Viewed

@@ -0,0 +1,8 @@
+:::flow-branching
+source: "Incoming Request"
+split: "Route"
+branches:
+  - "API Handler"
+  - "Static Files"
+  - "WebSocket"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md ADDED Viewed

@@ -0,0 +1,7 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+  - "DB Logs"
+target: "Dashboard"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md ADDED Viewed

@@ -0,0 +1,8 @@
+:::flow-converging
+sources:
+  - "Frontend Logs"
+  - "API Logs"
+  - "DB Logs"
+merge: "Aggregator"
+target: "Dashboard"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md ADDED Viewed

@@ -0,0 +1,7 @@
+:::staircase
+direction: down
+steps:
+  - "Optimized"
+  - "Managed"
+  - "Defined"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md ADDED Viewed

@@ -0,0 +1,8 @@
+:::staircase
+steps:
+  - "Ad Hoc"
+  - "Repeatable"
+  - "Defined"
+  - "Managed"
+  - "Optimized"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-horizontal.md ADDED Viewed

@@ -0,0 +1,9 @@
+:::timeline-horizontal
+events:
+  - label: "Kickoff"
+    date: "Jan 2026"
+  - label: "Alpha"
+    date: "Mar 2026"
+  - label: "GA Release"
+    date: "Jun 2026"
+:::

package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-vertical.md ADDED Viewed

@@ -0,0 +1,10 @@
+:::timeline-vertical
+events:
+  - label: "Research Phase"
+    date: "Q1"
+  - label: "Prototype"
+  - label: "User Testing"
+    date: "Q3"
+  - label: "Launch"
+    date: "Q4"
+:::

package/src/__tests__/shared.test.ts CHANGED Viewed

@@ -24,6 +24,7 @@ import {
 	envString,
 	escapeHtml,
 	exists,
+	filterUnknownSlidesVisualsTypeDiagnostics,
 	formatDate,
 	generateProvenance,
 	getGitInfo,
@@ -42,6 +43,7 @@ import {
 	stripQuotes,
 	toUrlPath,
 	validatePath,
+	validateSlidesVisualsFences,
 } from "../shared.ts";
 describe("slugify", () => {
@@ -155,6 +157,27 @@ Still one slide`;
 	});
 });
+describe("slides-visuals diagnostics filtering", () => {
+	it("drops unknown-type diagnostics while preserving schema violations", () => {
+		const markdown = `:::future-thing
+foo: bar
+:::
+:::kpi
+label: Missing value
+:::`;
+		const diagnostics = validateSlidesVisualsFences(markdown);
+		const filtered = filterUnknownSlidesVisualsTypeDiagnostics(diagnostics);
+		expect(
+			diagnostics.some((d) => d.message.startsWith("Unknown slides-visuals block type:")),
+		).toBe(true);
+		expect(filtered.some((d) => d.message.startsWith("Unknown slides-visuals block type:"))).toBe(
+			false,
+		);
+		expect(filtered.some((d) => d.message.includes("Missing required key: value"))).toBe(true);
+	});
+});
 describe("segmentSlides", () => {
 	it("uses frontmatter title and class when present", () => {
 		const input = `---

package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts CHANGED Viewed

@@ -112,3 +112,36 @@ test("slides-visuals: rowCells parses JSON array strings", async () => {
 	const hooks = await loadHooks();
 	expect(hooks.rowCells('["A", "B", "C"]')).toEqual(["A", "B", "C"]);
 });
+test("slides-visuals: absorbed scalar marker preserves preceding item (flow-converging)", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+	const out = parseBodyNodesWithFirstLines(
+		["sources:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "Frontend Logs\ntarget: Dashboard"),
+			new FakeElement("LI", "API Logs"),
+		]),
+		"flow-converging",
+	);
+	expect(out.target).toBe("Dashboard");
+	expect(out.sources).toEqual(["Frontend Logs", "API Logs"]);
+});
+test("slides-visuals: parses object list items for timeline events", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+	const out = parseBodyNodesWithFirstLines(
+		["events:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "label: Kickoff\ndate: Jan 2026"),
+			new FakeElement("LI", "label: Alpha"),
+		]),
+		"timeline-horizontal",
+	);
+	expect(out.events).toEqual([{ label: "Kickoff", date: "Jan 2026" }, { label: "Alpha" }]);
+});

package/src/shared.ts CHANGED Viewed

@@ -506,6 +506,11 @@ const SLIDES_VISUALS_TYPES = new Set([
 	"layer-cake",
 	"pyramid",
 	"funnel",
+	"timeline-horizontal",
+	"timeline-vertical",
+	"flow-branching",
+	"flow-converging",
+	"staircase",
 ]);
 const SLIDES_VISUALS_RULES: Record<
@@ -564,6 +569,31 @@ const SLIDES_VISUALS_RULES: Record<
 		scalars: [],
 		lists: { stages: { kind: "strings" } },
 	},
+	"timeline-horizontal": {
+		required: ["events"],
+		scalars: [],
+		lists: { events: { kind: "objects", fields: ["label"], optional: ["date"] } },
+	},
+	"timeline-vertical": {
+		required: ["events"],
+		scalars: [],
+		lists: { events: { kind: "objects", fields: ["label"], optional: ["date"] } },
+	},
+	"flow-branching": {
+		required: ["source", "branches"],
+		scalars: ["source", "split"],
+		lists: { branches: { kind: "strings" } },
+	},
+	"flow-converging": {
+		required: ["sources", "target"],
+		scalars: ["target", "merge"],
+		lists: { sources: { kind: "strings" } },
+	},
+	staircase: {
+		required: ["steps"],
+		scalars: ["direction"],
+		lists: { steps: { kind: "strings" } },
+	},
 };
 /**
@@ -754,6 +784,12 @@ export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenc
 	return diagnostics;
 }
+export function filterUnknownSlidesVisualsTypeDiagnostics(
+	diagnostics: SlidesVisualsFenceDiagnostic[],
+): SlidesVisualsFenceDiagnostic[] {
+	return diagnostics.filter((d) => !d.message.startsWith("Unknown slides-visuals block type:"));
+}
 /**
  * Split markdown content into slide chunks using explicit delimiter.
  * Delimiter lines inside fenced code blocks are ignored.