@backendkit-labs/curator-codex-agent 0.2.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.
- package/AGENT.md +187 -0
- package/README.md +475 -0
- package/dist/analyzer.d.ts +44 -0
- package/dist/analyzer.d.ts.map +1 -0
- package/dist/analyzer.js +381 -0
- package/dist/analyzer.js.map +1 -0
- package/dist/api/config.d.ts +57 -0
- package/dist/api/config.d.ts.map +1 -0
- package/dist/api/config.js +183 -0
- package/dist/api/config.js.map +1 -0
- package/dist/api/http-server.d.ts +24 -0
- package/dist/api/http-server.d.ts.map +1 -0
- package/dist/api/http-server.js +108 -0
- package/dist/api/http-server.js.map +1 -0
- package/dist/api/routes.d.ts +8 -0
- package/dist/api/routes.d.ts.map +1 -0
- package/dist/api/routes.js +382 -0
- package/dist/api/routes.js.map +1 -0
- package/dist/api/security.d.ts +107 -0
- package/dist/api/security.d.ts.map +1 -0
- package/dist/api/security.js +200 -0
- package/dist/api/security.js.map +1 -0
- package/dist/checksum.d.ts +56 -0
- package/dist/checksum.d.ts.map +1 -0
- package/dist/checksum.js +186 -0
- package/dist/checksum.js.map +1 -0
- package/dist/documentation-curator.d.ts +18 -0
- package/dist/documentation-curator.d.ts.map +1 -0
- package/dist/documentation-curator.js +231 -0
- package/dist/documentation-curator.js.map +1 -0
- package/dist/http-server-main.d.ts +28 -0
- package/dist/http-server-main.d.ts.map +1 -0
- package/dist/http-server-main.js +69 -0
- package/dist/http-server-main.js.map +1 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/knowledge/engine.d.ts +90 -0
- package/dist/knowledge/engine.d.ts.map +1 -0
- package/dist/knowledge/engine.js +181 -0
- package/dist/knowledge/engine.js.map +1 -0
- package/dist/knowledge/rag-provider.d.ts +87 -0
- package/dist/knowledge/rag-provider.d.ts.map +1 -0
- package/dist/knowledge/rag-provider.js +189 -0
- package/dist/knowledge/rag-provider.js.map +1 -0
- package/dist/knowledge/synthesis.d.ts +27 -0
- package/dist/knowledge/synthesis.d.ts.map +1 -0
- package/dist/knowledge/synthesis.js +142 -0
- package/dist/knowledge/synthesis.js.map +1 -0
- package/dist/providers/anthropic-adapter.d.ts +14 -0
- package/dist/providers/anthropic-adapter.d.ts.map +1 -0
- package/dist/providers/anthropic-adapter.js +29 -0
- package/dist/providers/anthropic-adapter.js.map +1 -0
- package/dist/providers/index.d.ts +14 -0
- package/dist/providers/index.d.ts.map +1 -0
- package/dist/providers/index.js +29 -0
- package/dist/providers/index.js.map +1 -0
- package/dist/providers/openai-adapter.d.ts +16 -0
- package/dist/providers/openai-adapter.d.ts.map +1 -0
- package/dist/providers/openai-adapter.js +37 -0
- package/dist/providers/openai-adapter.js.map +1 -0
- package/dist/providers/types.d.ts +4 -0
- package/dist/providers/types.d.ts.map +1 -0
- package/dist/providers/types.js +3 -0
- package/dist/providers/types.js.map +1 -0
- package/dist/server.d.ts +33 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +640 -0
- package/dist/server.js.map +1 -0
- package/dist/types.d.ts +41 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +4 -0
- package/dist/types.js.map +1 -0
- package/dist/watcher.d.ts +26 -0
- package/dist/watcher.d.ts.map +1 -0
- package/dist/watcher.js +168 -0
- package/dist/watcher.js.map +1 -0
- package/package.json +58 -0
package/AGENT.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# curator-codex-agent
|
|
2
|
+
|
|
3
|
+
**Unified Code + Documentation Curator**. Recursively analyzes both source code files AND documentation (.md, .txt), discovers associated files, and extracts structured knowledge into enterprise vaults using LLM reasoning.
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Analyze entire project (code + docs)
|
|
9
|
+
CURATOR_INPUT_PATH=/project \
|
|
10
|
+
CURATOR_OUTPUT_PATH=/vault \
|
|
11
|
+
CURATOR_API_KEY=sk-... \
|
|
12
|
+
npm run watch-code
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Core Capabilities
|
|
16
|
+
|
|
17
|
+
1. **Unified Processing** — Analyzes both code (.ts, .js, .py, etc) AND docs (.md, .txt) in single pass
|
|
18
|
+
2. **Multi-language Code Analysis** — TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Kotlin, Swift
|
|
19
|
+
3. **Documentation Analysis** — Extracts policies, procedures, decisions, lessons from .md/.txt
|
|
20
|
+
4. **Smart Documentation Discovery** — Finds and combines associated .md files, README.md, project context
|
|
21
|
+
5. **Automatic Type Detection** — Routes files to appropriate analyzer (CodeAnalyzer or DocumentationCurator)
|
|
22
|
+
6. **Reasoning-based Extraction** — Uses deepseek-reasoner for deep understanding
|
|
23
|
+
7. **Change Detection** — Manifest-based tracking; only reanalyzes changed files
|
|
24
|
+
8. **Vault Integration** — Outputs semantic markdown notes with metadata
|
|
25
|
+
9. **MCP Server** — Runs as stdio or HTTP MCP server
|
|
26
|
+
|
|
27
|
+
## Key Features
|
|
28
|
+
|
|
29
|
+
- ✅ Recursive directory scanning
|
|
30
|
+
- ✅ Public API extraction (types, functions, classes, interfaces)
|
|
31
|
+
- ✅ Pattern & architecture detection
|
|
32
|
+
- ✅ Dependency mapping
|
|
33
|
+
- ✅ Documentation association (code.ts + code.md → combined analysis)
|
|
34
|
+
- ✅ Change tracking via SHA256 manifest
|
|
35
|
+
- ✅ Efficient reprocessing (skip unchanged files)
|
|
36
|
+
- ✅ Multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama)
|
|
37
|
+
|
|
38
|
+
## Environment Variables
|
|
39
|
+
|
|
40
|
+
**Required:**
|
|
41
|
+
- `CURATOR_API_KEY` — LLM API key
|
|
42
|
+
- `CURATOR_OUTPUT_PATH` — Vault output directory
|
|
43
|
+
|
|
44
|
+
**Optional:**
|
|
45
|
+
- `CURATOR_INPUT_PATH` — Code directory to analyze once (default: watch mode)
|
|
46
|
+
- `CURATOR_PROVIDER` — LLM provider (default: deepseek)
|
|
47
|
+
- `CURATOR_MODEL` — Model ID (default: deepseek-reasoner)
|
|
48
|
+
- `CURATOR_PORT` — HTTP port for MCP (default: stdio transport)
|
|
49
|
+
|
|
50
|
+
See `.env.example` for all options.
|
|
51
|
+
|
|
52
|
+
## Architecture
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
CodeAnalyzer
|
|
56
|
+
├── findAssociatedDocs() — Discovers code.md, README.md, etc
|
|
57
|
+
├── analyzeFile() — Analyzes single file + combined docs
|
|
58
|
+
├── callLLM() — Sends to reasoning model
|
|
59
|
+
└── writeNote() — Outputs to vault
|
|
60
|
+
|
|
61
|
+
Manifest System
|
|
62
|
+
├── calculateFileHash() — SHA256 tracking
|
|
63
|
+
├── loadManifest() — Read .codex-manifest.json
|
|
64
|
+
├── hasFileChanged() — Detect changes
|
|
65
|
+
└── saveManifest() — Update tracking
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Vault Output
|
|
69
|
+
|
|
70
|
+
Generates markdown files with frontmatter per analyzed module:
|
|
71
|
+
|
|
72
|
+
```markdown
|
|
73
|
+
---
|
|
74
|
+
title: "AuthService: JWT-based Authentication"
|
|
75
|
+
area: general
|
|
76
|
+
tipo: componente
|
|
77
|
+
language: typescript
|
|
78
|
+
resumen: "NestJS service for JWT-based authentication..."
|
|
79
|
+
source_ref: "src/services/auth.service.ts"
|
|
80
|
+
sources_combined: ["src/services/auth.service.ts", "src/services/auth.service.md"]
|
|
81
|
+
depends_on: ["@nestjs/jwt", "@backendkit-labs/result"]
|
|
82
|
+
exports: ["AuthService", "login", "validateToken"]
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Overview
|
|
86
|
+
...
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Usage Modes
|
|
90
|
+
|
|
91
|
+
1. **Direct Analysis** (single run):
|
|
92
|
+
```bash
|
|
93
|
+
CURATOR_INPUT_PATH=/project npm run watch-code
|
|
94
|
+
# Analyzes once, exits
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
2. **Watch Mode** (continuous):
|
|
98
|
+
```bash
|
|
99
|
+
npm start
|
|
100
|
+
# Polls vault/incoming/ every 30s
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
3. **MCP Server**:
|
|
104
|
+
```bash
|
|
105
|
+
CURATOR_PORT=3101 npm start
|
|
106
|
+
# HTTP MCP server
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Performance
|
|
110
|
+
|
|
111
|
+
- 3-8 seconds per file (reasoning model)
|
|
112
|
+
- Skipped files: < 100ms
|
|
113
|
+
- 500 files, 1st run: ~40-60 min
|
|
114
|
+
- 500 files, 2nd run (1% changed): ~2-3 min
|
|
115
|
+
|
|
116
|
+
## Integration
|
|
117
|
+
|
|
118
|
+
### Claude Desktop
|
|
119
|
+
Add to `claude_desktop_config.json`:
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"mcpServers": {
|
|
123
|
+
"codex": {
|
|
124
|
+
"command": "npx",
|
|
125
|
+
"args": ["-y", "@backendkit-labs/curator-codex-agent"],
|
|
126
|
+
"env": {"CURATOR_API_KEY": "sk-...", "CURATOR_OUTPUT_PATH": "/vault"}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### bk-agent
|
|
133
|
+
Register as MCP skill in bk-agent manifest.
|
|
134
|
+
|
|
135
|
+
### knowledge-agent
|
|
136
|
+
Query vault generated by curator-codex for RAG-powered code questions.
|
|
137
|
+
|
|
138
|
+
## Architecture
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
CodeAnalyzer
|
|
142
|
+
├── analyzeFile() — Dispatcher
|
|
143
|
+
├── analyzeCode() — Route to CodeAnalyzer
|
|
144
|
+
├── analyzeDocumentation() — Route to DocumentationCurator
|
|
145
|
+
├── isDocFile() — File type detection
|
|
146
|
+
└── findAssociatedDocs() — Discover code.md, README.md
|
|
147
|
+
|
|
148
|
+
DocumentationCurator (embedded)
|
|
149
|
+
├── curateFile()
|
|
150
|
+
├── curateText()
|
|
151
|
+
└── callLLM() — Extract policies, procedures
|
|
152
|
+
|
|
153
|
+
Manifest System
|
|
154
|
+
├── findAllFiles() — Find code + docs (recursive)
|
|
155
|
+
├── isCodeFile() — Detect .ts, .js, .py, etc
|
|
156
|
+
├── isDocFile() — Detect .md, .txt
|
|
157
|
+
└── Change tracking — .codex-manifest.json
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Comparison
|
|
161
|
+
|
|
162
|
+
| Feature | curator-agent | curator-codex-agent |
|
|
163
|
+
|---------|---|---|
|
|
164
|
+
| **Input** | .md, .txt docs only | Code + Docs (.ts, .js, .py, .md, .txt) |
|
|
165
|
+
| **Code Analysis** | ❌ No | ✅ Yes (extract APIs, components) |
|
|
166
|
+
| **Doc Analysis** | ✅ Yes | ✅ Yes (extract policies, procedures) |
|
|
167
|
+
| **File Detection** | Manual separation | Automatic file routing |
|
|
168
|
+
| **Associated Docs** | N/A | ✅ Finds code.md, README.md |
|
|
169
|
+
| **Use Case** | Docs-only projects | Projects with code + docs |
|
|
170
|
+
| **Workflow** | Sequential | Unified (one pass) |
|
|
171
|
+
|
|
172
|
+
## When to Use Each
|
|
173
|
+
|
|
174
|
+
| Scenario | Use |
|
|
175
|
+
|----------|-----|
|
|
176
|
+
| I have code + docs (mixed project) | **curator-codex-agent** ← unified |
|
|
177
|
+
| I ONLY have documentation files | curator-agent |
|
|
178
|
+
| I ONLY have code (no docs) | curator-codex-agent |
|
|
179
|
+
| I want code analysis only | curator-codex-agent (will skip .md) |
|
|
180
|
+
| I want docs analysis only | curator-agent |
|
|
181
|
+
|
|
182
|
+
## See Also
|
|
183
|
+
|
|
184
|
+
- **curator-agent** — Specialized documentation curator (if you prefer separate concerns)
|
|
185
|
+
- **bk-agent** — Multi-agent framework
|
|
186
|
+
- **knowledge-agent** — RAG retrieval on curated vaults
|
|
187
|
+
- **curator-codex-agent** ← **You are here** (unified code + doc curator)
|
package/README.md
ADDED
|
@@ -0,0 +1,475 @@
|
|
|
1
|
+
# curator-codex-agent
|
|
2
|
+
|
|
3
|
+
**Codex Curator** — Unified source code and documentation analysis with intelligent knowledge extraction into enterprise vaults using LLM reasoning.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
`curator-codex-agent` is a **unified curator** that analyzes both source code and documentation:
|
|
8
|
+
|
|
9
|
+
### 🔵 Code Analysis
|
|
10
|
+
Analyzes source code files (TypeScript, JavaScript, Python, Go, Rust, Java, etc.) and extracts:
|
|
11
|
+
- **Public APIs** — functions, classes, interfaces, type definitions
|
|
12
|
+
- **Modules & Components** — what each file/directory does
|
|
13
|
+
- **Patterns & Architecture** — design patterns, integration points
|
|
14
|
+
- **Dependencies** — external libraries and internal module relationships
|
|
15
|
+
- **Usage Examples** — extracted from comments and associated documentation
|
|
16
|
+
|
|
17
|
+
### 📄 Documentation Analysis
|
|
18
|
+
Processes documentation files (.md, .txt) and extracts:
|
|
19
|
+
- **Policies** — company rules, procedures, governance
|
|
20
|
+
- **Decisions** — architectural decisions, standards
|
|
21
|
+
- **Procedures** — how-to guides, workflows
|
|
22
|
+
- **Lessons** — learned experiences, best practices
|
|
23
|
+
- **External Standards** — compliance requirements, ISO standards
|
|
24
|
+
|
|
25
|
+
### Key Features
|
|
26
|
+
|
|
27
|
+
✅ **Unified Processing** — Handles both source code AND documentation in single pass
|
|
28
|
+
✅ **Multi-language Code** — TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Kotlin, Swift
|
|
29
|
+
✅ **Smart Documentation Discovery** — automatically finds and combines associated .md files, README.md, and project context
|
|
30
|
+
✅ **Reasoning-based Analysis** — uses deepseek-reasoner for deep understanding of both code and docs
|
|
31
|
+
✅ **Change Detection** — SHA256 manifest tracking, intelligent reprocessing of only changed files
|
|
32
|
+
✅ **Recursive Scanning** — processes entire directory hierarchies, smart ignoring of node_modules, dist, venv, etc.
|
|
33
|
+
✅ **MCP Server** — works as stdio or HTTP server for integration with Claude, bk-agent, other tools
|
|
34
|
+
✅ **Vault Integration** — outputs semantic notes into shared vaults for knowledge sharing
|
|
35
|
+
✅ **Automatic Type Detection** — detects file type and routes to appropriate analyzer
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @backendkit-labs/curator-codex-agent
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Or clone and build:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cd packages/curator-codex-agent
|
|
47
|
+
npm install
|
|
48
|
+
npm run build
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Usage
|
|
52
|
+
|
|
53
|
+
### Mode 1: Direct Code Analysis (Single Run)
|
|
54
|
+
|
|
55
|
+
Analyze a project's code once and generate knowledge vault:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
CURATOR_INPUT_PATH=/path/to/my-project \
|
|
59
|
+
CURATOR_OUTPUT_PATH=/path/to/vault \
|
|
60
|
+
CURATOR_API_KEY=sk-... \
|
|
61
|
+
npm run watch-code
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This will:
|
|
65
|
+
1. Recursively scan `/path/to/my-project` for all code files
|
|
66
|
+
2. For each file, search for associated documentation:
|
|
67
|
+
- `filename.md` (same directory)
|
|
68
|
+
- `README.md` (same directory)
|
|
69
|
+
- `docs/filename.md` (in docs/ folder)
|
|
70
|
+
- Root `/README.md` (project context)
|
|
71
|
+
3. Analyze code + docs together with reasoning model
|
|
72
|
+
4. Extract structured knowledge and write to vault
|
|
73
|
+
5. Create `.codex-manifest.json` to track analyzed files
|
|
74
|
+
6. Exit
|
|
75
|
+
|
|
76
|
+
**Second run with same inputs** (after modifying some files):
|
|
77
|
+
- Manifest detects unchanged files → skips
|
|
78
|
+
- Manifest detects changed files → reanalyzes only those
|
|
79
|
+
- Efficiency: if 500 files and only 3 changed, processes only the 3
|
|
80
|
+
|
|
81
|
+
### Mode 2: Watch Incoming (Autonomous)
|
|
82
|
+
|
|
83
|
+
Monitor `vault/incoming/` directory for new code files:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
CURATOR_OUTPUT_PATH=/path/to/vault \
|
|
87
|
+
CURATOR_API_KEY=sk-... \
|
|
88
|
+
npm start
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Polls every 30 seconds (or `CURATOR_POLL_MS`), processes new code files automatically.
|
|
92
|
+
|
|
93
|
+
### Mode 3: MCP Server
|
|
94
|
+
|
|
95
|
+
Run as HTTP MCP server for Claude Desktop or remote clients:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
CURATOR_OUTPUT_PATH=/path/to/vault \
|
|
99
|
+
CURATOR_API_KEY=sk-... \
|
|
100
|
+
CURATOR_PORT=3101 \
|
|
101
|
+
npm start
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Then use via MCP client:
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
// Analyze a single file
|
|
108
|
+
POST http://localhost:3101/mcp
|
|
109
|
+
{
|
|
110
|
+
"tool": "analyze_file",
|
|
111
|
+
"params": {
|
|
112
|
+
"file_path": "/absolute/path/to/file.ts",
|
|
113
|
+
"relative_path": "src/services/auth.ts"
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// Analyze entire directory
|
|
118
|
+
POST http://localhost:3101/mcp
|
|
119
|
+
{
|
|
120
|
+
"tool": "analyze_directory",
|
|
121
|
+
"params": {
|
|
122
|
+
"directory_path": "/absolute/path/to/project"
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Configuration
|
|
128
|
+
|
|
129
|
+
### Environment Variables
|
|
130
|
+
|
|
131
|
+
**Required:**
|
|
132
|
+
- `CURATOR_API_KEY` — Your API key (DeepSeek, OpenAI, Anthropic, etc.)
|
|
133
|
+
- `CURATOR_OUTPUT_PATH` — Absolute path to vault root
|
|
134
|
+
|
|
135
|
+
**Optional:**
|
|
136
|
+
- `CURATOR_INPUT_PATH` — Code directory to analyze once (if not set, uses watch mode)
|
|
137
|
+
- `CURATOR_PROVIDER` — `deepseek`, `openai`, `anthropic`, `ollama` (default: `deepseek`)
|
|
138
|
+
- `CURATOR_MODEL` — Model ID (defaults to reasoning models for each provider)
|
|
139
|
+
- `CURATOR_BASE_URL` — Custom LLM endpoint
|
|
140
|
+
- `CURATOR_PORT` — HTTP port (if set, runs HTTP MCP; if not, uses stdio)
|
|
141
|
+
- `CURATOR_POLL_MS` — Polling interval in milliseconds (default: 30000)
|
|
142
|
+
|
|
143
|
+
### Example `.env.local`
|
|
144
|
+
|
|
145
|
+
```env
|
|
146
|
+
CURATOR_API_KEY=sk-...
|
|
147
|
+
CURATOR_OUTPUT_PATH=/Users/john/Vaults/code-knowledge
|
|
148
|
+
CURATOR_INPUT_PATH=/Users/john/Projects/my-framework
|
|
149
|
+
CURATOR_PROVIDER=deepseek
|
|
150
|
+
CURATOR_MODEL=deepseek-reasoner
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Vault Output
|
|
154
|
+
|
|
155
|
+
For each analyzed file, generates markdown notes with frontmatter:
|
|
156
|
+
|
|
157
|
+
**File:** `vault/general/2026-06-13-authservice-jwt-based-authentication.md`
|
|
158
|
+
|
|
159
|
+
```markdown
|
|
160
|
+
---
|
|
161
|
+
title: "AuthService: JWT-based Authentication"
|
|
162
|
+
area: general
|
|
163
|
+
tipo: componente
|
|
164
|
+
language: typescript
|
|
165
|
+
resumen: "NestJS service implementing JWT-based authentication..."
|
|
166
|
+
author: "agent/codex"
|
|
167
|
+
date: 2026-06-13
|
|
168
|
+
source_ref: "src/services/auth.service.ts"
|
|
169
|
+
sources_combined: ["src/services/auth.service.ts", "src/services/auth.service.md", "README.md"]
|
|
170
|
+
tags: ["code/typescript", "modulo/authentication", "tipo/service", "patron/jwt"]
|
|
171
|
+
version: 1.0
|
|
172
|
+
depends_on: ["@nestjs/jwt", "@backendkit-labs/result"]
|
|
173
|
+
exports: ["AuthService", "login", "validateToken"]
|
|
174
|
+
files: ["src/services/auth.service.ts"]
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Overview
|
|
178
|
+
JWT-based authentication service for NestJS applications.
|
|
179
|
+
|
|
180
|
+
## Public API
|
|
181
|
+
|
|
182
|
+
### login(username, password)
|
|
183
|
+
...
|
|
184
|
+
|
|
185
|
+
### validateToken(token)
|
|
186
|
+
...
|
|
187
|
+
|
|
188
|
+
## Dependencies
|
|
189
|
+
...
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Frontmatter Fields
|
|
193
|
+
|
|
194
|
+
| Field | Meaning |
|
|
195
|
+
|-------|---------|
|
|
196
|
+
| `title` | Human-readable name of the analyzed module/component |
|
|
197
|
+
| `area` | Category: general, backend, frontend, devops, infraestructura |
|
|
198
|
+
| `tipo` | Type: componente, api, patron, utilidad, arquitectura, integracion |
|
|
199
|
+
| `language` | Programming language detected |
|
|
200
|
+
| `resumen` | 1-2 sentences with searchable terms (function names, types) |
|
|
201
|
+
| `source_ref` | Original file analyzed |
|
|
202
|
+
| `sources_combined` | Array of files combined (code + associated docs) |
|
|
203
|
+
| `tags` | Searchable tags (e.g., code/typescript, modulo/auth) |
|
|
204
|
+
| `depends_on` | External dependencies or modules |
|
|
205
|
+
| `exports` | Public APIs this file exports |
|
|
206
|
+
| `files` | List of files analyzed for this note |
|
|
207
|
+
|
|
208
|
+
## How It Works
|
|
209
|
+
|
|
210
|
+
### 1. Discovery
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
Scans INPUT_PATH recursively
|
|
214
|
+
↓
|
|
215
|
+
Finds ALL files:
|
|
216
|
+
Code: .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .c, .cpp, .kt, .swift
|
|
217
|
+
Docs: .md, .txt
|
|
218
|
+
↓
|
|
219
|
+
For each code file:
|
|
220
|
+
- Look for filename.md (same dir)
|
|
221
|
+
- Look for README.md (same dir)
|
|
222
|
+
- Look for docs/filename.md
|
|
223
|
+
- Look for root README.md
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### 2. File Type Detection & Routing
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
Per file, determine type:
|
|
230
|
+
|
|
231
|
+
IF .md or .txt → Route to DocumentationCurator
|
|
232
|
+
↓
|
|
233
|
+
Analyzes as: policy, decision, procedure, lesson, standard
|
|
234
|
+
|
|
235
|
+
IF .ts, .js, .py, etc → Route to CodeAnalyzer
|
|
236
|
+
↓
|
|
237
|
+
1. Read code (truncate if > 20KB)
|
|
238
|
+
2. Read associated docs (if found)
|
|
239
|
+
3. Send to reasoning model
|
|
240
|
+
4. Extract: APIs, components, patterns, architecture
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### 3. Analysis
|
|
244
|
+
|
|
245
|
+
**Code Analysis (CodeAnalyzer):**
|
|
246
|
+
```
|
|
247
|
+
1. Read code file
|
|
248
|
+
2. Find & read associated .md file (if exists)
|
|
249
|
+
3. Find & read README.md for context
|
|
250
|
+
4. Send ALL THREE to reasoning model
|
|
251
|
+
5. LLM extracts: APIs, types, patterns, dependencies
|
|
252
|
+
6. Returns structured JSON
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
**Documentation Analysis (DocumentationCurator):**
|
|
256
|
+
```
|
|
257
|
+
1. Read .md or .txt file
|
|
258
|
+
2. Send to LLM
|
|
259
|
+
3. LLM extracts: policies, decisions, procedures, lessons
|
|
260
|
+
4. Returns structured JSON
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### 4. Deduplication
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
Check if output file already exists in vault
|
|
267
|
+
If yes → skip (avoid duplicate notes)
|
|
268
|
+
If no → write new markdown file
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
### 5. Manifest Tracking
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
On first run:
|
|
275
|
+
Creates .codex-manifest.json
|
|
276
|
+
Stores hash of EVERY file (code + docs) + analysis status
|
|
277
|
+
|
|
278
|
+
On subsequent runs:
|
|
279
|
+
Loads manifest
|
|
280
|
+
Checks hash of each file
|
|
281
|
+
If unchanged → skip analysis
|
|
282
|
+
If changed → reanalyze
|
|
283
|
+
If new → analyze
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## Example: Analyze a Framework with Code + Documentation
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
# Setup
|
|
290
|
+
export CURATOR_INPUT_PATH=/Users/john/Projects/my-framework
|
|
291
|
+
export CURATOR_OUTPUT_PATH=/Users/john/Vaults/framework-knowledge
|
|
292
|
+
export CURATOR_API_KEY=sk-...
|
|
293
|
+
|
|
294
|
+
# Project structure:
|
|
295
|
+
# my-framework/
|
|
296
|
+
# ├── src/
|
|
297
|
+
# │ ├── auth.service.ts
|
|
298
|
+
# │ ├── auth.service.md ← associated doc
|
|
299
|
+
# │ └── payment.ts
|
|
300
|
+
# ├── docs/
|
|
301
|
+
# │ ├── architecture.md
|
|
302
|
+
# │ ├── setup-guide.md
|
|
303
|
+
# │ └── contributing.md
|
|
304
|
+
# └── README.md
|
|
305
|
+
|
|
306
|
+
# First run: analyze EVERYTHING (code + docs)
|
|
307
|
+
npm run watch-code
|
|
308
|
+
# Output:
|
|
309
|
+
# - 100 code files analyzed (extracted APIs, components)
|
|
310
|
+
# - 10 doc files analyzed (extracted procedures, decisions)
|
|
311
|
+
# - .codex-manifest.json created
|
|
312
|
+
|
|
313
|
+
# Developer modifies 3 code files + 1 doc
|
|
314
|
+
# Second run: only those 4 files reanalyzed
|
|
315
|
+
npm run watch-code
|
|
316
|
+
# Output: 4 files analyzed, 106 skipped (96% efficiency!)
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
## MCP Integration
|
|
320
|
+
|
|
321
|
+
### Claude Desktop
|
|
322
|
+
|
|
323
|
+
Add to `claude_desktop_config.json`:
|
|
324
|
+
|
|
325
|
+
```json
|
|
326
|
+
{
|
|
327
|
+
"mcpServers": {
|
|
328
|
+
"codex": {
|
|
329
|
+
"command": "npx",
|
|
330
|
+
"args": ["-y", "@backendkit-labs/curator-codex-agent"],
|
|
331
|
+
"env": {
|
|
332
|
+
"CURATOR_API_KEY": "sk-...",
|
|
333
|
+
"CURATOR_OUTPUT_PATH": "/Users/john/Vaults/code-knowledge"
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Then use in Claude:
|
|
341
|
+
|
|
342
|
+
> I have a folder at `/path/to/my-project`. Can you analyze it and extract knowledge about the architecture and APIs?
|
|
343
|
+
|
|
344
|
+
### bk-agent
|
|
345
|
+
|
|
346
|
+
Add to skills or MCP registry:
|
|
347
|
+
|
|
348
|
+
```yaml
|
|
349
|
+
- name: curator-codex
|
|
350
|
+
command: npx @backendkit-labs/curator-codex-agent
|
|
351
|
+
env:
|
|
352
|
+
CURATOR_API_KEY: ${CURATOR_API_KEY}
|
|
353
|
+
CURATOR_OUTPUT_PATH: /shared-vault
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Scripts
|
|
357
|
+
|
|
358
|
+
```bash
|
|
359
|
+
npm run build # Compile TypeScript → dist/
|
|
360
|
+
npm run dev # Run analyzer in dev mode (tsx)
|
|
361
|
+
npm start # Run MCP server (stdio or HTTP)
|
|
362
|
+
npm run watch-code # Analyze code with progress bar
|
|
363
|
+
npm run typecheck # Type checking only
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## Supported Languages
|
|
367
|
+
|
|
368
|
+
| Language | Extensions | Example |
|
|
369
|
+
|----------|-----------|---------|
|
|
370
|
+
| TypeScript | .ts, .tsx | class, interface, type |
|
|
371
|
+
| JavaScript | .js, .jsx | function, class, export |
|
|
372
|
+
| Python | .py | def, class, async def |
|
|
373
|
+
| Go | .go | func, type, interface |
|
|
374
|
+
| Rust | .rs | fn, struct, trait, impl |
|
|
375
|
+
| Java | .java | class, interface, method |
|
|
376
|
+
| C | .c | struct, typedef, void |
|
|
377
|
+
| C++ | .cpp | class, namespace, template |
|
|
378
|
+
| Kotlin | .kt | class, fun, data class |
|
|
379
|
+
| Swift | .swift | class, struct, protocol |
|
|
380
|
+
|
|
381
|
+
## Unified Architecture
|
|
382
|
+
|
|
383
|
+
### curator-agent (Documentation Only)
|
|
384
|
+
- Specializes in .md and .txt files only
|
|
385
|
+
- Extracts: policies, procedures, decisions, standards
|
|
386
|
+
- Use when: processing documentation separately
|
|
387
|
+
|
|
388
|
+
### curator-codex-agent (Unified: Code + Documentation)
|
|
389
|
+
- Processes BOTH code files AND .md/.txt files in single pass
|
|
390
|
+
- Code Analysis: extracts APIs, components, patterns, architecture
|
|
391
|
+
- Documentation Analysis: extracts policies, procedures, decisions, standards
|
|
392
|
+
- Automatic File Detection: routes .ts to CodeAnalyzer, .md to DocumentationCurator
|
|
393
|
+
- Associated Doc Discovery: finds code.md, README.md, combines with code analysis
|
|
394
|
+
- Use when: analyzing projects with mixed code + documentation
|
|
395
|
+
|
|
396
|
+
### Single vs. Dual Curator Workflows
|
|
397
|
+
|
|
398
|
+
**Option A: Unified Workflow (Recommended for Projects)**
|
|
399
|
+
```
|
|
400
|
+
Project/
|
|
401
|
+
├── src/ ← Code (.ts, .js, .py)
|
|
402
|
+
├── docs/ ← Docs (.md, .txt)
|
|
403
|
+
└── README.md
|
|
404
|
+
|
|
405
|
+
curator-codex-agent INPUT=/project OUTPUT=/vault
|
|
406
|
+
↓
|
|
407
|
+
Processes EVERYTHING in one pass
|
|
408
|
+
↓
|
|
409
|
+
vault/
|
|
410
|
+
├── general/
|
|
411
|
+
│ ├── authservice-api.md (from src/auth.ts + auth.md)
|
|
412
|
+
│ ├── architecture-overview.md (from docs/architecture.md)
|
|
413
|
+
│ ├── setup-guide.md (from docs/setup.md)
|
|
414
|
+
│ └── ...
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
**Option B: Specialized Workflow (Separate Concerns)**
|
|
418
|
+
```
|
|
419
|
+
curator-codex-agent INPUT=/project/src OUTPUT=/vault # Code only
|
|
420
|
+
curator-agent INPUT=/project/docs OUTPUT=/vault # Docs only
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
## Troubleshooting
|
|
424
|
+
|
|
425
|
+
### No manifest found. Will process ALL X files.
|
|
426
|
+
|
|
427
|
+
Normal on first run. Creates `.codex-manifest.json` to track analyzed files.
|
|
428
|
+
|
|
429
|
+
### Files showing ⊘ (unchanged)
|
|
430
|
+
|
|
431
|
+
Good! Manifest detected no hash change. Skipped to save LLM costs. Run with file modifications to reanalyze.
|
|
432
|
+
|
|
433
|
+
### Model not found error
|
|
434
|
+
|
|
435
|
+
Check `CURATOR_MODEL` is valid for your provider:
|
|
436
|
+
- DeepSeek: `deepseek-reasoner`, `deepseek-chat`
|
|
437
|
+
- OpenAI: `o3-mini`, `gpt-4o`, `o1`
|
|
438
|
+
- Anthropic: `claude-opus-4-8`, `claude-sonnet-4-6`
|
|
439
|
+
- Ollama: `llama3.2`, `qwen2.5-coder:7b`
|
|
440
|
+
|
|
441
|
+
### API key rejected
|
|
442
|
+
|
|
443
|
+
Verify `CURATOR_API_KEY` is valid. Check provider's authentication method.
|
|
444
|
+
|
|
445
|
+
### Memory/timeout on large files
|
|
446
|
+
|
|
447
|
+
Files > 20KB are truncated to 20KB of code. Increase `maxInputChars` in code if needed:
|
|
448
|
+
|
|
449
|
+
```typescript
|
|
450
|
+
const analyzer = new CodeAnalyzer({
|
|
451
|
+
provider,
|
|
452
|
+
vaultPath,
|
|
453
|
+
maxInputChars: 40_000, // increase limit
|
|
454
|
+
});
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
## Performance
|
|
458
|
+
|
|
459
|
+
| Metric | Baseline |
|
|
460
|
+
|--------|----------|
|
|
461
|
+
| Analysis per file | 3-8 seconds (reasoning model) |
|
|
462
|
+
| Skipped files | < 100ms (hash check only) |
|
|
463
|
+
| 500 files, 1st run | ~40-60 minutes (depends on model) |
|
|
464
|
+
| 500 files, 2nd run (1% changed) | ~2-3 minutes |
|
|
465
|
+
| Vault size (500 files analyzed) | ~50-100 MB |
|
|
466
|
+
|
|
467
|
+
## License
|
|
468
|
+
|
|
469
|
+
MIT
|
|
470
|
+
|
|
471
|
+
## See Also
|
|
472
|
+
|
|
473
|
+
- [curator-agent](../curator-agent) — Documentation curator
|
|
474
|
+
- [bk-agent](../bk-agent) — Multi-agent framework
|
|
475
|
+
- [knowledge-agent](../knowledge-agent) — RAG knowledge retrieval
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { CuratorLLMProvider } from './providers/types.js';
|
|
2
|
+
import type { CodeAnalysisResult, AssociatedDocs } from './types.js';
|
|
3
|
+
export interface CodeAnalyzerOptions {
|
|
4
|
+
provider: CuratorLLMProvider;
|
|
5
|
+
vaultPath: string;
|
|
6
|
+
maxInputChars?: number;
|
|
7
|
+
}
|
|
8
|
+
export declare class CodeAnalyzer {
|
|
9
|
+
private readonly provider;
|
|
10
|
+
private readonly vaultPath;
|
|
11
|
+
private readonly maxInputChars;
|
|
12
|
+
private readonly docCurator;
|
|
13
|
+
constructor(opts: CodeAnalyzerOptions);
|
|
14
|
+
/**
|
|
15
|
+
* Find documentation files associated with a code file
|
|
16
|
+
*/
|
|
17
|
+
findAssociatedDocs(filePath: string, allFiles: Array<{
|
|
18
|
+
fullPath: string;
|
|
19
|
+
relativePath: string;
|
|
20
|
+
}>): Promise<AssociatedDocs>;
|
|
21
|
+
/**
|
|
22
|
+
* Analyze a file (code or documentation) with unified dispatcher
|
|
23
|
+
*/
|
|
24
|
+
analyzeFile(filePath: string, relativePath: string, allFiles?: Array<{
|
|
25
|
+
fullPath: string;
|
|
26
|
+
relativePath: string;
|
|
27
|
+
}>): Promise<CodeAnalysisResult>;
|
|
28
|
+
/**
|
|
29
|
+
* Analyze a code file with optional associated documentation
|
|
30
|
+
*/
|
|
31
|
+
private analyzeCode;
|
|
32
|
+
/**
|
|
33
|
+
* Analyze a documentation file (.md, .txt)
|
|
34
|
+
*/
|
|
35
|
+
private analyzeDocumentation;
|
|
36
|
+
/**
|
|
37
|
+
* Check if file is a documentation file
|
|
38
|
+
*/
|
|
39
|
+
private isDocFile;
|
|
40
|
+
private getSourcesCombined;
|
|
41
|
+
private callLLM;
|
|
42
|
+
private writeNote;
|
|
43
|
+
}
|
|
44
|
+
//# sourceMappingURL=analyzer.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAoB,kBAAkB,EAAuB,cAAc,EAAE,MAAM,YAAY,CAAC;AAsI5G,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAEtC,IAAI,EAAE,mBAAmB;IAUrC;;OAEG;IACG,kBAAkB,CACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5D,OAAO,CAAC,cAAc,CAAC;IAqC1B;;OAEG;IACG,WAAW,CACb,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAC7D,OAAO,CAAC,kBAAkB,CAAC;IAS9B;;OAEG;YACW,WAAW;IA8FzB;;OAEG;YACW,oBAAoB;IAIlC;;OAEG;IACH,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,kBAAkB;YA2BZ,OAAO;YAgCP,SAAS;CAuB1B"}
|