@knightcodeai/cli 0.17.3 → 0.18.0

package/examples/extensions/doom-overlay/index.ts

@@ -0,0 +1,74 @@
+/**
+ * DOOM Overlay Demo - Play DOOM as an overlay
+ *
+ * Usage: knightcode --extension ./examples/extensions/doom-overlay
+ *
+ * Commands:
+ *   /doom-overlay - Play DOOM in an overlay (Q to pause/exit)
+ *
+ * This demonstrates that overlays can handle real-time game rendering at 35 FPS.
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+import { DoomOverlayComponent } from "./doom-component.ts";
+import { DoomEngine } from "./doom-engine.ts";
+import { ensureWadFile } from "./wad-finder.ts";
+
+// Persistent engine instance - survives between invocations
+let activeEngine: DoomEngine | null = null;
+let activeWadPath: string | null = null;
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.registerCommand("doom-overlay", {
+		description: "Play DOOM as an overlay. Q to pause and exit.",
+
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("DOOM requires interactive mode", "error");
+				return;
+			}
+
+			// Auto-download WAD if not present
+			ctx.ui.notify("Loading DOOM...", "info");
+			const wad = args?.trim() ? args.trim() : await ensureWadFile();
+
+			if (!wad) {
+				ctx.ui.notify("Failed to download DOOM WAD file. Check your internet connection.", "error");
+				return;
+			}
+
+			try {
+				// Reuse existing engine if same WAD, otherwise create new
+				let isResume = false;
+				if (activeEngine && activeWadPath === wad) {
+					ctx.ui.notify("Resuming DOOM...", "info");
+					isResume = true;
+				} else {
+					ctx.ui.notify(`Loading DOOM from ${wad}...`, "info");
+					activeEngine = new DoomEngine(wad);
+					await activeEngine.init();
+					activeWadPath = wad;
+				}
+
+				await ctx.ui.custom(
+					(tui, _theme, _keybindings, done) => {
+						return new DoomOverlayComponent(tui, activeEngine!, () => done(undefined), isResume);
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							width: "75%",
+							maxHeight: "95%",
+							anchor: "center",
+							margin: { top: 1 },
+						},
+					},
+				);
+			} catch (error) {
+				ctx.ui.notify(`Failed to load DOOM: ${error}`, "error");
+				activeEngine = null;
+				activeWadPath = null;
+			}
+		},
+	});
+}

package/examples/extensions/doom-overlay/wad-finder.ts

@@ -0,0 +1,55 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+// Get the bundled WAD path (relative to this module)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_WAD = join(__dirname, "doom1.wad");
+const WAD_URL = "https://www.gamers.org/pub/idgames/idstuff/doom/doom-1.8.wad.gz";
+
+const DEFAULT_WAD_PATHS = ["./doom1.wad", "./DOOM1.WAD", "~/doom1.wad", "~/.doom/doom1.wad"];
+
+export function findWadFile(customPath?: string): string | null {
+	if (customPath) {
+		const resolved = resolve(customPath.replace(/^~/, process.env.HOME || ""));
+		if (existsSync(resolved)) return resolved;
+		return null;
+	}
+
+	// Check bundled WAD first
+	if (existsSync(BUNDLED_WAD)) {
+		return BUNDLED_WAD;
+	}
+
+	// Fall back to default paths
+	for (const p of DEFAULT_WAD_PATHS) {
+		const resolved = resolve(p.replace(/^~/, process.env.HOME || ""));
+		if (existsSync(resolved)) return resolved;
+	}
+
+	return null;
+}
+
+/** Download the shareware WAD if not present. Returns path or null on failure. */
+export async function ensureWadFile(): Promise<string | null> {
+	// Check if already exists
+	const existing = findWadFile();
+	if (existing) return existing;
+
+	// Download to bundled location
+	try {
+		const response = await fetch(WAD_URL);
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status}`);
+		}
+		const wad = gunzipSync(Buffer.from(await response.arrayBuffer()));
+		if (wad.subarray(0, 4).toString("ascii") !== "IWAD") {
+			throw new Error("Downloaded file is not a valid IWAD");
+		}
+		writeFileSync(BUNDLED_WAD, wad);
+		return BUNDLED_WAD;
+	} catch {
+		return null;
+	}
+}

package/examples/extensions/dynamic-resources/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: dynamic-resources
+description: Example skill loaded from resources_discover
+---
+
+# Dynamic Resources Skill
+
+This skill is provided by the dynamic-resources extension.

package/examples/extensions/dynamic-resources/dynamic.json

@@ -0,0 +1,75 @@
+{
+	"$schema": "https://knightcode.dev/schemas/theme.schema.json",
+	"name": "dynamic-resources",
+	"vars": {
+		"cyan": "#00d7ff",
+		"blue": "#5f87ff",
+		"green": "#b5bd68",
+		"red": "#cc6666",
+		"yellow": "#ffff00",
+		"gray": "#808080",
+		"dimGray": "#666666",
+		"darkGray": "#505050",
+		"accent": "#8abeb7",
+		"selectedBg": "#3a3a4a",
+		"userMsgBg": "#343541",
+		"toolPendingBg": "#282832",
+		"toolSuccessBg": "#283228",
+		"toolErrorBg": "#3c2828",
+		"customMsgBg": "#2d2838"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "blue",
+		"borderAccent": "cyan",
+		"borderMuted": "darkGray",
+		"success": "green",
+		"error": "red",
+		"warning": "yellow",
+		"muted": "gray",
+		"dim": "dimGray",
+		"text": "",
+		"thinkingText": "gray",
+		"scrollbarTrack": "darkGray",
+		"scrollbarThumb": "",
+		"selectedBg": "selectedBg",
+		"userMessageBg": "userMsgBg",
+		"userMessageText": "",
+		"customMessageBg": "customMsgBg",
+		"customMessageText": "",
+		"customMessageLabel": "#9575cd",
+		"toolPendingBg": "toolPendingBg",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "",
+		"toolOutput": "gray",
+		"mdHeading": "#f0c674",
+		"mdLink": "#81a2be",
+		"mdLinkUrl": "dimGray",
+		"mdCode": "accent",
+		"mdCodeBlock": "green",
+		"mdCodeBlockBorder": "gray",
+		"mdQuote": "gray",
+		"mdQuoteBorder": "gray",
+		"mdHr": "gray",
+		"mdListBullet": "accent",
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "gray",
+		"syntaxComment": "#6A9955",
+		"syntaxKeyword": "#569CD6",
+		"syntaxFunction": "#DCDCAA",
+		"syntaxVariable": "#9CDCFE",
+		"syntaxString": "#CE9178",
+		"syntaxNumber": "#B5CEA8",
+		"syntaxType": "#4EC9B0",
+		"syntaxOperator": "#D4D4D4",
+		"syntaxPunctuation": "#D4D4D4",
+		"bashMode": "green"
+	},
+	"export": {
+		"pageBg": "#18181e",
+		"cardBg": "#1e1e24",
+		"infoBg": "#3c3728"
+	}
+}

package/examples/extensions/dynamic-resources/dynamic.md

@@ -0,0 +1,5 @@
+---
+description: Example prompt template loaded from resources_discover
+---
+
+Summarize the current repository structure and mention any build or test commands.

package/examples/extensions/dynamic-resources/index.ts

@@ -0,0 +1,15 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.on("resources_discover", () => {
+		return {
+			skillPaths: [join(baseDir, "SKILL.md")],
+			promptPaths: [join(baseDir, "dynamic.md")],
+			themePaths: [join(baseDir, "dynamic.json")],
+		};
+	});
+}

package/examples/extensions/dynamic-tools.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+import { Type } from "typebox";
+
+const ECHO_PARAMS = Type.Object({
+	message: Type.String({ description: "Message to echo" }),
+});
+
+function normalizeToolName(input: string): string | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (!trimmed) return undefined;
+	if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export default function dynamicToolsExtension(knightcode: ExtensionAPI) {
+	const registeredToolNames = new Set<string>();
+
+	const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+		if (registeredToolNames.has(name)) {
+			return false;
+		}
+
+		registeredToolNames.add(name);
+		knightcode.registerTool({
+			name,
+			label,
+			description: `Echo a message with prefix: ${prefix}`,
+			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+			promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
+			parameters: ECHO_PARAMS,
+			async execute(_toolCallId, params) {
+				return {
+					content: [{ type: "text", text: `${prefix}${params.message}` }],
+					details: { tool: name, prefix },
+				};
+			},
+		});
+
+		return true;
+	};
+
+	knightcode.on("session_start", (_event, ctx) => {
+		registerEchoTool("echo_session", "Echo Session", "[session] ");
+		ctx.ui.notify("Registered dynamic tool: echo_session", "info");
+	});
+
+	knightcode.registerCommand("add-echo-tool", {
+		description: "Register a new echo tool dynamically: /add-echo-tool <tool_name>",
+		handler: async (args, ctx) => {
+			const toolName = normalizeToolName(args);
+			if (!toolName) {
+				ctx.ui.notify("Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)", "warning");
+				return;
+			}
+
+			const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+			if (!created) {
+				ctx.ui.notify(`Tool already registered: ${toolName}`, "warning");
+				return;
+			}
+
+			ctx.ui.notify(`Registered dynamic tool: ${toolName}`, "info");
+		},
+	});
+}

package/examples/extensions/entry-renderer.ts

@@ -0,0 +1,41 @@
+/**
+ * Custom entry rendering example.
+ *
+ * Shows how to render durable extension data inside the chat without sending it
+ * to the LLM. Custom entries are stored in the session via knightcode.appendEntry() and
+ * rendered in interactive mode via knightcode.registerEntryRenderer().
+ *
+ * Usage: /status-card [message]
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+import { Box, Text } from "@knightcode/tui";
+
+interface StatusCardData {
+	message: string;
+	timestamp: number;
+}
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.registerEntryRenderer<StatusCardData>("status-card", (entry, { expanded }, theme) => {
+		const data = entry.data ?? { message: "No data", timestamp: Date.now() };
+		const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+		box.addChild(new Text(`${theme.fg("accent", "[status]")} ${data.message}`, 0, 0));
+
+		if (expanded) {
+			box.addChild(new Text(theme.fg("dim", new Date(data.timestamp).toLocaleString()), 0, 0));
+		}
+
+		return box;
+	});
+
+	knightcode.registerCommand("status-card", {
+		description: "Render a durable status card that is not sent to the LLM",
+		handler: async (args) => {
+			knightcode.appendEntry<StatusCardData>("status-card", {
+				message: args.trim() || "Status card",
+				timestamp: Date.now(),
+			});
+		},
+	});
+}

package/examples/extensions/event-bus.ts

@@ -0,0 +1,43 @@
+/**
+ * Inter-extension event bus example.
+ *
+ * Shows knightcode.events for communication between extensions. One extension
+ * can emit events that other extensions listen to.
+ *
+ * Usage: /emit [event-name] [data] - emit an event on the bus
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+	// Store ctx for use in event handler
+	let currentCtx: ExtensionContext | undefined;
+
+	knightcode.on("session_start", async (_event, ctx) => {
+		currentCtx = ctx;
+	});
+
+	// Listen for events from other extensions
+	knightcode.events.on("my:notification", (data) => {
+		const { message, from } = data as { message: string; from: string };
+		currentCtx?.ui.notify(`Event from ${from}: ${message}`, "info");
+	});
+
+	// Command to emit events (emits "my:notification" which the listener above receives)
+	knightcode.registerCommand("emit", {
+		description: "Emit my:notification event (usage: /emit message)",
+		handler: async (args, _ctx) => {
+			const message = args.trim() || "hello";
+			knightcode.events.emit("my:notification", { message, from: "/emit command" });
+			// Listener above will show the notification
+		},
+	});
+
+	// Example: emit on session start
+	knightcode.on("session_start", async () => {
+		knightcode.events.emit("my:notification", {
+			message: "Session started",
+			from: "event-bus-example",
+		});
+	});
+}

package/examples/extensions/file-trigger.ts

@@ -0,0 +1,41 @@
+/**
+ * File Trigger Extension
+ *
+ * Watches a trigger file and injects its contents into the conversation.
+ * Useful for external systems to send messages to the agent.
+ *
+ * Usage:
+ *   echo "Run the tests" > /tmp/agent-trigger.txt
+ */
+
+import * as fs from "node:fs";
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.on("session_start", async (_event, ctx) => {
+		const triggerFile = "/tmp/agent-trigger.txt";
+
+		fs.watch(triggerFile, () => {
+			try {
+				const content = fs.readFileSync(triggerFile, "utf-8").trim();
+				if (content) {
+					knightcode.sendMessage(
+						{
+							customType: "file-trigger",
+							content: `External trigger: ${content}`,
+							display: true,
+						},
+						{ triggerTurn: true }, // triggerTurn - get LLM to respond
+					);
+					fs.writeFileSync(triggerFile, ""); // Clear after reading
+				}
+			} catch {
+				// File might not exist yet
+			}
+		});
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Watching ${triggerFile}`, "info");
+		}
+	});
+}

