kitfly 0.2.3 → 0.2.4

package/src/__tests__/planning-visuals-runtime.bun.test.ts

@@ -0,0 +1,192 @@
+import { expect, test } from "bun:test";
+
+type PlanningVisualsHooks = {
+	parseFence: (text: string) => { type: string; data: Record<string, unknown> } | null;
+	buildAxisCellLabel: (
+		unit: string,
+		info: { year: number; week?: number; month?: number; label: string },
+		prev: { year: number; week?: number; month?: number; label: string } | null,
+		index: number,
+		totalUnits: number,
+	) => string;
+	weekLabelStepForUnits: (totalUnits: number) => number;
+	weekAxisContextLabel: (
+		startInfo: { year: number; week: number; label: string },
+		endInfo: { year: number; week: number; label: string },
+	) => string;
+	parseListItemText: (rawText: string) => {
+		item: Record<string, string>;
+		switchListKey: string | null;
+	};
+	assignMarkerLabelLanes: (markers: Array<Record<string, any>>) => {
+		markers: Array<Record<string, any>>;
+		laneCount: number;
+	};
+	parseMarkerPosition: (value: string, unit: string) => number | null;
+	parseUnitOrdinal: (value: string, unit: string) => number | null;
+	weekLabelFromOrdinal: (ordinal: number) => { year: number; week: number; label: string };
+	monthLabelFromOrdinal: (ordinal: number) => { year: number; month: number; label: string };
+};
+
+async function loadHooks(): Promise<PlanningVisualsHooks> {
+	// @ts-expect-error JS plugin registers test hooks on globalThis in non-DOM environments.
+	await import("../../plugins-dist/planning-visuals.js");
+	const hooks = (globalThis as any).__kitflyPlanningVisualsTest as PlanningVisualsHooks | undefined;
+	if (!hooks) throw new Error("planning-visuals test hooks not found on globalThis");
+	return hooks;
+}
+
+test("planning-visuals: week roundtrip keeps same label", async () => {
+	const hooks = await loadHooks();
+	const ordinal = hooks.parseUnitOrdinal("2026-W14", "week");
+	expect(ordinal).not.toBeNull();
+	const label = hooks.weekLabelFromOrdinal(ordinal as number);
+	expect(label.label).toBe("W14");
+	expect(label.year).toBe(2026);
+});
+
+test("planning-visuals: week boundary label resolves correct year", async () => {
+	const hooks = await loadHooks();
+	const ordinal = hooks.parseUnitOrdinal("2027-W01", "week");
+	expect(ordinal).not.toBeNull();
+	const label = hooks.weekLabelFromOrdinal(ordinal as number);
+	expect(label.label).toBe("W01");
+	expect(label.year).toBe(2027);
+});
+
+test("planning-visuals: compact week axis uses sparse full week labels", async () => {
+	const hooks = await loadHooks();
+	expect(hooks.weekLabelStepForUnits(28)).toBe(4);
+	const first = hooks.weekLabelFromOrdinal(hooks.parseUnitOrdinal("2026-W10", "week") as number);
+	const interior = hooks.weekLabelFromOrdinal(
+		(hooks.parseUnitOrdinal("2026-W10", "week") as number) + 4,
+	);
+	const firstText = hooks.buildAxisCellLabel("week", first, null, 0, 28);
+	const interiorText = hooks.buildAxisCellLabel("week", interior, first, 4, 28);
+	expect(firstText.startsWith("W10")).toBe(true);
+	expect(interiorText).toBe("W14");
+});
+
+test("planning-visuals: week axis context label is explicit for audience clarity", async () => {
+	const hooks = await loadHooks();
+	const start = hooks.weekLabelFromOrdinal(hooks.parseUnitOrdinal("2026-W10", "week") as number);
+	const end = hooks.weekLabelFromOrdinal(hooks.parseUnitOrdinal("2026-W36", "week") as number);
+	const context = hooks.weekAxisContextLabel(start, end);
+	expect(context).toBe("ISO Weeks W10-W36 (2026)");
+});
+
+test("planning-visuals: parseFence preserves interleaved row order from repeated lists", async () => {
+	const hooks = await loadHooks();
+	const parsed = hooks.parseFence(
+		`:::gantt
++time-unit: week
++time-start: 2026-W14
++time-end: 2026-W20
++tracks:
++  - label: Wave 1
++    depth: 1
++    start: 2026-W14
++    end: 2026-W16
++milestones:
++  - label: Go/No-Go
++    date: 2026-W15
++tracks:
++  - label: Wave 2
++    depth: 1
++    start: 2026-W17
++    end: 2026-W20
++:::`.replace(/^\+/gm, ""),
+	);
+
+	expect(parsed?.type).toBe("gantt");
+	const order = (parsed?.data.__rowOrder as Array<{ kind: string; index: number }>) || [];
+	expect(order).toEqual([
+		{ kind: "track", index: 0 },
+		{ kind: "milestone", index: 0 },
+		{ kind: "track", index: 1 },
+	]);
+});
+
+test("planning-visuals: parseFence parses markers list", async () => {
+	const hooks = await loadHooks();
+	const parsed = hooks.parseFence(
+		`:::gantt
++time-unit: week
++time-start: 2026-W14
++time-end: 2026-W30
++markers:
++  - label: Go/No-Go
++    date: 2026-W20
++  - label: Phase Gate
++    date: 2026-W28
++tracks:
++  - label: Phase 1
++    depth: 1
++    start: 2026-W14
++    end: 2026-W24
++:::`.replace(/^\+/gm, ""),
+	);
+
+	expect(parsed?.type).toBe("gantt");
+	const markers = parsed?.data.markers as Array<Record<string, string>>;
+	expect(markers).toHaveLength(2);
+	expect(markers[0].label).toBe("Go/No-Go");
+	expect(markers[0].date).toBe("2026-W20");
+	expect(markers[1].label).toBe("Phase Gate");
+	expect(markers[1].date).toBe("2026-W28");
+});
+
+test("planning-visuals: parseFence keeps optional marker color", async () => {
+	const hooks = await loadHooks();
+	const parsed = hooks.parseFence(
+		`:::gantt
+time-unit: month
+time-start: 2026-03
+time-end: 2026-10
+markers:
+  - label: Go/No-Go
+    date: 2026-05-26
+    color: #38bdf8
+tracks:
+  - label: Phase 1
+    depth: 1
+    start: 2026-03
+    end: 2026-06
+:::`.replace(/^\+/gm, ""),
+	);
+	const markers = parsed?.data.markers as Array<Record<string, string>>;
+	expect(markers).toHaveLength(1);
+	expect(markers[0].color).toBe("#38bdf8");
+});
+
+test("planning-visuals: marker parser supports day precision in month mode", async () => {
+	const hooks = await loadHooks();
+	const monthCenter = hooks.parseMarkerPosition("2026-05", "month");
+	const monthDay = hooks.parseMarkerPosition("2026-05-26", "month");
+	expect(monthCenter).not.toBeNull();
+	expect(monthDay).not.toBeNull();
+	expect(monthDay as number).toBeGreaterThan(monthCenter as number);
+	expect(hooks.parseMarkerPosition("2026-02-30", "month")).toBeNull();
+});
+
+test("planning-visuals: list item parser detects in-item list key switch", async () => {
+	const hooks = await loadHooks();
+	const parsed = hooks.parseListItemText(
+		`label: "P66 Conf (May 26)"
+date: "2026-05"
+tracks:`,
+	);
+	expect(parsed.item.label).toBe("P66 Conf (May 26)");
+	expect(parsed.item.date).toBe("2026-05");
+	expect(parsed.switchListKey).toBe("tracks");
+});
+
+test("planning-visuals: marker layout assigns separate lanes for nearby labels", async () => {
+	const hooks = await loadHooks();
+	const layout = hooks.assignMarkerLabelLanes([
+		{ label: "Conference", left: 40, color: "" },
+		{ label: "Go-Live", left: 42, color: "" },
+	]);
+	expect(layout.laneCount).toBeGreaterThan(1);
+	expect(layout.markers[0].__lane).not.toBe(layout.markers[1].__lane);
+});

