btca-server 1.0.20

package/README.md

@@ -0,0 +1,195 @@
+# @btca/server
+
+BTCA (Better Context AI) server for answering questions about your codebase using OpenCode AI.
+
+## Installation
+
+```bash
+bun add @btca/server
+```
+
+## Usage
+
+### Starting the Server
+
+```typescript
+import { startServer } from '@btca/server';
+
+// Start with default options (port 8080 or process.env.PORT)
+const server = await startServer();
+console.log(`Server running at ${server.url}`);
+
+// Start with custom port
+const server = await startServer({ port: 3000 });
+
+// Start with quiet mode (no logging)
+const server = await startServer({ port: 3000, quiet: true });
+
+// Stop the server when needed
+server.stop();
+```
+
+### Server Instance
+
+The `startServer` function returns a `ServerInstance` object:
+
+```typescript
+interface ServerInstance {
+  port: number;       // Actual port the server is running on
+  url: string;        // Full URL (e.g., "http://localhost:8080")
+  stop: () => void;   // Function to stop the server
+}
+```
+
+### Random Port Assignment
+
+You can pass `port: 0` to let the OS assign a random available port:
+
+```typescript
+const server = await startServer({ port: 0 });
+console.log(`Server running on port ${server.port}`);
+```
+
+## API Endpoints
+
+Once the server is running, it exposes the following REST API endpoints:
+
+### Health Check
+
+```
+GET /
+```
+
+Returns service status and version info.
+
+### Configuration
+
+```
+GET /config
+```
+
+Returns current configuration (provider, model, resources).
+
+### Resources
+
+```
+GET /resources
+```
+
+Lists all configured resources (local directories or git repositories).
+
+```
+POST /config/resources
+```
+
+Add a new resource (git or local).
+
+```
+DELETE /config/resources
+```
+
+Remove a resource by name.
+
+```
+POST /clear
+```
+
+Clear all locally cloned resources.
+
+### Questions
+
+```
+POST /question
+```
+
+Ask a question (non-streaming response).
+
+```
+POST /question/stream
+```
+
+Ask a question with streaming SSE response.
+
+### OpenCode Instance
+
+```
+POST /opencode
+```
+
+Get an OpenCode instance URL for a collection of resources.
+
+### Model Configuration
+
+```
+PUT /config/model
+```
+
+Update the AI provider and model configuration.
+
+## Configuration
+
+The server reads configuration from `~/.btca/config.toml` or your local project's `.btca/config.toml`. You'll need to configure:
+
+- **AI Provider**: OpenCode AI provider (e.g., "anthropic")
+- **Model**: AI model to use (e.g., "claude-3-7-sonnet-20250219")
+- **Resources**: Local directories or git repositories to query
+
+Example config.toml:
+
+```toml
+provider = "anthropic"
+model = "claude-3-7-sonnet-20250219"
+resourcesDirectory = "~/.btca/resources"
+collectionsDirectory = "~/.btca/collections"
+
+[[resources]]
+type = "local"
+name = "my-project"
+path = "/path/to/my/project"
+
+[[resources]]
+type = "git"
+name = "some-repo"
+url = "https://github.com/user/repo"
+branch = "main"
+```
+
+## Environment Variables
+
+- `PORT`: Server port (default: 8080)
+- `OPENCODE_API_KEY`: OpenCode AI API key (required)
+
+## TypeScript Types
+
+The package exports TypeScript types for use with Hono RPC client:
+
+```typescript
+import type { AppType } from '@btca/server';
+import { hc } from 'hono/client';
+
+const client = hc<AppType>('http://localhost:8080');
+```
+
+## Stream Types
+
+For working with SSE streaming responses:
+
+```typescript
+import type { 
+  BtcaStreamEvent, 
+  BtcaStreamMetaEvent 
+} from '@btca/server/stream/types';
+```
+
+## Requirements
+
+- **Bun**: >= 1.1.0 (this package is designed specifically for Bun runtime)
+- **OpenCode AI API Key**: Required for AI functionality
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/bmdavis419/better-context](https://github.com/bmdavis419/better-context)

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "btca-server",
+	"version": "1.0.20",
+	"description": "BTCA server for answering questions about your codebase using OpenCode AI",
+	"author": "Ben Davis",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bmdavis419/better-context",
+		"directory": "apps/server"
+	},
+	"keywords": [
+		"btca",
+		"opencode",
+		"ai",
+		"codebase",
+		"documentation",
+		"server",
+		"api",
+		"bun"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"bun": ">=1.1.0"
+	},
+	"module": "src/index.ts",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./stream": "./src/stream/index.ts",
+		"./stream/types": "./src/stream/types.ts"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"check": "tsgo --noEmit",
+		"dev": "bun --watch src/index.ts",
+		"format": "prettier --write .",
+		"test": "bun test",
+		"test:watch": "bun test --watch"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@typescript/native-preview": "^7.0.0-dev.20260109.1",
+		"prettier": "^3.7.4"
+	},
+	"dependencies": {
+		"@opencode-ai/sdk": "^1.0.208",
+		"hono": "^4.7.11",
+		"zod": "^3.25.76"
+	}
+}

