@offworld/sdk 0.2.2 → 0.3.0

package/dist/ai/index.mjs

@@ -0,0 +1,924 @@
+import { d as toReferenceName, s as loadConfig } from "../config-DW8J4gl5.mjs";
+import { c as getCommitSha } from "../clone-DyLvmbJZ.mjs";
+import { z } from "zod";
+
+//#region src/ai/errors.ts
+/**
+* Base class for OpenCode reference errors
+*/
+var OpenCodeReferenceError = class extends Error {
+	_tag = "OpenCodeReferenceError";
+	constructor(message, details) {
+		super(message);
+		this.details = details;
+		this.name = "OpenCodeReferenceError";
+	}
+};
+/**
+* Error when the @opencode-ai/sdk package is not installed or invalid
+*/
+var OpenCodeSDKError = class extends OpenCodeReferenceError {
+	_tag = "OpenCodeSDKError";
+	constructor(message) {
+		super(message ?? "Failed to import @opencode-ai/sdk. Install it with: bun add @opencode-ai/sdk");
+		this.name = "OpenCodeSDKError";
+	}
+};
+/**
+* Error when the requested provider is not found
+*/
+var InvalidProviderError = class extends OpenCodeReferenceError {
+	_tag = "InvalidProviderError";
+	hint;
+	constructor(providerID, availableProviders) {
+		const hint = availableProviders.length > 0 ? `Available providers: ${availableProviders.join(", ")}` : "No providers available. Check your OpenCode configuration.";
+		super(`Provider "${providerID}" not found. ${hint}`);
+		this.providerID = providerID;
+		this.availableProviders = availableProviders;
+		this.name = "InvalidProviderError";
+		this.hint = hint;
+	}
+};
+/**
+* Error when the provider exists but is not connected/authenticated
+*/
+var ProviderNotConnectedError = class extends OpenCodeReferenceError {
+	_tag = "ProviderNotConnectedError";
+	hint;
+	constructor(providerID, connectedProviders) {
+		const hint = connectedProviders.length > 0 ? `Connected providers: ${connectedProviders.join(", ")}. Run 'opencode auth ${providerID}' to connect.` : `No providers connected. Run 'opencode auth ${providerID}' to authenticate.`;
+		super(`Provider "${providerID}" is not connected. ${hint}`);
+		this.providerID = providerID;
+		this.connectedProviders = connectedProviders;
+		this.name = "ProviderNotConnectedError";
+		this.hint = hint;
+	}
+};
+/**
+* Error when the requested model is not found for a provider
+*/
+var InvalidModelError = class extends OpenCodeReferenceError {
+	_tag = "InvalidModelError";
+	hint;
+	constructor(modelID, providerID, availableModels) {
+		const hint = availableModels.length > 0 ? `Available models for ${providerID}: ${availableModels.slice(0, 10).join(", ")}${availableModels.length > 10 ? ` (and ${availableModels.length - 10} more)` : ""}` : `No models available for provider "${providerID}".`;
+		super(`Model "${modelID}" not found for provider "${providerID}". ${hint}`);
+		this.modelID = modelID;
+		this.providerID = providerID;
+		this.availableModels = availableModels;
+		this.name = "InvalidModelError";
+		this.hint = hint;
+	}
+};
+/**
+* Error when the OpenCode server fails to start
+*/
+var ServerStartError = class extends OpenCodeReferenceError {
+	_tag = "ServerStartError";
+	hint;
+	constructor(message, port, details) {
+		const hint = port ? `Failed to start server on port ${port}. Ensure no other process is using this port.` : "Failed to start OpenCode server. Check your OpenCode installation and configuration.";
+		super(`${message}. ${hint}`, details);
+		this.port = port;
+		this.name = "ServerStartError";
+		this.hint = hint;
+	}
+};
+/**
+* Error when a session operation fails
+*/
+var SessionError = class extends OpenCodeReferenceError {
+	_tag = "SessionError";
+	hint;
+	constructor(message, sessionId, sessionState, details) {
+		const hint = `Session operation failed${sessionId ? ` (session: ${sessionId})` : ""}.${sessionState ? ` State: ${sessionState}.` : ""} Try creating a new session.`;
+		super(`${message}. ${hint}`, details);
+		this.sessionId = sessionId;
+		this.sessionState = sessionState;
+		this.name = "SessionError";
+		this.hint = hint;
+	}
+};
+/**
+* Error when a request times out
+*/
+var TimeoutError = class extends OpenCodeReferenceError {
+	_tag = "TimeoutError";
+	hint;
+	constructor(timeoutMs, operation = "operation") {
+		const hint = `The ${operation} did not complete within ${timeoutMs}ms. Consider increasing the timeout or checking if the model is responding.`;
+		super(`Timeout: ${operation} did not complete within ${timeoutMs}ms. ${hint}`);
+		this.timeoutMs = timeoutMs;
+		this.operation = operation;
+		this.name = "TimeoutError";
+		this.hint = hint;
+	}
+};
+
+//#endregion
+//#region src/ai/stream/types.ts
+/**
+* Zod schemas for OpenCode stream events
+* Replaces inline `as` casts with runtime-validated types
+*/
+const PartBaseSchema = z.object({
+	id: z.string().optional(),
+	sessionID: z.string().optional(),
+	messageID: z.string().optional()
+});
+const TextPartSchema = PartBaseSchema.extend({
+	type: z.literal("text"),
+	text: z.string().optional()
+});
+const ToolStatePendingSchema = z.object({ status: z.literal("pending") });
+const ToolStateRunningSchema = z.object({
+	status: z.literal("running"),
+	title: z.string().optional(),
+	input: z.unknown().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	time: z.object({ start: z.number() }).optional()
+});
+const ToolStateCompletedSchema = z.object({
+	status: z.literal("completed"),
+	title: z.string().optional(),
+	input: z.record(z.string(), z.unknown()).optional(),
+	output: z.string().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	time: z.object({
+		start: z.number(),
+		end: z.number()
+	}).optional()
+});
+const ToolStateErrorSchema = z.object({
+	status: z.literal("error"),
+	error: z.string().optional(),
+	input: z.record(z.string(), z.unknown()).optional(),
+	time: z.object({
+		start: z.number(),
+		end: z.number()
+	}).optional()
+});
+const ToolStateSchema = z.discriminatedUnion("status", [
+	ToolStatePendingSchema,
+	ToolStateRunningSchema,
+	ToolStateCompletedSchema,
+	ToolStateErrorSchema
+]);
+const ToolPartSchema = PartBaseSchema.extend({
+	type: z.literal("tool"),
+	callID: z.string().optional(),
+	tool: z.string().optional(),
+	state: ToolStateSchema.optional()
+});
+const StepStartPartSchema = PartBaseSchema.extend({ type: z.literal("step-start") });
+const StepFinishPartSchema = PartBaseSchema.extend({
+	type: z.literal("step-finish"),
+	reason: z.string().optional()
+});
+const ToolUsePartSchema = PartBaseSchema.extend({
+	type: z.literal("tool-use"),
+	toolUseId: z.string().optional(),
+	name: z.string().optional()
+});
+const ToolResultPartSchema = PartBaseSchema.extend({
+	type: z.literal("tool-result"),
+	toolUseId: z.string().optional()
+});
+const MessagePartSchema = z.discriminatedUnion("type", [
+	TextPartSchema,
+	ToolPartSchema,
+	StepStartPartSchema,
+	StepFinishPartSchema,
+	ToolUsePartSchema,
+	ToolResultPartSchema
+]);
+/**
+* Session error payload
+*/
+const SessionErrorSchema = z.object({
+	name: z.string().optional(),
+	message: z.string().optional(),
+	code: z.string().optional()
+});
+const MessagePartUpdatedPropsSchema = z.object({ part: MessagePartSchema });
+/**
+* Properties for session.idle event
+*/
+const SessionIdlePropsSchema = z.object({ sessionID: z.string() });
+/**
+* Properties for session.error event
+*/
+const SessionErrorPropsSchema = z.object({
+	sessionID: z.string(),
+	error: SessionErrorSchema.optional()
+});
+/**
+* Properties for session.updated event
+*/
+const SessionUpdatedPropsSchema = z.object({
+	sessionID: z.string(),
+	status: z.string().optional()
+});
+/**
+* message.part.updated event
+*/
+const MessagePartUpdatedEventSchema = z.object({
+	type: z.literal("message.part.updated"),
+	properties: MessagePartUpdatedPropsSchema
+});
+/**
+* session.idle event
+*/
+const SessionIdleEventSchema = z.object({
+	type: z.literal("session.idle"),
+	properties: SessionIdlePropsSchema
+});
+/**
+* session.error event
+*/
+const SessionErrorEventSchema = z.object({
+	type: z.literal("session.error"),
+	properties: SessionErrorPropsSchema
+});
+/**
+* session.updated event
+*/
+const SessionUpdatedEventSchema = z.object({
+	type: z.literal("session.updated"),
+	properties: SessionUpdatedPropsSchema
+});
+/**
+* Generic event for unknown types (passthrough)
+*/
+const GenericEventSchema = z.object({
+	type: z.string(),
+	properties: z.record(z.string(), z.unknown())
+});
+
+//#endregion
+//#region src/ai/stream/accumulator.ts
+/**
+* Accumulates text from streaming message parts.
+* Tracks multiple parts by ID and provides delta text between updates.
+*/
+var TextAccumulator = class {
+	parts = /* @__PURE__ */ new Map();
+	_firstTextReceived = false;
+	/**
+	* Whether any text has been received
+	*/
+	get hasReceivedText() {
+		return this._firstTextReceived;
+	}
+	/**
+	* Accumulate text from a message part and return the delta (new text only).
+	* Returns null if the part should be skipped (non-text, no ID, no text).
+	*/
+	accumulatePart(part) {
+		if (part.type !== "text" || !part.text || !part.id) return null;
+		const partId = part.id;
+		const prevText = this.parts.get(partId) ?? "";
+		this.parts.set(partId, part.text);
+		if (!this._firstTextReceived) this._firstTextReceived = true;
+		if (part.text.length > prevText.length) return part.text.slice(prevText.length);
+		return null;
+	}
+	/**
+	* Get the full accumulated text from all parts
+	*/
+	getFullText() {
+		return Array.from(this.parts.values()).join("");
+	}
+	/**
+	* Get the number of distinct parts accumulated
+	*/
+	getPartCount() {
+		return this.parts.size;
+	}
+	/**
+	* Get info about each part for debugging
+	*/
+	getPartInfo() {
+		return Array.from(this.parts.entries()).map(([id, text]) => ({
+			id,
+			length: text.length
+		}));
+	}
+	/**
+	* Clear accumulated text
+	*/
+	clear() {
+		this.parts.clear();
+		this._firstTextReceived = false;
+	}
+};
+
+//#endregion
+//#region src/ai/stream/transformer.ts
+/**
+* Stream event transformer and parser
+* Safely parses and validates stream events using Zod schemas
+*/
+/**
+* Parse a raw stream event into a typed result.
+* Uses safe parsing - returns type: "unknown" for unrecognized or invalid events.
+*/
+function parseStreamEvent(event) {
+	switch (event.type) {
+		case "message.part.updated": {
+			const propsResult = MessagePartUpdatedPropsSchema.safeParse(event.properties);
+			if (!propsResult.success) return {
+				type: "unknown",
+				rawType: event.type
+			};
+			const props = propsResult.data;
+			return {
+				type: "message.part.updated",
+				props,
+				textPart: props.part.type === "text" ? props.part : null,
+				toolPart: props.part.type === "tool" ? props.part : null
+			};
+		}
+		case "session.idle": {
+			const propsResult = SessionIdlePropsSchema.safeParse(event.properties);
+			if (!propsResult.success) return {
+				type: "unknown",
+				rawType: event.type
+			};
+			return {
+				type: "session.idle",
+				props: propsResult.data
+			};
+		}
+		case "session.error": {
+			const propsResult = SessionErrorPropsSchema.safeParse(event.properties);
+			if (!propsResult.success) return {
+				type: "unknown",
+				rawType: event.type
+			};
+			const props = propsResult.data;
+			let error = null;
+			if (props.error) {
+				const errorResult = SessionErrorSchema.safeParse(props.error);
+				if (errorResult.success) error = errorResult.data;
+			}
+			return {
+				type: "session.error",
+				props,
+				error
+			};
+		}
+		default: return {
+			type: "unknown",
+			rawType: event.type
+		};
+	}
+}
+function isEventForSession(event, sessionId) {
+	const props = event.properties;
+	if ("sessionID" in props && typeof props.sessionID === "string") return props.sessionID === sessionId;
+	if ("part" in props && typeof props.part === "object" && props.part !== null && "sessionID" in props.part && typeof props.part.sessionID === "string") return props.part.sessionID === sessionId;
+	return true;
+}
+
+//#endregion
+//#region src/ai/opencode.ts
+const DEFAULT_AI_PROVIDER = "opencode";
+const DEFAULT_AI_MODEL = "claude-opus-4-5";
+let cachedCreateOpencode = null;
+let cachedCreateOpencodeClient = null;
+async function getOpenCodeSDK() {
+	if (cachedCreateOpencode && cachedCreateOpencodeClient) return {
+		createOpencode: cachedCreateOpencode,
+		createOpencodeClient: cachedCreateOpencodeClient
+	};
+	try {
+		const sdk = await import("@opencode-ai/sdk");
+		if (typeof sdk.createOpencode !== "function" || typeof sdk.createOpencodeClient !== "function") throw new OpenCodeSDKError("SDK missing required exports");
+		cachedCreateOpencode = sdk.createOpencode;
+		cachedCreateOpencodeClient = sdk.createOpencodeClient;
+		return {
+			createOpencode: cachedCreateOpencode,
+			createOpencodeClient: cachedCreateOpencodeClient
+		};
+	} catch (error) {
+		if (error instanceof OpenCodeSDKError) throw error;
+		throw new OpenCodeSDKError();
+	}
+}
+function formatToolMessage(tool, state) {
+	if (state.title) return state.title;
+	if (!tool) return null;
+	const input = state.input && typeof state.input === "object" && !Array.isArray(state.input) ? state.input : void 0;
+	if (!input) return `Running ${tool}...`;
+	switch (tool) {
+		case "read": {
+			const path = input.filePath ?? input.path;
+			if (typeof path === "string") return `Reading ${path.split("/").pop()}...`;
+			return "Reading file...";
+		}
+		case "glob": {
+			const pattern = input.pattern;
+			if (typeof pattern === "string") return `Globbing ${pattern}...`;
+			return "Searching files...";
+		}
+		case "grep": {
+			const pattern = input.pattern;
+			if (typeof pattern === "string") return `Searching for "${pattern.length > 30 ? `${pattern.slice(0, 30)}...` : pattern}"...`;
+			return "Searching content...";
+		}
+		case "list": {
+			const path = input.path;
+			if (typeof path === "string") return `Listing ${path}...`;
+			return "Listing directory...";
+		}
+		default: return `Running ${tool}...`;
+	}
+}
+async function streamPrompt(options) {
+	const { prompt, cwd, systemPrompt, provider: optProvider, model: optModel, timeoutMs, onDebug, onStream } = options;
+	const debug = onDebug ?? (() => {});
+	const stream = onStream ?? (() => {});
+	const startTime = Date.now();
+	debug("Loading OpenCode SDK...");
+	const { createOpencode, createOpencodeClient } = await getOpenCodeSDK();
+	const maxAttempts = 10;
+	let server = null;
+	let client = null;
+	let port = 0;
+	const config = {
+		plugin: [],
+		mcp: {},
+		instructions: [],
+		agent: {
+			build: { disable: true },
+			general: { disable: true },
+			plan: { disable: true },
+			explore: { disable: true },
+			analyze: {
+				prompt: [
+					"You are an expert at analyzing open source codebases and producing documentation.",
+					"",
+					"Your job is to read the codebase and produce structured output based on the user's request.",
+					"Use glob to discover files, grep to search for patterns, and read to examine file contents.",
+					"",
+					"Guidelines:",
+					"- Explore the codebase thoroughly before producing output",
+					"- Focus on understanding architecture, key abstractions, and usage patterns",
+					"- When asked for JSON output, respond with ONLY valid JSON - no markdown, no code blocks",
+					"- When asked for prose, write clear and concise documentation",
+					"- Always base your analysis on actual code you've read, never speculate"
+				].join("\n"),
+				mode: "primary",
+				description: "Analyze open source codebases and produce summaries and reference files",
+				tools: {
+					read: true,
+					grep: true,
+					glob: true,
+					list: true,
+					write: false,
+					bash: false,
+					delete: false,
+					edit: false,
+					patch: false,
+					path: false,
+					todowrite: false,
+					todoread: false,
+					websearch: false,
+					webfetch: false,
+					codesearch: false,
+					skill: false,
+					task: false,
+					mcp: false,
+					question: false,
+					plan_enter: false,
+					plan_exit: false
+				},
+				permission: {
+					edit: "deny",
+					bash: "deny",
+					webfetch: "deny",
+					external_directory: "deny"
+				}
+			}
+		}
+	};
+	debug("Starting embedded OpenCode server...");
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		port = Math.floor(Math.random() * 3e3) + 3e3;
+		try {
+			server = (await createOpencode({
+				port,
+				cwd,
+				config
+			})).server;
+			client = createOpencodeClient({
+				baseUrl: `http://localhost:${port}`,
+				directory: cwd
+			});
+			debug(`Server started on port ${port}`);
+			break;
+		} catch (err) {
+			if (err instanceof Error && err.message?.includes("port")) continue;
+			throw new ServerStartError("Failed to start OpenCode server", port, err);
+		}
+	}
+	if (!server || !client) throw new ServerStartError("Failed to start OpenCode server after all attempts");
+	const providerID = optProvider ?? DEFAULT_AI_PROVIDER;
+	const modelID = optModel ?? DEFAULT_AI_MODEL;
+	try {
+		debug("Creating session...");
+		const sessionResult = await client.session.create();
+		if (sessionResult.error) throw new SessionError("Failed to create session", void 0, void 0, sessionResult.error);
+		const sessionId = sessionResult.data.id;
+		debug(`Session created: ${sessionId}`);
+		debug("Validating provider and model...");
+		const providerResult = await client.provider.list();
+		if (providerResult.error) throw new OpenCodeReferenceError("Failed to fetch provider list", providerResult.error);
+		const { all: allProviders, connected: connectedProviders } = providerResult.data;
+		const allProviderIds = allProviders.map((p) => p.id);
+		const provider = allProviders.find((p) => p.id === providerID);
+		if (!provider) throw new InvalidProviderError(providerID, allProviderIds);
+		if (!connectedProviders.includes(providerID)) throw new ProviderNotConnectedError(providerID, connectedProviders);
+		const availableModelIds = Object.keys(provider.models);
+		if (!provider.models[modelID]) throw new InvalidModelError(modelID, providerID, availableModelIds);
+		debug(`Provider "${providerID}" and model "${modelID}" validated`);
+		debug("Subscribing to events...");
+		const { stream: eventStream } = await client.event.subscribe();
+		const fullPrompt = systemPrompt ? `${systemPrompt}\n\nAnalyzing codebase at: ${cwd}\n\n${prompt}` : `Analyzing codebase at: ${cwd}\n\n${prompt}`;
+		debug("Sending prompt...");
+		const promptPromise = client.session.prompt({
+			path: { id: sessionId },
+			body: {
+				agent: "analyze",
+				parts: [{
+					type: "text",
+					text: fullPrompt
+				}],
+				model: {
+					providerID,
+					modelID
+				}
+			}
+		});
+		const textAccumulator = new TextAccumulator();
+		debug("Waiting for response...");
+		let timeoutId = null;
+		const processEvents = async () => {
+			for await (const event of eventStream) {
+				if (!isEventForSession(event, sessionId)) continue;
+				const parsed = parseStreamEvent(event);
+				switch (parsed.type) {
+					case "message.part.updated":
+						if (parsed.toolPart?.state) {
+							const { state, tool } = parsed.toolPart;
+							if (state.status === "running") {
+								const message = formatToolMessage(tool, state);
+								if (message) debug(message);
+							}
+						}
+						if (parsed.textPart) {
+							const delta = textAccumulator.accumulatePart(parsed.textPart);
+							if (!textAccumulator.hasReceivedText) debug("Writing reference...");
+							if (delta) stream(delta);
+						}
+						break;
+					case "session.idle":
+						if (parsed.props.sessionID === sessionId) {
+							debug("Response complete");
+							return textAccumulator.getFullText();
+						}
+						break;
+					case "session.error":
+						if (parsed.props.sessionID === sessionId) {
+							const errorName = parsed.error?.name ?? "Unknown session error";
+							debug(`Session error: ${JSON.stringify(parsed.props.error)}`);
+							throw new SessionError(errorName, sessionId, "error", parsed.props.error);
+						}
+						break;
+					case "unknown": break;
+				}
+			}
+			return textAccumulator.getFullText();
+		};
+		let responseText;
+		if (timeoutMs && timeoutMs > 0) {
+			const timeoutPromise = new Promise((_, reject) => {
+				timeoutId = setTimeout(() => {
+					reject(new TimeoutError(timeoutMs, "session response"));
+				}, timeoutMs);
+			});
+			responseText = await Promise.race([processEvents(), timeoutPromise]);
+			if (timeoutId) clearTimeout(timeoutId);
+		} else responseText = await processEvents();
+		await promptPromise;
+		if (!responseText) throw new OpenCodeReferenceError("No response received from OpenCode");
+		debug(`Response received (${responseText.length} chars)`);
+		const durationMs = Date.now() - startTime;
+		debug(`Complete in ${durationMs}ms`);
+		return {
+			text: responseText,
+			sessionId,
+			durationMs
+		};
+	} finally {
+		debug("Closing server...");
+		server.close();
+	}
+}
+
+//#endregion
+//#region src/generate.ts
+/**
+* This module provides a streamlined approach to generating reference files
+* by delegating all codebase exploration to the AI agent via OpenCode.
+*/
+function createReferenceGenerationPrompt(referenceName) {
+	return `You are an expert at analyzing open source libraries and producing reference documentation for AI coding agents.
+
+## PRIMARY GOAL
+
+Generate a reference markdown file that helps developers USE this library effectively. This is NOT a contribution guide - it's a usage reference for developers consuming this library in their own projects.
+
+## CRITICAL RULES
+
+1. **USER PERSPECTIVE ONLY**: Write for developers who will npm/pip/cargo install this library and use it in THEIR code.
+   - DO NOT include: how to contribute, internal test commands, repo-specific policies
+   - DO NOT include: "never mock in tests" or similar internal dev guidelines
+   - DO NOT include: commands like "npx hereby", "just ready", "bun test" that run the library's own tests
+   - DO include: how to install, import, configure, and use the public API
+
+2. **NO FRONTMATTER**: Output pure markdown with NO YAML frontmatter. Start directly with the library name heading.
+
+3. **QUICK REFERENCES**: Include a "Quick References" section with paths to key entry points in the repo:
+   - Paths must be relative from repo root (e.g., \`src/index.ts\`, \`docs/api.md\`)
+   - Include: main entry point, type definitions, README, key docs
+   - DO NOT include absolute paths or user-specific paths
+   - Keep to 3-5 most important files that help users understand the library
+
+4. **PUBLIC API FOCUS**: Document what users import and call, not internal implementation details.
+   - Entry points: what to import from the package
+   - Configuration: how to set up/initialize
+   - Core methods/functions: the main API surface
+   - Types: key TypeScript interfaces users need
+
+5. **MONOREPO AWARENESS**: Many libraries are monorepos with multiple packages:
+   - Check for \`packages/\`, \`apps/\`, \`crates/\`, or \`libs/\` directories
+   - Check root package.json for \`workspaces\` field
+   - If monorepo: document the package structure and key packages users would install
+   - Use full paths from repo root (e.g., \`packages/core/src/index.ts\`)
+   - Identify which packages are publishable vs internal
+
+## EXPLORATION STEPS
+
+Use Read, Grep, Glob tools to explore:
+1. Root package.json / Cargo.toml - check for workspaces/monorepo config
+2. Check for \`packages/\`, \`apps/\`, \`crates/\` directories
+3. README.md - official usage documentation
+4. For monorepos: explore each publishable package's entry point
+5. docs/ or website/ - find documentation
+6. examples/ - real usage patterns
+7. TypeScript definitions (.d.ts) - public API surface
+
+## OUTPUT FORMAT
+
+IMPORTANT: Reference name is "${referenceName}" (for internal tracking only - do NOT include in output).
+
+\`\`\`markdown
+# {Library Name}
+
+{2-3 sentence overview of what this library does and its key value proposition}
+
+## Quick References
+
+| File | Purpose |
+|------|---------|
+| \`packages/{pkg}/src/index.ts\` | Main entry point (monorepo example) |
+| \`src/index.ts\` | Main entry point (single-package example) |
+| \`README.md\` | Documentation |
+
+(For monorepos, include paths to key publishable packages)
+
+## Packages (for monorepos only)
+
+| Package | npm name | Description |
+|---------|----------|-------------|
+| \`packages/core\` | \`@scope/core\` | Core functionality |
+| \`packages/react\` | \`@scope/react\` | React bindings |
+
+(OMIT this section for single-package repos)
+
+## When to Use
+
+- {Practical scenario where a developer would reach for this library}
+- {Another real-world use case}
+- {Problem this library solves}
+
+## Installation
+
+\`\`\`bash
+# Single package
+npm install {package-name}
+
+# Monorepo (show key packages)
+npm install @scope/core @scope/react
+\`\`\`
+
+## Best Practices
+
+1. {Actionable best practice for USERS of this library}
+2. {Common mistake to avoid when using this library}
+3. {Performance or correctness tip}
+
+## Common Patterns
+
+**{Pattern Name}:**
+\`\`\`{language}
+{Minimal working code example}
+\`\`\`
+
+**{Another Pattern}:**
+\`\`\`{language}
+{Another code example}
+\`\`\`
+
+## API Quick Reference
+
+| Export | Type | Description |
+|--------|------|-------------|
+| \`{main export}\` | {type} | {what it does} |
+| \`{another export}\` | {type} | {what it does} |
+
+{Add more sections as appropriate for the library: Configuration, Types, CLI Commands (if user-facing), etc.}
+\`\`\`
+
+## QUALITY CHECKLIST
+
+Before outputting, verify:
+- [ ] NO YAML frontmatter - start directly with # heading
+- [ ] Every code example is something a USER would write, not a contributor
+- [ ] No internal test commands or contribution workflows
+- [ ] Quick References paths are relative from repo root (no absolute/user paths)
+- [ ] Best practices are for using the library, not developing it
+- [ ] If monorepo: Packages section lists publishable packages with npm names
+- [ ] If monorepo: paths include package directory (e.g., \`packages/core/src/index.ts\`)
+
+Now explore the codebase and generate the reference content.
+
+## OUTPUT INSTRUCTIONS
+
+After exploring, output your complete reference wrapped in XML tags like this:
+
+\`\`\`
+<reference_output>
+(your complete markdown reference here)
+</reference_output>
+\`\`\`
+
+REQUIREMENTS:
+- Start with a level-1 heading with the actual library name (e.g., "# TanStack Query")
+- Include sections: Quick References (table), When to Use (bullets), Installation, Best Practices, Common Patterns (with code), API Quick Reference (table)
+- Minimum 2000 characters of actual content - short or placeholder content will be rejected
+- Fill in real information from your exploration - do not use placeholder text like "{Library Name}"
+- No YAML frontmatter - start directly with the markdown heading
+- Output ONLY the reference inside the tags, no other text
+
+Begin exploring now.`;
+}
+/**
+* Extract the actual reference markdown content from AI response.
+* The response may include echoed prompt/system context before the actual reference.
+* Handles multiple edge cases:
+* - Model echoes the prompt template (skip template content)
+* - Model forgets to close the tag (extract to end of response)
+* - Multiple tag pairs (find the one with real content)
+*/
+function extractReferenceContent(rawResponse, onDebug) {
+	const openTag = "<reference_output>";
+	const closeTag = "</reference_output>";
+	onDebug?.(`[extract] Raw response length: ${rawResponse.length} chars`);
+	const openIndices = [];
+	const closeIndices = [];
+	let pos = 0;
+	while ((pos = rawResponse.indexOf(openTag, pos)) !== -1) {
+		openIndices.push(pos);
+		pos += 18;
+	}
+	pos = 0;
+	while ((pos = rawResponse.indexOf(closeTag, pos)) !== -1) {
+		closeIndices.push(pos);
+		pos += 19;
+	}
+	onDebug?.(`[extract] Found ${openIndices.length} open tag(s), ${closeIndices.length} close tag(s)`);
+	const cleanContent = (raw) => {
+		let content = raw.trim();
+		if (content.startsWith("```")) {
+			content = content.replace(/^```(?:markdown)?\s*\n?/, "");
+			content = content.replace(/\n?```\s*$/, "");
+		}
+		return content.trim();
+	};
+	const isTemplateContent = (content) => {
+		return content.includes("{Library Name}") || content.includes("(your complete markdown reference here)");
+	};
+	for (let i = openIndices.length - 1; i >= 0; i--) {
+		const openIdx = openIndices[i];
+		if (openIdx === void 0) continue;
+		const closeIdx = closeIndices.find((c) => c > openIdx);
+		if (closeIdx !== void 0) {
+			const content = cleanContent(rawResponse.slice(openIdx + 18, closeIdx));
+			onDebug?.(`[extract] Pair ${i}: open=${openIdx}, close=${closeIdx}, len=${content.length}`);
+			onDebug?.(`[extract] Preview: "${content.slice(0, 200)}${content.length > 200 ? "..." : ""}"`);
+			if (isTemplateContent(content)) {
+				onDebug?.(`[extract] Skipping pair ${i} - template placeholder content`);
+				continue;
+			}
+			if (content.length >= 500) {
+				onDebug?.(`[extract] Using pair ${i} - valid content`);
+				validateReferenceContent(content);
+				return content;
+			}
+			onDebug?.(`[extract] Pair ${i} too short (${content.length} chars)`);
+		}
+	}
+	const lastOpenIdx = openIndices[openIndices.length - 1];
+	if (lastOpenIdx !== void 0) {
+		if (!closeIndices.some((c) => c > lastOpenIdx)) {
+			onDebug?.(`[extract] Last open tag at ${lastOpenIdx} is unclosed - extracting to end`);
+			const content = cleanContent(rawResponse.slice(lastOpenIdx + 18));
+			onDebug?.(`[extract] Unclosed content: ${content.length} chars`);
+			onDebug?.(`[extract] Preview: "${content.slice(0, 200)}${content.length > 200 ? "..." : ""}"`);
+			if (!isTemplateContent(content) && content.length >= 500) {
+				onDebug?.(`[extract] Using unclosed content - valid`);
+				validateReferenceContent(content);
+				return content;
+			}
+		}
+	}
+	onDebug?.(`[extract] No valid content found`);
+	onDebug?.(`[extract] Response tail: "${rawResponse.slice(-300)}"`);
+	throw new Error("Failed to extract reference content: no valid <reference_output> tags found. The AI may have failed to follow the output format or produced placeholder content.");
+}
+/**
+* Validate extracted reference content has minimum required structure.
+* Throws if content is invalid.
+*/
+function validateReferenceContent(content) {
+	const foundPlaceholders = [
+		"{Library Name}",
+		"{Full overview paragraph}",
+		"{Table with 3-5 key files}",
+		"{3+ bullet points}",
+		"{Install commands}",
+		"{3+ numbered items}",
+		"{2+ code examples",
+		"{Table of key exports}",
+		"{Additional sections"
+	].filter((p) => content.includes(p));
+	if (foundPlaceholders.length > 0) throw new Error(`Invalid reference content: contains template placeholders (${foundPlaceholders.slice(0, 3).join(", ")}). The AI echoed the format instead of generating actual content.`);
+	if (content.length < 500) throw new Error(`Invalid reference content: too short (${content.length} chars, minimum 500). The AI may have produced placeholder or incomplete content.`);
+	if (!content.startsWith("#")) throw new Error("Invalid reference content: must start with markdown heading. Content must begin with '# Library Name' (no YAML frontmatter).");
+}
+/**
+* Generate a reference markdown file for a repository using AI.
+*
+* Opens an OpenCode session and instructs the AI agent to explore the codebase
+* using Read, Grep, and Glob tools, then produce a comprehensive reference.
+*
+* @param repoPath - Path to the repository to analyze
+* @param repoName - Qualified name of the repo (e.g., "tanstack/query" or "my-local-repo")
+* @param options - Generation options (provider, model, callbacks)
+* @returns The generated reference content and commit SHA
+*/
+async function generateReferenceWithAI(repoPath, repoName, options = {}) {
+	const { provider, model, onDebug, onStream } = options;
+	const [configProvider, configModel] = loadConfig().defaultModel?.split("/") ?? [];
+	const aiProvider = provider ?? configProvider;
+	const aiModel = model ?? configModel;
+	onDebug?.(`Starting AI reference generation for ${repoName}`);
+	onDebug?.(`Repo path: ${repoPath}`);
+	onDebug?.(`Provider: ${aiProvider ?? "default"}, Model: ${aiModel ?? "default"}`);
+	const commitSha = getCommitSha(repoPath);
+	onDebug?.(`Commit SHA: ${commitSha}`);
+	const referenceName = toReferenceName(repoName);
+	onDebug?.(`Reference name: ${referenceName}`);
+	const result = await streamPrompt({
+		prompt: createReferenceGenerationPrompt(referenceName),
+		cwd: repoPath,
+		provider: aiProvider,
+		model: aiModel,
+		onDebug,
+		onStream
+	});
+	onDebug?.(`Generation complete (${result.durationMs}ms, ${result.text.length} chars)`);
+	const referenceContent = extractReferenceContent(result.text, onDebug);
+	onDebug?.(`Extracted reference content (${referenceContent.length} chars)`);
+	return {
+		referenceContent,
+		commitSha
+	};
+}
+
+//#endregion
+export { DEFAULT_AI_MODEL, DEFAULT_AI_PROVIDER, InvalidModelError, InvalidProviderError, OpenCodeReferenceError, OpenCodeSDKError, ProviderNotConnectedError, ServerStartError, SessionError, TimeoutError, generateReferenceWithAI, streamPrompt };
+//# sourceMappingURL=index.mjs.map