btca-server 1.0.20

package/src/index.ts

@@ -0,0 +1,468 @@
+import { Hono } from 'hono';
+import type { Context as HonoContext, Next } from 'hono';
+import { z } from 'zod';
+
+import { Agent } from './agent/service.ts';
+import { Collections } from './collections/service.ts';
+import { getCollectionKey } from './collections/types.ts';
+import { Config } from './config/index.ts';
+import { Context } from './context/index.ts';
+import { getErrorMessage, getErrorTag } from './errors.ts';
+import { Metrics } from './metrics/index.ts';
+import { Resources } from './resources/service.ts';
+import { GitResourceSchema, LocalResourceSchema } from './resources/schema.ts';
+import { StreamService } from './stream/service.ts';
+import type { BtcaStreamMetaEvent } from './stream/types.ts';
+import { LIMITS } from './validation/index.ts';
+
+/**
+ * BTCA Server API
+ *
+ * Endpoints:
+ *
+ * GET  /                  - Health check, returns { ok, service, version }
+ * GET  /config            - Returns current configuration (provider, model, directories)
+ * GET  /resources         - Lists all configured resources
+ * POST /question          - Ask a question (non-streaming)
+ * POST /question/stream   - Ask a question (streaming SSE response)
+ * POST /opencode          - Get OpenCode instance URL for a collection
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_PORT = 8080;
+const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : DEFAULT_PORT;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resource name pattern: must start with a letter, alphanumeric and hyphens only.
+ */
+const RESOURCE_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+
+/**
+ * Safe name pattern for provider/model names.
+ */
+const SAFE_NAME_REGEX = /^[a-zA-Z0-9._+\-/:]+$/;
+
+/**
+ * Validated resource name field for request schemas.
+ */
+const ResourceNameField = z
+	.string()
+	.min(1, 'Resource name cannot be empty')
+	.max(LIMITS.RESOURCE_NAME_MAX)
+	.regex(RESOURCE_NAME_REGEX, 'Invalid resource name format');
+
+const QuestionRequestSchema = z.object({
+	question: z
+		.string()
+		.min(1, 'Question cannot be empty')
+		.max(LIMITS.QUESTION_MAX, `Question too long (max ${LIMITS.QUESTION_MAX} chars)`),
+	resources: z
+		.array(ResourceNameField)
+		.max(LIMITS.MAX_RESOURCES_PER_REQUEST, `Too many resources (max ${LIMITS.MAX_RESOURCES_PER_REQUEST})`)
+		.optional(),
+	quiet: z.boolean().optional()
+});
+
+const OpencodeRequestSchema = z.object({
+	resources: z
+		.array(ResourceNameField)
+		.max(LIMITS.MAX_RESOURCES_PER_REQUEST, `Too many resources (max ${LIMITS.MAX_RESOURCES_PER_REQUEST})`)
+		.optional(),
+	quiet: z.boolean().optional()
+});
+
+const UpdateModelRequestSchema = z.object({
+	provider: z
+		.string()
+		.min(1, 'Provider name cannot be empty')
+		.max(LIMITS.PROVIDER_NAME_MAX)
+		.regex(SAFE_NAME_REGEX, 'Invalid provider name format'),
+	model: z
+		.string()
+		.min(1, 'Model name cannot be empty')
+		.max(LIMITS.MODEL_NAME_MAX)
+		.regex(SAFE_NAME_REGEX, 'Invalid model name format')
+});
+
+/**
+ * Add resource request - uses the full resource schemas for validation.
+ * This ensures all security checks (URL, branch, path traversal) are applied.
+ */
+const AddGitResourceRequestSchema = z.object({
+	type: z.literal('git'),
+	name: GitResourceSchema.shape.name,
+	url: GitResourceSchema.shape.url,
+	branch: GitResourceSchema.shape.branch.optional().default('main'),
+	searchPath: GitResourceSchema.shape.searchPath,
+	specialNotes: GitResourceSchema.shape.specialNotes
+});
+
+const AddLocalResourceRequestSchema = z.object({
+	type: z.literal('local'),
+	name: LocalResourceSchema.shape.name,
+	path: LocalResourceSchema.shape.path,
+	specialNotes: LocalResourceSchema.shape.specialNotes
+});
+
+const AddResourceRequestSchema = z.discriminatedUnion('type', [
+	AddGitResourceRequestSchema,
+	AddLocalResourceRequestSchema
+]);
+
+const RemoveResourceRequestSchema = z.object({
+	name: ResourceNameField
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Errors & Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+class RequestError extends Error {
+	readonly _tag = 'RequestError';
+
+	constructor(message: string, cause?: unknown) {
+		super(message, cause ? { cause } : undefined);
+	}
+}
+
+const decodeJson = async <T>(req: Request, schema: z.ZodType<T>): Promise<T> => {
+	let body: unknown;
+	try {
+		body = await req.json();
+	} catch (cause) {
+		throw new RequestError('Failed to parse request JSON', cause);
+	}
+
+	const parsed = schema.safeParse(body);
+	if (!parsed.success) throw new RequestError('Invalid request body', parsed.error);
+	return parsed.data;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// App Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+const createApp = (deps: {
+	config: Config.Service;
+	resources: Resources.Service;
+	collections: Collections.Service;
+	agent: Agent.Service;
+}) => {
+	const { config, collections, agent } = deps;
+
+	const app = new Hono()
+		// ─────────────────────────────────────────────────────────────────────
+		// Middleware
+		// ─────────────────────────────────────────────────────────────────────
+		.use('*', async (c: HonoContext, next: Next) => {
+			const requestId = crypto.randomUUID();
+			return Context.run({ requestId, txDepth: 0 }, async () => {
+				Metrics.info('http.request', { method: c.req.method, path: c.req.path });
+				try {
+					await next();
+				} finally {
+					Metrics.info('http.response', {
+						path: c.req.path,
+						status: c.res.status
+					});
+				}
+			});
+		})
+		.onError((err: Error, c: HonoContext) => {
+			Metrics.error('http.error', { error: Metrics.errorInfo(err) });
+			const tag = getErrorTag(err);
+			const message = getErrorMessage(err);
+			const status = tag === 'CollectionError' || tag === 'ResourceError' ? 400 : 500;
+			return c.json({ error: message, tag }, status);
+		})
+
+		// ─────────────────────────────────────────────────────────────────────
+		// Routes
+		// ─────────────────────────────────────────────────────────────────────
+
+		// GET / - Health check
+		.get('/', (c: HonoContext) => {
+			return c.json({
+				ok: true,
+				service: 'btca-server',
+				version: '0.0.1'
+			});
+		})
+
+		// GET /config
+		.get('/config', (c: HonoContext) => {
+			return c.json({
+				provider: config.provider,
+				model: config.model,
+				resourcesDirectory: config.resourcesDirectory,
+				collectionsDirectory: config.collectionsDirectory,
+				resourceCount: config.resources.length
+			});
+		})
+
+		// GET /resources
+		.get('/resources', (c: HonoContext) => {
+			return c.json({
+				resources: config.resources.map((r) => {
+					if (r.type === 'git') {
+						return {
+							name: r.name,
+							type: r.type,
+							url: r.url,
+							branch: r.branch,
+							searchPath: r.searchPath ?? null,
+							specialNotes: r.specialNotes ?? null
+						};
+					} else {
+						return {
+							name: r.name,
+							type: r.type,
+							path: r.path,
+							specialNotes: r.specialNotes ?? null
+						};
+					}
+				})
+			});
+		})
+
+		// POST /question
+		.post('/question', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, QuestionRequestSchema);
+			const resourceNames =
+				decoded.resources && decoded.resources.length > 0
+					? decoded.resources
+					: config.resources.map((r) => r.name);
+
+			const collectionKey = getCollectionKey(resourceNames);
+			Metrics.info('question.received', {
+				stream: false,
+				quiet: decoded.quiet ?? false,
+				questionLength: decoded.question.length,
+				resources: resourceNames,
+				collectionKey
+			});
+
+			const collection = await collections.load({ resourceNames, quiet: decoded.quiet });
+			Metrics.info('collection.ready', { collectionKey, path: collection.path });
+
+			const result = await agent.ask({ collection, question: decoded.question });
+			Metrics.info('question.done', {
+				collectionKey,
+				answerLength: result.answer.length,
+				model: result.model
+			});
+
+			return c.json({
+				answer: result.answer,
+				model: result.model,
+				resources: resourceNames,
+				collection: { key: collectionKey, path: collection.path }
+			});
+		})
+
+		// POST /question/stream
+		.post('/question/stream', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, QuestionRequestSchema);
+			const resourceNames =
+				decoded.resources && decoded.resources.length > 0
+					? decoded.resources
+					: config.resources.map((r) => r.name);
+
+			const collectionKey = getCollectionKey(resourceNames);
+			Metrics.info('question.received', {
+				stream: true,
+				quiet: decoded.quiet ?? false,
+				questionLength: decoded.question.length,
+				resources: resourceNames,
+				collectionKey
+			});
+
+			const collection = await collections.load({ resourceNames, quiet: decoded.quiet });
+			Metrics.info('collection.ready', { collectionKey, path: collection.path });
+
+			const { stream: eventStream, model } = await agent.askStream({
+				collection,
+				question: decoded.question
+			});
+
+			const meta = {
+				type: 'meta',
+				model,
+				resources: resourceNames,
+				collection: {
+					key: collectionKey,
+					path: collection.path
+				}
+			} satisfies BtcaStreamMetaEvent;
+
+			Metrics.info('question.stream.start', { collectionKey });
+			const stream = StreamService.createSseStream({ meta, eventStream });
+
+			return new Response(stream, {
+				headers: {
+					'content-type': 'text/event-stream',
+					'cache-control': 'no-cache',
+					connection: 'keep-alive'
+				}
+			});
+		})
+
+		// POST /opencode - Get OpenCode instance URL for a collection
+		.post('/opencode', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, OpencodeRequestSchema);
+			const resourceNames =
+				decoded.resources && decoded.resources.length > 0
+					? decoded.resources
+					: config.resources.map((r) => r.name);
+
+			const collectionKey = getCollectionKey(resourceNames);
+			Metrics.info('opencode.requested', {
+				quiet: decoded.quiet ?? false,
+				resources: resourceNames,
+				collectionKey
+			});
+
+			const collection = await collections.load({ resourceNames, quiet: decoded.quiet });
+			Metrics.info('collection.ready', { collectionKey, path: collection.path });
+
+			const { url, model } = await agent.getOpencodeInstance({ collection });
+			Metrics.info('opencode.ready', { collectionKey, url });
+
+			return c.json({
+				url,
+				model,
+				resources: resourceNames,
+				collection: { key: collectionKey, path: collection.path }
+			});
+		})
+
+		// PUT /config/model - Update model configuration
+		.put('/config/model', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, UpdateModelRequestSchema);
+			const result = await config.updateModel(decoded.provider, decoded.model);
+			return c.json(result);
+		})
+
+		// POST /config/resources - Add a new resource
+		// All validation (URL, branch, path traversal, etc.) is handled by the schema
+		.post('/config/resources', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, AddResourceRequestSchema);
+
+			if (decoded.type === 'git') {
+				const resource = {
+					type: 'git' as const,
+					name: decoded.name,
+					url: decoded.url,
+					branch: decoded.branch ?? 'main',
+					...(decoded.searchPath && { searchPath: decoded.searchPath }),
+					...(decoded.specialNotes && { specialNotes: decoded.specialNotes })
+				};
+				const added = await config.addResource(resource);
+				return c.json(added, 201);
+			} else {
+				const resource = {
+					type: 'local' as const,
+					name: decoded.name,
+					path: decoded.path,
+					...(decoded.specialNotes && { specialNotes: decoded.specialNotes })
+				};
+				const added = await config.addResource(resource);
+				return c.json(added, 201);
+			}
+		})
+
+		// DELETE /config/resources - Remove a resource
+		.delete('/config/resources', async (c: HonoContext) => {
+			const decoded = await decodeJson(c.req.raw, RemoveResourceRequestSchema);
+			await config.removeResource(decoded.name);
+			return c.json({ success: true, name: decoded.name });
+		})
+
+		// POST /clear - Clear all locally cloned resources
+		.post('/clear', async (c: HonoContext) => {
+			const result = await config.clearResources();
+			return c.json(result);
+		});
+
+	return app;
+};
+
+// Export app type for Hono RPC client
+// We create a dummy app with null deps just to get the type
+type AppType = ReturnType<typeof createApp>;
+export type { AppType };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ServerInstance {
+	port: number;
+	url: string;
+	stop: () => void;
+}
+
+export interface StartServerOptions {
+	port?: number;
+	quiet?: boolean;
+}
+
+/**
+ * Start the btca server programmatically.
+ * Returns a ServerInstance with the port, url, and stop function.
+ *
+ * If port is 0, a random available port will be assigned by the OS.
+ */
+export const startServer = async (options: StartServerOptions = {}): Promise<ServerInstance> => {
+	if (options.quiet) {
+		Metrics.setQuiet(true);
+	}
+
+	const requestedPort = options.port ?? PORT;
+	Metrics.info('server.starting', { port: requestedPort });
+
+	const config = await Config.load();
+	Metrics.info('config.ready', {
+		provider: config.provider,
+		model: config.model,
+		resources: config.resources.map((r) => r.name),
+		resourcesDirectory: config.resourcesDirectory,
+		collectionsDirectory: config.collectionsDirectory
+	});
+
+	const resources = Resources.create(config);
+	const collections = Collections.create({ config, resources });
+	const agent = Agent.create(config);
+
+	const app = createApp({ config, resources, collections, agent });
+
+	const server = Bun.serve({
+		port: requestedPort,
+		fetch: app.fetch
+	});
+
+	const actualPort = server.port ?? requestedPort;
+	Metrics.info('server.started', { port: actualPort });
+
+	return {
+		port: actualPort,
+		url: `http://localhost:${actualPort}`,
+		stop: () => server.stop()
+	};
+};
+
+// Export all public types and interfaces for consumers
+export type { BtcaStreamEvent, BtcaStreamMetaEvent } from './stream/types.ts';
+
+// Auto-start when run directly (not imported)
+const isMainModule = import.meta.main;
+if (isMainModule) {
+	await startServer({ port: PORT });
+}

