@ctxo/cli 0.0.1 → 0.7.0-alpha.0

package/llms-full.txt

@@ -0,0 +1,284 @@
+# Ctxo MCP Server — Full Reference
+
+> AI agents don't fail because they can't code. They fail because they code blind. Ctxo gives them the full picture before they write a single line.
+> npm: @ctxo/cli (v0.7.0-alpha.0) | GitHub: https://github.com/alperhankendi/Ctxo
+
+## Setup
+
+```bash
+npx @ctxo/cli init            # Detect languages + install plugins + wire MCP
+npx @ctxo/cli index           # Build codebase index (required once)
+npx @ctxo/cli index --check   # CI gate: fail if index stale
+npx @ctxo/cli                 # Start MCP server (stdio transport)
+```
+
+MCP client configuration:
+```json
+{ "mcpServers": { "ctxo": { "command": "npx", "args": ["-y", "@ctxo/cli"] } } }
+```
+
+---
+
+## Monorepo & Plugin Architecture (v0.7+)
+
+Ctxo is a pnpm workspace monorepo with five packages:
+
+- `@ctxo/cli` (packages/cli) — CLI entry, composition root, MCP server, tool handlers
+- `@ctxo/plugin-api` (packages/plugin-api) — `CtxoLanguagePlugin` v1 protocol interface
+- `@ctxo/lang-typescript` — ts-morph (full tier) plugin for TS/JS
+- `@ctxo/lang-go` — tree-sitter / gopls plugin for Go
+- `@ctxo/lang-csharp` — Roslyn plugin for C#
+
+Plugin protocol v1 (`CtxoLanguagePlugin`):
+- `apiVersion: 1`
+- `id`: unique plugin identifier
+- `extensions`: file extensions handled (e.g. `['.ts', '.tsx']`)
+- `tier`: `'syntax'` | `'full'`
+- `createAdapter(ctx)`: factory returning an `ILanguageAdapter` instance
+
+Discovery: at startup Ctxo scans the project's `package.json` dependencies for names matching `@ctxo/lang-*` or `ctxo-lang-*` and registers them. `ctxo install` adds plugins; `ctxo index --install-missing` auto-installs plugins required by detected languages. New CLI: `ctxo doctor --fix`, `ctxo version`, and `ctxo --version --verbose|--json` for plugin/runtime diagnostics.
+
+Source paths referenced below live under `packages/cli/src/`.
+
+---
+
+## Tool Reference (14 tools)
+
+### get_logic_slice
+Retrieve a symbol and all its transitive dependencies.
+
+Parameters:
+- symbolId (string, optional): Symbol ID (format: file::name::kind)
+- symbolIds (string[], optional): Batch: array of symbol IDs
+- level (number 1-4, default 3): L1=signature, L2=direct deps, L3=full closure, L4=with token budget
+- intent (string, optional): Filter dependencies by keyword
+
+When to use: Understanding what a symbol depends on (downstream view).
+Instead of: get_blast_radius (upstream/impact), get_context_for_task (task-specific).
+
+### get_blast_radius
+Find all symbols that would break if a target changes.
+
+Parameters:
+- symbolId (string, required): Symbol ID
+- confidence (enum: confirmed|likely|potential, optional): Filter by tier
+- intent (string, optional): Filter by keyword
+
+Returns: impactedSymbols array with symbolId, depth, riskScore, confidence, edgeKinds.
+3-tier model: confirmed (calls/extends/implements), likely (uses/co-changed), potential (imports-only).
+
+When to use: BEFORE modifying any function or class.
+Instead of: get_logic_slice (forward deps), get_pr_impact (PR-level).
+
+### get_architectural_overlay
+Get project architectural layer map.
+
+Parameters:
+- layer (string, optional): Filter by layer name
+
+Returns: Symbols grouped into Domain, Infrastructure, Adapter, Test, Composition, Configuration layers.
+
+When to use: Onboarding to a new codebase, validating layer boundaries.
+
+### get_why_context
+Retrieve git commit history and anti-pattern warnings for a symbol.
+
+Parameters:
+- symbolId (string, required): Symbol ID
+- maxCommits (number, optional): Limit to N most recent commits
+
+Returns: commitHistory array + antiPatternWarnings (reverts, rollbacks, undo patterns).
+
+When to use: Understanding WHY code was written this way, checking for problem history.
+Pair with: get_change_intelligence (complexity/churn scores).
+
+### get_change_intelligence
+Retrieve complexity x churn composite score.
+
+Parameters:
+- symbolId (string, required): Symbol ID
+
+Returns: complexity (0-1), churn (0-1), composite (0-1), band (low|medium|high|critical).
+
+When to use: Identifying refactoring targets, assessing modification risk.
+
+### find_dead_code
+Find unreachable symbols and files.
+
+Parameters:
+- includeTests (boolean, default false): Include test files
+- intent (string, optional): Filter results by keyword
+
+Returns: deadSymbols (with confidence 1.0/0.9/0.7 and reason), deadFiles, unusedExports, scaffolding markers.
+
+When to use: Cleanup, refactoring, confirming code is truly unused.
+Instead of: find_importers (specific symbol reverse lookup).
+
+### get_context_for_task
+Get task-optimized context for a symbol.
+
+Parameters:
+- symbolId (string, required): Symbol ID
+- taskType (enum: fix|extend|refactor|understand, required): Determines context mix
+- tokenBudget (number, default 4000): Max tokens
+
+Task types:
+- fix: History + anti-patterns + direct deps (bug investigation)
+- extend: Deps + blast radius + interfaces (adding features)
+- refactor: Importers + complexity + churn (restructuring)
+- understand: Full slice + architecture (learning)
+
+When to use: BEST starting point when you know the symbol AND your intent.
+
+### get_ranked_context
+Search and rank symbols by relevance to a query.
+
+Parameters:
+- query (string, required): Natural language search query
+- tokenBudget (number, default 4000): Max tokens for results
+- strategy (enum: combined|dependency|importance, default combined): Ranking strategy
+
+Returns: Symbols ranked by BM25 relevance + PageRank importance, packed within budget.
+
+When to use: Have a question/topic but don't know which symbol to look at.
+Instead of: search_symbols (exact name/regex search).
+
+### search_symbols
+Search symbols by name or regex pattern.
+
+Parameters:
+- pattern (string, required): Substring or regex pattern
+- kind (enum: function|class|interface|method|variable|type, optional): Filter by kind
+- filePattern (string, optional): Filter by file path substring
+- limit (number 1-100, default 25): Max results
+
+When to use: Know (part of) the symbol name, need its ID for other tools.
+Instead of: get_ranked_context (semantic/relevance search).
+
+### get_changed_symbols
+Get symbols in recently changed files.
+
+Parameters:
+- since (string, default HEAD~1): Git ref to diff against
+- maxFiles (number, default 50): Max files to process
+
+When to use: See what was modified in recent commits.
+Instead of: get_pr_impact (full PR risk assessment).
+
+### find_importers
+Find all symbols that depend on a given symbol (reverse dependency).
+
+Parameters:
+- symbolId (string, required): Symbol ID
+- edgeKinds (string[], optional): Filter by imports|calls|extends|implements|uses
+- transitive (boolean, default false): Follow transitive reverse edges
+- maxDepth (number 1-10, default 5): Max BFS depth
+- intent (string, optional): Filter by keyword
+
+When to use: Check if safe to modify/delete, find all consumers.
+Instead of: get_blast_radius (aggregated impact with risk scores).
+
+### get_class_hierarchy
+Get class inheritance hierarchy.
+
+Parameters:
+- symbolId (string, optional): Root symbol (omit for full project)
+- direction (enum: ancestors|descendants|both, default both): Traversal direction
+
+When to use: OOP code, understanding type relationships before modifying base class/interface.
+
+### get_symbol_importance
+Rank symbols by PageRank centrality.
+
+Parameters:
+- limit (number 1-200, default 25): Max results
+- kind (enum: function|class|interface|method|variable|type, optional): Filter
+- filePattern (string, optional): Filter by file path
+- damping (number 0-1, default 0.85): PageRank damping factor
+
+When to use: Identify most critical symbols, high-risk modification targets.
+Instead of: find_dead_code (unused/unimportant code).
+
+### get_pr_impact
+Analyze PR impact in a single call.
+
+Parameters:
+- since (string, default HEAD~1): Git ref to diff against
+- maxFiles (number, default 50): Max files
+- confidence (enum: confirmed|likely|potential, optional): Filter tier
+
+Returns: changedFiles, changedSymbols, totalImpact, riskLevel (low|medium|high), per-file blast radius, co-change data.
+
+When to use: FIRST tool when reviewing a PR or evaluating recent commits.
+
+---
+
+## Tool Selection Guide
+
+```
+Reviewing a PR or recent changes?
+  -> get_pr_impact (single call, full risk assessment)
+
+About to modify a function or class?
+  -> get_blast_radius (what breaks if I change this?)
+  -> then get_why_context (any history of problems?)
+
+Need to understand what a symbol does?
+  -> get_context_for_task(taskType: "understand")
+  -> or get_logic_slice (L2 for overview, L3 for full closure)
+
+Fixing a bug?
+  -> get_context_for_task(taskType: "fix")
+
+Adding a feature / extending code?
+  -> get_context_for_task(taskType: "extend")
+
+Refactoring?
+  -> get_context_for_task(taskType: "refactor")
+
+Don't know the symbol name?
+  -> search_symbols (by name/regex)
+  -> get_ranked_context (by natural language query)
+
+Onboarding to a new codebase?
+  -> get_architectural_overlay (layer map)
+  -> get_symbol_importance (most critical symbols)
+
+Cleaning up code?
+  -> find_dead_code (unused symbols)
+  -> get_change_intelligence (complexity hotspots)
+
+Checking if safe to delete/rename?
+  -> find_importers (who depends on this?)
+  -> get_blast_radius (full impact)
+
+Working with class hierarchies?
+  -> get_class_hierarchy (extends/implements tree)
+```
+
+---
+
+## Cross-Cutting Features
+
+### Response Envelope (_meta)
+All tool responses include:
+```json
+{ "_meta": { "totalItems": 50, "returnedItems": 25, "truncated": true, "totalBytes": 12400, "hint": "Use search_symbols to narrow results." } }
+```
+- Default truncation threshold: 8KB
+- Configurable via CTXO_RESPONSE_LIMIT environment variable
+
+### Intent Filtering
+4 tools accept `intent` parameter: get_blast_radius, get_logic_slice, find_importers, find_dead_code.
+- Keywords extracted from intent string, matched case-insensitively against symbolId, file, name, kind, edgeKind, reason
+- Multiple keywords use OR logic
+- No intent = full results (backward compatible)
+
+### Symbol ID Format
+All symbols use deterministic IDs: `"<relativePath>::<name>::<kind>"`
+- Example: `"src/core/graph/symbol-graph.ts::SymbolGraph::class"`
+- Valid kinds: function, class, interface, method, variable, type
+- Valid edge kinds: imports, calls, extends, implements, uses
+
+### Resources
+- `ctxo://status` — Health check resource (confirms server is running)

