luca 1.1.2 → 3.0.0

package/src/agi/features/docs-reader.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
+import type { ContentDb } from '@/node.js'
+import type Assistant from './assistant.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		docsReader: typeof DocsReader
+	}
+}
+
+export const DocsReaderStateSchema = FeatureStateSchema.extend({
+	started: z.boolean().describe('Whether the docs reader has been started'),
+})
+
+export const DocsReaderOptionsSchema = FeatureOptionsSchema.extend({
+	contentDb: z.union([
+		z.string(),
+		z.any()
+	]).describe('Either the contentDb instance or the path to the contentDb you want to load'),
+	model: z.string().describe('The model to use for the conversation').default("gpt-5.4"),
+	local: z.boolean().default(false).describe('Whether to use a local model for the conversation')
+}).loose()
+
+export const DocsReaderEventsSchema = FeatureEventsSchema.extend({
+	loaded: z.tuple([]).describe('Fired after the docs reader has been started'),
+}).describe('DocsReader events')
+
+export type DocsReaderState = z.infer<typeof DocsReaderStateSchema>
+export type DocsReaderOptions = z.infer<typeof DocsReaderOptionsSchema>
+
+/**
+ * The DocsReader feature is an AI Assisted wrapper around a ContentDB feature.
+ *
+ * You can ask it questions about the content, and it will use the ContentDB to find the answers
+ * from the documents.
+*/
+export class DocsReader extends Feature<DocsReaderState, DocsReaderOptions> {
+	static override stateSchema = DocsReaderStateSchema
+	static override optionsSchema = DocsReaderOptionsSchema
+	static override eventsSchema = DocsReaderEventsSchema
+	static override shortcut = 'features.docsReader' as const
+
+	static { Feature.register(this, 'docsReader') }
+
+	/** @returns Default state with started=false. */
+	override get initialState(): DocsReaderState {
+		return {
+			...super.initialState,
+			started: false,
+		}
+	}
+
+	/** Whether the docs reader has been started. */
+	get isStarted(): boolean {
+		return !!this.state.get('started')
+	}
+
+	calculateCacheKeyForQuestion(question: string) {
+		return this.container.utils.hashObject({
+			question,
+			sha: this.container.git?.sha,
+		})
+	}
+
+	get answerCache() {
+		return this.container.feature('diskCache')
+	}
+
+	get contentDb() : ContentDb {
+		return typeof this.options.contentDb === 'object' ?
+			this.options.contentDb as ContentDb :
+			this.container.feature('contentDb', { rootPath: this.options.contentDb })
+	}
+
+	async ask(question: string) {
+		if (!this.isStarted) {
+			await this.start()
+		}
+
+		if (!this.assistant) {
+			throw new Error('DocsReader not started')
+		}
+
+		return this.assistant.ask(question)
+	}
+
+	async askCached(question: string) {
+		if (!this.isStarted) {
+			await this.start()
+		}
+
+		if (!this.assistant) {
+			throw new Error('DocsReader not started')
+		}
+
+		const cacheKey = this.calculateCacheKeyForQuestion(question)
+		const cached = await this.answerCache.get(cacheKey)
+		if (cached) {
+			return cached
+		}
+
+		const answer = await this.assistant.ask(question)
+		await this.answerCache.set(cacheKey, answer)
+		return answer
+	}
+
+	assistant?: Assistant
+
+
+	private generateSpecificCollectionExplainer() {
+		const { contentDb } = this
+		const fileTree = contentDb.fileTree
+		const modelDefinitionTable = contentDb.modelDefinitionTable
+		const modelNames = contentDb.modelNames
+		
+		const domainTermSummary = this.container.feature('ui').endent(`
+		## Domain Specific Terms 
+		
+		When the user is referring to one of the following nouns: ${modelNames.join(', ')} they are likely
+		referencing one of the documents defined by the following content models:
+
+		${Object.entries(modelDefinitionTable).map(([name, { description, glob, routePatterns }]) => `
+		- **${name}**: ${description}
+		Glob: ${glob}
+		Route Patterns: ${routePatterns.join(', ')}
+		`).join('\n')}
+		`)
+
+		return domainTermSummary
+	}
+
+	/** Start the docs reader by loading the contentDb and wiring its tools into an assistant. */
+	async start(): Promise<DocsReader> {
+		if (this.isStarted) return this
+
+		const contentDb = this.contentDb
+		if (!contentDb.isLoaded) await contentDb.load()
+			
+
+		this.assistant = this.container.feature('assistant', {
+			systemPrompt: [CONTENT_DB_SYSTEM_PROMPT, this.generateSpecificCollectionExplainer()].filter(Boolean).join('\n\n'),
+			model: this.options.model,
+			local: this.options.local,
+		}).use(contentDb)
+
+
+		this.state.set('started', true)
+		this.emit('started')
+
+		return this
+	}
+}
+
+export default DocsReader
+
+export const CONTENT_DB_SYSTEM_PROMPT = `You answer questions using a collection of structured documents. Follow this workflow:
+
+1. Start with getCollectionOverview to understand the collection structure, available models, and document counts
+2. Use listDocuments or queryDocuments to find relevant documents by model, glob pattern, or metadata filters
+3. Use searchContent for text/regex search or semanticSearch for natural language queries
+4. Use readDocument to read specific documents — use include/exclude to focus on relevant sections and avoid loading unnecessary content
+5. Synthesize your answer from the documents you've read
+
+Be precise: read only what you need, use section filtering to stay focused, and cite document IDs in your answers.`