package/src/agent/agent.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import { Agent } from './service.ts';
+import { Config } from '../config/index.ts';
+import type { CollectionResult } from '../collections/types.ts';
+
+describe('Agent', () => {
+	let testDir: string;
+	let originalCwd: string;
+	let originalHome: string | undefined;
+
+	beforeEach(async () => {
+		testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-agent-test-'));
+		originalCwd = process.cwd();
+		originalHome = process.env.HOME;
+		process.env.HOME = testDir;
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.env.HOME = originalHome;
+		await fs.rm(testDir, { recursive: true, force: true });
+	});
+
+	describe('Agent.create', () => {
+		it('creates an agent service with ask and askStream methods', async () => {
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			expect(agent).toBeDefined();
+			expect(typeof agent.ask).toBe('function');
+			expect(typeof agent.askStream).toBe('function');
+		});
+	});
+
+	// Integration tests - require valid OpenCode credentials and provider
+	// Run with: BTCA_RUN_INTEGRATION_TESTS=1 bun test
+	describe.skipIf(!process.env.BTCA_RUN_INTEGRATION_TESTS)('Agent.ask (integration)', () => {
+		it('asks a question and receives an answer', async () => {
+			// Create a simple collection directory with a test file
+			const collectionPath = path.join(testDir, 'test-collection');
+			await fs.mkdir(collectionPath, { recursive: true });
+			await fs.writeFile(
+				path.join(collectionPath, 'README.md'),
+				'# Test Documentation\n\nThis is a test file. The answer to life is 42.'
+			);
+
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const collection: CollectionResult = {
+				path: collectionPath,
+				agentInstructions: 'This is a test collection with a README file.'
+			};
+
+			const result = await agent.ask({
+				collection,
+				question: 'What number is the answer to life according to the README?'
+			});
+
+			expect(result).toBeDefined();
+			expect(result.answer).toBeDefined();
+			expect(typeof result.answer).toBe('string');
+			expect(result.answer.length).toBeGreaterThan(0);
+			expect(result.model).toBeDefined();
+			expect(result.model.provider).toBeDefined();
+			expect(result.model.model).toBeDefined();
+			expect(result.events).toBeDefined();
+			expect(Array.isArray(result.events)).toBe(true);
+		}, 60000);
+
+		it('handles askStream and receives events', async () => {
+			const collectionPath = path.join(testDir, 'stream-collection');
+			await fs.mkdir(collectionPath, { recursive: true });
+			await fs.writeFile(path.join(collectionPath, 'data.txt'), 'The capital of France is Paris.');
+
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const collection: CollectionResult = {
+				path: collectionPath,
+				agentInstructions: 'Simple test collection.'
+			};
+
+			const { stream, model } = await agent.askStream({
+				collection,
+				question: 'What is the capital of France according to the data file?'
+			});
+
+			expect(model).toBeDefined();
+			expect(model.provider).toBeDefined();
+			expect(model.model).toBeDefined();
+
+			const events = [];
+			for await (const event of stream) {
+				events.push(event);
+			}
+
+			expect(events.length).toBeGreaterThan(0);
+			// Should have received some message.part.updated events
+			const textEvents = events.filter((e) => e.type === 'message.part.updated');
+			expect(textEvents.length).toBeGreaterThan(0);
+		}, 60000);
+	});
+});