package/llms.txt

@@ -0,0 +1,72 @@
+# Ctxo MCP Server
+
+> AI agents don't fail because they can't code. They fail because they code blind. Ctxo gives them the full picture before they write a single line.
+
+Ctxo is a Model Context Protocol (MCP) server that gives AI agents structured context about codebases: symbol graphs, blast radius, architectural overlays, change intelligence, dead code detection, and PR impact analysis.
+
+## Quick Start
+
+```
+npx @ctxo/cli init     # Detect languages, install plugins, wire MCP
+npx @ctxo/cli index    # Build codebase index
+npx @ctxo/cli          # Start MCP server (stdio)
+```
+
+## Package Layout (v0.7.0-alpha.0, pnpm monorepo)
+
+- `@ctxo/cli` — CLI + MCP server (formerly `ctxo-mcp`)
+- `@ctxo/plugin-api` — `CtxoLanguagePlugin` v1 interface (apiVersion, id, extensions, tier, createAdapter)
+- `@ctxo/lang-typescript` — ts-morph full-tier plugin
+- `@ctxo/lang-go` — tree-sitter / gopls plugin
+- `@ctxo/lang-csharp` — Roslyn plugin
+
+Language adapters ship as separate npm packages and are discovered by scanning the project `package.json` for `@ctxo/lang-*` or `ctxo-lang-*` dependencies.
+
+## 14 Tools
+
+- get_logic_slice: Symbol + transitive dependencies (L1-L4 detail levels)
+- get_blast_radius: What breaks if a symbol changes (3-tier: confirmed/likely/potential)
+- get_architectural_overlay: Project layer map (Domain/Infrastructure/Adapter)
+- get_why_context: Git commit intent + anti-pattern warnings (reverts, rollbacks)
+- get_change_intelligence: Complexity x churn composite score
+- find_dead_code: Unreachable symbols and files
+- get_context_for_task: Task-optimized context (fix/extend/refactor/understand)
+- get_ranked_context: BM25 + PageRank search within token budget
+- search_symbols: Symbol name/regex search across index
+- get_changed_symbols: Symbols in recently changed files (git diff)
+- find_importers: Reverse dependency lookup ("who uses this?")
+- get_class_hierarchy: Class inheritance tree (ancestors + descendants)
+- get_symbol_importance: PageRank centrality ranking
+- get_pr_impact: Full PR risk assessment in a single call
+
+## Tool Selection Guide
+
+- Reviewing a PR? -> get_pr_impact
+- About to modify code? -> get_blast_radius
+- Understanding a symbol? -> get_context_for_task(taskType: "understand")
+- Fixing a bug? -> get_context_for_task(taskType: "fix")
+- Refactoring? -> get_context_for_task(taskType: "refactor")
+- Don't know the symbol name? -> search_symbols or get_ranked_context
+- Finding unused code? -> find_dead_code
+- Safe to delete? -> find_importers
+
+## New in v0.7
+
+- `ctxo install` — install language plugin packages
+- `ctxo init` — project-aware language detection + plugin wiring
+- `ctxo index --install-missing` — auto-install missing plugins during index
+- `ctxo doctor --fix` — repair common issues
+- `ctxo version` subcommand; `ctxo --version --verbose|--json` for plugin/runtime details
+
+## Key Concepts
+
+- Symbol ID format: "file::name::kind" (e.g., "src/foo.ts::myFn::function")
+- All responses include _meta: { totalItems, returnedItems, truncated, totalBytes }
+- 4 tools support intent filtering: get_blast_radius, get_logic_slice, find_importers, find_dead_code
+- Large responses auto-truncated at 8KB (configurable via CTXO_RESPONSE_LIMIT)
+
+## Links
+
+- npm: https://www.npmjs.com/package/@ctxo/cli
+- GitHub: https://github.com/alperhankendi/Ctxo
+- Full reference: llms-full.txt

