@vpxa/kb 0.1.11 → 0.1.13

package/README.md

@@ -23,7 +23,7 @@ This is an **MCP (Model Context Protocol) server** that gives AI agents:
 8. **Graph auto-population** — during indexing, a lightweight regex extractor builds the knowledge graph automatically from TS/JS source files (functions, classes, interfaces, types, imports)
 9. **Optimized reindex** — full reindex skips redundant hash checks, batches graph writes (flush every 50 files), and skips per-file graph deletes when bulk-cleared
 
-The KB auto-indexes configured source directories on startup, stores embeddings in a local LanceDB vector store, and exposes everything through 64 MCP tools, 47 CLI commands, and 2 resources.
+The KB auto-indexes configured source directories on startup, stores embeddings in a local LanceDB vector store, and exposes everything through 64 MCP tools, 45 CLI commands, and 2 resources.
 
 ---
 
@@ -54,13 +54,12 @@ npx @vpxa/kb serve
 | Tool | CLI | Description |
 |------|-----|-------------|
 | `kb_search` | `kb search` | Hybrid vector + keyword search |
-| `kb_find` | `kb find` | Federated search (vector, FTS, glob, regex) |
+| `kb_find` | `kb find` | Federated search (vector, FTS, glob, regex). Use `mode: 'examples'` to find usage examples. |
 | `kb_symbol` | `kb symbol` | Resolve symbol definition, imports, references |
 | `kb_lookup` | `kb lookup` | Look up indexed chunks by file path |
 | `kb_trace` | `kb trace` | Forward/backward flow tracing |
-| `kb_find_examples` | `kb examples` | Find usage examples of a symbol |
 | `kb_scope_map` | `kb scope-map` | Generate task-scoped reading plan |
-| `kb_dead_symbols` | `kb dead-symbols` | Find unused exported symbols |
+| `kb_dead_symbols` | `kb dead-symbols` | Find unused exported symbols (source vs docs) |
 | `kb_file_summary` | `kb summarize` | Structural file overview |
 
 ### Code Analysis
@@ -70,14 +69,14 @@ npx @vpxa/kb serve
 | `kb_analyze_dependencies` | `kb analyze deps` | Dependency graph |
 | `kb_analyze_symbols` | `kb analyze symbols` | Symbol extraction |
 | `kb_analyze_patterns` | `kb analyze patterns` | Code pattern detection |
-| `kb_analyze_entry_points` | `kb analyze entry-points` | Entry point discovery |
+| `kb_analyze_entry_points` | `kb analyze entry-points` | Entry point discovery: handlers, CDK constructs, test suites, package exports (walks monorepo workspaces) |
 | `kb_analyze_diagram` | `kb analyze diagram` | Mermaid diagram generation |
 | `kb_blast_radius` | `kb analyze blast-radius` | Change impact analysis |
 
 ### Context Management
 | Tool | CLI | Description |
 |------|-----|-------------|
-| `kb_compact` | `kb compact` | Compress text to relevant sections |
+| `kb_compact` | `kb compact` | Compress text/file to relevant sections (accepts `path`) |
 | `kb_workset` | `kb workset` | Named file set management |
 | `kb_stash` | `kb stash` | Named key-value store |
 | `kb_checkpoint` | `kb checkpoint` | Session checkpoint save/restore |
@@ -104,9 +103,10 @@ npx @vpxa/kb serve
 | Tool | CLI | Description |
 |------|-----|-------------|
 | `kb_eval` | `kb eval` | Sandboxed JavaScript/TypeScript execution |
-| `kb_check` | `kb check` | Incremental typecheck + lint |
+| `kb_check` | `kb check` | Incremental typecheck + lint (`detail`: summary/errors/full) |
 | `kb_test_run` | `kb test` | Run tests with structured results |
 | `kb_batch` | `kb batch` | Parallel operation execution |
+| `kb_audit` | `kb audit` | Unified project audit: runs structure, deps, patterns, health, dead symbols, check, entry points in one call. Returns score, recommendations, and next steps. |
 
 ### Knowledge Management
 | Tool | CLI | Description |
@@ -158,14 +158,14 @@ npx @vpxa/kb serve
 ### System
 | Tool | CLI | Description |
 |------|-----|-------------|
-| `kb_status` | `kb status` | Index statistics |
+| `kb_status` | `kb status` | Index statistics + tree-sitter availability |
 | `kb_reindex` | `kb reindex` | Rebuild index |
-| `kb_health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, etc.) |
+| `kb_health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
+| `kb_guide` | `kb guide` | Tool discovery — given a goal, recommends tools and workflow order |
 | `kb_queue` | `kb queue` | Task queue for sequential agent operations |
 | `kb_graph` | `kb graph` | Query and manage the knowledge graph (8 actions: find_nodes, find_edges, neighbors, traverse, stats, add, delete, clear) |
 | `kb_onboard` | `kb onboard` | First-time codebase onboarding — runs all analysis tools in one command, auto-persists results |
-| `kb_replay_list` | `kb replay` | View audit trail of tool invocations |
-| `kb_replay_clear` | `kb replay-clear` | Clear the replay audit trail |
+| `kb_replay` | `kb replay` | View or clear the audit trail of tool invocations (action: list/clear) |
 
 ### TUI Dashboard
 
@@ -211,7 +211,7 @@ kb analyze <type> <path>
 kb lookup <path>
 
 # Context
-kb compact <query> [--max-chars N]
+kb compact <query> [--path <file>] [--max-chars N]
 kb workset <action> [name] [--files f1,f2]
 kb stash <action> [key] [value]
 kb checkpoint <action> [label]
