@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/cli/src/internal/agents.ts

@@ -0,0 +1,365 @@
+import {
+	SessionManager,
+	createAgentSessionServices,
+	createAgentSessionFromServices,
+	createEventBus,
+	type AgentSession,
+	type CreateAgentSessionOptions,
+} from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import type { NornAgentCreateSessionInput, NornAgentPromptInput, NornAgentRunRawAttempt, NornAgentRunResult, NornAgentSessionEvents, NornAgentSession, NornAgentSinglePromptInput, NornAgentUsage } from "@vimhead.dev/norn";
+import { AGENT_RESPONSE_TOOL_NAME } from "@vimhead.dev/norn-core/agent-protocol";
+import {
+	NornAgentResponseCollector,
+	NornAgentResponseToolFactory,
+	type NornCapturedAgentResponse,
+} from "./agent-response-tool.ts";
+import { resolveNornAgentDirectory } from "./agent-directory.ts";
+import { errorMessage } from "./errors.ts";
+import type { NornRunLogs } from "./logs.ts";
+import { safeFileName } from "./file-names.ts";
+import { NornSessionResourceBindings } from "./resource-bindings.ts";
+import type { NornRunLogger } from "./run-log.ts";
+import { agentUsageFromValue, emptyAgentUsage, totalAgentUsage } from "./usage.ts";
+
+const DEFAULT_AGENT_ATTEMPTS = 3;
+const DEFAULT_AGENT_TOOL_ALLOWLIST = ["read", "bash", "edit", "write", AGENT_RESPONSE_TOOL_NAME] as const;
+
+type NornAgentRunnerInput = {
+	readonly id: string;
+	readonly runRoot: string;
+	readonly boundaryRoot: string;
+	readonly boundaryName: string;
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+	readonly model?: CreateAgentSessionOptions["model"];
+	readonly thinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
+	readonly agentDir?: string;
+	readonly logs: NornRunLogs;
+	readonly logger: NornRunLogger;
+	readonly responseCollector: NornAgentResponseCollector;
+};
+
+type CreatedNornAgentSessionInput = NornAgentRunnerInput & {
+	readonly label: string;
+	readonly cwd: string;
+	readonly session: AgentSession;
+	readonly resourceBindings: NornSessionResourceBindings;
+	readonly events: NornAgentSessionEvents;
+};
+
+export class NornAgentRunner {
+	private readonly responseToolFactory: NornAgentResponseToolFactory;
+
+	constructor(private readonly input: NornAgentRunnerInput) {
+		this.responseToolFactory = new NornAgentResponseToolFactory(input.responseCollector);
+	}
+
+	async createSession(agentInput: NornAgentCreateSessionInput): Promise<NornAgentSession> {
+		const cwd = agentInput.cwd ? this.resolveFromCwd(agentInput.cwd) : this.input.cwd;
+		const sessionDir = resolve(this.input.runRoot, "sessions");
+		await mkdir(sessionDir, { recursive: true });
+
+		const eventBus = createEventBus();
+		const agentDir = this.input.agentDir ?? resolveNornAgentDirectory({ home: homedir(), environment: process.env });
+		const services = await createAgentSessionServices({
+			cwd,
+			agentDir,
+			resourceLoaderOptions: {
+				eventBus,
+				systemPromptOverride: systemPromptOverride(agentInput),
+				appendSystemPromptOverride: appendSystemPromptOverride(agentInput),
+			},
+		});
+		const loader = services.resourceLoader;
+		const errors = [
+			...services.diagnostics.filter(diagnostic => diagnostic.type === "error").map(diagnostic => diagnostic.message),
+			...loader.getExtensions().errors.map(error => `Failed to load extension ${error.path}: ${error.error}`),
+		];
+		if (errors.length > 0) throw new Error(errors.join("\n"));
+		const resourceBindings = new NornSessionResourceBindings();
+		let session: AgentSession | undefined;
+		try {
+			await resourceBindings.bind({
+				adapters: agentInput.resourceAdapters ?? [], runId: this.input.id, label: agentInput.label,
+				reservedTools: ["read", "bash", "edit", "write", "grep", "find", "ls", "powershell", AGENT_RESPONSE_TOOL_NAME,
+					...loader.getExtensions().extensions.flatMap((extension) => [...extension.tools.keys()])],
+			});
+			({ session } = await createAgentSessionFromServices({
+				services,
+				sessionManager: SessionManager.create(cwd, sessionDir),
+				tools: [...withAgentResponseTool(agentInput.tools), ...resourceBindings.tools.map((tool) => tool.name)],
+				customTools: [this.responseToolFactory.create(), ...resourceBindings.tools],
+				model: agentInput.model ?? this.input.model,
+				thinkingLevel: agentInput.thinkingLevel ?? this.input.thinkingLevel,
+			}));
+			await agentInput.beforeSessionStart?.({ events: eventBus });
+			await session.bindExtensions({});
+			await this.input.logger.record({ type: "agent.spawned", label: agentInput.label, cwd });
+			return new CreatedNornAgentSession({
+				...this.input, label: agentInput.label, cwd, session, resourceBindings, events: eventBus,
+			});
+		} catch (error) {
+			const errors = [error];
+			try { session?.dispose(); } catch (cleanupError) { errors.push(cleanupError); }
+			try { await resourceBindings.dispose(); } catch (cleanupError) { errors.push(cleanupError); }
+			if (errors.length > 1) throw new AggregateError(errors, "Agent creation and resource cleanup failed");
+			throw error;
+		}
+	}
+
+	async prompt<ResponseSchema extends z.ZodType>(agentInput: NornAgentSinglePromptInput<ResponseSchema>): Promise<z.output<ResponseSchema>> {
+		const agent = await this.createSession(agentInput);
+		try {
+			return await agent.prompt(agentInput);
+		} finally {
+			await agent.dispose();
+		}
+	}
+
+	private resolveFromCwd(path: string): string {
+		const resolvedPath = isAbsolute(path) ? path : resolve(this.input.cwd, path);
+		const pathFromBoundary = relative(this.input.boundaryRoot, resolvedPath);
+		if (pathFromBoundary === ".." || pathFromBoundary.startsWith(`..${sep}`) || isAbsolute(pathFromBoundary)) {
+			throw new Error(`Agent cwd escapes ${this.input.boundaryName} isolation: ${path}`);
+		}
+		return resolvedPath;
+	}
+}
+
+function systemPromptOverride(agentInput: NornAgentCreateSessionInput): (() => string) | undefined {
+	const systemPrompt = agentInput.systemPrompt;
+	return systemPrompt === undefined ? undefined : () => systemPrompt;
+}
+
+function appendSystemPromptOverride(agentInput: NornAgentCreateSessionInput): ((base: string[]) => string[]) | undefined {
+	const appendSystemPrompt = agentInput.appendSystemPrompt;
+	return appendSystemPrompt === undefined ? undefined : (base) => [...base, ...appendSystemPrompt];
+}
+
+class CreatedNornAgentSession implements NornAgentSession {
+	readonly label: string;
+	readonly cwd: string;
+	readonly events: NornAgentSessionEvents;
+	private isDisposed = false;
+
+	constructor(private readonly input: CreatedNornAgentSessionInput) {
+		this.label = input.label;
+		this.cwd = input.cwd;
+		this.events = input.events;
+	}
+
+	async prompt<ResponseSchema extends z.ZodType>(agentInput: NornAgentPromptInput<ResponseSchema>): Promise<z.output<ResponseSchema>> {
+		return (await this.promptWithResult(agentInput)).response;
+	}
+
+	private async promptWithResult<ResponseSchema extends z.ZodType>(agentInput: NornAgentPromptInput<ResponseSchema>): Promise<NornAgentRunResult<ResponseSchema>> {
+		if (this.isDisposed) throw new Error(`Workflow agent session is disposed: ${this.label}`);
+		const maxAttempts = Math.max(1, Math.floor(agentInput.maxAttempts ?? DEFAULT_AGENT_ATTEMPTS));
+		const attempts: NornAgentRunRawAttempt[] = [];
+		const startedAtMs = Date.now();
+		let isTerminalEventRecorded = false;
+		await this.input.logger.record({ type: "agent.started", label: this.label, cwd: this.cwd, maxAttempts });
+
+		try {
+			for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+				await this.input.logger.record({ type: "agent.attempt.started", label: this.label, attempt });
+				const raw = await this.runAttempt(agentInput, attempt, attempts.at(-1)?.error);
+				const rawAttempt: NornAgentRunRawAttempt = { attempt, ...raw };
+				attempts.push(rawAttempt);
+
+				try {
+					if (!raw.responseToolCalled) throw new Error(`Agent did not call ${AGENT_RESPONSE_TOOL_NAME}`);
+					const response = agentInput.response.parse(raw.toolResponse);
+					const usage = totalAgentUsage(attempts.map((candidate) => candidate.usage));
+					const result: NornAgentRunResult<ResponseSchema> = {
+						label: this.label,
+						cwd: this.cwd,
+						response,
+						usage,
+						raw: { ...raw, usage, attempts },
+					};
+					await this.input.logs.write(`agents/${safeFileName(this.label)}.json`, JSON.stringify(result, null, 2));
+					isTerminalEventRecorded = true;
+					await this.input.logger.record({ type: "agent.completed", label: this.label, attempts: attempt, durationMs: Date.now() - startedAtMs, usage });
+					return result;
+				} catch (error) {
+					const message = errorMessage(error);
+					attempts[attempts.length - 1] = { ...rawAttempt, error: message };
+					await this.input.logs.write(
+						`agents/${safeFileName(this.label)}.attempt-${attempt}.raw.json`,
+						JSON.stringify({ label: this.label, cwd: this.cwd, raw: attempts.at(-1) }, null, 2),
+					);
+					await this.input.logger.record({ type: "agent.attempt.failed", label: this.label, attempt, error: message });
+					if (attempt === maxAttempts) {
+						const usage = totalAgentUsage(attempts.map((candidate) => candidate.usage));
+						isTerminalEventRecorded = true;
+						await this.input.logger.record({ type: "agent.failed", label: this.label, attempts: attempt, durationMs: Date.now() - startedAtMs, usage, error: message });
+						throw new Error(
+							`Agent ${this.label} did not return a valid structured response after ${attempt} attempt(s). Raw output saved to logs/agents/${safeFileName(this.label)}.attempt-${attempt}.raw.json: ${message}`,
+						);
+					}
+				}
+			}
+
+			throw new Error(`Agent ${this.label} did not run`);
+		} catch (error) {
+			if (!isTerminalEventRecorded) {
+				await this.input.logger.record({
+					type: "agent.failed",
+					label: this.label,
+					attempts: attempts.length,
+					durationMs: Date.now() - startedAtMs,
+					usage: totalAgentUsage(attempts.map((candidate) => candidate.usage)),
+					error: errorMessage(error),
+				});
+			}
+			throw error;
+		}
+	}
+
+	async dispose(): Promise<void> {
+		if (this.isDisposed) return;
+		this.isDisposed = true;
+		const errors: unknown[] = [];
+		try { await this.input.session.abort(); } catch (error) { errors.push(error); }
+		try { this.input.session.dispose(); } catch (error) { errors.push(error); }
+		try { await this.input.resourceBindings.dispose(); } catch (error) { errors.push(error); }
+		if (errors.length) throw new AggregateError(errors, "Agent disposal failed");
+		await this.input.logger.record({ type: "agent.disposed", label: this.label });
+	}
+
+	private async runAttempt<ResponseSchema extends z.ZodType>(
+		agentInput: NornAgentPromptInput<ResponseSchema>,
+		attempt: number,
+		previousError: string | undefined,
+	): Promise<Omit<NornAgentRunRawAttempt, "attempt" | "error">> {
+		const responseRunId = `${this.input.id}:${attempt}:${randomUUID()}`;
+		const messages: unknown[] = [];
+		let text = "";
+		const releaseResponseSlot = this.input.responseCollector.begin(responseRunId, this.label, agentInput.response);
+		const unsubscribe = this.input.session.subscribe((event) => {
+			if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+				text += event.assistantMessageEvent.delta;
+			}
+			if (event.type === "message_end" && event.message) messages.push(event.message);
+		});
+		const abortNestedSession = () => {
+			void this.input.session.abort();
+		};
+		this.input.signal?.addEventListener("abort", abortNestedSession, { once: true });
+
+		let capturedResponse: NornCapturedAgentResponse = { called: false };
+		try {
+			this.input.signal?.throwIfAborted();
+			await this.input.session.prompt(withResponseToolInstruction(agentInput.prompt, agentInput.response, this.label, responseRunId, attempt, previousError), {
+				...agentInput.options,
+				source: agentInput.options?.source ?? "extension",
+			});
+			this.input.signal?.throwIfAborted();
+			capturedResponse = this.input.responseCollector.get(responseRunId);
+			if (!capturedResponse.called) {
+				await this.promptForStructuredResponse(agentInput, responseRunId, attempt, previousError);
+				this.input.signal?.throwIfAborted();
+				capturedResponse = this.input.responseCollector.get(responseRunId);
+			}
+		} finally {
+			this.input.signal?.removeEventListener("abort", abortNestedSession);
+			releaseResponseSlot();
+			unsubscribe();
+		}
+
+		return {
+			text: text.trim(),
+			messages,
+			responseToolCalled: capturedResponse.called,
+			usage: usageFromMessages(messages),
+			toolResponse: capturedResponse.response,
+			sessionFile: this.input.session.sessionFile,
+		};
+	}
+
+	private async promptForStructuredResponse<ResponseSchema extends z.ZodType>(
+		agentInput: NornAgentPromptInput<ResponseSchema>,
+		responseRunId: string,
+		attempt: number,
+		previousError: string | undefined,
+	): Promise<void> {
+		const activeToolNames = this.input.session.getActiveToolNames();
+		await this.input.logger.record({ type: "agent.response-finalization.started", label: this.label, attempt });
+		this.input.session.setActiveToolsByName([AGENT_RESPONSE_TOOL_NAME]);
+		try {
+			await this.input.session.prompt(withResponseToolFinalizationInstruction(agentInput.response, this.label, responseRunId, attempt, previousError), {
+				...agentInput.options,
+				source: agentInput.options?.source ?? "extension",
+			});
+			await this.input.logger.record({ type: "agent.response-finalization.completed", label: this.label, attempt });
+		} catch (error) {
+			await this.input.logger.record({ type: "agent.response-finalization.failed", label: this.label, attempt, error: errorMessage(error) });
+			throw error;
+		} finally {
+			this.input.session.setActiveToolsByName(activeToolNames);
+		}
+	}
+}
+
+function usageFromMessages(messages: readonly unknown[]): NornAgentUsage {
+	return totalAgentUsage(messages.map(usageFromMessage).filter((usage): usage is NornAgentUsage => usage !== undefined));
+}
+
+function usageFromMessage(message: unknown): NornAgentUsage | undefined {
+	if (!message || typeof message !== "object" || !("usage" in message)) return undefined;
+	return agentUsageFromValue((message as { usage?: unknown }).usage) ?? emptyAgentUsage();
+}
+
+function withResponseToolInstruction(
+	prompt: string,
+	responseSchema: z.ZodType,
+	label: string,
+	responseRunId: string,
+	attempt: number,
+	previousError: string | undefined,
+): string {
+	return [
+		prompt,
+		"",
+		"Structured workflow response:",
+		`Use the ${AGENT_RESPONSE_TOOL_NAME} tool as your final action to record the workflow response.`,
+		"Do not emit the workflow response as assistant text or Markdown.",
+		`Pass runId exactly as: ${responseRunId}`,
+		`Pass label exactly as: ${label}`,
+		"Pass the structured workflow response in the tool's response argument.",
+		"The response argument must match this JSON Schema:",
+		JSON.stringify(z.toJSONSchema(responseSchema), null, 2),
+		...(attempt > 1 && previousError ? ["", `Previous structured response attempt failed: ${previousError}`] : []),
+	].join("\n");
+}
+
+function withResponseToolFinalizationInstruction(
+	responseSchema: z.ZodType,
+	label: string,
+	responseRunId: string,
+	attempt: number,
+	previousError: string | undefined,
+): string {
+	return [
+		"Your previous workflow response turn ended without recording the structured response.",
+		`Use the ${AGENT_RESPONSE_TOOL_NAME} tool now. It is the only active tool for this turn.`,
+		"Do not answer in assistant text or Markdown.",
+		`Pass runId exactly as: ${responseRunId}`,
+		`Pass label exactly as: ${label}`,
+		"Pass the structured workflow response in the tool's response argument, based on the work you already completed in this session.",
+		"The response argument must match this JSON Schema:",
+		JSON.stringify(z.toJSONSchema(responseSchema), null, 2),
+		...(attempt > 1 && previousError ? ["", `Previous structured response attempt failed: ${previousError}`] : []),
+	].join("\n");
+}
+
+function withAgentResponseTool(tools: readonly string[] | undefined): string[] {
+	if (!tools) return [...DEFAULT_AGENT_TOOL_ALLOWLIST];
+	return Array.from(new Set([...tools, AGENT_RESPONSE_TOOL_NAME]));
+}