package/examples/extensions/git-checkpoint.ts

@@ -0,0 +1,53 @@
+/**
+ * Git Checkpoint Extension
+ *
+ * Creates git stash checkpoints at each turn so /fork can restore code state.
+ * When forking, offers to restore code to that point in history.
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+	const checkpoints = new Map<string, string>();
+	let currentEntryId: string | undefined;
+
+	// Track the current entry ID when user messages are saved
+	knightcode.on("tool_result", async (_event, ctx) => {
+		const leaf = ctx.sessionManager.getLeafEntry();
+		if (leaf) currentEntryId = leaf.id;
+	});
+
+	knightcode.on("turn_start", async () => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await knightcode.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref && currentEntryId) {
+			checkpoints.set(currentEntryId, ref);
+		}
+	});
+
+	knightcode.on("session_before_fork", async (event, ctx) => {
+		const ref = checkpoints.get(event.entryId);
+		if (!ref) return;
+
+		if (!ctx.hasUI) {
+			// In non-interactive mode, don't restore automatically
+			return;
+		}
+
+		const choice = await ctx.ui.select("Restore code state?", [
+			"Yes, restore code to that point",
+			"No, keep current code",
+		]);
+
+		if (choice?.startsWith("Yes")) {
+			await knightcode.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+	});
+
+	knightcode.on("agent_settled", async () => {
+		// Clear checkpoints after the full agent run completes
+		checkpoints.clear();
+	});
+}

package/examples/extensions/git-merge-and-resolve.ts

@@ -0,0 +1,115 @@
+/**
+ * Merge and Resolve
+ *
+ * Keeps the working branch up to date with its upstream tracking ref.
+ * After each agent turn, fetches and merges. Clean merges complete
+ * silently. When conflicts arise, the working tree is left dirty and
+ * the agent receives a follow-up message listing each conflict block
+ * with file, line range, and ours/theirs sections so it can resolve them.
+ * Also re-sends unresolved conflicts from a previous incomplete merge.
+ *
+ * Start knightcode with this extension:
+ *   knightcode -e ./examples/extensions/git-merge-and-resolve.ts
+ */
+import { createReadStream } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+interface ConflictBlock {
+	file: string;
+	startLine: number;
+	separatorLine: number;
+	endLine: number;
+}
+
+/** Parse conflict markers from working tree files with unmerged paths. */
+async function findConflicts(knightcode: ExtensionAPI, cwd: string): Promise<ConflictBlock[]> {
+	const { stdout, code } = await knightcode.exec("git", ["diff", "--name-only", "--diff-filter=U"]);
+	if (code !== 0 || !stdout.trim()) return [];
+
+	const blocks: ConflictBlock[] = [];
+	for (const file of stdout.trim().split("\n")) {
+		try {
+			const rl = createInterface({ input: createReadStream(join(cwd, file), "utf-8") });
+			let lineNo = 0;
+			let blockStart: number | undefined;
+			let separatorLine: number | undefined;
+			for await (const line of rl) {
+				lineNo++;
+				if (line.startsWith("<<<<<<<")) {
+					blockStart = lineNo;
+					separatorLine = undefined;
+				} else if (line.startsWith("=======") && blockStart !== undefined) {
+					separatorLine = lineNo;
+				} else if (line.startsWith(">>>>>>>") && blockStart !== undefined && separatorLine !== undefined) {
+					blocks.push({ file, startLine: blockStart, separatorLine, endLine: lineNo });
+					blockStart = undefined;
+					separatorLine = undefined;
+				}
+			}
+		} catch {}
+	}
+	return blocks;
+}
+
+function formatRange(start: number, end: number): string {
+	if (start > end) return "empty";
+	if (start === end) return `${start}`;
+	return `${start}-${end}`;
+}
+
+function formatConflicts(ref: string, blocks: ConflictBlock[]): string {
+	const lines = [`Merged ${ref} with conflicts:`, ""];
+	for (const b of blocks) {
+		const ours = formatRange(b.startLine + 1, b.separatorLine - 1);
+		const theirs = formatRange(b.separatorLine + 1, b.endLine - 1);
+		lines.push(`  ${b.file}:${b.startLine}-${b.endLine} (ours ${ours}, theirs ${theirs})`);
+	}
+	lines.push("", "Resolve these conflicts.");
+	return lines.join("\n");
+}
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.on("agent_end", async (_event, ctx) => {
+		const { code: revParseCode } = await knightcode.exec("git", ["rev-parse", "--git-dir"]);
+		if (revParseCode !== 0) return;
+
+		let ref = "MERGE_HEAD";
+
+		// If not already in a merge, attempt one
+		const { code: mergeHeadCode } = await knightcode.exec("git", ["rev-parse", "MERGE_HEAD"]);
+		if (mergeHeadCode !== 0) {
+			// Only attempt a new merge if the working tree is clean
+			const { stdout: status } = await knightcode.exec("git", ["status", "--porcelain"]);
+			if (status.trim()) return;
+
+			const { stdout: upstream, code: upstreamCode } = await knightcode.exec("git", [
+				"rev-parse",
+				"--abbrev-ref",
+				"--symbolic-full-name",
+				"@{u}",
+			]);
+			if (upstreamCode !== 0) return;
+
+			ref = upstream.trim();
+			const remote = ref.split("/")[0];
+			ctx.ui.notify(`git-merge-and-resolve: fetching ${remote}, merging ${ref}`, "info");
+
+			const { code: fetchCode, stderr: fetchErr } = await knightcode.exec("git", ["fetch", remote]);
+			if (fetchCode !== 0) {
+				ctx.ui.notify(`git-merge-and-resolve: fetch failed: ${fetchErr.trim()}`, "warning");
+				return;
+			}
+
+			const { code: mergeCode } = await knightcode.exec("git", ["merge", "--no-ff", ref]);
+			if (mergeCode === 0) return;
+		}
+
+		// Either we just merged with conflicts, or we were already in an unfinished merge
+		const conflicts = await findConflicts(knightcode, ctx.cwd);
+		if (conflicts.length === 0) return;
+
+		knightcode.sendUserMessage(formatConflicts(ref, conflicts), { deliverAs: "followUp" });
+	});
+}