btca-server 1.0.63 → 1.0.70

package/README.md

@@ -140,7 +140,6 @@ Example config.toml:
 provider = "anthropic"
 model = "claude-3-7-sonnet-20250219"
 resourcesDirectory = "~/.btca/resources"
-collectionsDirectory = "~/.btca/collections"
 
 [[resources]]
 type = "local"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "btca-server",
-	"version": "1.0.63",
+	"version": "1.0.70",
 	"description": "BTCA server for answering questions about your codebase using OpenCode AI",
 	"author": "Ben Davis",
 	"license": "MIT",
@@ -70,6 +70,7 @@
 		"@opencode-ai/sdk": "^1.1.28",
 		"ai": "^6.0.49",
 		"hono": "^4.7.11",
+		"just-bash": "^2.7.0",
 		"opencode-ai": "^1.1.36",
 		"zod": "^3.25.76"
 	}

package/src/agent/agent.test.ts

@@ -6,6 +6,11 @@ import os from 'node:os';
 import { Agent } from './service.ts';
 import { Config } from '../config/index.ts';
 import type { CollectionResult } from '../collections/types.ts';
+import {
+	getVirtualCollectionMetadata,
+	setVirtualCollectionMetadata
+} from '../collections/virtual-metadata.ts';
+import { VirtualFs } from '../vfs/virtual-fs.ts';
 
 describe('Agent', () => {
 	let testDir: string;
@@ -41,21 +46,22 @@ describe('Agent', () => {
 	// 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 vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.writeFile(
+				'/README.md',
+				'# Test Documentation\n\nThis is a test file. The answer to life is 42.',
+				vfsId
+			);
+
 			const collection: CollectionResult = {
-				path: collectionPath,
-				agentInstructions: 'This is a test collection with a README file.'
+				path: '/',
+				agentInstructions: 'This is a test collection with a README file.',
+				vfsId
 			};
 
 			const result = await agent.ask({
@@ -75,17 +81,18 @@ describe('Agent', () => {
 		}, 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 vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.writeFile('/data.txt', 'The capital of France is Paris.', vfsId);
+
 			const collection: CollectionResult = {
-				path: collectionPath,
-				agentInstructions: 'Simple test collection.'
+				path: '/',
+				agentInstructions: 'Simple test collection.',
+				vfsId
 			};
 
 			const { stream, model } = await agent.askStream({
@@ -107,5 +114,96 @@ describe('Agent', () => {
 			const textEvents = events.filter((e) => e.type === 'text-delta');
 			expect(textEvents.length).toBeGreaterThan(0);
 		}, 60000);
+
+		it('cleans up virtual collections after ask', async () => {
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.mkdir('/docs', { recursive: true }, vfsId);
+			await VirtualFs.writeFile('/docs/README.md', 'Virtual README\nThe answer is 42.', vfsId);
+
+			setVirtualCollectionMetadata({
+				vfsId,
+				collectionKey: 'virtual-test',
+				createdAt: new Date().toISOString(),
+				resources: [
+					{
+						name: 'docs',
+						fsName: 'docs',
+						type: 'local',
+						path: '/docs',
+						repoSubPaths: [],
+						loadedAt: new Date().toISOString()
+					}
+				]
+			});
+
+			const collection: CollectionResult = {
+				path: '/',
+				agentInstructions: 'This is a virtual collection with a README file.',
+				vfsId
+			};
+
+			const result = await agent.ask({
+				collection,
+				question: 'What number is the answer according to the README?'
+			});
+
+			expect(result).toBeDefined();
+			expect(VirtualFs.has(vfsId)).toBe(false);
+			expect(getVirtualCollectionMetadata(vfsId)).toBeUndefined();
+		}, 60000);
+
+		it('cleans up virtual collections after askStream', async () => {
+			process.chdir(testDir);
+			const config = await Config.load();
+			const agent = Agent.create(config);
+
+			const vfsId = VirtualFs.create();
+			await VirtualFs.mkdir('/', { recursive: true }, vfsId);
+			await VirtualFs.mkdir('/docs', { recursive: true }, vfsId);
+			await VirtualFs.writeFile(
+				'/docs/README.md',
+				'Virtual README\nThe capital of France is Paris.',
+				vfsId
+			);
+
+			setVirtualCollectionMetadata({
+				vfsId,
+				collectionKey: 'virtual-stream-test',
+				createdAt: new Date().toISOString(),
+				resources: [
+					{
+						name: 'docs',
+						fsName: 'docs',
+						type: 'local',
+						path: '/docs',
+						repoSubPaths: [],
+						loadedAt: new Date().toISOString()
+					}
+				]
+			});
+
+			const collection: CollectionResult = {
+				path: '/',
+				agentInstructions: 'This is a virtual collection with a README file.',
+				vfsId
+			};
+
+			const { stream } = await agent.askStream({
+				collection,
+				question: 'What is the capital of France according to the README?'
+			});
+
+			for await (const _event of stream) {
+				// drain stream to trigger cleanup
+			}
+
+			expect(VirtualFs.has(vfsId)).toBe(false);
+			expect(getVirtualCollectionMetadata(vfsId)).toBeUndefined();
+		}, 60000);
 	});
 });

package/src/agent/loop.ts

@@ -25,6 +25,7 @@ export namespace AgentLoop {
 		providerId: string;
 		modelId: string;
 		collectionPath: string;
+		vfsId?: string;
 		agentInstructions: string;
 		question: string;
 		maxSteps?: number;
@@ -65,13 +66,13 @@ export namespace AgentLoop {
 	/**
 	 * Create the tools for the agent
 	 */
-	function createTools(basePath: string) {
+	function createTools(basePath: string, vfsId?: string) {
 		return {
 			read: tool({
 				description: 'Read the contents of a file. Returns the file contents with line numbers.',
 				inputSchema: ReadTool.Parameters,
 				execute: async (params: ReadTool.ParametersType) => {
-					const result = await ReadTool.execute(params, { basePath });
+					const result = await ReadTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -81,7 +82,7 @@ export namespace AgentLoop {
 					'Search for a regex pattern in file contents. Returns matching lines with file paths and line numbers.',
 				inputSchema: GrepTool.Parameters,
 				execute: async (params: GrepTool.ParametersType) => {
-					const result = await GrepTool.execute(params, { basePath });
+					const result = await GrepTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -91,7 +92,7 @@ export namespace AgentLoop {
 					'Find files matching a glob pattern (e.g. "**/*.ts", "src/**/*.js"). Returns a list of matching file paths sorted by modification time.',
 				inputSchema: GlobTool.Parameters,
 				execute: async (params: GlobTool.ParametersType) => {
-					const result = await GlobTool.execute(params, { basePath });
+					const result = await GlobTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			}),
@@ -101,7 +102,7 @@ export namespace AgentLoop {
 					'List the contents of a directory. Returns files and subdirectories with their types.',
 				inputSchema: ListTool.Parameters,
 				execute: async (params: ListTool.ParametersType) => {
-					const result = await ListTool.execute(params, { basePath });
+					const result = await ListTool.execute(params, { basePath, vfsId });
 					return result.output;
 				}
 			})
@@ -111,8 +112,8 @@ export namespace AgentLoop {
 	/**
 	 * Get initial context by listing the collection directory
 	 */
-	async function getInitialContext(collectionPath: string): Promise<string> {
-		const result = await ListTool.execute({ path: '.' }, { basePath: collectionPath });
+	async function getInitialContext(collectionPath: string, vfsId?: string) {
+		const result = await ListTool.execute({ path: '.' }, { basePath: collectionPath, vfsId });
 		return `Collection contents:\n${result.output}`;
 	}
 
@@ -124,6 +125,7 @@ export namespace AgentLoop {
 			providerId,
 			modelId,
 			collectionPath,
+			vfsId,
 			agentInstructions,
 			question,
 			maxSteps = 40
@@ -133,7 +135,7 @@ export namespace AgentLoop {
 		const model = await Model.getModel(providerId, modelId);
 
 		// Get initial context
-		const initialContext = await getInitialContext(collectionPath);
+		const initialContext = await getInitialContext(collectionPath, vfsId);
 
 		// Build messages
 		const messages: ModelMessage[] = [
@@ -144,7 +146,7 @@ export namespace AgentLoop {
 		];
 
 		// Create tools
-		const tools = createTools(collectionPath);
+		const tools = createTools(collectionPath, vfsId);
 
 		// Collect events
 		const events: AgentEvent[] = [];
@@ -218,6 +220,7 @@ export namespace AgentLoop {
 			providerId,
 			modelId,
 			collectionPath,
+			vfsId,
 			agentInstructions,
 			question,
 			maxSteps = 40
@@ -227,7 +230,7 @@ export namespace AgentLoop {
 		const model = await Model.getModel(providerId, modelId);
 
 		// Get initial context
-		const initialContext = await getInitialContext(collectionPath);
+		const initialContext = await getInitialContext(collectionPath, vfsId);
 
 		// Build messages
 		const messages: ModelMessage[] = [
@@ -238,7 +241,7 @@ export namespace AgentLoop {
 		];
 
 		// Create tools
-		const tools = createTools(collectionPath);
+		const tools = createTools(collectionPath, vfsId);
 
 		// Run streamText with tool execution
 		const result = streamText({

package/src/agent/service.ts

@@ -14,6 +14,8 @@ import { CommonHints, type TaggedErrorOptions } from '../errors.ts';
 import { Metrics } from '../metrics/index.ts';
 import { Auth, getSupportedProviders } from '../providers/index.ts';
 import type { CollectionResult } from '../collections/types.ts';
+import { clearVirtualCollectionMetadata } from '../collections/virtual-metadata.ts';
+import { VirtualFs } from '../vfs/virtual-fs.ts';
 import type { AgentResult, TrackedInstance, InstanceInfo } from './types.ts';
 import { AgentLoop } from './loop.ts';
 
@@ -272,10 +274,17 @@ export namespace Agent {
 				questionLength: question.length
 			});
 
+			const cleanup = () => {
+				if (!collection.vfsId) return;
+				VirtualFs.dispose(collection.vfsId);
+				clearVirtualCollectionMetadata(collection.vfsId);
+			};
+
 			// Validate provider is authenticated
 			const isAuthed = await Auth.isAuthenticated(config.provider);
 			if (!isAuthed && config.provider !== 'opencode') {
 				const authenticated = await Auth.getAuthenticatedProviders();
+				cleanup();
 				throw new ProviderNotConnectedError({
 					providerId: config.provider,
 					connectedProviders: authenticated
@@ -283,13 +292,23 @@ export namespace Agent {
 			}
 
 			// Create a generator that wraps the AgentLoop stream
-			const eventGenerator = AgentLoop.stream({
-				providerId: config.provider,
-				modelId: config.model,
-				collectionPath: collection.path,
-				agentInstructions: collection.agentInstructions,
-				question
-			});
+			const eventGenerator = (async function* () {
+				try {
+					const stream = AgentLoop.stream({
+						providerId: config.provider,
+						modelId: config.model,
+						collectionPath: collection.path,
+						vfsId: collection.vfsId,
+						agentInstructions: collection.agentInstructions,
+						question
+					});
+					for await (const event of stream) {
+						yield event;
+					}
+				} finally {
+					cleanup();
+				}
+			})();
 
 			return {
 				stream: eventGenerator,
@@ -307,10 +326,17 @@ export namespace Agent {
 				questionLength: question.length
 			});
 
+			const cleanup = () => {
+				if (!collection.vfsId) return;
+				VirtualFs.dispose(collection.vfsId);
+				clearVirtualCollectionMetadata(collection.vfsId);
+			};
+
 			// Validate provider is authenticated
 			const isAuthed = await Auth.isAuthenticated(config.provider);
 			if (!isAuthed && config.provider !== 'opencode') {
 				const authenticated = await Auth.getAuthenticatedProviders();
+				cleanup();
 				throw new ProviderNotConnectedError({
 					providerId: config.provider,
 					connectedProviders: authenticated
@@ -322,6 +348,7 @@ export namespace Agent {
 					providerId: config.provider,
 					modelId: config.model,
 					collectionPath: collection.path,
+					vfsId: collection.vfsId,
 					agentInstructions: collection.agentInstructions,
 					question
 				});
@@ -345,6 +372,8 @@ export namespace Agent {
 					hint: 'This may be a temporary issue. Try running the command again.',
 					cause: error
 				});
+			} finally {
+				cleanup();
 			}
 		};
 
@@ -353,31 +382,11 @@ export namespace Agent {
 		 * This still spawns a full OpenCode instance for clients that need it
 		 */
 		const getOpencodeInstance: Service['getOpencodeInstance'] = async ({ collection }) => {
-			const ocConfig = buildOpenCodeConfig({
-				agentInstructions: collection.agentInstructions,
-				providerId: config.provider,
-				providerTimeoutMs: config.providerTimeoutMs
-			});
-			const { server, baseUrl } = await createOpencodeInstance({
-				collectionPath: collection.path,
-				ocConfig
-			});
-
-			// Register the instance for lifecycle management
-			const instanceId = generateInstanceId();
-			registerInstance(instanceId, server, collection.path);
-
-			Metrics.info('agent.oc.instance.ready', {
-				baseUrl,
-				collectionPath: collection.path,
-				instanceId
+			throw new AgentError({
+				message: 'OpenCode instance not available',
+				hint: 'BTCA uses virtual collections only. Use the btca ask/stream APIs instead.',
+				cause: new Error('Virtual collections are not compatible with filesystem-based OpenCode')
 			});
-
-			return {
-				url: baseUrl,
-				model: { provider: config.provider, model: config.model },
-				instanceId
-			};
 		};
 
 		/**

package/src/collections/service.ts

@@ -1,4 +1,3 @@
-import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
 import { Config } from '../config/index.ts';
@@ -6,8 +5,15 @@ import { Transaction } from '../context/transaction.ts';
 import { CommonHints, getErrorHint, getErrorMessage } from '../errors.ts';
 import { Metrics } from '../metrics/index.ts';
 import { Resources } from '../resources/service.ts';
+import { isGitResource } from '../resources/schema.ts';
 import { FS_RESOURCE_SYSTEM_NOTE, type BtcaFsResource } from '../resources/types.ts';
 import { CollectionError, getCollectionKey, type CollectionResult } from './types.ts';
+import { VirtualFs } from '../vfs/virtual-fs.ts';
+import {
+	clearVirtualCollectionMetadata,
+	setVirtualCollectionMetadata,
+	type VirtualResourceMetadata
+} from './virtual-metadata.ts';
 
 export namespace Collections {
 	export type Service = {
@@ -32,6 +38,48 @@ export namespace Collections {
 		return lines.join('\n');
 	};
 
+	const getGitHeadHash = async (resourcePath: string) => {
+		try {
+			const proc = Bun.spawn(['git', 'rev-parse', 'HEAD'], {
+				cwd: resourcePath,
+				stdout: 'pipe',
+				stderr: 'pipe'
+			});
+			const stdout = await new Response(proc.stdout).text();
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) return undefined;
+			const trimmed = stdout.trim();
+			return trimmed.length > 0 ? trimmed : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+
+	const buildVirtualMetadata = async (args: {
+		resource: BtcaFsResource;
+		resourcePath: string;
+		loadedAt: string;
+		definition?: ReturnType<Config.Service['getResource']>;
+	}) => {
+		if (!args.definition) return null;
+		const base = {
+			name: args.resource.name,
+			fsName: args.resource.fsName,
+			type: args.resource.type,
+			path: args.resourcePath,
+			repoSubPaths: args.resource.repoSubPaths,
+			loadedAt: args.loadedAt
+		};
+		if (!isGitResource(args.definition)) return base;
+		const commit = await getGitHeadHash(args.resourcePath);
+		return {
+			...base,
+			url: args.definition.url,
+			branch: args.definition.branch,
+			commit
+		};
+	};
+
 	export const create = (args: {
 		config: Config.Service;
 		resources: Resources.Service;
@@ -50,19 +98,28 @@ export namespace Collections {
 
 					const sortedNames = [...uniqueNames].sort((a, b) => a.localeCompare(b));
 					const key = getCollectionKey(sortedNames);
-					const collectionPath = path.join(args.config.collectionsDirectory, key);
+					const collectionPath = '/';
+					const vfsId = VirtualFs.create();
+					const cleanupVirtual = () => {
+						VirtualFs.dispose(vfsId);
+						clearVirtualCollectionMetadata(vfsId);
+					};
 
 					try {
-						await fs.mkdir(collectionPath, { recursive: true });
+						// Virtual collections use the VFS root as the collection root.
+						await VirtualFs.mkdir(collectionPath, { recursive: true }, vfsId);
 					} catch (cause) {
+						cleanupVirtual();
 						throw new CollectionError({
-							message: `Failed to create collection directory: "${collectionPath}"`,
-							hint: 'Check that you have write permissions to the btca data directory.',
+							message: `Failed to initialize virtual collection root: "${collectionPath}"`,
+							hint: 'Check that the virtual filesystem is available.',
 							cause
 						});
 					}
 
 					const loadedResources: BtcaFsResource[] = [];
+					const metadataResources: VirtualResourceMetadata[] = [];
+					const loadedAt = new Date().toISOString();
 					for (const name of sortedNames) {
 						try {
 							loadedResources.push(await args.resources.load(name, { quiet }));
@@ -70,6 +127,7 @@ export namespace Collections {
 							// Preserve the hint from the underlying error if available
 							const underlyingHint = getErrorHint(cause);
 							const underlyingMessage = getErrorMessage(cause);
+							cleanupVirtual();
 							throw new CollectionError({
 								message: `Failed to load resource "${name}": ${underlyingMessage}`,
 								hint:
@@ -85,6 +143,7 @@ export namespace Collections {
 						try {
 							resourcePath = await resource.getAbsoluteDirectoryPath();
 						} catch (cause) {
+							cleanupVirtual();
 							throw new CollectionError({
 								message: `Failed to get path for resource "${resource.name}"`,
 								hint: CommonHints.CLEAR_CACHE,
@@ -92,29 +151,58 @@ export namespace Collections {
 							});
 						}
 
-						const linkPath = path.join(collectionPath, resource.fsName);
+						const virtualResourcePath = path.posix.join('/', resource.fsName);
 						try {
-							await fs.rm(linkPath, { recursive: true, force: true });
+							await VirtualFs.rm(virtualResourcePath, { recursive: true, force: true }, vfsId);
 						} catch {
 							// ignore
 						}
-
 						try {
-							await fs.symlink(resourcePath, linkPath, 'junction');
+							await VirtualFs.importDirectoryFromDisk({
+								sourcePath: resourcePath,
+								destinationPath: virtualResourcePath,
+								vfsId,
+								ignore: (relativePath) => {
+									const normalized = relativePath.split(path.sep).join('/');
+									return (
+										normalized === '.git' ||
+										normalized.startsWith('.git/') ||
+										normalized.includes('/.git/')
+									);
+								}
+							});
 						} catch (cause) {
+							cleanupVirtual();
 							throw new CollectionError({
-								message: `Failed to create symlink for resource "${resource.name}"`,
-								hint: 'This may be a filesystem permissions issue or the link already exists.',
+								message: `Failed to virtualize resource "${resource.name}"`,
+								hint: CommonHints.CLEAR_CACHE,
 								cause
 							});
 						}
+
+						const definition = args.config.getResource(resource.name);
+						const metadata = await buildVirtualMetadata({
+							resource,
+							resourcePath,
+							loadedAt,
+							definition
+						});
+						if (metadata) metadataResources.push(metadata);
 					}
 
+					setVirtualCollectionMetadata({
+						vfsId,
+						collectionKey: key,
+						createdAt: loadedAt,
+						resources: metadataResources
+					});
+
 					const instructionBlocks = loadedResources.map(createCollectionInstructionBlock);
 
 					return {
 						path: collectionPath,
-						agentInstructions: instructionBlocks.join('\n\n')
+						agentInstructions: instructionBlocks.join('\n\n'),
+						vfsId
 					};
 				})
 		};

package/src/collections/types.ts

@@ -4,6 +4,7 @@ import { resourceNameToKey } from '../resources/helpers.ts';
 export type CollectionResult = {
 	path: string;
 	agentInstructions: string;
+	vfsId?: string;
 };
 
 export class CollectionError extends Error {

package/src/collections/virtual-metadata.ts

@@ -0,0 +1,32 @@
+export type VirtualResourceMetadata = {
+	name: string;
+	fsName: string;
+	type: 'git' | 'local';
+	path: string;
+	repoSubPaths: readonly string[];
+	url?: string;
+	branch?: string;
+	commit?: string;
+	loadedAt: string;
+};
+
+export type VirtualCollectionMetadata = {
+	vfsId: string;
+	collectionKey: string;
+	createdAt: string;
+	resources: VirtualResourceMetadata[];
+};
+
+const metadataByVfsId = new Map<string, VirtualCollectionMetadata>();
+
+export const setVirtualCollectionMetadata = (metadata: VirtualCollectionMetadata) => {
+	metadataByVfsId.set(metadata.vfsId, metadata);
+};
+
+export const getVirtualCollectionMetadata = (vfsId: string) => metadataByVfsId.get(vfsId);
+
+export const clearVirtualCollectionMetadata = (vfsId: string) => metadataByVfsId.delete(vfsId);
+
+export const clearAllVirtualCollectionMetadata = () => {
+	metadataByVfsId.clear();
+};