raga-cli 0.0.0-stage → 0.8.0

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -0,0 +1,405 @@
+/**
+ * GitLab Duo Provider Extension
+ *
+ * Provides access to GitLab Duo AI models (Claude and GPT) through GitLab's AI Gateway.
+ * Delegates to pi-ai's built-in Anthropic and OpenAI streaming implementations.
+ *
+ * Usage:
+ *   pi -e ./packages/coding-agent/examples/extensions/custom-provider-gitlab-duo
+ *   # Then /login gitlab-duo, or set GITLAB_TOKEN=glpat-...
+ */
+
+import {
+	type Api,
+	type AssistantMessageEventStream,
+	anthropicMessagesApi,
+	createAssistantMessageEventStream,
+	type Model,
+	type OAuthCredentials,
+	type OAuthLoginCallbacks,
+	openAIResponsesApi,
+	type SimpleStreamOptions,
+	type ThinkingLevelMap,
+	type TranscriptContext,
+} from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const GITLAB_COM_URL = "https://gitlab.com";
+const AI_GATEWAY_URL = "https://cloud.gitlab.com";
+const ANTHROPIC_PROXY_URL = `${AI_GATEWAY_URL}/ai/v1/proxy/anthropic/`;
+const OPENAI_PROXY_URL = `${AI_GATEWAY_URL}/ai/v1/proxy/openai/v1`;
+
+const BUNDLED_CLIENT_ID = "da4edff2e6ebd2bc3208611e2768bc1c1dd7be791dc5ff26ca34ca9ee44f7d4b";
+const OAUTH_SCOPES = ["api"];
+const REDIRECT_URI = "http://127.0.0.1:8080/callback";
+const DIRECT_ACCESS_TTL = 25 * 60 * 1000;
+
+// =============================================================================
+// Models - exported for use by tests
+// =============================================================================
+
+type Backend = "anthropic" | "openai";
+
+interface GitLabModel {
+	id: string;
+	name: string;
+	backend: Backend;
+	baseUrl: string;
+	reasoning: boolean;
+	thinkingLevelMap?: ThinkingLevelMap;
+	input: ("text" | "image")[];
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow: number;
+	maxTokens: number;
+}
+
+export const MODELS: GitLabModel[] = [
+	// Anthropic
+	{
+		id: "claude-opus-4-8",
+		name: "Claude Opus 4.8",
+		backend: "anthropic",
+		baseUrl: ANTHROPIC_PROXY_URL,
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "max" },
+		input: ["text", "image"],
+		cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+		contextWindow: 1000000,
+		maxTokens: 128000,
+	},
+	{
+		id: "claude-sonnet-4-6",
+		name: "Claude Sonnet 4.6",
+		backend: "anthropic",
+		baseUrl: ANTHROPIC_PROXY_URL,
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "max" },
+		input: ["text", "image"],
+		cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+		contextWindow: 1000000,
+		maxTokens: 64000,
+	},
+	{
+		id: "claude-opus-4-5-20251101",
+		name: "Claude Opus 4.5",
+		backend: "anthropic",
+		baseUrl: ANTHROPIC_PROXY_URL,
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "max" },
+		input: ["text", "image"],
+		cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+		contextWindow: 200000,
+		maxTokens: 32000,
+	},
+	{
+		id: "claude-sonnet-4-5-20250929",
+		name: "Claude Sonnet 4.5",
+		backend: "anthropic",
+		baseUrl: ANTHROPIC_PROXY_URL,
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "max" },
+		input: ["text", "image"],
+		cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+		contextWindow: 200000,
+		maxTokens: 16384,
+	},
+	{
+		id: "claude-haiku-4-5-20251001",
+		name: "Claude Haiku 4.5",
+		backend: "anthropic",
+		baseUrl: ANTHROPIC_PROXY_URL,
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "max" },
+		input: ["text", "image"],
+		cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+		contextWindow: 200000,
+		maxTokens: 8192,
+	},
+	// OpenAI (all use Responses API)
+	{
+		id: "gpt-5.5-2026-04-23",
+		name: "GPT-5.5",
+		backend: "openai",
+		baseUrl: OPENAI_PROXY_URL,
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+		contextWindow: 272000,
+		maxTokens: 128000,
+	},
+	{
+		id: "gpt-5.1-2025-11-13",
+		name: "GPT-5.1",
+		backend: "openai",
+		baseUrl: OPENAI_PROXY_URL,
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+	{
+		id: "gpt-5-mini-2025-08-07",
+		name: "GPT-5 Mini",
+		backend: "openai",
+		baseUrl: OPENAI_PROXY_URL,
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+	{
+		id: "gpt-5-codex",
+		name: "GPT-5 Codex",
+		backend: "openai",
+		baseUrl: OPENAI_PROXY_URL,
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+];
+
+const MODEL_MAP = new Map(MODELS.map((m) => [m.id, m]));
+
+// =============================================================================
+// Direct Access Token Cache
+// =============================================================================
+
+interface DirectAccessToken {
+	token: string;
+	headers: Record<string, string>;
+	expiresAt: number;
+}
+
+let cachedDirectAccess: DirectAccessToken | null = null;
+
+async function getDirectAccessToken(gitlabAccessToken: string): Promise<DirectAccessToken> {
+	const now = Date.now();
+	if (cachedDirectAccess && cachedDirectAccess.expiresAt > now) {
+		return cachedDirectAccess;
+	}
+
+	const response = await fetch(`${GITLAB_COM_URL}/api/v4/ai/third_party_agents/direct_access`, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${gitlabAccessToken}`, "Content-Type": "application/json" },
+		body: JSON.stringify({ feature_flags: { DuoAgentPlatformNext: true } }),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		if (response.status === 403) {
+			throw new Error(
+				`GitLab Duo access denied. Ensure GitLab Duo is enabled for your account. Error: ${errorText}`,
+			);
+		}
+		throw new Error(`Failed to get direct access token: ${response.status} ${errorText}`);
+	}
+
+	const data = (await response.json()) as { token: string; headers: Record<string, string> };
+	cachedDirectAccess = { token: data.token, headers: data.headers, expiresAt: now + DIRECT_ACCESS_TTL };
+	return cachedDirectAccess;
+}
+
+function invalidateDirectAccessToken() {
+	cachedDirectAccess = null;
+}
+
+// =============================================================================
+// OAuth
+// =============================================================================
+
+async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+	const array = new Uint8Array(32);
+	crypto.getRandomValues(array);
+	const verifier = btoa(String.fromCharCode(...array))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+	const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+	return { verifier, challenge };
+}
+
+async function loginGitLab(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+	const { verifier, challenge } = await generatePKCE();
+	const authParams = new URLSearchParams({
+		client_id: BUNDLED_CLIENT_ID,
+		redirect_uri: REDIRECT_URI,
+		response_type: "code",
+		scope: OAUTH_SCOPES.join(" "),
+		code_challenge: challenge,
+		code_challenge_method: "S256",
+		state: crypto.randomUUID(),
+	});
+
+	callbacks.onAuth({ url: `${GITLAB_COM_URL}/oauth/authorize?${authParams.toString()}` });
+	const callbackUrl = await callbacks.onPrompt({ message: "Paste the callback URL:" });
+	const code = new URL(callbackUrl).searchParams.get("code");
+	if (!code) throw new Error("No authorization code found in callback URL");
+
+	const tokenResponse = await fetch(`${GITLAB_COM_URL}/oauth/token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: BUNDLED_CLIENT_ID,
+			grant_type: "authorization_code",
+			code,
+			code_verifier: verifier,
+			redirect_uri: REDIRECT_URI,
+		}).toString(),
+	});
+
+	if (!tokenResponse.ok) throw new Error(`Token exchange failed: ${await tokenResponse.text()}`);
+	const data = (await tokenResponse.json()) as {
+		access_token: string;
+		refresh_token: string;
+		expires_in: number;
+		created_at: number;
+	};
+	invalidateDirectAccessToken();
+	return {
+		refresh: data.refresh_token,
+		access: data.access_token,
+		expires: (data.created_at + data.expires_in) * 1000 - 5 * 60 * 1000,
+	};
+}
+
+async function refreshGitLabToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials> {
+	const response = await fetch(`${GITLAB_COM_URL}/oauth/token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: BUNDLED_CLIENT_ID,
+			grant_type: "refresh_token",
+			refresh_token: credentials.refresh,
+		}).toString(),
+		signal,
+	});
+	if (!response.ok) throw new Error(`Token refresh failed: ${await response.text()}`);
+	const data = (await response.json()) as {
+		access_token: string;
+		refresh_token: string;
+		expires_in: number;
+		created_at: number;
+	};
+	invalidateDirectAccessToken();
+	return {
+		refresh: data.refresh_token,
+		access: data.access_token,
+		expires: (data.created_at + data.expires_in) * 1000 - 5 * 60 * 1000,
+	};
+}
+
+// =============================================================================
+// Stream Function
+// =============================================================================
+
+export function streamGitLabDuo(
+	model: Model<Api>,
+	context: TranscriptContext,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const stream = createAssistantMessageEventStream();
+
+	(async () => {
+		try {
+			const gitlabAccessToken = options?.apiKey;
+			if (!gitlabAccessToken) throw new Error("No GitLab access token. Run /login gitlab-duo or set GITLAB_TOKEN");
+
+			const cfg = MODEL_MAP.get(model.id);
+			if (!cfg) throw new Error(`Unknown model: ${model.id}`);
+
+			const directAccess = await getDirectAccessToken(gitlabAccessToken);
+			const modelWithBaseUrl = { ...model, baseUrl: cfg.baseUrl };
+			const headers = { ...directAccess.headers, Authorization: `Bearer ${directAccess.token}` };
+			const streamOptions = { ...options, apiKey: "gitlab-duo", headers };
+
+			const innerStream =
+				cfg.backend === "anthropic"
+					? anthropicMessagesApi().streamSimple(
+							{
+								...(modelWithBaseUrl as Model<"anthropic-messages">),
+								compat: {
+									...(modelWithBaseUrl as Model<"anthropic-messages">).compat,
+									forceAdaptiveThinking: true,
+								},
+							},
+							context,
+							streamOptions,
+						)
+					: openAIResponsesApi().streamSimple(
+							modelWithBaseUrl as Model<"openai-responses">,
+							context,
+							streamOptions,
+						);
+
+			for await (const event of innerStream) stream.push(event);
+			stream.end();
+		} catch (error) {
+			stream.push({
+				type: "error",
+				reason: "error",
+				error: {
+					role: "assistant",
+					content: [],
+					api: model.api,
+					provider: model.provider,
+					model: model.id,
+					usage: {
+						input: 0,
+						output: 0,
+						cacheRead: 0,
+						cacheWrite: 0,
+						totalTokens: 0,
+						cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+					},
+					stopReason: "error",
+					errorMessage: error instanceof Error ? error.message : String(error),
+					timestamp: Date.now(),
+				},
+			});
+			stream.end();
+		}
+	})();
+
+	return stream;
+}
+
+// =============================================================================
+// Extension Entry Point
+// =============================================================================
+
+export default function (pi: ExtensionAPI) {
+	pi.registerProvider("gitlab-duo", {
+		baseUrl: AI_GATEWAY_URL,
+		apiKey: "$GITLAB_TOKEN",
+		api: "gitlab-duo-api",
+		models: MODELS.map(({ id, name, reasoning, thinkingLevelMap, input, cost, contextWindow, maxTokens }) => ({
+			id,
+			name,
+			reasoning,
+			thinkingLevelMap,
+			input,
+			cost,
+			contextWindow,
+			maxTokens,
+		})),
+		oauth: {
+			name: "GitLab Duo",
+			login: loginGitLab,
+			refreshToken: refreshGitLabToken,
+			getApiKey: (cred) => cred.access,
+		},
+		streamSimple: streamGitLabDuo,
+	});
+}

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pi-extension-custom-provider-gitlab-duo",
+  "private": true,
+  "version": "1.4.0",
+  "type": "module",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -0,0 +1,82 @@
+/**
+ * Test script for GitLab Duo extension
+ * Run: node test.ts [model-id] [--thinking]
+ *
+ * Examples:
+ *   node test.ts                              # Test default (claude-sonnet-4-5-20250929)
+ *   node test.ts gpt-5-codex                  # Test GPT-5 Codex
+ *   node test.ts claude-sonnet-4-5-20250929 --thinking
+ */
+
+import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@earendil-works/pi-ai/compat";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { MODELS, streamGitLabDuo } from "./index.ts";
+
+const MODEL_MAP = new Map(MODELS.map((m) => [m.id, m]));
+
+async function main() {
+	const modelId = process.argv[2] || "claude-sonnet-4-5-20250929";
+	const useThinking = process.argv.includes("--thinking");
+
+	const cfg = MODEL_MAP.get(modelId);
+	if (!cfg) {
+		console.error(`Unknown model: ${modelId}`);
+		console.error("Available:", MODELS.map((m) => m.id).join(", "));
+		process.exit(1);
+	}
+
+	// Read auth
+	const authPath = join(getAgentDir(), "extensions", "auth.json");
+	const authData = JSON.parse(readFileSync(authPath, "utf-8"));
+	const gitlabCred = authData["gitlab-duo"];
+	if (!gitlabCred?.access) {
+		console.error("No gitlab-duo credentials. Run /login gitlab-duo first.");
+		process.exit(1);
+	}
+
+	// Register provider
+	registerApiProvider({
+		api: "gitlab-duo-api" as Api,
+		stream: streamGitLabDuo,
+		streamSimple: streamGitLabDuo,
+	});
+
+	// Create model
+	const model: Model<Api> = {
+		id: cfg.id,
+		name: cfg.name,
+		api: "gitlab-duo-api" as Api,
+		provider: "gitlab-duo",
+		baseUrl: cfg.baseUrl,
+		reasoning: cfg.reasoning,
+		input: cfg.input,
+		cost: cfg.cost,
+		contextWindow: cfg.contextWindow,
+		maxTokens: cfg.maxTokens,
+	};
+
+	const context: Context = {
+		messages: [{ role: "user", content: "Say hello in exactly 3 words.", timestamp: Date.now() }],
+	};
+
+	console.log(`Model: ${model.id}, Backend: ${cfg.backend}, Thinking: ${useThinking}`);
+
+	const stream = streamSimple(model, context, {
+		apiKey: gitlabCred.access,
+		maxTokens: 100,
+		reasoning: useThinking ? "low" : undefined,
+	});
+
+	for await (const event of stream) {
+		if (event.type === "thinking_start") console.log("[Thinking]");
+		else if (event.type === "thinking_delta") process.stdout.write(event.delta);
+		else if (event.type === "thinking_end") console.log("\n[/Thinking]\n");
+		else if (event.type === "text_delta") process.stdout.write(event.delta);
+		else if (event.type === "error") console.error("\nError:", event.error.errorMessage);
+		else if (event.type === "done") console.log("\n\nDone!", event.reason, event.message.usage);
+	}
+}
+
+main().catch(console.error);

package/examples/extensions/debug-provider.ts

@@ -0,0 +1,90 @@
+/**
+ * Raw provider event viewer.
+ *
+ * Usage: /debug-provider [on|off]
+ * With no argument, the command toggles capture. Captured events are persisted
+ * as expandable custom entries.
+ */
+
+import { type ExtensionAPI, keyHint } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+
+const ENTRY_TYPE = "debug-provider-events";
+const STATUS_KEY = "debug-provider";
+
+interface ProviderDebugEntry {
+	provider: string;
+	api: string;
+	model: string;
+	events: unknown[];
+}
+
+export default function (pi: ExtensionAPI) {
+	let enabled = false;
+	let activeEvents: unknown[] | undefined;
+	let completedEntry: ProviderDebugEntry | undefined;
+
+	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded }, theme) => {
+		const data = entry.data;
+		if (!data) return new Text(theme.fg("warning", "[provider debug] Missing event data"), 0, 0);
+
+		const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+		const count = `${data.events.length} event${data.events.length === 1 ? "" : "s"}`;
+		const expandHint = expanded ? "" : ` (${keyHint("app.tools.expand", "to view events")})`;
+		box.addChild(
+			new Text(
+				`${theme.fg("accent", "[provider debug]")} ${data.provider}/${data.model} (${data.api}) · ${count}${expandHint}`,
+				0,
+				0,
+			),
+		);
+		if (expanded) {
+			box.addChild(new Text(JSON.stringify(data.events, null, 2), 0, 0));
+		}
+		return box;
+	});
+
+	pi.registerCommand("debug-provider", {
+		description: "Toggle capture of raw provider stream events",
+		handler: async (args, ctx) => {
+			const requestedState = args.trim().toLowerCase();
+			if (requestedState !== "" && requestedState !== "on" && requestedState !== "off") {
+				ctx.ui.notify("Usage: /debug-provider [on|off]", "warning");
+				return;
+			}
+
+			enabled = requestedState === "" ? !enabled : requestedState === "on";
+			if (!enabled) {
+				activeEvents = undefined;
+				completedEntry = undefined;
+			}
+			ctx.ui.setStatus(STATUS_KEY, enabled ? "provider debug" : undefined);
+			ctx.ui.notify(`Provider event capture ${enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+
+	pi.on("turn_start", () => {
+		activeEvents = enabled ? [] : undefined;
+	});
+
+	pi.on("provider_stream_event", (event) => {
+		activeEvents?.push(structuredClone(event.data));
+	});
+
+	pi.on("message_end", (event) => {
+		if (event.message.role !== "assistant" || !activeEvents) return;
+		completedEntry = {
+			provider: event.message.provider,
+			api: event.message.api,
+			model: event.message.model,
+			events: activeEvents,
+		};
+		activeEvents = undefined;
+	});
+
+	pi.on("turn_end", () => {
+		if (!completedEntry) return;
+		pi.appendEntry<ProviderDebugEntry>(ENTRY_TYPE, completedEntry);
+		completedEntry = undefined;
+	});
+}

package/examples/extensions/dirty-repo-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * Dirty Repo Guard Extension
+ *
+ * Prevents session changes when there are uncommitted git changes.
+ * Useful to ensure work is committed before switching context.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+async function checkDirtyRepo(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	action: string,
+): Promise<{ cancel: boolean } | undefined> {
+	// Check for uncommitted changes
+	const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+	if (code !== 0) {
+		// Not a git repo, allow the action
+		return;
+	}
+
+	const hasChanges = stdout.trim().length > 0;
+	if (!hasChanges) {
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		// In non-interactive mode, block by default
+		return { cancel: true };
+	}
+
+	// Count changed files
+	const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
+
+	const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
+		"Yes, proceed anyway",
+		"No, let me commit first",
+	]);
+
+	if (choice !== "Yes, proceed anyway") {
+		ctx.ui.notify("Commit your changes first", "warning");
+		return { cancel: true };
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_switch", async (event, ctx) => {
+		const action = event.reason === "new" ? "new session" : "switch session";
+		return checkDirtyRepo(pi, ctx, action);
+	});
+
+	pi.on("session_before_fork", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "fork");
+	});
+}