package/src/metrics/index.ts

@@ -0,0 +1,60 @@
+import { Context } from '../context/index.ts';
+import { getErrorMessage, getErrorTag } from '../errors.ts';
+
+type LogLevel = 'info' | 'error';
+
+let quietMode = false;
+
+export namespace Metrics {
+	export type Fields = Record<string, unknown>;
+
+	export const setQuiet = (quiet: boolean) => {
+		quietMode = quiet;
+	};
+
+	export const isQuiet = () => quietMode;
+
+	export const errorInfo = (cause: unknown) => ({
+		tag: getErrorTag(cause),
+		message: getErrorMessage(cause)
+	});
+
+	const emit = (level: LogLevel, event: string, fields?: Fields) => {
+		if (quietMode) return;
+
+		const payload = {
+			ts: new Date().toISOString(),
+			level,
+			event,
+			requestId: Context.requestId(),
+			...fields
+		};
+		const line = JSON.stringify(payload);
+		if (level === 'error') console.error(line);
+		else console.log(line);
+	};
+
+	export const info = (event: string, fields?: Fields) => emit('info', event, fields);
+	export const error = (event: string, fields?: Fields) => emit('error', event, fields);
+
+	export const span = async <T>(
+		name: string,
+		fn: () => Promise<T>,
+		fields?: Fields
+	): Promise<T> => {
+		const start = performance.now();
+		try {
+			const result = await fn();
+			info('span.ok', { name, ms: Math.round(performance.now() - start), ...fields });
+			return result;
+		} catch (cause) {
+			error('span.err', {
+				name,
+				ms: Math.round(performance.now() - start),
+				...fields,
+				error: errorInfo(cause)
+			});
+			throw cause;
+		}
+	};
+}