package/src/agi/features/file-tools.ts

@@ -0,0 +1,293 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+import type { FS } from '../../node/features/fs.js'
+import type { Grep, GrepMatch } from '../../node/features/grep.js'
+import type { Helper } from '../../helper.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		fileTools: typeof FileTools
+	}
+}
+
+export const FileToolsStateSchema = FeatureStateSchema.extend({})
+export const FileToolsOptionsSchema = FeatureOptionsSchema.extend({})
+
+/**
+ * Curated file-system and code-search tools for AI assistants.
+ *
+ * Wraps the container's `fs` and `grep` features into a focused tool surface
+ * modeled on the tools that coding assistants (Claude Code, Cursor, etc.) rely on:
+ * read, write, edit, list, search, find, stat, mkdir, move, copy, delete.
+ *
+ * Usage:
+ * ```typescript
+ * const fileTools = container.feature('fileTools')
+ * assistant.use(fileTools)
+ * // or selectively:
+ * assistant.use(fileTools.toTools({ only: ['readFile', 'searchFiles', 'listDirectory'] }))
+ * ```
+ *
+ * @extends Feature
+ */
+export class FileTools extends Feature {
+	static override shortcut = 'features.fileTools' as const
+	static override stateSchema = FileToolsStateSchema
+	static override optionsSchema = FileToolsOptionsSchema
+
+	static { Feature.register(this, 'fileTools') }
+
+	static override tools: Record<string, { schema: z.ZodType; description?: string }> = {
+		readFile: {
+			description: 'Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.',
+			schema: z.object({
+				path: z.string().describe('File path relative to the project root'),
+				offset: z.number().optional().describe('Line number to start reading from (1-based)'),
+				limit: z.number().optional().describe('Maximum number of lines to read'),
+			}).describe('Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.'),
+		},
+		writeFile: {
+			description: 'Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.',
+			schema: z.object({
+				path: z.string().describe('File path relative to the project root. Parent directories are created automatically.'),
+				content: z.string().describe('The complete file content. This replaces everything in the file — there is no merge or append.'),
+			}).describe('Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.'),
+		},
+		editFile: {
+			description: 'Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.',
+			schema: z.object({
+				path: z.string().describe('File path relative to the project root'),
+				oldString: z.string().describe('The EXACT text to find, copied verbatim from the file — including whitespace and indentation. Must appear exactly once in the file (unless replaceAll is true). If the match fails, read the file again and copy the exact text.'),
+				newString: z.string().describe('The replacement text. Preserve the same indentation style as the surrounding code.'),
+				replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness. Use for renaming a variable across a file. Default: false.'),
+			}).describe('Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.'),
+		},
+		listDirectory: {
+			description: 'List files and directories at a path. Returns arrays of file and directory names.',
+			schema: z.object({
+				path: z.string().optional().describe('Directory path relative to project root (defaults to ".")'),
+				recursive: z.boolean().optional().describe('Whether to list recursively (default: false)'),
+				include: z.string().optional().describe('Glob pattern to filter results (e.g. "*.ts")'),
+				exclude: z.string().optional().describe('Glob pattern to exclude (e.g. "node_modules")'),
+			}).describe('List files and directories at a path. Returns arrays of file and directory names.'),
+		},
+		searchFiles: {
+			description: 'Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.',
+			schema: z.object({
+				pattern: z.string().describe('Search pattern — supports regex. Examples: "function handleAuth", "TODO|FIXME", "import.*from.*react"'),
+				path: z.string().optional().describe('Directory to search in (defaults to project root). Narrow this to avoid searching node_modules or irrelevant directories.'),
+				include: z.string().optional().describe('Glob to filter which files to search (e.g. "*.ts", "*.tsx"). Use this to scope to specific file types.'),
+				exclude: z.string().optional().describe('Glob to exclude files (e.g. "node_modules", "dist"). node_modules is excluded by default.'),
+				ignoreCase: z.boolean().optional().describe('Case insensitive search. Default: false.'),
+				maxResults: z.number().optional().describe('Maximum results to return. Default: 50. Use a smaller number for broad patterns.'),
+			}).describe('Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.'),
+		},
+		findFiles: {
+			description: 'Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).',
+			schema: z.object({
+				pattern: z.string().describe('Glob pattern to match file names. Examples: "**/*.test.ts", "src/**/*.tsx", "**/config.*"'),
+				path: z.string().optional().describe('Directory to search from (defaults to project root)'),
+				exclude: z.string().optional().describe('Glob pattern to exclude. node_modules and .git are excluded by default.'),
+			}).describe('Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).'),
+		},
+		fileInfo: {
+			description: 'Get information about a file or directory: whether it exists, its type (file/directory), size, and modification time.',
+			schema: z.object({
+				path: z.string().describe('File path relative to the project root'),
+			}).describe('Get information about a file or directory: whether it exists, its type, size, and modification time.'),
+		},
+		createDirectory: {
+			description: 'Create a directory and all parent directories if they do not exist.',
+			schema: z.object({
+				path: z.string().describe('Directory path relative to the project root'),
+			}).describe('Create a directory and all parent directories if they do not exist.'),
+		},
+		moveFile: {
+			description: 'Move or rename a file or directory.',
+			schema: z.object({
+				source: z.string().describe('Source path relative to the project root'),
+				destination: z.string().describe('Destination path relative to the project root'),
+			}).describe('Move or rename a file or directory.'),
+		},
+		copyFile: {
+			description: 'Copy a file or directory (recursive for directories).',
+			schema: z.object({
+				source: z.string().describe('Source path relative to the project root'),
+				destination: z.string().describe('Destination path relative to the project root'),
+			}).describe('Copy a file or directory (recursive for directories).'),
+		},
+		deleteFile: {
+			description: 'Delete a file. Does not delete directories — use with care.',
+			schema: z.object({
+				path: z.string().describe('File path relative to the project root'),
+			}).describe('Delete a file. Does not delete directories — use with care.'),
+		},
+	}
+
+	private get fs(): FS {
+		return this.container.feature('fs') as unknown as FS
+	}
+
+	private get grep(): Grep {
+		return this.container.feature('grep') as unknown as Grep
+	}
+
+	// -------------------------------------------------------------------------
+	// Tool implementations — each matches a static tools key by name
+	// -------------------------------------------------------------------------
+
+	async readFile(args: { path: string; offset?: number; limit?: number }): Promise<string> {
+		const content = await this.fs.readFileAsync(args.path) as string
+
+		if (args.offset || args.limit) {
+			const lines = content.split('\n')
+			const start = Math.max(0, (args.offset || 1) - 1)
+			const end = args.limit ? start + args.limit : lines.length
+			return lines.slice(start, end).map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+		}
+
+		return content
+	}
+
+	async writeFile(args: { path: string; content: string }): Promise<string> {
+		await this.fs.ensureFolderAsync(args.path.includes('/') ? args.path.split('/').slice(0, -1).join('/') : '.')
+		await this.fs.writeFileAsync(args.path, args.content)
+		return `Wrote ${args.content.length} bytes to ${args.path}`
+	}
+
+	async editFile(args: { path: string; oldString: string; newString: string; replaceAll?: boolean }): Promise<string> {
+		const content = await this.fs.readFileAsync(args.path) as string
+
+		if (args.replaceAll) {
+			const updated = content.split(args.oldString).join(args.newString)
+			const count = (content.split(args.oldString).length - 1)
+			if (count === 0) return `Error: "${args.oldString}" not found in ${args.path}`
+			await this.fs.writeFileAsync(args.path, updated)
+			return `Replaced ${count} occurrence(s) in ${args.path}`
+		}
+
+		const idx = content.indexOf(args.oldString)
+		if (idx === -1) return `Error: "${args.oldString}" not found in ${args.path}`
+
+		const lastIdx = content.lastIndexOf(args.oldString)
+		if (idx !== lastIdx) {
+			const count = content.split(args.oldString).length - 1
+			return `Error: "${args.oldString}" appears ${count} times in ${args.path}. Use replaceAll or provide a more specific string.`
+		}
+
+		const updated = content.slice(0, idx) + args.newString + content.slice(idx + args.oldString.length)
+		await this.fs.writeFileAsync(args.path, updated)
+		return `Edited ${args.path}`
+	}
+
+	async listDirectory(args: { path?: string; recursive?: boolean; include?: string; exclude?: string }): Promise<string> {
+		const dir = args.path || '.'
+		const result = await this.fs.walkAsync(dir, {
+			files: true,
+			directories: true,
+			relative: true,
+			include: args.include ? [args.include] : undefined,
+			exclude: args.exclude ? [args.exclude] : ['node_modules', '.git'],
+		})
+
+		// For non-recursive, filter to top-level only
+		if (!args.recursive) {
+			result.files = result.files.filter(f => !f.includes('/'))
+			result.directories = result.directories.filter(d => !d.includes('/'))
+		}
+
+		return JSON.stringify({ files: result.files, directories: result.directories })
+	}
+
+	async searchFiles(args: { pattern: string; path?: string; include?: string; exclude?: string; ignoreCase?: boolean; maxResults?: number }): Promise<string> {
+		const results: GrepMatch[] = await this.grep.search({
+			pattern: args.pattern,
+			path: args.path,
+			include: args.include,
+			exclude: args.exclude || 'node_modules',
+			ignoreCase: args.ignoreCase,
+			maxResults: args.maxResults || 50,
+		})
+
+		return JSON.stringify(results.map(r => ({
+			file: r.file,
+			line: r.line,
+			content: r.content,
+		})))
+	}
+
+	async findFiles(args: { pattern: string; path?: string; exclude?: string }): Promise<string> {
+		const dir = args.path || '.'
+		const result = await this.fs.walkAsync(dir, {
+			files: true,
+			directories: false,
+			relative: true,
+			include: [args.pattern],
+			exclude: args.exclude ? [args.exclude, 'node_modules', '.git'] : ['node_modules', '.git'],
+		})
+		return JSON.stringify(result.files)
+	}
+
+	async fileInfo(args: { path: string }): Promise<string> {
+		const exists = await this.fs.existsAsync(args.path)
+		if (!exists) return JSON.stringify({ exists: false })
+
+		const stat = await this.fs.statAsync(args.path)
+		return JSON.stringify({
+			exists: true,
+			isFile: stat.isFile(),
+			isDirectory: stat.isDirectory(),
+			size: stat.size,
+			modified: stat.mtime.toISOString(),
+		})
+	}
+
+	async createDirectory(args: { path: string }): Promise<string> {
+		await this.fs.ensureFolderAsync(args.path)
+		return `Created ${args.path}`
+	}
+
+	async moveFile(args: { source: string; destination: string }): Promise<string> {
+		await this.fs.moveAsync(args.source, args.destination)
+		return `Moved ${args.source} → ${args.destination}`
+	}
+
+	async copyFile(args: { source: string; destination: string }): Promise<string> {
+		await this.fs.copyAsync(args.source, args.destination)
+		return `Copied ${args.source} → ${args.destination}`
+	}
+
+	async deleteFile(args: { path: string }): Promise<string> {
+		const isDir = await this.fs.isDirectoryAsync(args.path)
+		if (isDir) return `Error: "${args.path}" is a directory. Use deleteFile only for files.`
+		await this.fs.rm(args.path)
+		return `Deleted ${args.path}`
+	}
+
+	/**
+	 * When an assistant uses fileTools, inject system prompt guidance
+	 * about how to use the tools effectively.
+	 */
+	override setupToolsConsumer(consumer: Helper) {
+		if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+			(consumer as any).addSystemPromptExtension('fileTools', [
+				'## File Tools',
+				'',
+				'All paths are relative to the project root unless they start with /.',
+				'',
+				'**Before modifying code:** Always read the file first. Use `searchFiles` to find where something is defined before making changes. Use `listDirectory` to verify paths exist before assuming.',
+				'',
+				'**Editing files:** Prefer `editFile` over `writeFile` for existing files — it makes surgical replacements. The `oldString` must appear exactly once in the file (unless using `replaceAll`). If your match isn\'t unique, include more surrounding context to make it unique. Never guess at file contents — read first, then edit.',
+				'',
+				'**Finding things:** Use `findFiles` to locate files by name or glob pattern (e.g. "**/*.test.ts"). Use `searchFiles` to find specific content inside files (grep). These are different tools for different questions: "where is the file?" vs "where is this code?".',
+				'',
+				'**Large files:** Use `readFile` with `offset` and `limit` to read portions. Don\'t load a 5000-line file when you only need lines 100-150.',
+				'',
+				'**`writeFile` is destructive** — it overwrites the entire file. Only use it for creating new files or when you intend a complete rewrite.',
+			].join('\n'))
+		}
+	}
+}
+
+export default FileTools