@@ -226,7 +226,7 @@ kb transform <expression>
 # Execution
 kb eval <code> [--lang js|ts] [--timeout N]
 kb test [files...] [--grep pattern]
-kb check [--skip-types] [--skip-lint]
+kb check [--skip-types] [--skip-lint] [--detail summary|errors|full]
 kb batch
 
 # Knowledge
@@ -296,7 +296,7 @@ kb init [--force]
 │   ├── chunker/      — tree-sitter + regex code chunking
 │   ├── indexer/      — incremental file indexer
 │   ├── analyzers/    — blast-radius, deps, symbols, patterns, diagrams
-│   ├── tools/        — 49 tool modules (64 MCP tools)
+│   ├── tools/        — 52 tool modules (64 MCP tools)
 │   ├── server/       — MCP protocol server
 │   └── cli/          — command-line interface
 ├── bin/kb.mjs        — CLI entry point
@@ -466,7 +466,9 @@ Dependency results include a **confidence** level per import: `high` (ES static
 |-----------|------|----------|-------------|
 | `path` | string | **yes** | Root path |
 
-#### `kb_analyze_entry_points` — Find Lambda handlers, CLI bins, server starts
+#### `kb_analyze_entry_points` — Find Lambda handlers, CDK constructs, test suites, package exports
+
+Walks monorepo workspace packages (pnpm-workspace.yaml / package.json#workspaces), parses `exports` fields, detects CDK constructs and test suites.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -485,12 +487,13 @@ Dependency results include a **confidence** level per import: `high` (ES static
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `text` | string | **yes** | — | The text to compress |
+| `text` | string | no* | — | The text to compress (provide `text` or `path`) |
+| `path` | string | no* | — | File path to read server-side (avoids read_file round-trip) |
 | `query` | string | **yes** | — | Focus query — what are you trying to understand? |
 | `max_chars` | number (100–50000) | no | `3000` | Target output size in characters |
 | `segmentation` | enum | no | `paragraph` | How to split: `paragraph`, `sentence`, `line` |
 
-Uses embedding similarity (no LLM needed) to keep only the segments most relevant to the query. Returns compression stats (original → compressed chars, ratio, segments kept/total) and the compressed text.
+\* At least one of `text` or `path` must be provided. Using `path` is preferred — it eliminates the `read_file` → `compact` two-call chain and prevents token doubling.
 
 #### `kb_workset` — Manage named file sets
 
@@ -641,16 +644,6 @@ Returns a ranked file list with estimated token counts, relevance %, focus line
 
 Follows imports, call sites, and references to build a relationship graph from a starting symbol or file location.
 
-#### `kb_find_examples` — Find real usage examples
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | **yes** | — | Symbol or pattern to find examples of |
-| `limit` | number (1–20) | no | `5` | Maximum examples to return |
-| `content_type` | string | no | — | Filter by content type |
-
-Returns usage examples with file paths and code snippets from the indexed codebase.
-
 #### `kb_dead_symbols` — Find unused exported symbols
 
 | Parameter | Type | Required | Default | Description |
@@ -748,6 +741,18 @@ Returns structured pass/fail summary. `isError` set if any tests failed.
 
 Returns per-operation outcomes (success/failure with results or errors).
 
+#### `kb_audit` — Unified project audit
+
+Runs multiple analysis checks in a single call and returns a synthesized report with a composite score (0–100), per-check summaries, and prioritized recommendations.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | no | `.` | Root path to audit |
+| `checks` | string[] | no | all | Subset of checks: `structure`, `dependencies`, `patterns`, `health`, `dead_symbols`, `check`, `entry_points` |
+| `detail` | enum | no | `summary` | `summary` (markdown overview) or `full` (structured JSON data) |
+
+Returns `KBResponse<AuditData>` with `next[]` hints for follow-up actions.
+
 ### Git & Environment
 
 #### `kb_git_context` — Summarize Git repository state
@@ -931,13 +936,22 @@ Isolated file copies for parallel exploration. Create a lane, make changes, diff
 
 ### System
 
+#### `kb_guide` — Tool discovery
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `goal` | string | **yes** | — | What you want to accomplish |
+| `max_recommendations` | number | no | 5 | Max tools to recommend (1-10) |
+
+Given a goal description, recommends which KB tools to use and in what order. Matches against 10 predefined workflows: onboard, audit, bugfix, implement, refactor, search, context, memory, validate, analyze.
+
 #### `kb_health` — Run project health checks
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `path` | string | no | cwd | Root directory to check |
 
-Verifies package.json, tsconfig, scripts, lockfile, README, LICENSE, .gitignore.
+Verifies package.json, tsconfig, scripts, lockfile, README, LICENSE, .gitignore, circular dependencies.
 
 #### `kb_queue` — Manage task queues
 
@@ -952,21 +966,18 @@ Verifies package.json, tsconfig, scripts, lockfile, README, LICENSE, .gitignore.
 
 Sequential task queues for agent operations.
 
-#### `kb_replay_list` — View audit trail
+#### `kb_replay` — View or clear audit trail
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `last` | number | no | 20 | Number of entries to return |
-| `tool` | string | no | — | Filter by tool name (e.g., `kb_search`) |
-| `source` | enum | no | — | Filter by source: `mcp` or `cli` |
-| `since` | string | no | — | ISO timestamp — only show entries after this time |
+| `action` | enum | no | `list` | `list` to view entries, `clear` to wipe the log |
+| `last` | number | no | 20 | Number of entries to return (list only) |
+| `tool` | string | no | — | Filter by tool name (list only) |
+| `source` | enum | no | — | Filter by source: `mcp` or `cli` (list only) |
+| `since` | string | no | — | ISO timestamp — only show entries after this time (list only) |
 
 Shows the audit trail of recent tool invocations. Each entry includes tool name, duration, input/output summaries, and status. Useful for debugging agent behavior.
 
-#### `kb_replay_clear` — Clear audit trail
-
-No parameters. Clears the entire replay log.
-
 ---
 
 ## MCP Resources

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/kb",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/packages/analyzers/dist/entry-point-analyzer.d.ts

@@ -3,7 +3,25 @@ export declare class EntryPointAnalyzer implements IAnalyzer<AnalyzerOptions> {
     readonly name = "entry-points";
     analyze(rootPath: string, _options?: AnalyzerOptions): Promise<AnalysisResult>;
     private fromPackageJson;
+    /** Parse package.json `exports` field into entry points. */
+    private parseExportsField;
+    /** Resolve export value through condition maps (import > default > first string). */
+    private resolveExportValue;
+    /**
+     * Find all workspace package directories in a monorepo.
+     * Supports pnpm-workspace.yaml and package.json#workspaces.
+     */
+    private findWorkspacePackages;
+    /** Simple YAML parser for pnpm-workspace.yaml — extracts packages list. */
+    private parsePnpmWorkspaceYaml;
+    /**
+     * Expand a workspace glob like "packages/*" into actual directories
+     * that contain package.json files.
+     */
+    private expandWorkspaceGlob;
     private fromHandlerExports;
+    /** Check if a file is a test suite. */
+    private isTestFile;
     /** Extract a meaningful name from the file path for non-JS entry points */
     private inferNameFromFile;
     /**

package/packages/analyzers/dist/entry-point-analyzer.js

@@ -1,5 +1,6 @@
-import{access as f,readdir as m,readFile as g}from"node:fs/promises";import{extname as d,join as l,relative as h}from"node:path";const y=new Set(["node_modules",".git","dist","build","coverage",".turbo",".cache","cdk.out","__pycache__",".venv","target","bin","obj",".gradle","venv","env"]),S=new Set(["test","tests","__tests__","spec","specs","test-utils"]),E=[/export\s+const\s+(handler|main)\s*(?::[^=]*)?\s*=/,/export\s+(?:async\s+)?function\s+(handler|main)\s*\(/,/export\s+const\s+(\w+Handler)\s*(?::[^=]*)?\s*=/,/export\s+default\s+app/,/^app\s*=\s*(?:Flask|FastAPI)\s*\(/m,/^urlpatterns\s*=\s*\[/m,/^if\s+__name__\s*==\s*['"]__main__['"]:/m,/public\s+static\s+void\s+main\s*\(\s*String/,/@SpringBootApplication/,/^func\s+main\s*\(\s*\)/m],v=[{regex:/SqsEventSource|SQSEvent|sqs/i,trigger:"SQS"},{regex:/SnsEventSource|SNSEvent|sns/i,trigger:"SNS"},{regex:/ApiGateway|APIGatewayEvent|httpApi|restApi/i,trigger:"API Gateway"},{regex:/ScheduleExpression|EventBridgeRule|schedule/i,trigger:"EventBridge Schedule"},{regex:/S3EventSource|S3Event|s3/i,trigger:"S3"},{regex:/DynamoEventSource|DynamoDBStream/i,trigger:"DynamoDB Stream"},{regex:/@RequestMapping|@GetMapping|@PostMapping/i,trigger:"HTTP Endpoint"},{regex:/http\.ListenAndServe|gin\.Default|echo\.New/i,trigger:"HTTP Server"},{regex:/app\.route\(|@app\.get|@app\.post|@router\./i,trigger:"HTTP Route"}];class A{name="entry-points";async analyze(n,e={}){const r=Date.now(),t=[],s=await this.fromPackageJson(n);t.push(...s);const i=await this.fromHandlerExports(n);return t.push(...i),{output:this.formatMarkdown(t,n),data:{entryPoints:t,total:t.length},meta:{analyzedAt:new Date().toISOString(),scope:n,fileCount:t.length,durationMs:Date.now()-r}}}async fromPackageJson(n){const e=[];try{const r=l(n,"package.json");await f(r);const t=JSON.parse(await g(r,"utf-8"));if(t.main&&e.push({name:"main",type:"main",filePath:t.main}),t.bin){const s=typeof t.bin=="string"?{[t.name??"cli"]:t.bin}:t.bin;for(const[i,c]of Object.entries(s))e.push({name:i,type:"cli",filePath:c})}t.scripts?.start&&e.push({name:"start",type:"server",filePath:t.scripts.start,trigger:"npm start"})}catch{}return e}async fromHandlerExports(n){const e=[],r=await this.collectFiles(n);for(const t of r)try{const s=await g(t,"utf-8"),i=h(n,t).replace(/\\/g,"/");if(i.split("/").some(a=>S.has(a)))continue;for(const a of E){const o=s.match(a);if(o){let p=o[1]??this.inferNameFromFile(i);(p==="handler"||p==="main")&&(p=this.deriveContextualName(i)??p);const u=/@SpringBootApplication/.test(s)?"HTTP Server":this.detectTrigger(s);e.push({name:p,type:this.inferEntryType(o[1]??p,i),filePath:i,trigger:u});break}}}catch{}return e}inferNameFromFile(n){return(n.split(/[/\\]/).pop()??"default").replace(/\.\w+$/,"")}deriveContextualName(n){const e=n.split("/").filter(s=>s!=="src"&&s!=="lib");if(e.pop(),e.length===0)return;const r=e.filter(s=>!["services","functions","lambdas","handlers","packages","apps"].includes(s));if(r.length===0)return;const t=r.slice(-2);return t.length===2&&t[1].startsWith(t[0])?t[1]:t.join("-")}inferEntryType(n,e){return n==="handler"||n==="main"||e.includes("handler")||/functions[/]/.test(e)||n.endsWith("Handler")?"lambda-handler":(e.endsWith(".py")||e.endsWith(".go")||e.endsWith(".java"),"main")}detectTrigger(n){for(const e of v)if(e.regex.test(n))return e.trigger}async collectFiles(n){const e=[],r=new Set([".ts",".tsx",".js",".jsx",".java",".py",".go",".cs",".kt",".rb",".rs",".php",".swift"]),t=async(s,i)=>{if(i>10)return;const c=await m(s,{withFileTypes:!0});for(const a of c){if(y.has(a.name)||a.name.startsWith("."))continue;const o=l(s,a.name);a.isDirectory()?await t(o,i+1):r.has(d(a.name))&&e.push(o)}};return await t(n,0),e}formatMarkdown(n,e){const r=[];if(r.push(`## Entry Points: ${e}
-`),r.push(`**${n.length} entry ${n.length===1?"point":"points"}** found
-`),n.length===0)return r.push("No entry points detected."),r.join(`
-`);r.push("| Name | Type | File | Trigger |"),r.push("|------|------|------|---------|");for(const t of n)r.push(`| ${t.name} | ${t.type} | ${t.filePath} | ${t.trigger??"\u2014"} |`);return r.join(`
-`)}}export{A as EntryPointAnalyzer};
+import{access as f,readdir as h,readFile as u}from"node:fs/promises";import{extname as S,join as p,relative as d,resolve as y}from"node:path";const k=new Set(["node_modules",".git","dist","build","coverage",".turbo",".cache","cdk.out","__pycache__",".venv","target","bin","obj",".gradle","venv","env"]),w=new Set(["test","tests","__tests__","spec","specs","test-utils"]),v=[/export\s+const\s+(handler|main)\s*(?::[^=]*)?\s*=/,/export\s+(?:async\s+)?function\s+(handler|main)\s*\(/,/export\s+const\s+(\w+Handler)\s*(?::[^=]*)?\s*=/,/export\s+default\s+app/,/^app\s*=\s*(?:Flask|FastAPI)\s*\(/m,/^urlpatterns\s*=\s*\[/m,/^if\s+__name__\s*==\s*['"]__main__['"]:/m,/public\s+static\s+void\s+main\s*\(\s*String/,/@SpringBootApplication/,/^func\s+main\s*\(\s*\)/m],P=/export\s+(?:default\s+)?class\s+(\w+)\s+extends\s+(?:Construct|Stack|NestedStack|Stage)/,x=[/from\s+['"]vitest['"]/,/from\s+['"]jest['"]/,/from\s+['"]mocha['"]/,/import\s+.*['"]@jest\/globals['"]/,/require\s*\(\s*['"](?:vitest|jest|mocha)['"]\s*\)/],T=[{regex:/SqsEventSource|SQSEvent|sqs/i,trigger:"SQS"},{regex:/SnsEventSource|SNSEvent|sns/i,trigger:"SNS"},{regex:/ApiGateway|APIGatewayEvent|httpApi|restApi/i,trigger:"API Gateway"},{regex:/ScheduleExpression|EventBridgeRule|schedule/i,trigger:"EventBridge Schedule"},{regex:/S3EventSource|S3Event|s3/i,trigger:"S3"},{regex:/DynamoEventSource|DynamoDBStream/i,trigger:"DynamoDB Stream"},{regex:/@RequestMapping|@GetMapping|@PostMapping/i,trigger:"HTTP Endpoint"},{regex:/http\.ListenAndServe|gin\.Default|echo\.New/i,trigger:"HTTP Server"},{regex:/app\.route\(|@app\.get|@app\.post|@router\./i,trigger:"HTTP Route"}];class ${name="entry-points";async analyze(t,e={}){const s=Date.now(),n=[],i=await this.findWorkspacePackages(t);if(i.length>0)for(const a of i){const c=await this.fromPackageJson(a,t);n.push(...c)}else{const a=await this.fromPackageJson(t,t);n.push(...a)}const r=await this.fromHandlerExports(t);return n.push(...r),{output:this.formatMarkdown(n,t),data:{entryPoints:n,total:n.length},meta:{analyzedAt:new Date().toISOString(),scope:t,fileCount:n.length,durationMs:Date.now()-s}}}async fromPackageJson(t,e){const s=[],n=d(e,t).replace(/\\/g,"/")||".";try{const i=p(t,"package.json");await f(i);const r=JSON.parse(await u(i,"utf-8")),o=n==="."?"":`${n}/`;if(r.main&&s.push({name:r.name?`${r.name}:main`:"main",type:"main",filePath:`${o}${r.main}`}),r.bin){const a=typeof r.bin=="string"?{[r.name??"cli"]:r.bin}:r.bin;for(const[c,g]of Object.entries(a))s.push({name:c,type:"cli",filePath:`${o}${g}`})}if(r.exports){const a=this.parseExportsField(r.exports,r.name??n,o);s.push(...a)}r.scripts?.start&&s.push({name:r.name?`${r.name}:start`:"start",type:"server",filePath:r.scripts.start,trigger:"npm start"})}catch{}return s}parseExportsField(t,e,s){const n=[];if(typeof t=="string")return n.push({name:e,type:"main",filePath:`${s}${t}`}),n;if(typeof t!="object"||t===null)return n;for(const[i,r]of Object.entries(t)){if(!i.startsWith("."))continue;const o=i==="."?e:`${e}/${i.slice(2)}`,a=this.resolveExportValue(r);a&&n.push({name:o,type:"main",filePath:`${s}${a}`})}return n}resolveExportValue(t){if(typeof t=="string")return t;if(typeof t!="object"||t===null)return;const e=t;for(const s of["import","default","require"])if(typeof e[s]=="string")return e[s];for(const s of Object.values(e))if(typeof s=="string")return s}async findWorkspacePackages(t){const e=[];try{const s=p(t,"pnpm-workspace.yaml");await f(s);const n=await u(s,"utf-8"),i=this.parsePnpmWorkspaceYaml(n);for(const r of i){const o=await this.expandWorkspaceGlob(t,r);e.push(...o)}if(e.length>0)return e}catch{}try{const s=p(t,"package.json"),n=JSON.parse(await u(s,"utf-8")),i=Array.isArray(n.workspaces)?n.workspaces:n.workspaces?.packages??[];for(const r of i){const o=await this.expandWorkspaceGlob(t,r);e.push(...o)}}catch{}return e}parsePnpmWorkspaceYaml(t){const e=[];let s=!1;for(const n of t.split(`
+`)){const i=n.trim();if(i==="packages:"){s=!0;continue}if(s){if(i.startsWith("- "))e.push(i.slice(2).replace(/^['"]|['"]$/g,""));else if(i&&!i.startsWith("#"))break}}return e}async expandWorkspaceGlob(t,e){const s=[],n=e.indexOf("*");if(n===-1){const r=y(t,e);try{await f(p(r,"package.json")),s.push(r)}catch{}return s}const i=y(t,e.slice(0,n));try{const r=await h(i,{withFileTypes:!0});for(const o of r){if(!o.isDirectory()||k.has(o.name))continue;const a=p(i,o.name);try{await f(p(a,"package.json")),s.push(a)}catch{}}}catch{}return s}async fromHandlerExports(t){const e=[],s=await this.collectFiles(t);for(const n of s)try{const i=await u(n,"utf-8"),r=d(t,n).replace(/\\/g,"/");if(!r.split("/").some(c=>w.has(c))){let c=!1;for(const g of v){const m=i.match(g);if(m){let l=m[1]??this.inferNameFromFile(r);(l==="handler"||l==="main")&&(l=this.deriveContextualName(r)??l);const E=/@SpringBootApplication/.test(i)?"HTTP Server":this.detectTrigger(i);e.push({name:l,type:this.inferEntryType(m[1]??l,r),filePath:r,trigger:E}),c=!0;break}}if(!c){const g=i.match(P);g&&e.push({name:g[1],type:"cdk-construct",filePath:r,trigger:"CDK Construct"})}}this.isTestFile(r,i)&&e.push({name:this.inferNameFromFile(r),type:"test",filePath:r,trigger:"Test Suite"})}catch{}return e}isTestFile(t,e){return/\.(test|spec)\.[jt]sx?$/.test(t)?x.some(s=>s.test(e)):!1}inferNameFromFile(t){return(t.split(/[/\\]/).pop()??"default").replace(/\.\w+$/,"")}deriveContextualName(t){const e=t.split("/").filter(i=>i!=="src"&&i!=="lib");if(e.pop(),e.length===0)return;const s=e.filter(i=>!["services","functions","lambdas","handlers","packages","apps"].includes(i));if(s.length===0)return;const n=s.slice(-2);return n.length===2&&n[1].startsWith(n[0])?n[1]:n.join("-")}inferEntryType(t,e){return t==="handler"||t==="main"||e.includes("handler")||/functions[/]/.test(e)||t.endsWith("Handler")?"lambda-handler":(e.endsWith(".py")||e.endsWith(".go")||e.endsWith(".java"),"main")}detectTrigger(t){for(const e of T)if(e.regex.test(t))return e.trigger}async collectFiles(t){const e=[],s=new Set([".ts",".tsx",".js",".jsx",".java",".py",".go",".cs",".kt",".rb",".rs",".php",".swift"]),n=async(i,r)=>{if(r>10)return;const o=await h(i,{withFileTypes:!0});for(const a of o){if(k.has(a.name)||a.name.startsWith("."))continue;const c=p(i,a.name);a.isDirectory()?await n(c,r+1):s.has(S(a.name))&&e.push(c)}};return await n(t,0),e}formatMarkdown(t,e){const s=[];if(s.push(`## Entry Points: ${e}
+`),s.push(`**${t.length} entry ${t.length===1?"point":"points"}** found
+`),t.length===0)return s.push("No entry points detected."),s.join(`
+`);const n=new Map;for(const o of t){const a=n.get(o.type)??[];a.push(o),n.set(o.type,a)}const i=["lambda-handler","main","server","cli","bin","cdk-construct","test"],r=[...n.entries()].sort((o,a)=>i.indexOf(o[0])-i.indexOf(a[0]));s.push("| Name | Type | File | Trigger |"),s.push("|------|------|------|---------|");for(const[,o]of r)for(const a of o)s.push(`| ${a.name} | ${a.type} | ${a.filePath} | ${a.trigger??"\u2014"} |`);return s.join(`
+`)}}export{$ as EntryPointAnalyzer};

package/packages/analyzers/dist/pattern-analyzer.js

@@ -1,4 +1,4 @@
-import{access as P,readdir as h,readFile as C}from"node:fs/promises";import{extname as m,join as u,relative as S}from"node:path";const y=new Set(["node_modules",".git","dist","build","coverage",".turbo",".cache","cdk.out","__pycache__",".venv","target","bin","obj",".gradle","venv","env"]),v=[{dirs:["adapters","ports"],pattern:"Hexagonal Architecture",description:"Ports & adapters (hexagonal) separation"},{dirs:["domain","infrastructure","application"],pattern:"Clean Architecture",description:"Layered with domain/infrastructure separation"},{dirs:["controllers","models"],pattern:"MVC Pattern",description:"Model-View-Controller structure"},{dirs:["repositories"],pattern:"Repository Pattern",description:"Data access abstraction via repositories"},{dirs:["factories"],pattern:"Factory Pattern",description:"Object creation via factories"},{dirs:["handlers"],pattern:"Handler Pattern",description:"Event/request handler separation"},{dirs:["middleware"],pattern:"Middleware Pattern",description:"Request pipeline middleware"},{dirs:["hooks"],pattern:"React Hooks",description:"Custom React hooks for logic reuse"},{dirs:["components"],pattern:"Component Architecture",description:"UI component-based structure"},{dirs:["stacks","constructs"],pattern:"CDK IaC",description:"AWS CDK infrastructure as code"},{dirs:["lambdas","functions"],pattern:"Serverless",description:"Serverless function architecture"}];function A(g){if(g.length<=3)return g;const r=new Map;for(const e of g){const t=e.split("/"),n=t.length>1?t.slice(0,-1).join("/"):".",a=r.get(n);a?a.push(e):r.set(n,[e])}const o=[];for(const[e,t]of r)t.length>=3?o.push(`${e}/ (${t.length} files)`):o.push(...t);return o.slice(0,5)}const w=[{regex:/container\.register|@injectable|@inject/i,pattern:"Dependency Injection",description:"IoC container or DI decorators"},{regex:/\.pipe\(|Observable|BehaviorSubject/i,pattern:"Reactive (RxJS)",description:"Reactive programming with observables",lang:"js"},{regex:/createContext|useContext/i,pattern:"React Context",description:"React Context API for state sharing",lang:"js"},{regex:/createSlice|configureStore/i,pattern:"Redux Toolkit",description:"Redux state management",lang:"js"},{regex:/defineStore|usePinia/i,pattern:"Pinia Store",description:"Vue Pinia state management",lang:"js"},{regex:/\.(test|spec)\.[jt]sx?|describe\s*\(|\bit\s*\([\s'"]/i,pattern:"Test Suite",description:"Unit/integration test files"},{regex:/@SpringBootApplication|@EnableAutoConfiguration/,pattern:"Spring Boot",description:"Spring Boot application framework",lang:"java",definitive:!0},{regex:/@Autowired|@Component|@Service|@Repository|@Controller/,pattern:"Spring DI",description:"Spring dependency injection",lang:"java"},{regex:/@RestController|@RequestMapping|@GetMapping|@PostMapping/,pattern:"Spring REST",description:"Spring REST API controllers",lang:"java"},{regex:/app\s*=\s*Flask\s*\(|@app\.route/,pattern:"Flask",description:"Flask web framework",lang:"python"},{regex:/app\s*=\s*FastAPI\s*\(|@app\.get|@app\.post/,pattern:"FastAPI",description:"FastAPI web framework",lang:"python"},{regex:/func\s+main\s*\(\s*\)|http\.ListenAndServe/,pattern:"Go Application",description:"Go main application",lang:"go"}];class D{name="patterns";async analyze(r,o={}){const e=Date.now(),t=await this.collectDirectories(r),n=this.detectDirectoryPatterns(t,r),a=await this.collectCodeFiles(r),i=await this.detectCodePatterns(a,r),s=[...n,...i],c=await this.detectConfigPatterns(r),p=c.find(l=>l.pattern==="Maven"||l.pattern==="Gradle"||l.pattern==="Gradle (Kotlin DSL)"||l.pattern==="Node.js Project"||l.pattern==="Go Module"||l.pattern==="Rust (Cargo)"),f=new Set(["Ruby (Bundler)","PHP (Composer)","Swift Package","SBT"]);for(const l of c)p&&f.has(l.pattern)||s.push(l);return{output:this.formatMarkdown(s,r),data:{patterns:s,total:s.length},meta:{analyzedAt:new Date().toISOString(),scope:r,fileCount:a.length,durationMs:Date.now()-e}}}async collectDirectories(r){const o=[],e=async(t,n)=>{if(n>5)return;const a=await h(t,{withFileTypes:!0});for(const i of a){if(!i.isDirectory()||y.has(i.name)||i.name.startsWith("."))continue;const s=u(t,i.name);o.push(i.name),await e(s,n+1)}};return await e(r,0),o}async collectCodeFiles(r){const o=[],e=new Set([".ts",".tsx",".js",".jsx",".java",".py",".go",".cs",".kt",".scala",".rb",".rs",".php",".swift"]),t=async n=>{const a=await h(n,{withFileTypes:!0});for(const i of a){if(y.has(i.name)||i.name.startsWith("."))continue;const s=u(n,i.name);i.isDirectory()?await t(s):e.has(m(i.name))&&o.push(s)}};return await t(r),o}detectDirectoryPatterns(r,o){const e=new Set(r.map(n=>n.toLowerCase())),t=[];for(const n of v){const a=n.dirs.filter(i=>e.has(i));a.length!==0&&(n.dirs.length>1&&a.length<2||t.push({pattern:n.pattern,description:n.description,locations:a.map(i=>`${i}/`),confidence:a.length===n.dirs.length?"high":"medium"}))}return t}async detectCodePatterns(r,o){const e=[],t={},n=r.filter(s=>/Application\.\w+$|Main\.\w+$|app\.\w+$|main\.\w+$/i.test(s)||/Controller|Service|Handler|Router/i.test(s)),a=r.filter(s=>!n.includes(s)),i=[...n.slice(0,50),...a.slice(0,150)];for(const s of i)try{const c=await C(s,"utf-8"),p=m(s).toLowerCase(),f=p===".java"||p===".kt"||p===".scala"?"java":p===".py"?"python":p===".go"?"go":"js";for(const d of w)d.lang&&d.lang!==f||d.regex.test(c)&&(t[d.pattern]||(t[d.pattern]=new Set),t[d.pattern].add(S(o,s).replace(/\\/g,"/")))}catch{}for(const s of w){const c=t[s.pattern];if(c&&c.size>0){const p=A([...c]);e.push({pattern:s.pattern,description:s.description,locations:p,confidence:s.definitive||c.size>=3?"high":c.size>=2?"medium":"low"})}}return e}async detectConfigPatterns(r){const o=[],e=[{file:"Dockerfile",pattern:"Docker",description:"Containerized application"},{file:"docker-compose.yml",pattern:"Docker Compose",description:"Container orchestration"},{file:"cdk.json",pattern:"AWS CDK",description:"AWS CDK infrastructure as code"},{file:"terraform.tf",pattern:"Terraform",description:"Terraform IaC"},{file:"main.tf",pattern:"Terraform",description:"Terraform IaC"}];for(const t of e)try{await P(u(r,t.file)),o.push({pattern:t.pattern,description:t.description,locations:[t.file],confidence:"high"})}catch{}return o}formatMarkdown(r,o){const e=[];e.push(`## Patterns Detected: ${o}
+import{access as P,readdir as h,readFile as C}from"node:fs/promises";import{extname as m,join as f,relative as S}from"node:path";const w=new Set(["node_modules",".git","dist","build","coverage",".turbo",".cache","cdk.out","__pycache__",".venv","target","bin","obj",".gradle","venv","env"]),v=[{dirs:["adapters","ports"],pattern:"Hexagonal Architecture",description:"Ports & adapters (hexagonal) separation"},{dirs:["domain","infrastructure","application"],pattern:"Clean Architecture",description:"Layered with domain/infrastructure separation"},{dirs:["controllers","models"],pattern:"MVC Pattern",description:"Model-View-Controller structure"},{dirs:["repositories"],pattern:"Repository Pattern",description:"Data access abstraction via repositories"},{dirs:["factories"],pattern:"Factory Pattern",description:"Object creation via factories"},{dirs:["handlers"],pattern:"Handler Pattern",description:"Event/request handler separation"},{dirs:["middleware"],pattern:"Middleware Pattern",description:"Request pipeline middleware"},{dirs:["hooks"],pattern:"React Hooks",description:"Custom React hooks for logic reuse"},{dirs:["components"],pattern:"Component Architecture",description:"UI component-based structure"},{dirs:["stacks","constructs"],pattern:"CDK IaC",description:"AWS CDK infrastructure as code"},{dirs:["lambdas","functions"],pattern:"Serverless",description:"Serverless function architecture"}];function x(g){if(g.length<=3)return g;const r=new Map;for(const e of g){const t=e.split("/"),n=t.length>1?t.slice(0,-1).join("/"):".",a=r.get(n);a?a.push(e):r.set(n,[e])}const o=[];for(const[e,t]of r)t.length>=3?o.push(`${e}/ (${t.length} files)`):o.push(...t);return o.slice(0,5)}const y=[{regex:/container\.register|@injectable|@inject/i,pattern:"Dependency Injection",description:"IoC container or DI decorators"},{regex:/\.pipe\(|Observable|BehaviorSubject/i,pattern:"Reactive (RxJS)",description:"Reactive programming with observables",lang:"js"},{regex:/createContext|useContext/i,pattern:"React Context",description:"React Context API for state sharing",lang:"js"},{regex:/createSlice|configureStore/i,pattern:"Redux Toolkit",description:"Redux state management",lang:"js"},{regex:/defineStore|usePinia/i,pattern:"Pinia Store",description:"Vue Pinia state management",lang:"js"},{regex:/\.(test|spec)\.[jt]sx?|describe\s*\(|\bit\s*\([\s'"]/i,pattern:"Test Suite",description:"Unit/integration test files"},{regex:/@SpringBootApplication|@EnableAutoConfiguration/,pattern:"Spring Boot",description:"Spring Boot application framework",lang:"java",definitive:!0},{regex:/@Autowired|@Component|@Service|@Repository|@Controller/,pattern:"Spring DI",description:"Spring dependency injection",lang:"java"},{regex:/@RestController|@RequestMapping|@GetMapping|@PostMapping/,pattern:"Spring REST",description:"Spring REST API controllers",lang:"java"},{regex:/app\s*=\s*Flask\s*\(|@app\.route/,pattern:"Flask",description:"Flask web framework",lang:"python"},{regex:/app\s*=\s*FastAPI\s*\(|@app\.get|@app\.post/,pattern:"FastAPI",description:"FastAPI web framework",lang:"python"},{regex:/func\s+main\s*\(\s*\)|http\.ListenAndServe/,pattern:"Go Application",description:"Go main application",lang:"go"},{regex:/export\s+(?:async\s+)?function\s+create[A-Z]\w+/,pattern:"Factory",description:"Object creation via create*() functions",lang:"js"},{regex:/(?:export\s+)?function\s+wrap[A-Z]\w+/,pattern:"Wrapper/Decorator",description:"Higher-order function wrapping",lang:"js"},{regex:/(?:const|let)\s+\w+\s*=\s*new\s+(?:Map|WeakMap)\s*[<(]/,pattern:"Singleton Cache",description:"Module-level cache with lazy initialization",lang:"js"},{regex:/Record<string,\s*(?:\w+)?Handler>|\.(?:get|post|put|delete)\s*\(/,pattern:"Router/Dispatcher",description:"Request routing/dispatch table",lang:"js"},{regex:/export\s+(?:default\s+)?class\s+\w+\s+extends\s+(?:Construct|Stack|NestedStack|Stage)/,pattern:"CDK Construct",description:"AWS CDK infrastructure construct",lang:"js",definitive:!0}];class D{name="patterns";async analyze(r,o={}){const e=Date.now(),t=await this.collectDirectories(r),n=this.detectDirectoryPatterns(t,r),a=await this.collectCodeFiles(r),i=await this.detectCodePatterns(a,r),s=[...n,...i],c=await this.detectConfigPatterns(r),p=c.find(l=>l.pattern==="Maven"||l.pattern==="Gradle"||l.pattern==="Gradle (Kotlin DSL)"||l.pattern==="Node.js Project"||l.pattern==="Go Module"||l.pattern==="Rust (Cargo)"),u=new Set(["Ruby (Bundler)","PHP (Composer)","Swift Package","SBT"]);for(const l of c)p&&u.has(l.pattern)||s.push(l);return{output:this.formatMarkdown(s,r),data:{patterns:s,total:s.length},meta:{analyzedAt:new Date().toISOString(),scope:r,fileCount:a.length,durationMs:Date.now()-e}}}async collectDirectories(r){const o=[],e=async(t,n)=>{if(n>5)return;const a=await h(t,{withFileTypes:!0});for(const i of a){if(!i.isDirectory()||w.has(i.name)||i.name.startsWith("."))continue;const s=f(t,i.name);o.push(i.name),await e(s,n+1)}};return await e(r,0),o}async collectCodeFiles(r){const o=[],e=new Set([".ts",".tsx",".js",".jsx",".java",".py",".go",".cs",".kt",".scala",".rb",".rs",".php",".swift"]),t=async n=>{const a=await h(n,{withFileTypes:!0});for(const i of a){if(w.has(i.name)||i.name.startsWith("."))continue;const s=f(n,i.name);i.isDirectory()?await t(s):e.has(m(i.name))&&o.push(s)}};return await t(r),o}detectDirectoryPatterns(r,o){const e=new Set(r.map(n=>n.toLowerCase())),t=[];for(const n of v){const a=n.dirs.filter(i=>e.has(i));a.length!==0&&(n.dirs.length>1&&a.length<2||t.push({pattern:n.pattern,description:n.description,locations:a.map(i=>`${i}/`),confidence:a.length===n.dirs.length?"high":"medium"}))}return t}async detectCodePatterns(r,o){const e=[],t={},n=r.filter(s=>/Application\.\w+$|Main\.\w+$|app\.\w+$|main\.\w+$/i.test(s)||/Controller|Service|Handler|Router/i.test(s)),a=r.filter(s=>!n.includes(s)),i=[...n.slice(0,50),...a.slice(0,150)];for(const s of i)try{const c=await C(s,"utf-8"),p=m(s).toLowerCase(),u=p===".java"||p===".kt"||p===".scala"?"java":p===".py"?"python":p===".go"?"go":"js";for(const d of y)d.lang&&d.lang!==u||d.regex.test(c)&&(t[d.pattern]||(t[d.pattern]=new Set),t[d.pattern].add(S(o,s).replace(/\\/g,"/")))}catch{}for(const s of y){const c=t[s.pattern];if(c&&c.size>0){const p=x([...c]);e.push({pattern:s.pattern,description:s.description,locations:p,confidence:s.definitive||c.size>=3?"high":c.size>=2?"medium":"low"})}}return e}async detectConfigPatterns(r){const o=[],e=[{file:"Dockerfile",pattern:"Docker",description:"Containerized application"},{file:"docker-compose.yml",pattern:"Docker Compose",description:"Container orchestration"},{file:"cdk.json",pattern:"AWS CDK",description:"AWS CDK infrastructure as code"},{file:"terraform.tf",pattern:"Terraform",description:"Terraform IaC"},{file:"main.tf",pattern:"Terraform",description:"Terraform IaC"}];for(const t of e)try{await P(f(r,t.file)),o.push({pattern:t.pattern,description:t.description,locations:[t.file],confidence:"high"})}catch{}return o}formatMarkdown(r,o){const e=[];e.push(`## Patterns Detected: ${o}
 `),e.push(`**${r.length} patterns** found
 `);const t={high:[],medium:[],low:[]};for(const n of r)t[n.confidence].push(n);for(const[n,a]of Object.entries(t))if(a.length!==0){e.push(`### ${n.charAt(0).toUpperCase()+n.slice(1)} Confidence
 `);for(const i of a)e.push(`- **${i.pattern}**: ${i.description}`),e.push(`  Locations: ${i.locations.slice(0,5).join(", ")}`);e.push("")}return e.join(`

package/packages/analyzers/dist/types.d.ts

@@ -78,7 +78,7 @@ export interface PatternMatch {
 }
 export interface EntryPoint {
     name: string;
-    type: 'lambda-handler' | 'main' | 'bin' | 'server' | 'cli';
+    type: 'lambda-handler' | 'main' | 'bin' | 'server' | 'cli' | 'test' | 'cdk-construct';
     filePath: string;
     trigger?: string;
 }

package/packages/cli/dist/commands/init.d.ts

@@ -1,7 +1,8 @@
 /**
  * `kb init` — scaffold a knowledge base in the current directory.
  * Creates kb.config.json, .gitignore entry, optional IDE config,
- * and agent instruction files (.github/copilot-instructions.md, AGENTS.md).
+ * agent instruction files (.github/copilot-instructions.md, AGENTS.md),
+ * and skills/knowledge-base/SKILL.md.
  */
 export declare function initProject(options: {
     force: boolean;