package/src/resources/helpers.ts

@@ -0,0 +1,10 @@
+export class ResourceError extends Error {
+	readonly _tag = 'ResourceError';
+	override readonly cause?: unknown;
+
+	constructor(args: { message: string; cause?: unknown; stack?: string }) {
+		super(args.message);
+		this.cause = args.cause;
+		if (args.stack) this.stack = args.stack;
+	}
+}

package/src/resources/impls/git.test.ts

@@ -0,0 +1,119 @@
+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 { loadGitResource } from './git.ts';
+import type { BtcaGitResourceArgs } from '../types.ts';
+
+describe('Git Resource', () => {
+	let testDir: string;
+
+	beforeEach(async () => {
+		testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'btca-git-test-'));
+	});
+
+	afterEach(async () => {
+		await fs.rm(testDir, { recursive: true, force: true });
+	});
+
+	describe('loadGitResource', () => {
+		describe.skipIf(!process.env.BTCA_RUN_INTEGRATION_TESTS)('integration (network)', () => {
+			it('clones a git repository', async () => {
+				const args: BtcaGitResourceArgs = {
+					type: 'git',
+					name: 'test-repo',
+					url: 'https://github.com/honojs/hono',
+					branch: 'main',
+					repoSubPath: 'docs',
+					resourcesDirectoryPath: testDir,
+					specialAgentInstructions: 'Test notes',
+					quiet: true
+				};
+
+				const resource = await loadGitResource(args);
+
+				expect(resource._tag).toBe('fs-based');
+				expect(resource.name).toBe('test-repo');
+				expect(resource.type).toBe('git');
+				expect(resource.repoSubPath).toBe('docs');
+				expect(resource.specialAgentInstructions).toBe('Test notes');
+
+				const resourcePath = await resource.getAbsoluteDirectoryPath();
+				expect(resourcePath).toBe(path.join(testDir, 'test-repo'));
+
+				const stat = await fs.stat(resourcePath);
+				expect(stat.isDirectory()).toBe(true);
+
+				const gitDir = await fs.stat(path.join(resourcePath, '.git'));
+				expect(gitDir.isDirectory()).toBe(true);
+			}, 30000);
+
+			it('updates an existing git repository', async () => {
+				const args: BtcaGitResourceArgs = {
+					type: 'git',
+					name: 'update-test',
+					url: 'https://github.com/honojs/hono',
+					branch: 'main',
+					repoSubPath: '',
+					resourcesDirectoryPath: testDir,
+					specialAgentInstructions: '',
+					quiet: true
+				};
+
+				await loadGitResource(args);
+				const resource = await loadGitResource(args);
+
+				expect(resource.name).toBe('update-test');
+				const resourcePath = await resource.getAbsoluteDirectoryPath();
+				const stat = await fs.stat(resourcePath);
+				expect(stat.isDirectory()).toBe(true);
+			}, 60000);
+		});
+
+		it('throws error for invalid git URL', async () => {
+			const args: BtcaGitResourceArgs = {
+				type: 'git',
+				name: 'invalid-url',
+				url: 'not-a-valid-url',
+				branch: 'main',
+				repoSubPath: '',
+				resourcesDirectoryPath: testDir,
+				specialAgentInstructions: '',
+				quiet: true
+			};
+
+			expect(loadGitResource(args)).rejects.toThrow('Invalid git URL');
+		});
+
+		it('throws error for invalid branch name', async () => {
+			const args: BtcaGitResourceArgs = {
+				type: 'git',
+				name: 'invalid-branch',
+				url: 'https://github.com/test/repo',
+				branch: 'invalid branch name!',
+				repoSubPath: '',
+				resourcesDirectoryPath: testDir,
+				specialAgentInstructions: '',
+				quiet: true
+			};
+
+			expect(loadGitResource(args)).rejects.toThrow('Invalid branch name');
+		});
+
+		it('throws error for path traversal attempt', async () => {
+			const args: BtcaGitResourceArgs = {
+				type: 'git',
+				name: 'path-traversal',
+				url: 'https://github.com/test/repo',
+				branch: 'main',
+				repoSubPath: '../../../etc',
+				resourcesDirectoryPath: testDir,
+				specialAgentInstructions: '',
+				quiet: true
+			};
+
+			expect(loadGitResource(args)).rejects.toThrow('Invalid path');
+		});
+	});
+});