@skroyc/librarian 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/CHANGELOG.md +176 -0
  2. package/LICENSE +210 -0
  3. package/README.md +614 -0
  4. package/biome.jsonc +9 -0
  5. package/dist/agents/context-schema.d.ts +17 -0
  6. package/dist/agents/context-schema.d.ts.map +1 -0
  7. package/dist/agents/context-schema.js +16 -0
  8. package/dist/agents/context-schema.js.map +1 -0
  9. package/dist/agents/react-agent.d.ts +38 -0
  10. package/dist/agents/react-agent.d.ts.map +1 -0
  11. package/dist/agents/react-agent.js +719 -0
  12. package/dist/agents/react-agent.js.map +1 -0
  13. package/dist/agents/tool-runtime.d.ts +7 -0
  14. package/dist/agents/tool-runtime.d.ts.map +1 -0
  15. package/dist/agents/tool-runtime.js +2 -0
  16. package/dist/agents/tool-runtime.js.map +1 -0
  17. package/dist/cli.d.ts +4 -0
  18. package/dist/cli.d.ts.map +1 -0
  19. package/dist/cli.js +172 -0
  20. package/dist/cli.js.map +1 -0
  21. package/dist/config.d.ts +4 -0
  22. package/dist/config.d.ts.map +1 -0
  23. package/dist/config.js +243 -0
  24. package/dist/config.js.map +1 -0
  25. package/dist/index.d.ts +41 -0
  26. package/dist/index.d.ts.map +1 -0
  27. package/dist/index.js +470 -0
  28. package/dist/index.js.map +1 -0
  29. package/dist/tools/file-finding.tool.d.ts +24 -0
  30. package/dist/tools/file-finding.tool.d.ts.map +1 -0
  31. package/dist/tools/file-finding.tool.js +198 -0
  32. package/dist/tools/file-finding.tool.js.map +1 -0
  33. package/dist/tools/file-listing.tool.d.ts +12 -0
  34. package/dist/tools/file-listing.tool.d.ts.map +1 -0
  35. package/dist/tools/file-listing.tool.js +132 -0
  36. package/dist/tools/file-listing.tool.js.map +1 -0
  37. package/dist/tools/file-reading.tool.d.ts +9 -0
  38. package/dist/tools/file-reading.tool.d.ts.map +1 -0
  39. package/dist/tools/file-reading.tool.js +112 -0
  40. package/dist/tools/file-reading.tool.js.map +1 -0
  41. package/dist/tools/grep-content.tool.d.ts +27 -0
  42. package/dist/tools/grep-content.tool.d.ts.map +1 -0
  43. package/dist/tools/grep-content.tool.js +229 -0
  44. package/dist/tools/grep-content.tool.js.map +1 -0
  45. package/dist/utils/file-utils.d.ts +2 -0
  46. package/dist/utils/file-utils.d.ts.map +1 -0
  47. package/dist/utils/file-utils.js +28 -0
  48. package/dist/utils/file-utils.js.map +1 -0
  49. package/dist/utils/logger.d.ts +32 -0
  50. package/dist/utils/logger.d.ts.map +1 -0
  51. package/dist/utils/logger.js +177 -0
  52. package/dist/utils/logger.js.map +1 -0
  53. package/dist/utils/path-utils.d.ts +2 -0
  54. package/dist/utils/path-utils.d.ts.map +1 -0
  55. package/dist/utils/path-utils.js +9 -0
  56. package/dist/utils/path-utils.js.map +1 -0
  57. package/package.json +84 -0
  58. package/src/agents/context-schema.ts +61 -0
  59. package/src/agents/react-agent.ts +928 -0
  60. package/src/agents/tool-runtime.ts +21 -0
  61. package/src/cli.ts +206 -0
  62. package/src/config.ts +309 -0
  63. package/src/index.ts +628 -0
  64. package/src/tools/file-finding.tool.ts +324 -0
  65. package/src/tools/file-listing.tool.ts +212 -0
  66. package/src/tools/file-reading.tool.ts +154 -0
  67. package/src/tools/grep-content.tool.ts +325 -0
  68. package/src/utils/file-utils.ts +39 -0
  69. package/src/utils/logger.ts +295 -0
  70. package/src/utils/path-utils.ts +17 -0
  71. package/tsconfig.json +37 -0
  72. package/tsconfig.test.json +17 -0