package/assets/packages/cli/src/internal/artifacts.ts

@@ -0,0 +1,26 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { NornFileCoordinator } from "@vimhead.dev/norn/files";
+import type { NornArtifactRef } from "@vimhead.dev/norn";
+
+export class NornArtifacts {
+	constructor(private readonly artifactsRoot: string, private readonly files: NornFileCoordinator) {}
+
+	async write(path: string, content: string): Promise<NornArtifactRef> {
+		await this.files.writeText(this.resolveArtifactPath(path), content);
+		return { path };
+	}
+
+	async read(ref: NornArtifactRef): Promise<string> {
+		return this.files.readText(this.resolveArtifactPath(ref.path));
+	}
+
+	private resolveArtifactPath(path: string): string {
+		if (isAbsolute(path)) throw new Error(`Artifact path must be relative: ${path}`);
+		const resolvedPath = resolve(this.artifactsRoot, path);
+		const relativePath = relative(this.artifactsRoot, resolvedPath);
+		if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+			throw new Error(`Artifact path escapes artifacts directory: ${path}`);
+		}
+		return resolvedPath;
+	}
+}

package/assets/packages/cli/src/internal/commands.ts

@@ -0,0 +1,180 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { WriteStream } from "node:fs";
+import type { NornCommandRunInput, NornCommandRunResult, NornLogRef } from "@vimhead.dev/norn";
+import { errorMessage } from "./errors.ts";
+import { safeFileName } from "./file-names.ts";
+import type { NornRunLogs } from "./logs.ts";
+import type { NornRunLogger } from "./run-log.ts";
+
+type NornCommandRunnerInput = {
+	readonly boundaryRoot: string;
+	readonly boundaryName: string;
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+	readonly logs: NornRunLogs;
+	readonly logger: NornRunLogger;
+};
+
+export class NornCommandRunner {
+	constructor(private readonly input: NornCommandRunnerInput) {}
+
+	async run(commandInput: NornCommandRunInput): Promise<NornCommandRunResult> {
+		const cwd = this.resolveFromCwd(commandInput.cwd ?? this.input.cwd);
+		const startedAtMs = Date.now();
+		const invocationId = randomUUID();
+		const stdoutRef = commandLog({ label: commandInput.label, invocationId, stream: "stdout" });
+		const stderrRef = commandLog({ label: commandInput.label, invocationId, stream: "stderr" });
+		await this.input.logger.record({ type: "command.started", invocationId, label: commandInput.label, command: commandInput.command, cwd, stdoutLogId: stdoutRef.id, stderrLogId: stderrRef.id });
+		let result: SpawnCommandResult;
+		const stdoutLog = await this.input.logs.createWriteStream(stdoutRef);
+		const stderrLog = await this.input.logs.createWriteStream(stderrRef);
+		try {
+			result = await spawnCommand({
+				command: commandInput.command,
+				cwd,
+				env: { ...process.env, ...(commandInput.env ?? {}) },
+				timeoutMs: commandInput.timeoutMs,
+				signal: this.input.signal,
+				stdoutStream: stdoutLog.stream,
+				stderrStream: stderrLog.stream,
+			});
+		} catch (error) {
+			await this.input.logger.record({ type: "command.failed", invocationId, label: commandInput.label, durationMs: Date.now() - startedAtMs, error: errorMessage(error) });
+			throw error;
+		}
+		const commandResult = {
+			label: commandInput.label,
+			command: commandInput.command,
+			cwd,
+			exitCode: result.exitCode,
+			stdoutTail: result.stdoutTail,
+			stderrTail: result.stderrTail,
+			killed: result.killed,
+			stdoutLog: stdoutLog.log,
+			stderrLog: stderrLog.log,
+		};
+		await this.input.logger.record({
+			type: "command.completed",
+			invocationId,
+			label: commandInput.label,
+			durationMs: Date.now() - startedAtMs,
+			exitCode: result.exitCode,
+			killed: result.killed,
+			stdoutLogId: commandResult.stdoutLog.id,
+			stderrLogId: commandResult.stderrLog.id,
+		});
+		return commandResult;
+	}
+
+	private resolveFromCwd(path: string): string {
+		const resolvedPath = isAbsolute(path) ? path : resolve(this.input.cwd, path);
+		const pathFromBoundary = relative(this.input.boundaryRoot, resolvedPath);
+		if (pathFromBoundary === ".." || pathFromBoundary.startsWith(`..${sep}`) || isAbsolute(pathFromBoundary)) {
+			throw new Error(`Command cwd escapes ${this.input.boundaryName} isolation: ${path}`);
+		}
+		return resolvedPath;
+	}
+}
+
+type SpawnCommandInput = {
+	command: string | readonly [string, ...string[]];
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	stdoutStream: WriteStream;
+	stderrStream: WriteStream;
+};
+
+type SpawnCommandResult = {
+	exitCode: number | null;
+	stdoutTail: string;
+	stderrTail: string;
+	killed: boolean;
+};
+
+async function spawnCommand(input: SpawnCommandInput): Promise<SpawnCommandResult> {
+	const command = typeof input.command === "string" ? "bash" : input.command[0];
+	const args = typeof input.command === "string" ? ["-c", input.command] : input.command.slice(1);
+	let killed = false;
+	const stdout = new BoundedTextBuffer();
+	const stderr = new BoundedTextBuffer();
+
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(command, args, { cwd: input.cwd, env: input.env, shell: false });
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		let escalation: ReturnType<typeof setTimeout> | undefined;
+		let isSettled = false;
+		const cleanup = () => {
+			if (timeout) clearTimeout(timeout);
+			if (escalation) clearTimeout(escalation);
+			input.signal?.removeEventListener("abort", killChild);
+		};
+		const finish = (result: SpawnCommandResult) => {
+			if (isSettled) return;
+			isSettled = true;
+			cleanup();
+			void closeStreams(input.stdoutStream, input.stderrStream).then(() => resolvePromise(result), reject);
+		};
+		const fail = (error: Error) => {
+			if (isSettled) return;
+			isSettled = true;
+			cleanup();
+			void closeStreams(input.stdoutStream, input.stderrStream).then(() => reject(error), reject);
+		};
+		const killChild = () => {
+			if (isSettled || killed) return;
+			killed = true;
+			child.kill("SIGTERM");
+			escalation = setTimeout(() => {
+				if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+			}, 5_000);
+			escalation.unref?.();
+		};
+
+		if (input.timeoutMs !== undefined) timeout = setTimeout(killChild, input.timeoutMs);
+		if (input.signal?.aborted) killChild();
+		input.signal?.addEventListener("abort", killChild, { once: true });
+
+		child.stdout?.on("data", (chunk) => {
+			const text = chunk.toString();
+			stdout.append(text);
+			input.stdoutStream.write(text);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = chunk.toString();
+			stderr.append(text);
+			input.stderrStream.write(text);
+		});
+		child.on("error", fail);
+		child.on("close", (code) => finish({ exitCode: code, stdoutTail: stdout.value(), stderrTail: stderr.value(), killed }));
+	});
+}
+
+function commandLog(input: { readonly label: string; readonly invocationId: string; readonly stream: "stdout" | "stderr" }): NornLogRef {
+	return { id: `commands/${safeFileName(input.label)}-${input.invocationId}.${input.stream}` };
+}
+
+class BoundedTextBuffer {
+	private text = "";
+
+	constructor(private readonly maxChars = 128_000) {}
+
+	append(value: string): void {
+		this.text += value;
+		if (this.text.length > this.maxChars) this.text = this.text.slice(this.text.length - this.maxChars);
+	}
+
+	value(): string {
+		return this.text;
+	}
+}
+
+async function closeStreams(...streams: WriteStream[]): Promise<void> {
+	await Promise.all(streams.map((stream) => new Promise<void>((resolvePromise, reject) => {
+		stream.on("error", reject);
+		stream.end(resolvePromise);
+	})));
+}