package/examples/extensions/doom-overlay/README.md

@@ -0,0 +1,46 @@
+# DOOM Overlay Demo
+
+Play DOOM as an overlay in pi. Demonstrates that the overlay system can handle real-time game rendering at 35 FPS.
+
+## Usage
+
+```bash
+pi --extension ./examples/extensions/doom-overlay
+```
+
+Then run:
+```
+/doom-overlay
+```
+
+The shareware WAD file (~4MB) is auto-downloaded on first run.
+
+## Controls
+
+| Action | Keys |
+|--------|------|
+| Move | WASD or Arrow Keys |
+| Run | Shift + WASD |
+| Fire | F or Ctrl |
+| Use/Open | Space |
+| Weapons | 1-7 |
+| Map | Tab |
+| Menu | Escape |
+| Pause/Quit | Q |
+
+## How It Works
+
+DOOM runs as WebAssembly compiled from [doomgeneric](https://github.com/ozkl/doomgeneric). Each frame is rendered using half-block characters (▀) with 24-bit color, where the top pixel is the foreground color and the bottom pixel is the background color.
+
+The overlay uses:
+- `width: "90%"` - 90% of terminal width
+- `maxHeight: "80%"` - Maximum 80% of terminal height
+- `anchor: "center"` - Centered in terminal
+
+Height is calculated from width to maintain DOOM's 3.2:1 aspect ratio (accounting for half-block rendering).
+
+## Credits
+
+- [id Software](https://github.com/id-Software/DOOM) for the original DOOM
+- [doomgeneric](https://github.com/ozkl/doomgeneric) for the portable DOOM implementation
+- [pi-doom](https://github.com/badlogic/pi-doom) for the original pi integration