Repo-Ramp

# RepoRamp MCP RepoRamp is a deterministic, local repository-onboarding assistant for Codex. It inventories an unfamiliar repository, finds evidence for its structure and operating commands, and produces a reviewable overview, setup plan, open questions, and Mermaid diagrams. RepoRamp supports Python, Node.js, and a generic fallback. It does not execute commands found in a repository, call a model, or contact a remote service. Repository text is always treated as untrusted data. The full product rationale is in the [product requirements document](docs/RepoRamp_MCP_Product_Requirements_Document.docx). ## What it produces An explicitly exported scan contains: ```text REPO_OVERVIEW.md SETUP_PLAN.md OPEN_QUESTIONS.md evidence.json diagrams/ workflow.mmd dependencies.mmd ``` Material claims carry stable evidence IDs. Findings include source paths and line or manifest-field references, confidence, conflicts, and command risk flags. RepoRamp intentionally does not generate or run a `setup.sh` in P0. A frozen, test-verified Orbit Tasks bundle is available in [`examples/sample-output`](examples/sample-output) for review without running a scan. ## Requirements - Python 3.11 or newer - Node.js 20 or newer and npm only for the optional Mermaid syntax check - Codex CLI only when using RepoRamp as an MCP server ## Install From a clean checkout: ```bash python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e . ``` For development, install the test extra instead: ```bash python -m pip install -e '.[test]' ``` Confirm the entry point is available: ```bash reporamp --help ``` ## CLI usage Scan a repository. On an interactive terminal, RepoRamp shows a colored onboarding map with stage progress, ranked files, commands, and terminal-native workflow and dependency previews: ```bash reporamp scan ./orbit_tasks_sample_repo ``` When stdout is redirected, the same command automatically emits the existing deterministic Markdown instead. This keeps pipes and saved reports clean. Output can also be selected explicitly: ```bash # Polished terminal view, even when auto-detection is unavailable reporamp scan ./orbit_tasks_sample_repo --format terminal # Terminal preview plus the canonical Mermaid source reporamp scan ./orbit_tasks_sample_repo --format terminal --diagrams both # ASCII structure with no color or motion reporamp scan ./orbit_tasks_sample_repo --plain # Stable Markdown for a file or another program reporamp scan ./orbit_tasks_sample_repo --format markdown ``` The progress animation is written only to an interactive stderr and can be disabled with `--no-motion`. `NO_COLOR`, `TERM=dumb`, `CI`, and `REPORAMP_REDUCE_MOTION=1` are respected; `--color always|never` provides an explicit override. Ordinary terminals cannot render Mermaid graphics directly. RepoRamp therefore provides a terminal-native preview for people and keeps Mermaid source canonical for tools. The `diagram` subcommand exposes either form: ```bash reporamp diagram ./orbit_tasks_sample_repo --view workflow --format terminal reporamp diagram ./orbit_tasks_sample_repo --view dependencies --format mermaid ``` Print the complete structured scan as JSON: ```bash reporamp scan ./orbit_tasks_sample_repo --format json ``` Add repeatable gitignore-style exclusions: ```bash reporamp scan ./orbit_tasks_sample_repo \ --exclude 'data/' \ --exclude '*.generated.py' ``` No files are written unless `--output` is present. A relative output directory is resolved from the scanned repository root, and the resolved destination must remain inside that repository: ```bash reporamp scan ./orbit_tasks_sample_repo \ --output reporamp-output ``` The export command prints a JSON manifest. It fails if a managed artifact already exists; pass `--overwrite` to replace RepoRamp-managed files while preserving unrelated files: ```bash reporamp scan ./orbit_tasks_sample_repo \ --output reporamp-output \ --overwrite ``` Diagnostics go to stderr in Markdown, JSON, and export modes, and appear in the terminal view's scan-notes section. Complete and partial scans exit `0`, path and policy errors exit `2`, and unexpected failures exit `1`. ## Register the local MCP server with Codex RepoRamp uses the official MCP Python SDK over STDIO. Register the virtual-environment executable so Codex launches the same installation every time. Run this from the RepoRamp checkout: ```bash codex mcp add reporamp -- \ "$PWD/.venv/bin/reporamp" mcp \ --allowed-root "$PWD" ``` `--allowed-root` is the boundary for both repository scans and artifact exports. Set it to the narrowest directory containing the repositories you intend to analyze. If omitted when launching the server directly, it defaults to the server's working directory. Verify the registration: ```bash codex mcp list ``` Then ask Codex, for example: > Use RepoRamp to scan `orbit_tasks_sample_repo`. Show me the overview, setup plan, and both diagrams. Explain conflicts and risky commands, but do not execute any repository command. Do not export files until I approve the destination. To change the allowed root, remove and re-add the registration: ```bash codex mcp remove reporamp codex mcp add reporamp -- \ "/absolute/path/to/reporamp/.venv/bin/reporamp" mcp \ --allowed-root "/absolute/path/to/repositories" ``` ### MCP interface The server retains the eight most recently completed scans in memory. Start with `scan_repository`; pass its `scan_id` to the remaining tools: - `scan_repository(repo_path, exclude=[])` - `get_repository_overview(scan_id)` - `get_setup_plan(scan_id)` - `get_diagrams(scan_id, views=["workflow", "dependencies"])` - `get_evidence(scan_id, claim_id=None, kind=None, cursor=None, limit=50)` - `export_artifacts(scan_id, output_dir, overwrite=False)` The same results are exposed as MCP resources: ```text repo://scan/{scan_id}/overview repo://scan/{scan_id}/setup repo://scan/{scan_id}/evidence repo://scan/{scan_id}/unknowns repo://scan/{scan_id}/diagram/{view} ``` An evicted or unknown scan ID returns `SCAN_NOT_FOUND`; run `scan_repository` again. Server state is never persisted implicitly. ## Validate generated Mermaid The Python package does not require Node.js. Maintainers can use the official Mermaid parser to validate exported `.mmd` files or source produced by `reporamp diagram --format mermaid`: ```bash npm ci npm run validate:mermaid -- \ ./examples/sample-output/diagrams/workflow.mmd \ ./examples/sample-output/diagrams/dependencies.mmd ``` The validation harness supplies Mermaid's required DOM APIs with a local JSDOM instance; it does not launch a browser or render repository HTML. The committed lockfile makes this maintainer-only toolchain reproducible across local and CI installs. See [TESTING.md](TESTING.md) for the complete verification workflow and [DEMO.md](DEMO.md) for a five-minute walkthrough. ## Safety and analysis boundaries RepoRamp applies these rules before synthesis: - canonicalize the approved root and reject path escape; - never follow symlinks, and report links that resolve outside the root; - honor `.gitignore`, user exclusions, and built-in dependency/build/cache exclusions; - skip binary content and secret files such as `.env`; - redact secret-like values and keep excerpts bounded; - enforce file-count, file-size, total-text, depth, relationship, and diagram limits; - parse manifests and source without importing or executing repository code; - flag privileged, destructive, deployment, migration, credential, pipe-to-shell, and network-dependent commands; and - preserve conflicting commands as unresolved evidence instead of silently choosing one. A partial scan is useful but not complete. Consult its coverage and diagnostics before relying on it. ## Implementation architecture The diagram below maps the current Python modules rather than a future product concept. Both interfaces call the same analyzer, so CLI and MCP scans use the same inventory rules, detectors, evidence model, and renderers. ```mermaid flowchart LR REPO["Target repository<br/>untrusted, read-only input"] USER["Terminal user"] CODEX["Codex"] subgraph PROCESS["Local RepoRamp process - no model calls or repository command execution"] subgraph INTERFACES["Interfaces"] CLI["CLI<br/>cli.py"] MCP["STDIO MCP server<br/>mcp_server.py"] end subgraph CORE["Shared analysis core"] ANALYZER["Analyzer orchestration<br/>analyzer.py"] POLICY["Path and secret policy<br/>policy.py"] INVENTORY["Bounded file inventory<br/>inventory.py"] DETECTORS["Generic, Python, and Node detectors<br/>detectors.py"] RESULT["Typed ScanResult<br/>models.py"] end STORE["MCP ScanStore<br/>8-result in-memory LRU"] RENDERERS["Markdown, JSON, and Mermaid renderers<br/>renderers.py"] EXPORTER["Atomic explicit exporter<br/>exporter.py"] end RESPONSES["CLI output or MCP tools/resources"] BUNDLE["Six-file artifact bundle"] USER --> CLI CODEX --> MCP CLI --> ANALYZER MCP --> ANALYZER ANALYZER --> POLICY POLICY --> INVENTORY REPO --> INVENTORY INVENTORY --> DETECTORS DETECTORS --> ANALYZER ANALYZER --> RESULT RESULT -->|"CLI path"| RENDERERS RESULT -->|"MCP path"| STORE STORE -->|"follow-up by scan_id"| RENDERERS RENDERERS --> RESPONSES RESULT -->|"CLI --output"| EXPORTER STORE -->|"MCP export_artifacts"| EXPORTER EXPORTER --> RENDERERS EXPORTER --> BUNDLE ``` The MCP store is only a convenience for follow-up calls. It holds the eight most recently used `ScanResult` objects in memory and does not create a hidden database or implicit files. The CLI uses the same result directly and normally prints it without retaining state. ## Scan and export flow This sequence shows what happens during a scan and why obtaining information is separate from writing files. The export block runs only when the CLI receives `--output` or the MCP client explicitly calls `export_artifacts`. ```mermaid sequenceDiagram actor U as User or Codex participant I as CLI or MCP interface participant A as Analyzer participant P as Path policy participant V as Inventory participant D as Detectors participant S as MCP ScanStore participant R as Renderers participant E as Exporter U->>I: Request scan with path and exclusions I->>A: scan(...) A->>P: Canonicalize path and enforce MCP allowed root P-->>A: Existing approved directory A->>V: Inventory eligible files within limits V-->>A: Files, directories, coverage, diagnostics A->>D: Run generic, Python, and Node detection D-->>A: Findings, relationships, diagnostics A->>A: Merge findings, mark conflicts, reconcile edges, compute scan_id alt MCP request A-->>I: ScanResult I->>S: Store result by scan_id I-->>U: Return ScanSummary and scan_id U->>I: Request overview, setup, diagrams, or evidence I->>S: Load result by scan_id S-->>I: ScanResult else CLI request A-->>I: ScanResult end I->>R: Render requested Markdown, JSON, or Mermaid R-->>I: Rendered content I-->>U: Show result for human review opt Explicit export requested I->>E: export_artifacts(result, output directory) E->>P: Validate child path and symlink boundaries E->>R: Render the six managed artifacts E-->>I: ExportManifest with paths and SHA-256 hashes I-->>U: Report written files end ``` The two control points are deliberate: policy checks happen before repository content is read, and export-path checks happen before artifacts are written. Repository instructions remain data throughout the flow; RepoRamp parses them but never executes them. This is the evidence-bounded hybrid described by the PRD: RepoRamp performs predictable local analysis, while the existing Codex session can organize and explain the returned evidence. RepoRamp itself needs no API key or separate login. ## Development Run the Python suite: ```bash pytest ``` Run the slower generated-repository benchmark explicitly: ```bash pytest -m performance ``` Repository fixtures cover the Orbit Tasks Python sample, a synthetic Node workspace, and an adversarial repository with conflicting instructions, malformed configuration, secret-like data, a binary, and a path-escaping symlink. Development and testing details are in [TESTING.md](TESTING.md). The role and limits of AI assistance are recorded in [AI_USAGE.md](AI_USAGE.md). ## Success criteria P0 is successful when all three fixtures produce the complete six-file artifact bundle; every rendered material claim resolves to evidence; expected entry points and commands are detected; secret values and files outside the approved root never appear; no repository command is executed; CLI and MCP results agree; and both Mermaid diagrams parse successfully.