package/src/agent/index.ts

@@ -0,0 +1,2 @@
+export { Agent } from './service.ts';
+export type { AgentResult, OcEvent, SessionState } from './types.ts';

package/src/agent/service.ts

@@ -0,0 +1,328 @@
+import {
+	createOpencode,
+	createOpencodeClient,
+	type Config as OpenCodeConfig,
+	type OpencodeClient,
+	type Event as OcEvent
+} from '@opencode-ai/sdk';
+
+import { Config } from '../config/index.ts';
+import { Metrics } from '../metrics/index.ts';
+import type { CollectionResult } from '../collections/types.ts';
+import type { AgentResult } from './types.ts';
+
+export namespace Agent {
+	export class AgentError extends Error {
+		readonly _tag = 'AgentError';
+		override readonly cause?: unknown;
+
+		constructor(args: { message: string; cause?: unknown }) {
+			super(args.message);
+			this.cause = args.cause;
+		}
+	}
+
+	export class InvalidProviderError extends Error {
+		readonly _tag = 'InvalidProviderError';
+		readonly providerId: string;
+		readonly availableProviders: string[];
+
+		constructor(args: { providerId: string; availableProviders: string[] }) {
+			super(`Invalid provider: ${args.providerId}`);
+			this.providerId = args.providerId;
+			this.availableProviders = args.availableProviders;
+		}
+	}
+
+	export class InvalidModelError extends Error {
+		readonly _tag = 'InvalidModelError';
+		readonly providerId: string;
+		readonly modelId: string;
+		readonly availableModels: string[];
+
+		constructor(args: { providerId: string; modelId: string; availableModels: string[] }) {
+			super(`Invalid model: ${args.modelId}`);
+			this.providerId = args.providerId;
+			this.modelId = args.modelId;
+			this.availableModels = args.availableModels;
+		}
+	}
+
+	export class ProviderNotConnectedError extends Error {
+		readonly _tag = 'ProviderNotConnectedError';
+		readonly providerId: string;
+		readonly connectedProviders: string[];
+
+		constructor(args: { providerId: string; connectedProviders: string[] }) {
+			super(`Provider not connected: ${args.providerId}`);
+			this.providerId = args.providerId;
+			this.connectedProviders = args.connectedProviders;
+		}
+	}
+
+	export type Service = {
+		askStream: (args: {
+			collection: CollectionResult;
+			question: string;
+		}) => Promise<{ stream: AsyncIterable<OcEvent>; model: { provider: string; model: string } }>;
+
+		ask: (args: { collection: CollectionResult; question: string }) => Promise<AgentResult>;
+
+		getOpencodeInstance: (args: { collection: CollectionResult }) => Promise<{
+			url: string;
+			model: { provider: string; model: string };
+		}>;
+	};
+
+	const buildOpenCodeConfig = (args: { agentInstructions: string }): OpenCodeConfig => {
+		const prompt = [
+			'You are an expert internal agent who`s job is to answer questions about the collection.',
+			'You operate inside a collection directory.',
+			'Use the resources in this collection to answer the user`s question.',
+			args.agentInstructions
+		].join('\n');
+
+		return {
+			agent: {
+				build: { disable: true },
+				explore: { disable: true },
+				general: { disable: true },
+				plan: { disable: true },
+				docs: {
+					prompt,
+					description: 'Answer questions by searching the collection',
+					permission: {
+						webfetch: 'deny',
+						edit: 'deny',
+						bash: 'deny',
+						external_directory: 'deny',
+						doom_loop: 'deny'
+					},
+					mode: 'primary',
+					tools: {
+						write: false,
+						bash: false,
+						delete: false,
+						read: true,
+						grep: true,
+						glob: true,
+						list: true,
+						path: false,
+						todowrite: false,
+						todoread: false,
+						websearch: false,
+						webfetch: false,
+						skill: false,
+						task: false,
+						mcp: false,
+						edit: false
+					}
+				}
+			}
+		};
+	};
+
+	const validateProviderAndModel = async (
+		client: OpencodeClient,
+		providerId: string,
+		modelId: string
+	) => {
+		const response = await client.provider.list().catch(() => null);
+		if (!response?.data) return;
+
+		type ProviderInfo = { id: string; models: Record<string, unknown> };
+		const data = response.data as { all: ProviderInfo[]; connected: string[] };
+
+		const { all, connected } = data;
+		const provider = all.find((p) => p.id === providerId);
+		if (!provider)
+			throw new InvalidProviderError({ providerId, availableProviders: all.map((p) => p.id) });
+		if (!connected.includes(providerId)) {
+			throw new ProviderNotConnectedError({ providerId, connectedProviders: connected });
+		}
+
+		const modelIds = Object.keys(provider.models);
+		if (!modelIds.includes(modelId)) {
+			throw new InvalidModelError({ providerId, modelId, availableModels: modelIds });
+		}
+	};
+
+	const getOpencodeInstance = async (args: {
+		collectionPath: string;
+		ocConfig: OpenCodeConfig;
+	}): Promise<{
+		client: OpencodeClient;
+		server: { close(): void; url: string };
+		baseUrl: string;
+	}> => {
+		const maxAttempts = 10;
+		for (let attempt = 0; attempt < maxAttempts; attempt++) {
+			const port = Math.floor(Math.random() * 3000) + 3000;
+			const created = await createOpencode({ port, config: args.ocConfig }).catch((err: any) => {
+				if (err?.cause instanceof Error && err.cause.stack?.includes('port')) return null;
+				throw new AgentError({ message: 'Failed to create OpenCode instance', cause: err });
+			});
+
+			if (created) {
+				const baseUrl = `http://localhost:${port}`;
+				return {
+					client: createOpencodeClient({ baseUrl, directory: args.collectionPath }),
+					server: created.server,
+					baseUrl
+				};
+			}
+		}
+
+		throw new AgentError({
+			message: 'Failed to create OpenCode instance - all port attempts exhausted'
+		});
+	};
+
+	const sessionEvents = async (args: {
+		sessionID: string;
+		client: OpencodeClient;
+	}): Promise<AsyncIterable<OcEvent>> => {
+		const events = await args.client.event.subscribe().catch((cause: unknown) => {
+			throw new AgentError({ message: 'Failed to subscribe to events', cause });
+		});
+
+		async function* gen() {
+			for await (const event of events.stream) {
+				const props = event.properties as any;
+				if (props && 'sessionID' in props && props.sessionID !== args.sessionID) continue;
+				yield event;
+				if (
+					event.type === 'session.idle' &&
+					(event.properties as any)?.sessionID === args.sessionID
+				)
+					return;
+			}
+		}
+
+		return gen();
+	};
+
+	const extractAnswerFromEvents = (events: readonly OcEvent[]): string => {
+		const partIds: string[] = [];
+		const partText = new Map<string, string>();
+
+		for (const event of events) {
+			if (event.type !== 'message.part.updated') continue;
+			const part: any = (event.properties as any).part;
+			if (!part || part.type !== 'text') continue;
+			if (!partIds.includes(part.id)) partIds.push(part.id);
+			partText.set(part.id, String(part.text ?? ''));
+		}
+
+		return partIds
+			.map((id) => partText.get(id) ?? '')
+			.join('')
+			.trim();
+	};
+
+	export const create = (config: Config.Service): Service => {
+		const askStream: Service['askStream'] = async ({ collection, question }) => {
+			const ocConfig = buildOpenCodeConfig({ agentInstructions: collection.agentInstructions });
+			const { client, server, baseUrl } = await getOpencodeInstance({
+				collectionPath: collection.path,
+				ocConfig
+			});
+
+			Metrics.info('agent.oc.ready', { baseUrl, collectionPath: collection.path });
+
+			try {
+				try {
+					await validateProviderAndModel(client, config.provider, config.model);
+					Metrics.info('agent.validate.ok', { provider: config.provider, model: config.model });
+				} catch (cause) {
+					throw new AgentError({ message: 'Provider/model validation failed', cause });
+				}
+
+				const session = await client.session.create().catch((cause: unknown) => {
+					throw new AgentError({ message: 'Failed to create session', cause });
+				});
+
+				if (session.error)
+					throw new AgentError({ message: 'Failed to create session', cause: session.error });
+
+				const sessionID = session.data?.id;
+				if (!sessionID) {
+					throw new AgentError({
+						message: 'Failed to create session',
+						cause: new Error('Missing session id')
+					});
+				}
+				Metrics.info('agent.session.created', { sessionID });
+
+				const eventStream = await sessionEvents({ sessionID, client });
+
+				Metrics.info('agent.prompt.sent', { sessionID, questionLength: question.length });
+				void client.session
+					.prompt({
+						path: { id: sessionID },
+						body: {
+							agent: 'docs',
+							model: { providerID: config.provider, modelID: config.model },
+							parts: [{ type: 'text', text: question }]
+						}
+					})
+					.catch((cause: unknown) => {
+						Metrics.error('agent.prompt.err', { error: Metrics.errorInfo(cause) });
+					});
+
+				async function* filtered() {
+					try {
+						for await (const event of eventStream) {
+							if (event.type === 'session.error') {
+								const props: any = event.properties;
+								throw new AgentError({
+									message: props?.error?.name ?? 'Unknown session error',
+									cause: props?.error
+								});
+							}
+							yield event;
+						}
+					} finally {
+						Metrics.info('agent.session.closed', { sessionID });
+						server.close();
+					}
+				}
+
+				return {
+					stream: filtered(),
+					model: { provider: config.provider, model: config.model }
+				};
+			} catch (cause) {
+				server.close();
+				throw cause;
+			}
+		};
+
+		const ask: Service['ask'] = async ({ collection, question }) => {
+			const { stream, model } = await askStream({ collection, question });
+			const events: OcEvent[] = [];
+			for await (const event of stream) events.push(event);
+			return { answer: extractAnswerFromEvents(events), model, events };
+		};
+
+		const getOpencodeInstanceMethod: Service['getOpencodeInstance'] = async ({ collection }) => {
+			const ocConfig = buildOpenCodeConfig({ agentInstructions: collection.agentInstructions });
+			const { baseUrl } = await getOpencodeInstance({
+				collectionPath: collection.path,
+				ocConfig
+			});
+
+			Metrics.info('agent.oc.instance.ready', { baseUrl, collectionPath: collection.path });
+
+			// Note: The server stays alive - it's the caller's responsibility to manage the lifecycle
+			// For CLI usage, the opencode CLI will connect to this instance and manage it
+
+			return {
+				url: baseUrl,
+				model: { provider: config.provider, model: config.model }
+			};
+		};
+
+		return { askStream, ask, getOpencodeInstance: getOpencodeInstanceMethod };
+	};
+}

package/src/agent/types.ts

@@ -0,0 +1,16 @@
+import type { Event as OcEvent, OpencodeClient } from '@opencode-ai/sdk';
+
+export type AgentResult = {
+	answer: string;
+	model: { provider: string; model: string };
+	events: OcEvent[];
+};
+
+export type SessionState = {
+	client: OpencodeClient;
+	server: { close: () => void; url: string };
+	sessionID: string;
+	collectionPath: string;
+};
+
+export { type OcEvent };

package/src/collections/index.ts

@@ -0,0 +1,2 @@
+export { Collections } from './service.ts';
+export { CollectionError, getCollectionKey, type CollectionResult } from './types.ts';