package/package.json

@@ -1,13 +1,65 @@
-{
-  "name": "@ctxo/cli",
-  "version": "0.0.1",
-  "description": "Reserved for v0.7.0 release — Ctxo CLI + MCP server",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/alperhankendi/Ctxo.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@ctxo/cli",
+  "version": "0.7.0-alpha.0",
+  "description": "MCP server delivering dependency-aware, history-enriched context for codebases",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "ctxo": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "pages/visualize-template.html",
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "mcp",
+    "context",
+    "ai",
+    "coding-assistant",
+    "dependency-graph"
+  ],
+  "author": "Alper Hankendi",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chokidar": "^5.0.0",
+    "picocolors": "^1.1.1",
+    "simple-git": "^3.27.0",
+    "sql.js": "^1.14.1",
+    "zod": "^4.3.6",
+    "@ctxo/plugin-api": "0.7.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "^3.1.3",
+    "eslint": "^9.26.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^3.1.3",
+    "@ctxo/lang-go": "0.7.0-alpha.0",
+    "@ctxo/lang-csharp": "0.7.0-alpha.0",
+    "@ctxo/lang-typescript": "0.7.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run --config vitest.config.unit.ts",
+    "test:unit:coverage": "vitest run --config vitest.config.unit.ts --coverage",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}