package/src/__tests__/shared.test.ts

@@ -19,6 +19,7 @@ import {
 	buildToc,
 	type ContentFile,
 	collectFiles,
+	collectPlanningVisualsContainmentWarnings,
 	collectSlides,
 	envBool,
 	envInt,
@@ -26,6 +27,7 @@ import {
 	escapeHtml,
 	exists,
 	filterByProfile,
+	filterUnknownPlanningVisualsTypeDiagnostics,
 	filterUnknownSlidesVisualsTypeDiagnostics,
 	formatDate,
 	generateProvenance,
@@ -50,6 +52,7 @@ import {
 	stripQuotes,
 	toUrlPath,
 	validatePath,
+	validatePlanningVisualsFences,
 	validateSlidesVisualsFences,
 } from "../shared.ts";
 
@@ -450,6 +453,124 @@ label: Missing value
 	});
 });
 
+describe("planning-visuals diagnostics filtering", () => {
+	it("drops unknown-type diagnostics while preserving schema violations", () => {
+		const markdown = `:::future-planning
+foo: bar
+:::
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::`;
+		const diagnostics = validatePlanningVisualsFences(markdown);
+		const filtered = filterUnknownPlanningVisualsTypeDiagnostics(diagnostics);
+		expect(
+			diagnostics.some((d) => d.message.startsWith("Unknown planning-visuals block type:")),
+		).toBe(true);
+		expect(filtered.some((d) => d.message.startsWith("Unknown planning-visuals block type:"))).toBe(
+			false,
+		);
+		expect(filtered.some((d) => d.message.includes("Missing required key: tracks"))).toBe(true);
+	});
+});
+
+describe("planning-visuals containment warnings", () => {
+	it("returns non-fatal containment warnings when rows exceed axis", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-06
+tracks:
+  - label: Wave 1
+    depth: 1
+    start: 2026-03
+    end: 2026-07
+milestones:
+  - label: Late marker
+    date: 2026-08
+:::`;
+		const warnings = collectPlanningVisualsContainmentWarnings(markdown);
+		expect(warnings.some((w) => w.message.includes("Track range is outside axis"))).toBe(true);
+		expect(warnings.some((w) => w.message.includes("Milestone date is outside axis"))).toBe(true);
+	});
+
+	it("warns when marker date is outside axis range", () => {
+		const markdown = `:::gantt
+time-unit: week
+time-start: 2026-W14
+time-end: 2026-W20
+markers:
+  - label: Late gate
+    date: 2026-W22
+tracks:
+  - label: Phase 1
+    depth: 1
+    start: 2026-W14
+    end: 2026-W18
+:::`;
+		const warnings = collectPlanningVisualsContainmentWarnings(markdown);
+		expect(warnings.some((w) => w.message.includes("Marker date is outside axis"))).toBe(true);
+	});
+});
+
+describe("planning-visuals marker validation", () => {
+	it("accepts valid markers", () => {
+		const markdown = `:::gantt
+time-unit: week
+time-start: 2026-W14
+time-end: 2026-W30
+markers:
+  - label: Go/No-Go
+    date: 2026-W20
+tracks:
+  - label: Phase 1
+    depth: 1
+    start: 2026-W14
+    end: 2026-W24
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags).toHaveLength(0);
+	});
+
+	it("rejects marker with mismatched date format", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-10
+markers:
+  - label: Gate
+    date: 2026-W20
+tracks:
+  - label: Build
+    depth: 1
+    start: 2026-04
+    end: 2026-07
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags.some((d) => d.message.includes("Marker date must match month format"))).toBe(true);
+	});
+
+	it("accepts month markers with day precision", () => {
+		const markdown = `:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-10
+markers:
+  - label: Conference
+    date: 2026-05-26
+tracks:
+  - label: Build
+    depth: 1
+    start: 2026-04
+    end: 2026-07
+:::`;
+		const diags = validatePlanningVisualsFences(markdown);
+		expect(diags).toHaveLength(0);
+	});
+});
+
 describe("segmentSlides", () => {
 	it("uses frontmatter title and class when present", () => {
 		const input = `---

package/src/cli.ts

@@ -12,6 +12,9 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadSiteConfig } from "./shared.ts";
 
+// Exit cleanly when piped output is closed early (e.g., `kitfly docs show x | less` then quit)
+process.on("SIGPIPE", () => process.exit(0));
+
 // Resolve paths relative to CLI location (works in binary too)
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
@@ -76,6 +79,7 @@ Usage:
   kitfly servers          List running dev servers
   kitfly stop <port|all>  Stop dev server(s)
   kitfly logs <port>      View daemon server logs
+  kitfly docs [list|show]  Browse embedded documentation
   kitfly version          Show version (use 'version extended' for details)
   kitfly help             Show this help
 
@@ -275,7 +279,7 @@ async function main() {
 
 			if (daemon) {
 				// Daemon mode: spawn detached process using shell redirection
-				const { mkdir, writeFile } = await import("node:fs/promises");
+				const { mkdir, writeFile, open: fsOpen } = await import("node:fs/promises");
 				const logsDir = join(getKitflyHome(), "logs");
 				await mkdir(logsDir, { recursive: true });
 
@@ -287,19 +291,53 @@ async function main() {
 
 				// Build command with shell redirection for logging
 				// Pass --log-format structured so dev.ts enables structured request logging
-				// Use nohup to prevent SIGHUP on terminal close
 				const profileArg = profile ? ` --profile "${profile}"` : "";
-				const shellCmd = `nohup bun run "${devScript}" "${folder}" --port ${port} --host "${host}"${profileArg} --no-open --log-format structured > "${logPath}" 2>&1 &`;
-
-				const proc = Bun.spawn(["sh", "-c", shellCmd], {
-					cwd: process.cwd(),
-					stdout: "ignore",
-					stderr: "ignore",
-					stdin: "ignore",
-				});
 
-				// Wait for shell to spawn the background process
-				await proc.exited;
+				// Open log file as a write handle to pass as stdout/stderr for the child
+				const logFd = await fsOpen(logPath, "a");
+
+				let proc: ReturnType<typeof Bun.spawn>;
+				if (process.platform === "win32") {
+					// On Windows, use Bun.spawn with detached:true and stdio redirected to log file.
+					// nohup and sh -c are not available; Bun's detached mode achieves the same.
+					const args = [
+						"bun",
+						"run",
+						devScript,
+						folder,
+						"--port",
+						String(port),
+						"--host",
+						host,
+						...(profile ? ["--profile", profile] : []),
+						"--no-open",
+						"--log-format",
+						"structured",
+					];
+					proc = Bun.spawn(args, {
+						cwd: process.cwd(),
+						stdout: logFd.fd,
+						stderr: logFd.fd,
+						stdin: "ignore",
+						detached: true,
+					});
+					proc.unref();
+					await logFd.close();
+					// Give Windows a moment to spawn the child before proc.exited resolves
+					await new Promise((resolve) => setTimeout(resolve, 200));
+				} else {
+					// Unix: nohup via sh -c keeps the process alive after terminal close
+					await logFd.close();
+					const shellCmd = `nohup bun run "${devScript}" "${folder}" --port ${port} --host "${host}"${profileArg} --no-open --log-format structured > "${logPath}" 2>&1 &`;
+					proc = Bun.spawn(["sh", "-c", shellCmd], {
+						cwd: process.cwd(),
+						stdout: "ignore",
+						stderr: "ignore",
+						stdin: "ignore",
+					});
+					// Wait for shell to spawn the background process
+					await proc.exited;
+				}
 
 				// Give server a moment to start
 				await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -538,12 +576,47 @@ async function main() {
 			const follow = flags.follow === true || flags.f === true;
 
 			if (follow) {
-				// tail -f equivalent using Bun.spawn
-				const proc = Bun.spawn(["tail", "-f", logFile], {
-					stdout: "inherit",
-					stderr: "inherit",
-				});
-				await proc.exited;
+				if (process.platform !== "win32") {
+					// Unix: tail -f is available and efficient
+					const proc = Bun.spawn(["tail", "-f", logFile], {
+						stdout: "inherit",
+						stderr: "inherit",
+					});
+					await proc.exited;
+				} else {
+					// Windows: tail -f is not available; poll the file for new content
+					const { watch } = await import("node:fs");
+					const { open: fsOpen } = await import("node:fs/promises");
+					let fd: import("node:fs/promises").FileHandle;
+					try {
+						fd = await fsOpen(logFile, "r");
+					} catch {
+						console.error(`No log file found for port ${logPort}`);
+						console.error(`  Expected: ${logFile}`);
+						process.exit(1);
+					}
+					// Print existing content first
+					const existing = await fd.readFile("utf-8");
+					if (existing.length > 0) process.stdout.write(existing);
+					let offset = Buffer.byteLength(existing, "utf-8");
+					// Watch for changes and stream new bytes
+					const watcher = watch(logFile, async () => {
+						const buf = Buffer.alloc(65536);
+						const { bytesRead } = await fd.read(buf, 0, buf.length, offset);
+						if (bytesRead > 0) {
+							offset += bytesRead;
+							process.stdout.write(buf.subarray(0, bytesRead));
+						}
+					});
+					// Keep running until Ctrl+C
+					await new Promise<void>((resolve) => {
+						process.on("SIGINT", () => {
+							watcher.close();
+							void fd.close();
+							resolve();
+						});
+					});
+				}
 			} else {
 				const { readFile } = await import("node:fs/promises");
 				try {
@@ -562,6 +635,28 @@ async function main() {
 			break;
 		}
 
+		case "docs": {
+			const sub = positional[0];
+			const { docsList, docsShow } = await import("./commands/docs.ts");
+			if (!sub || sub === "list") {
+				docsList();
+			} else if (sub === "show") {
+				const slug = positional[1];
+				if (!slug) {
+					console.error("Error: Slug required.\n");
+					console.error("Usage: kitfly docs show <slug>");
+					console.error("       kitfly docs list");
+					process.exit(1);
+				}
+				docsShow(slug);
+			} else {
+				console.error(`Unknown docs subcommand: "${sub}"\n`);
+				console.error("Usage: kitfly docs [list|show <slug>]");
+				process.exit(1);
+			}
+			break;
+		}
+
 		case "version":
 		case "-v":
 		case "--version": {

package/src/commands/docs.ts

@@ -0,0 +1,71 @@
+/**
+ * kitfly docs — browse embedded documentation from the CLI.
+ *
+ * Subcommands:
+ *   kitfly docs [list]       List available doc slugs with titles
+ *   kitfly docs show <slug>  Output raw markdown to stdout
+ */
+
+import { EMBEDDED_DOCS } from "../generated/embedded-docs.ts";
+
+// Build a Map from the generated tuple array for O(1) lookup
+const docsMap = new Map<string, { title: string; content: string }>();
+for (const [slug, title, content] of EMBEDDED_DOCS) {
+	docsMap.set(slug, { title, content });
+}
+
+export function docsList(): void {
+	if (docsMap.size === 0) {
+		console.log("No embedded documentation available.");
+		return;
+	}
+
+	const slugs = [...docsMap.keys()].sort();
+	const maxSlug = Math.max(...slugs.map((s) => s.length));
+
+	console.log(`Embedded documentation (${slugs.length} topics):\n`);
+
+	for (const slug of slugs) {
+		const entry = docsMap.get(slug);
+		if (entry) console.log(`  ${slug.padEnd(maxSlug + 2)}${entry.title}`);
+	}
+
+	console.log(`\nUsage: kitfly docs show <slug>`);
+}
+
+export function docsShow(slug: string): void {
+	const entry = docsMap.get(slug);
+
+	if (!entry) {
+		const suggestions = findSimilar(slug, [...docsMap.keys()], 3);
+		console.error(`Not found: "${slug}"`);
+		if (suggestions.length > 0) {
+			console.error(`Did you mean: ${suggestions.join(", ")}?`);
+		}
+		console.error(`\nUse 'kitfly docs list' to see available topics.`);
+		process.exit(1);
+	}
+
+	console.log(entry.content);
+}
+
+/**
+ * Find similar slugs by prefix or substring match.
+ * Returns up to `max` results, prioritizing prefix matches.
+ */
+export function findSimilar(query: string, slugs: string[], max: number): string[] {
+	const q = query.toLowerCase();
+	const prefixMatches: string[] = [];
+	const substringMatches: string[] = [];
+
+	for (const slug of slugs) {
+		const s = slug.toLowerCase();
+		if (s.startsWith(q) || q.startsWith(s)) {
+			prefixMatches.push(slug);
+		} else if (s.includes(q) || q.includes(s)) {
+			substringMatches.push(slug);
+		}
+	}
+
+	return [...prefixMatches, ...substringMatches].slice(0, max);
+}