package/README.md ADDED
@@ -0,0 +1,614 @@
1
+ # Librarian CLI - Technology Research Agent
2
+
3
+ A powerful CLI tool that enables AI coding agents to query specific technology repositories and receive detailed technical responses through autonomous exploration.
4
+
5
+ ## Overview
6
+
7
+ Librarian CLI allows AI coding agents to:
8
+
9
+ - Query specific technology repositories with detailed technical questions
10
+ - Receive autonomous exploration through a ReAct agent that reads and analyzes the codebase
11
+ - Get streaming markdown responses with technical insights and explanations
12
+ - Works out-of-the-box with OpenCode Zen (no LLM configuration required by default)
13
+ - Supports multiple LLM providers through LangChain's unified interface
14
+
15
+ ## Features
16
+
17
+ - **Repository Management**: Auto-clone and sync from Git before each query
18
+ - **LangChain-Powered Agent**: Advanced AI agent using LangChain's createAgent for intelligent exploration
19
+ - **Unified Model Abstraction**: Support for OpenAI, Anthropic, Google, OpenAI-compatible, Anthropic-compatible, Claude CLI, and Gemini CLI APIs through LangChain (OpenCode Zen integration - no LLM required by default)
20
+ - **Dynamic Prompt Construction**: Context-aware system prompts based on technology/group selection
21
+ - **Sandboxed Tool Execution**: Secure file operations within isolated working directories
22
+ - **Integrated Toolset**: Built-in tools for file listing, reading, grep, and glob search
23
+ - **Grouped Technologies**: Organize tech stacks by groups (default, langchain, etc.)
24
+ - **Streamlined CLI**: Simple commands for exploration and listing available technologies
25
+ - **Robust Configuration**: YAML-based config with validation and path resolution
26
+
27
+ ## Installation
28
+
29
+ ### NPM Installation
30
+
31
+ ```bash
32
+ # Install globally
33
+ npm install -g @skroyc/librarian
34
+
35
+ # Or install locally
36
+ npm install @skroyc/librarian
37
+ ```
38
+
39
+ ### Bun Installation
40
+
41
+ ```bash
42
+ # Install globally
43
+ bun add -g @skroyc/librarian
44
+
45
+ # Or install locally
46
+ bun add @skroyc/librarian
47
+ ```
48
+
49
+ ### Quick Try
50
+
51
+ ```bash
52
+ # Build and run directly with Nix
53
+ nix run github:SkrOYC/librarian -- --help
54
+ ```
55
+
56
+ ### Nix Installation
57
+
58
+ This project supports building with Nix using [bun2nix](https://github.com/nix-community/bun2nix).
59
+
60
+ #### Prerequisites
61
+
62
+ Ensure you have Nix with flakes enabled:
63
+
64
+ ```bash
65
+ # Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf
66
+ experimental-features = nix-command flakes
67
+ ```
68
+
69
+ #### Option 1: NixOS System-wide
70
+
71
+ Add the librarian flake to your system configuration:
72
+
73
+ ```nix
74
+ # In your /etc/nixos/flake.nix
75
+ {
76
+ inputs = {
77
+ nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
78
+ librarian.url = "github:SkrOYC/librarian";
79
+ };
80
+
81
+ outputs = inputs: {
82
+ # ... your existing nixosConfiguration ...
83
+ nixosConfigurations.yourhost = inputs.nixpkgs.lib.nixosSystem {
84
+ system = "x86_64-linux";
85
+ modules = [
86
+ # Your existing modules
87
+ ({ pkgs, ... }: {
88
+ nixpkgs.overlays = [ inputs.librarian.overlays.default ];
89
+ environment.systemPackages = [ pkgs.librarian ];
90
+ })
91
+ ];
92
+ };
93
+ };
94
+ }
95
+ ```
96
+
97
+ Then rebuild:
98
+ ```bash
99
+ sudo nixos-rebuild switch
100
+ ```
101
+
102
+ #### Option 2: Home Manager (Recommended for multi-user systems)
103
+
104
+ Add to your Home Manager configuration:
105
+
106
+ ```nix
107
+ # In ~/.config/nixpkgs/home.nix or within your home-manager module
108
+ { inputs, pkgs, ... }:
109
+
110
+ {
111
+ home = {
112
+ packages = [ pkgs.librarian ];
113
+ };
114
+
115
+ # Or if using flake-based Home Manager
116
+ programs.home-manager.enable = true;
117
+ home-manager.users.youruser = { pkgs, ... }: {
118
+ home.packages = [ pkgs.librarian ];
119
+ };
120
+ }
121
+ ```
122
+
123
+ With flakes:
124
+ ```nix
125
+ # In your home-manager flake
126
+ {
127
+ inputs = {
128
+ nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
129
+ home-manager.url = "github:nix-community/home-manager";
130
+ librarian.url = "github:SkrOYC/librarian";
131
+ };
132
+
133
+ outputs = inputs: {
134
+ homeManagerModules = {
135
+ my-home = { pkgs, ... }: {
136
+ home.packages = [ pkgs.librarian ];
137
+ };
138
+ };
139
+ };
140
+ }
141
+ ```
142
+
143
+ Then:
144
+ ```bash
145
+ home-manager switch
146
+ ```
147
+
148
+ #### Option 3: nix profile (User-wide, any Linux/macOS)
149
+
150
+ Install to your user profile:
151
+
152
+ ```bash
153
+ # Install latest version
154
+ nix profile install github:SkrOYC/librarian
155
+
156
+ # Or pin to a specific version
157
+ nix profile install github:SkrOYC/librarian?ref=v0.1.0
158
+
159
+ # Update
160
+ nix profile upgrade librarian
161
+
162
+ # List installed packages
163
+ nix profile list
164
+
165
+ # Remove
166
+ nix profile remove librarian
167
+ ```
168
+
169
+ #### Option 4: Flake Overlay (For your own flakes)
170
+
171
+ Use librarian as an overlay in your flake:
172
+
173
+ ```nix
174
+ # In your flake.nix
175
+ {
176
+ inputs = {
177
+ nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
178
+ librarian.url = "github:SkrOYC/librarian";
179
+ };
180
+
181
+ outputs = inputs: {
182
+ packages = inputs.nixpkgs.lib.genAttrs [ "x86_64-linux" "aarch64-linux" ] (system: {
183
+ default = import inputs.nixpkgs {
184
+ inherit system;
185
+ overlays = [ inputs.librarian.overlays.default ];
186
+ }.librarian;
187
+ });
188
+ };
189
+ }
190
+ ```
191
+
192
+ #### Building from Source
193
+
194
+ ```bash
195
+ # Build the package (requires Nix flakes enabled)
196
+ nix build .#default
197
+
198
+ # The binary will be at ./result/bin/librarian
199
+ ./result/bin/librarian --help
200
+ ```
201
+
202
+ #### Darwin/macOS Support
203
+
204
+ Librarian supports macOS on both x86_64 and Apple Silicon:
205
+
206
+ ```bash
207
+ # Run directly
208
+ nix run github:SkrOYC/librarian -- --help
209
+
210
+ # Install to profile
211
+ nix profile install github:SkrOYC/librarian
212
+ ```
213
+
214
+ Note: Full system installation on macOS requires [nix-darwin](https://github.com/LnL7/nix-darwin):
215
+
216
+ ## Quick Start
217
+
218
+ ### 1. Configure Technologies
219
+
220
+ Create a configuration file at `~/.config/librarian/config.yaml`:
221
+
222
+ ```yaml
223
+ repos_path: "~/.local/share/librarian/repos"
224
+ technologies:
225
+ default:
226
+ react:
227
+ repo: "https://github.com/facebook/react.git"
228
+ # Branch must be optional
229
+ branch: "main"
230
+ description: "JavaScript library for building user interfaces"
231
+ nodejs:
232
+ repo: "https://github.com/nodejs/node.git"
233
+ branch: "main"
234
+ description: "JavaScript runtime environment"
235
+ langchain:
236
+ langchain-javascript:
237
+ repo: "https://github.com/langchain-ai/langchainjs"
238
+ description: "LangChain is a framework for building LLM-powered..."
239
+ langgraph-javascript:
240
+ repo: "https://github.com/langchain-ai/langgraphjs"
241
+ description: "LangGraph is low-level orchestration framework..."
242
+ # Optional: Uncomment and configure LLM provider if you want to override OpenCode Zen
243
+ # aiProvider:
244
+ # type: openai # Options: openai, anthropic, google, openai-compatible, anthropic-compatible, claude-code, gemini-cli
245
+ # apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
246
+ # model: gpt-5.2
247
+ # baseURL: # Optional for openai-compatible providers
248
+ ```
249
+
250
+ ### 2. Explore a Technology
251
+
252
+ ```bash
253
+ # Query an specific tech
254
+ librarian explore "How does React handle state management?" --tech react
255
+
256
+ # Query a whole group (all technologies under it)
257
+ librarian explore "How does LangChain handle memory management?" --group langchain
258
+ ```
259
+
260
+ ### 3. List Available Technologies
261
+
262
+ ```bash
263
+ # List all technologies
264
+ librarian list
265
+ # Returns this:
266
+ # group
267
+ # tech1: description
268
+ # tech2: description
269
+ # e.g.:
270
+ # default
271
+ # react: JavaScript library for building user interfaces
272
+ # nodejs: JavaScript runtime environment
273
+ # langchain
274
+ # langchain-javascript: LangChain is a framework for building...
275
+ # langgraph-javascript: LangGraph is low-level orchestration framework...
276
+
277
+ # List technologies in a specific group
278
+ librarian list --group langchain
279
+ # Returns this:
280
+ # langchain
281
+ # langchain-javascript: LangChain is a framework for building...
282
+ # langgraph-javascript: LangGraph is low-level orchestration framework...
283
+ ```
284
+
285
+ ## Commands
286
+
287
+ ### `explore <query> --tech <technology>`
288
+
289
+ Execute agentic research on specified technology using a LangChain-powered agent. The agent operates in a sandboxed environment at `{repos_path}/{group}/{technology}` and streams the response to stdout.
290
+
291
+ **Options:**
292
+
293
+ - `--tech, -t <technology>`: Technology name
294
+
295
+ **Examples:**
296
+
297
+ ```bash
298
+ librarian explore "Explain the virtual DOM implementation" --tech react
299
+ librarian explore "How are errors handled in this codebase?" --tech default:nodejs
300
+ ```
301
+
302
+ ### `explore <query> --group <group>`
303
+
304
+ Execute agentic research on whole group using a LangChain-powered agent. The agent operates in a sandboxed environment at `{repos_path}/{group}` with access to all technologies in the group.
305
+
306
+ **Options:**
307
+
308
+ - `--group, -g <group>`: Group name
309
+
310
+ **Examples:**
311
+
312
+ ```bash
313
+ librarian explore "What are common patterns across React libraries?" --group default
314
+ librarian explore "What are middlewares in the langchain ecosystem?" --group langchain
315
+ ```
316
+
317
+ ### `list --group [group]`
318
+
319
+ List available technologies with descriptions.
320
+
321
+ **Options:**
322
+
323
+ - `--group, -g [group]`: Filter by technology group (default: all groups)
324
+
325
+ **Examples:**
326
+
327
+ ```bash
328
+ librarian list
329
+ librarian list --group langchain
330
+ ```
331
+
332
+ ### `--help/-h`
333
+
334
+ Display help information for all commands.
335
+
336
+ ## Configuration
337
+
338
+ ### Configuration File Location
339
+
340
+ The configuration file must be located at `~/.config/librarian/config.yaml`.
341
+
342
+ ### Configuration Schema
343
+
344
+ ```yaml
345
+ repos_path: "~/.local/share/librarian/repos" # Shared directory for all technologies
346
+ technologies:
347
+ default: # Default group
348
+ react:
349
+ repo: "https://github.com/facebook/react.git"
350
+ branch: "main" # Optional, defaults to main/master
351
+ description: "JavaScript library for building user interfaces"
352
+ nodejs:
353
+ repo: "https://github.com/nodejs/node.git"
354
+ branch: "main"
355
+ description: "JavaScript runtime environment"
356
+ langchain: # Custom group
357
+ langchain-javascript:
358
+ repo: "https://github.com/langchain-ai/langchainjs"
359
+ description: "LangChain is a framework for building LLM-powered applications..."
360
+ langgraph-javascript:
361
+ repo: "https://github.com/langchain-ai/langgraphjs"
362
+ description: "LangGraph is low-level orchestration framework..."
363
+ # Optional: Uncomment and configure LLM provider if you want to override OpenCode Zen
364
+ # aiProvider:
365
+ # type: openai # Options: openai, anthropic, google, openai-compatible, anthropic-compatible, claude-code, gemini-cli
366
+ # apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
367
+ # model: gpt-5.2
368
+ # baseURL: # Optional for openai-compatible providers
369
+ ```
370
+
371
+ **Note**: The system works out-of-the-box with OpenCode Zen integration (no LLM configuration required by default). When configured, the system supports multiple providers through LangChain's unified interface.
372
+
373
+ ### Repository Path Structure
374
+
375
+ Repositories are cloned to: `{repos_path}/{group}/{technology}`
376
+
377
+ **Agent Working Directory Sandboxing:**
378
+
379
+ - For `--tech` commands: Agent operates in `{repos_path}/{group}/{technology}`
380
+ - For `--group` commands: Agent operates in `{repos_path}/{group}`
381
+
382
+ This ensures all file paths are relative to the target directory and tool execution is securely isolated.
383
+
384
+ Example:
385
+
386
+ - `~/.local/share/librarian/repos/default/react/` (single tech exploration)
387
+ - `~/.local/share/librarian/repos/langchain/` (group-wide exploration)
388
+
389
+ ## Architecture
390
+
391
+ ### Core Components
392
+
393
+ 1. **CLI Entry Point** (`src/cli.ts`)
394
+ - Command parsing with Commander.js
395
+ - Configuration loading and validation
396
+ - Error handling and exit codes
397
+
398
+ 2. **Core Librarian** (`src/index.ts`)
399
+ - Main class for orchestrating operations
400
+ - Technology resolution
401
+ - Repository synchronization logic
402
+
403
+ 3. **Repository Manager** (`src/repo/`)
404
+ - Git clone/pull operations
405
+ - Repository synchronization
406
+ - Local path management
407
+
408
+ 4. **Agent Orchestrator** (`src/agent/`)
409
+ - LangChain createAgent-based implementation
410
+ - Dynamic system prompt construction based on group/tech context
411
+ - Tool integration with sandboxed execution environment
412
+ - Memory management with LangGraph
413
+
414
+ 5. **LLM Provider** (`src/llm/`)
415
+ - LangChain unified model abstraction through `initChatModel`
416
+ - Multi-provider support via LangChain integrations
417
+ - Dynamic model switching without code changes
418
+ - Response streaming and structured output handling
419
+
420
+ ### Agent Tools
421
+
422
+ The Librarian agent includes four core tools for repository exploration:
423
+
424
+ - **File Listing**: List files and directories within the sandboxed working directory
425
+ - **File Reading**: Read file contents with support for various file types
426
+ - **Grep Search**: Search file contents using regex patterns
427
+ - **Glob Search**: Find files by name patterns using glob syntax
428
+
429
+ All tools operate within the agent's isolated working directory, ensuring secure and context-aware file operations.
430
+
431
+ ## Technology Management
432
+
433
+ ### Adding New Technologies
434
+
435
+ 1. Edit your `~/.config/librarian/config.yaml` file
436
+ 2. Add your technology under the appropriate group
437
+ 3. Specify the GitHub repository URL, branch, and description
438
+ 4. Ensure the technology name is unique within its group
439
+
440
+ ### Repository Management
441
+
442
+ - **Auto-Clone**: Repositories are automatically cloned when first accessed
443
+ - **Auto-Update**: Repositories are pulled for updates before each query
444
+ - **Path Resolution**: Repositories follow the pattern `{repos_path}/{group}/{technology}`
445
+ - **Branch Support**: Specify any branch (defaults to main/master if not specified)
446
+
447
+ ## LLM Provider Configuration
448
+
449
+ Librarian uses LangChain's unified model abstraction and works out-of-the-box with OpenCode Zen (no LLM configuration required by default). Seamless switching between providers is possible through configuration. No code changes required when changing models.
450
+
451
+ By default, the system uses OpenCode Zen:
452
+
453
+ ```yaml
454
+ aiProvider:
455
+ type: openai-compatible
456
+ model: grok-code
457
+ baseURL: "https://opencode.ai/zen/v1"
458
+ ```
459
+
460
+ ### OpenAI
461
+
462
+ ```yaml
463
+ aiProvider:
464
+ type: openai
465
+ apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
466
+ model: gpt-5.2
467
+ ```
468
+
469
+ ### Anthropic
470
+
471
+ ```yaml
472
+ aiProvider:
473
+ type: anthropic
474
+ apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
475
+ model: claude-opus-4-5-20251101
476
+ ```
477
+
478
+ ### Google
479
+
480
+ ```yaml
481
+ aiProvider:
482
+ type: google
483
+ apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
484
+ model: gemini-3-pro-preview
485
+ ```
486
+
487
+ ### OpenAI-Compatible
488
+
489
+ ```yaml
490
+ aiProvider:
491
+ type: openai-compatible
492
+ model: your-model-name
493
+ baseURL: "https://your-provider.com/v1"
494
+ apiKey: # Optional API key (loaded from .env as LIBRARIAN_API_KEY if required by provider)
495
+ ```
496
+
497
+ ### Anthropic-Compatible
498
+
499
+ ```yaml
500
+ aiProvider:
501
+ type: anthropic-compatible
502
+ model: your-model-name
503
+ baseURL: "https://your-anthropic-compatible-provider.com/v1"
504
+ apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
505
+ ```
506
+
507
+ ### Claude Code (CLI-based)
508
+
509
+ ```yaml
510
+ aiProvider:
511
+ type: claude-code
512
+ model: claude-sonnet-4-5 # Model name passed to Claude CLI
513
+ ```
514
+
515
+ **Note**: For Claude Code provider, ensure the `claude` CLI is installed and available in your PATH.
516
+
517
+ ### Gemini CLI (CLI-based)
518
+
519
+ ```yaml
520
+ aiProvider:
521
+ type: gemini-cli
522
+ model: gemini-3-pro-preview # Model name passed to Gemini CLI
523
+ ```
524
+
525
+ **Note**: For Gemini CLI provider, ensure the `gemini` CLI is installed and available in your PATH.
526
+
527
+ **Note**: The same configuration interface works across all providers thanks to LangChain's `initChatModel` abstraction and OpenCode Zen integration.
528
+
529
+ ## Error Handling
530
+
531
+ - **Fatal Errors**: CLI exits with appropriate error codes
532
+ - **Repository Issues**: Clear error messages for missing or inaccessible repositories
533
+ - **LLM Errors**: Graceful handling of API failures and rate limits
534
+ - **Configuration Errors**: Validation errors with helpful guidance
535
+
536
+ ## Development
537
+
538
+ ### Project Setup
539
+
540
+ ```bash
541
+ # Clone the repository
542
+ git clone https://github.com/SkrOYC/librarian.git
543
+ cd librarian
544
+
545
+ # Install dependencies with Bun (recommended)
546
+ bun install
547
+
548
+ # OR install dependencies with npm
549
+ npm install
550
+
551
+ # Build the project with Bun
552
+ bun run build
553
+
554
+ # OR build with npm
555
+ npm run build
556
+
557
+ # Run tests with Bun
558
+ bun run test
559
+
560
+ # OR run tests with npm
561
+ npm run test
562
+ ```
563
+
564
+ ### NPM Publishing
565
+
566
+ ```bash
567
+ # Login to npm (if not already logged in)
568
+ npm login
569
+
570
+ # Dry run to verify package contents
571
+ npm pack --dry-run
572
+
573
+ # Publish to npm
574
+ npm publish
575
+
576
+ # Publish with specific tag (e.g., beta, next)
577
+ npm publish --tag beta
578
+ ```
579
+
580
+ ### Dependencies
581
+
582
+ #### Core
583
+
584
+ - `commander`: CLI argument parsing
585
+ - `yaml`: Configuration file parsing
586
+ - `isomorphic-git`: Git operations
587
+ - `zod`: Runtime validation
588
+
589
+ #### Agent System
590
+
591
+ - `langchain`: Core LangChain framework (createAgent, initChatModel, tool)
592
+ - `@langchain/langgraph`: Memory management with MemorySaver
593
+ - `@langchain/openai`: OpenAI provider integration
594
+ - `@langchain/anthropic`: Anthropic provider integration
595
+ - `@langchain/google-genai`: Google provider integration
596
+ - `zod`: Tool schema validation and structured responses
597
+
598
+ ## Contributing
599
+
600
+ 1. Fork the repository
601
+ 2. Create a feature branch
602
+ 3. Make your changes
603
+ 4. Add tests for new functionality
604
+ 5. Submit a pull request
605
+
606
+ ## License
607
+
608
+ Apache 2.0
609
+
610
+ ## Support
611
+
612
+ For support and questions:
613
+
614
+ - Create an issue on GitHub
package/biome.jsonc ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
3
+ "extends": [
4
+ "ultracite/biome/core"
5
+ ],
6
+ "javascript": {
7
+ "globals": ["Bun"]
8
+ }
9
+ }
@@ -0,0 +1,17 @@
1
+ import { z } from 'zod';
2
+ export declare const contextSchema: z.ZodObject<{
3
+ workingDir: z.ZodString;
4
+ environment: z.ZodOptional<z.ZodString>;
5
+ group: z.ZodString;
6
+ technology: z.ZodString;
7
+ }, z.core.$strip>;
8
+ export type Context = z.infer<typeof contextSchema>;
9
+ export interface AgentContext {
10
+ workingDir: string;
11
+ environment?: string;
12
+ group: string;
13
+ technology: string;
14
+ }
15
+ export type { AgentContext as AgentContextType };
16
+ export declare function createContext(workingDir: string, group: string, technology: string, environment?: string): Context;
17
+ //# sourceMappingURL=context-schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-schema.d.ts","sourceRoot":"","sources":["../../src/agents/context-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,eAAO,MAAM,aAAa;;;;;iBASxB,CAAC;AAMH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAMpD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,CAAC;AAWjD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAOT"}
@@ -0,0 +1,16 @@
1
+ import { z } from 'zod';
2
+ export const contextSchema = z.object({
3
+ workingDir: z.string().describe("The absolute path to sandbox directory"),
4
+ environment: z.string().optional().describe("Optional environment identifier"),
5
+ group: z.string().describe("The technology group name"),
6
+ technology: z.string().describe("The technology/repo name"),
7
+ });
8
+ export function createContext(workingDir, group, technology, environment) {
9
+ return contextSchema.parse({
10
+ workingDir,
11
+ group,
12
+ technology,
13
+ environment,
14
+ });
15
+ }
16
+ //# sourceMappingURL=context-schema.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-schema.js","sourceRoot":"","sources":["../../src/agents/context-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAEpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAEzE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAE9E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IAEvD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;CAC5D,CAAC,CAAC;AA+BH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,KAAa,EACb,UAAkB,EAClB,WAAoB;IAEpB,OAAO,aAAa,CAAC,KAAK,CAAC;QACzB,UAAU;QACV,KAAK;QACL,UAAU;QACV,WAAW;KACZ,CAAC,CAAC;AACL,CAAC"}
@@ -0,0 +1,38 @@
1
+ import type { z } from "zod";
2
+ import type { AgentContext } from "./context-schema.js";
3
+ export interface ReactAgentConfig {
4
+ aiProvider: {
5
+ type: "openai" | "anthropic" | "google" | "openai-compatible" | "anthropic-compatible" | "claude-code" | "gemini-cli";
6
+ apiKey: string;
7
+ model?: string;
8
+ baseURL?: string;
9
+ };
10
+ workingDir: string;
11
+ technology?: {
12
+ name: string;
13
+ repository: string;
14
+ branch: string;
15
+ };
16
+ contextSchema?: z.ZodType | undefined;
17
+ }
18
+ export declare class ReactAgent {
19
+ private readonly aiModel?;
20
+ private readonly tools;
21
+ private agent?;
22
+ private readonly config;
23
+ private readonly contextSchema?;
24
+ constructor(config: ReactAgentConfig);
25
+ createDynamicSystemPrompt(): string;
26
+ private createGeminiTempDir;
27
+ private setupGeminiConfig;
28
+ private buildGeminiEnv;
29
+ private cleanupGeminiTempDir;
30
+ private streamClaudeCli;
31
+ private streamGeminiCli;
32
+ private parseGeminiStreamLine;
33
+ private createAIModel;
34
+ initialize(): Promise<void>;
35
+ queryRepository(_repoPath: string, query: string, context?: AgentContext): Promise<string>;
36
+ streamRepository(_repoPath: string, query: string, context?: AgentContext): AsyncGenerator<string, void, unknown>;
37
+ }
38
+ //# sourceMappingURL=react-agent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react-agent.d.ts","sourceRoot":"","sources":["../../src/agents/react-agent.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAe7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKxD,MAAM,WAAW,gBAAgB;IAEhC,UAAU,EAAE;QACX,IAAI,EACD,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,UAAU,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;IAEF,aAAa,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC;CACtC;AAED,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAsD;IAC/E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwB;gBAE3C,MAAM,EAAE,gBAAgB;IA2BpC,yBAAyB,IAAI,MAAM;YAmSrB,mBAAmB;YAMnB,iBAAiB;IA+B/B,OAAO,CAAC,cAAc;YAaR,oBAAoB;YAUnB,eAAe;YAqFf,eAAe;IA2E9B,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,aAAa;IA8DrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CrB,eAAe,CACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC;IAwEX,gBAAgB,CACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACpB,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;CAqExC"}