package/assets/packages/cli/src/internal/documentation-bundle.ts

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+
+export type NornDocumentationFile = {
+	readonly path: string;
+	readonly content: string;
+};
+
+export type NornDocumentationBundle = {
+	readonly version: string;
+	readonly files: readonly NornDocumentationFile[];
+};
+
+export const DOCUMENTATION_PATHS = {
+	readme: "README.md",
+	index: "docs/README.md",
+	docs: "docs",
+	examples: "examples",
+} as const;
+
+export function validateDocumentationBundle(bundle: NornDocumentationBundle): void {
+	if (typeof bundle.version !== "string" || bundle.version.length === 0) throw new Error("Documentation bundle version must not be empty");
+	const paths = new Set<string>();
+	for (const file of bundle.files) {
+		if (typeof file.content !== "string") throw new Error(`Documentation asset must contain text: ${file.path}`);
+		if (typeof file.path !== "string" || !/^[a-zA-Z0-9._/-]+$/.test(file.path) || file.path.split("/").some(part => part === "" || part === "." || part === ".." || part.endsWith(".") || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+			throw new Error(`Invalid documentation asset path: ${file.path}`);
+		}
+		const portablePath = file.path.toLowerCase();
+		if (paths.has(portablePath)) throw new Error(`Duplicate documentation asset path: ${file.path}`);
+		paths.add(portablePath);
+	}
+	for (const path of paths) {
+		const parts = path.split("/");
+		while (parts.pop() && parts.length > 0) {
+			if (paths.has(parts.join("/"))) throw new Error(`Documentation file/directory collision: ${path}`);
+		}
+	}
+	for (const path of [DOCUMENTATION_PATHS.readme, DOCUMENTATION_PATHS.index]) {
+		if (!bundle.files.some(file => file.path === path)) throw new Error(`Missing documentation asset: ${path}`);
+	}
+	if (!bundle.files.some(file => file.path.startsWith("examples/"))) throw new Error("Missing documentation examples");
+}
+
+export function hashDocumentationBundle(bundle: NornDocumentationBundle): string {
+	return createHash("sha256").update(JSON.stringify({
+		version: bundle.version,
+		files: bundle.files.map(file => ({ path: file.path, content: file.content })).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0),
+	})).digest("hex");
+}