claude-toolstack-cli 1.0.0__py3-none-any.whl

claude_toolstack_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: claude-toolstack-cli
+Version: 1.0.0
+Summary: CLI client for Claude Toolstack gateway
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.24; extra == "semantic"
+Requires-Dist: sentence-transformers>=2.2; extra == "semantic"
+Dynamic: license-file
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-toolstack/readme.png" width="400" alt="Claude ToolStack">
+</p>
+
+<p align="center">
+  Docker + Claude Code workstation config for 64-GB Linux hosts.<br>
+  cgroup v2 slices &bull; Compose tool farm &bull; FastAPI gateway &bull; no thrash.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/claude-toolstack-cli/"><img src="https://img.shields.io/pypi/v/claude-toolstack-cli" alt="PyPI"></a>
+  <a href="https://github.com/mcp-tool-shop-org/claude-toolstack/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/claude-toolstack/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/mcp-tool-shop-org/claude-toolstack"><img src="https://codecov.io/gh/mcp-tool-shop-org/claude-toolstack/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/mcp-tool-shop-org/claude-toolstack/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-toolstack/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+---
+
+## What This Is
+
+A ready-to-deploy stack that keeps Claude Code productive on large, multi-language repositories without thrashing a 64-GB Linux workstation.
+
+**Core idea:** don't load the repo into Claude. Keep durable indexes near the code in resource-governed containers. Stream only the smallest necessary evidence back to Claude through a thin HTTP gateway.
+
+## Architecture
+
+```
+64-GB Linux host (Ubuntu 22.04 / Fedora 38)
+├── systemd slices (cgroup v2 governance)
+│   ├── claude-gw.slice      — gateway + socket proxy
+│   ├── claude-index.slice   — indexing + search
+│   ├── claude-lsp.slice     — language servers
+│   ├── claude-build.slice   — build/test runners
+│   └── claude-vector.slice  — vector DB (optional)
+├── Docker Compose stack
+│   ├── gateway         — FastAPI, 6 endpoints, 127.0.0.1:8088
+│   ├── dockerproxy     — socket proxy (exec-only model)
+│   ├── toolstack       — cts CLI inside the stack (cli profile)
+│   ├── ctags           — universal-ctags indexer
+│   └── build           — generic build runner
+└── Claude Code / Claude Desktop
+    └── calls gateway → gets bounded evidence
+```
+
+## Quick Start
+
+### 1. Bootstrap the host
+
+```bash
+sudo ./scripts/bootstrap.sh
+```
+
+This installs:
+- zram swap (Ubuntu) or verifies swap-on-zram (Fedora)
+- Sysctl tuning (swappiness, inotify watches)
+- systemd slices with MemoryHigh/Max governance
+- Docker daemon config (local log driver)
+- claude-toolstack.service (boot management)
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+# Edit .env: set API_KEY, ALLOWED_REPOS, etc.
+```
+
+### 3. Clone repos
+
+```bash
+# Repos go under /workspace/repos/<org>/<repo>
+git clone https://github.com/myorg/myrepo /workspace/repos/myorg/myrepo
+```
+
+### 4. Start the stack
+
+```bash
+docker compose up -d --build
+```
+
+### 5. Verify
+
+```bash
+./scripts/smoke-test.sh "$API_KEY" myorg/myrepo
+./scripts/health.sh
+```
+
+## Gateway API
+
+All endpoints require `x-api-key` header. Gateway binds to `127.0.0.1:8088` only.
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| `GET` | `/v1/status` | Health + config |
+| `POST` | `/v1/search/rg` | Ripgrep with guardrails |
+| `POST` | `/v1/file/slice` | Fetch file range (max 800 lines) |
+| `POST` | `/v1/index/ctags` | Build ctags index (async) |
+| `POST` | `/v1/symbol/ctags` | Query symbol definitions |
+| `POST` | `/v1/run/job` | Run allowlisted test/build/lint |
+| `GET` | `/v1/metrics` | Prometheus-format counters |
+
+All responses include `X-Request-ID` for end-to-end correlation. Clients can send their own via the `X-Request-ID` header.
+
+## CLI (`cts`)
+
+A zero-dependency Python CLI that wraps all gateway endpoints.
+
+### Install
+
+```bash
+pip install -e .
+# or: pipx install -e .
+```
+
+### Configure
+
+```bash
+export CLAUDE_TOOLSTACK_API_KEY=<your-key>
+export CLAUDE_TOOLSTACK_URL=http://127.0.0.1:8088  # default
+```
+
+### Usage
+
+```bash
+# Gateway health
+cts status
+
+# Search (text output)
+cts search "PaymentService" --repo myorg/myrepo --max 50
+
+# Search (evidence bundle for Claude — auto-fetches context slices)
+cts search "PaymentService" --repo myorg/myrepo --format claude
+
+# File slice
+cts slice --repo myorg/myrepo src/main.ts:120-180
+
+# Symbol lookup
+cts symbol PaymentService --repo myorg/myrepo
+
+# Run tests
+cts job test --repo myorg/myrepo --preset node
+
+# Stack diagnostics
+cts doctor
+cts doctor --format json
+
+# Performance knobs
+cts perf
+cts perf --format json
+
+# Semantic search (default-on when store exists)
+cts semantic index --repo myorg/myrepo --root /workspace/repos/myorg/myrepo
+cts semantic search "what does auth do?" --repo myorg/myrepo
+
+# All commands support: --format json|text|claude --request-id <id> --debug
+```
+
+### Evidence Bundles v2 (`--format claude`)
+
+The `--claude` output mode produces compact, paste-ready evidence packs with structured v2 headers. Four bundle modes are available:
+
+| Mode | Flag | What it does |
+|------|------|-------------|
+| `default` | `--bundle default` | Search + ranked matches + context slices |
+| `error` | `--bundle error` | Stack-trace-aware: extracts files from trace, boosts in ranking |
+| `symbol` | `--bundle symbol` | Definitions + call sites from search |
+| `change` | `--bundle change` | Git diff + hunk context slices |
+
+```bash
+# Default bundle (search + slices)
+cts search "PaymentService" --repo myorg/myrepo --format claude
+
+# Error bundle (pass stack trace for trace-aware ranking)
+cts search "ConnectionError" --repo myorg/myrepo --format claude \
+  --bundle error --error-text "$(cat /tmp/traceback.txt)"
+
+# Symbol bundle (definitions + call sites)
+cts symbol PaymentService --repo myorg/myrepo --format claude --bundle symbol
+
+# Path preferences (boost src, demote vendor)
+cts search "handler" --repo myorg/myrepo --format claude \
+  --prefer-paths src,core --avoid-paths vendor,test
+
+# Git recency scoring (requires local repo access)
+cts search "handler" --repo myorg/myrepo --format claude \
+  --repo-root /workspace/repos/myorg/myrepo
+```
+
+Tuning: `--evidence-files 5` (files to slice), `--context 30` (lines around hit).
+
+### curl examples
+
+```bash
+# Search
+curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
+  -d '{"repo":"myorg/myrepo","query":"PaymentService","max_matches":50}' \
+  http://127.0.0.1:8088/v1/search/rg | jq
+
+# File slice
+curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
+  -d '{"repo":"myorg/myrepo","path":"src/main.ts","start":120,"end":160}' \
+  http://127.0.0.1:8088/v1/file/slice | jq
+
+# Run tests
+curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
+  -d '{"repo":"myorg/myrepo","job":"test","preset":"node"}' \
+  http://127.0.0.1:8088/v1/run/job | jq
+```
+
+## Resource Governance
+
+systemd slices enforce MemoryHigh (throttle) and MemoryMax (hard cap) per service group:
+
+| Slice | MemoryHigh | MemoryMax | Purpose |
+|-------|-----------|-----------|---------|
+| `claude-gw` | 2 GB | 4 GB | Gateway + socket proxy |
+| `claude-index` | 6 GB | 10 GB | Indexers, search |
+| `claude-lsp` | 8 GB | 16 GB | Language servers |
+| `claude-build` | 10 GB | 18 GB | Build/test runners |
+| `claude-vector` | 8 GB | 16 GB | Vector DB (optional) |
+
+These are medium-repo defaults. Edit the slice files in `systemd/` for your workload.
+
+OS + headroom: 10-14 GB always reserved for filesystem cache, desktop, SSH.
+
+## Security
+
+### Threat Model
+
+**What we protect against:**
+- Gateway abuse (unauthorized access, resource exhaustion)
+- Path traversal (escaping repo root via `../` or symlinks)
+- Docker socket escalation (raw socket = root-equivalent)
+- Output flooding (unbounded search/build results consuming memory)
+
+**Security layers:**
+
+| Layer | Mechanism |
+|-------|-----------|
+| Auth | API key (`x-api-key` header), configurable |
+| Network | Gateway binds `127.0.0.1` only |
+| Docker | Socket proxy (Tecnativa), only `CONTAINERS+EXEC` |
+| Repos | Allowlist/denylist with glob support |
+| Paths | `realpath` jail, null byte rejection |
+| Commands | Preset allowlist only, no arbitrary exec |
+| Output | 512 KB cap, line truncation |
+| Rate limit | Token bucket per key+ip |
+| Audit | JSONL log, key hashed, rotated |
+| Containers | Named allowlist, no wildcards |
+| Resources | cgroup v2 slices, per-container mem/cpu limits |
+
+### What the gateway cannot do
+
+- Execute arbitrary commands (preset allowlist only)
+- Access repos outside `/workspace/repos` (path jail)
+- Touch Docker images, volumes, networks, or system (proxy blocks)
+- Return unbounded output (512 KB hard cap)
+- Accept connections from non-localhost (bind address)
+- Collect or send telemetry — **no telemetry, no phone-home, no analytics**
+
+## Directory Structure
+
+```
+claude-toolstack/
+├── compose.yaml           # Docker Compose stack (exec-only model)
+├── .env.example           # Configuration template
+├── pyproject.toml         # CLI packaging (cts)
+├── repos.yaml             # Declarative repo registry
+├── cts/                   # CLI client (zero deps for core)
+│   ├── cli.py             # argparse commands (doctor, perf, search, ...)
+│   ├── errors.py          # Structured error shape (CtsError)
+│   ├── http.py            # gateway HTTP client
+│   ├── render.py          # json/text/claude renderers (v1+v2)
+│   ├── bundle.py          # v2 bundle orchestrator (4 modes)
+│   ├── ranking.py         # path scoring, trace extraction, recency
+│   ├── config.py          # env + defaults
+│   └── semantic/          # Embedding-based search (optional dep)
+│       ├── store.py       # SQLite vector store
+│       ├── search.py      # cosine similarity + narrowing
+│       ├── candidates.py  # candidate selection strategies
+│       └── config.py      # semantic knobs
+├── tests/                 # 890+ unit tests (pytest)
+├── gateway/
+│   ├── main.py            # FastAPI gateway
+│   ├── Dockerfile         # python:3.12-slim + ripgrep + tini
+│   └── requirements.txt   # 6 dependencies
+├── nginx/
+│   └── gateway.conf       # Reverse proxy (optional)
+├── systemd/
+│   ├── claude-gw.slice    # gateway + dockerproxy (2G/4G)
+│   ├── claude-index.slice # indexers + search (6G/10G)
+│   ├── claude-lsp.slice   # language servers (8G/16G)
+│   ├── claude-build.slice # build/test runners (10G/18G)
+│   ├── claude-vector.slice
+│   ├── claude-toolstack.service
+│   └── ...                # zram, sysctl, daemon.json
+├── scripts/
+│   ├── bootstrap.sh       # Host setup (run once)
+│   ├── verify.sh          # All quality gates in one command
+│   ├── cts-docker         # Run cts inside Docker stack
+│   ├── smoke-test.sh      # Validation suite
+│   └── ...                # health, add-repo, policy-lint, triage
+└── docs/
+    └── tuning.md          # Slice tuning guide
+```
+
+## Claude Code Integration
+
+### Local Linux
+
+Claude Code runs directly on the host. Configure gateway as an MCP server or call it via HTTP from task scripts.
+
+### Remote (macOS/Windows)
+
+Use Claude Desktop's Code tab with an SSH environment pointing to your Linux host. The tool farm runs on the host; the GUI stays on your laptop.
+
+## Tuning
+
+See [docs/tuning.md](docs/tuning.md) for:
+- Slice sizing by repo size (small/medium/large)
+- PSI monitoring and thrash detection
+- Adding language servers (clangd, rust-analyzer, tsserver)
+- Vector store options (SQLite+FAISS, Weaviate, Milvus)
+- Job preset customization
+
+## No-Thrash Validation
+
+After deployment, confirm:
+
+1. **PSI full near zero**: `watch -n 1 'cat /proc/pressure/memory'`
+2. **Containers hit MemoryHigh before Max**: check slice status
+3. **SSH stays responsive**: during indexing and builds
+4. **Containment works**: shrink one service's limit, run heavy task, confirm only that container dies
+
+---
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

claude_toolstack_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+claude_toolstack_cli-1.0.0.dist-info/licenses/LICENSE,sha256=Nn5RQeT1iE5XkcQCHzOp-qlYhApd7PROGyc6h6rRxFk,1070
+cts/__init__.py,sha256=GCqJ3UPKTraIwSad0uav4IoxKVC_vFLurNhJlpzZPDA,66
+cts/__main__.py,sha256=HZ4lHY34h9rwTwkiLtHEE9p_uT1uywdCM1jPO3jHWeg,68
+cts/autopilot.py,sha256=1_7HOEqGR_NzZwvKwzx0TQuZ1R6Ye3iRTl6-oXIVX1E,22426
+cts/bundle.py,sha256=FuUCO2kQVkVxl3X7ma-cp23s3jLFHn4v5e6aPts0x_Q,30046
+cts/cli.py,sha256=-ohmSIqujgzWL8ak59Pvp6E8QMLytmDa4OuPzqsGiek,85664
+cts/confidence.py,sha256=GoIc04Mu5GTwAOdEPMnOwQyis_ej6L-inYrugxNzp3U,6896
+cts/config.py,sha256=C9t4unA50ngSb_5efFLbU4N9-caJtMsFl4lUJw0aTQs,458
+cts/ctags.py,sha256=hywk74AwBPckMLpIOb1qJtAEqrs26yEhhpBmWs1PNJU,3727
+cts/diff_context.py,sha256=h4XRVPQcd1Grn7lNbwrBQDhM8TO_sy0eGMq0JQPAqro,2857
+cts/errors.py,sha256=qKcQ53sUITV6wJp7PfX8GRErin8A4JFnjU_jetSREuk,3360
+cts/http.py,sha256=XWYx2vox1KffMa43khVNVxFhy9PuMjf28cJNwKjBzvc,2635
+cts/ranking.py,sha256=cKQNsiK7LiDO3fFUNZslQfH6sJBQLJ4PgNPdkSJBSHY,15116
+cts/render.py,sha256=bU9fRG8Hy36WO7vW7IYz8MITOkuy6ImMm-fDUD1Z3To,12856
+cts/schema.py,sha256=MLEwy3zawxB-d5Eb3iwfZXxeIgxBEg1c6y75RDL7KJQ,3026
+cts/sidecar.py,sha256=qn05Ohqnm2AZdOv7eRscJba6Yi5a_Pf2nSOH7-xfO9I,13215
+cts/structural.py,sha256=8ar0YAEEBguHV0mDkGFkFBbNu7bYBXNJtjDeXNqQ0cM,9323
+cts/corpus/__init__.py,sha256=uHjXBLLQythYL4ecjL-nJ0FRvcYjYKMaTnyHI-e1dH4,3396
+cts/corpus/apply.py,sha256=XpO-1vV-tRntDR4Ofdw38XhJqlJvqKu32EBnZIiaW1E,8300
+cts/corpus/archive.py,sha256=yorK9Fz5Lz8GSeXthpMFPOb_GqGYI4WlJl4LZQQgH2Q,10243
+cts/corpus/baseline.py,sha256=UfYTSFRG7yn1p2Z8jmZxubwpJ0Jk14NlprBDfqmSfbU,9300
+cts/corpus/evaluate.py,sha256=T9mRRFhc2uUQQIpa_AUjS-TWGEn3osaE3xXxkTxW30g,12448
+cts/corpus/experiment_eval.py,sha256=kIqfbObPjnTmajZDbaq3ANsUNdP0r5-31KR46wduvOI,19114
+cts/corpus/experiment_schema.py,sha256=CyENfPY1CnOGYsxaDEYQfu-RBjDXZRl9oR_G9K0b8nY,11563
+cts/corpus/extract.py,sha256=vICtB005ujhEAujQay1nKqJu7S5mXy04o2lCjzIba7k,11782
+cts/corpus/load.py,sha256=PA61299IHPCnaMZetbcQRW6X76fyrStZc2ZmycAWUy0,1275
+cts/corpus/model.py,sha256=TKxvy08ha2Rf9WoK7k8GQ3GgHdmWLslQs1aeZ7arQIk,4056
+cts/corpus/patch.py,sha256=7ko-dF66yc67AqSHSOOHacKlcoR9QPI_fli1eSgjZEo,14629
+cts/corpus/registry.py,sha256=PcER8wQNMEvJz7VzFK7sqrH1-6ZMq3bIHhryXp7N_TM,12934
+cts/corpus/report.py,sha256=AkQwjV4kWncnIG53M0uDIomqD-T2Vf4CwfLfp6XfKck,25264
+cts/corpus/scan.py,sha256=2P3Jkyip9NyDepjbwFdZhtDcVLUppBHcq3HVGQFKemg,2180
+cts/corpus/store.py,sha256=IMA8M4Ubxzi7gAwG5zAAThG3z5PF6HZpUmkmtvEtB9U,1628
+cts/corpus/trends.py,sha256=uE1G3AyqYW-YQfpy7pC0YdXvcVZ-_jkM3IWk4oUPAYU,15167
+cts/corpus/tuning_schema.py,sha256=JBpQvAYTxjbd_mIcjDl0EZ-SLo3Cvj4tjP2myzOmN3E,11424
+cts/corpus/variants.py,sha256=4zLLvPg-B0nsGON0yQquQnkC4xT4pki32MH_8BM0SDs,10978
+cts/semantic/__init__.py,sha256=4emR8Nbtaftkxh1766h7CcDF2d1xq_owsOGPJE-BOhg,1192
+cts/semantic/candidates.py,sha256=rJPvz2_WeGOW6Cxc0AkHyz93PPVOlWG0YRq_3ADLw3w,4669
+cts/semantic/chunker.py,sha256=zzD4oDhruP5NWYdL6OmCLygMAKMiZ7vZ1eJxOxEpWJ8,4916
+cts/semantic/config.py,sha256=lq-7DqCNkD6iGyceLdlQ5nGqveFVaSmUfdHmtISc6Hw,3787
+cts/semantic/embedder.py,sha256=OMMzYNpp1gc0MKGDknEbFFTE4p7pSdvjaYAp2WbjSUU,4244
+cts/semantic/indexer.py,sha256=xC6Ikb4kqNCSby2KWHmnQtfdnTkd9LrzGuINag-oMtY,4851
+cts/semantic/search.py,sha256=x8aNTazqTdb4U_MRgQc3Z44KF1BDqbBoIdtfUPiJeOc,7292
+cts/semantic/store.py,sha256=vUmwNQYO8XUomMFjmDZ_gAPjibMGlsGQJPLvoDf62PY,11447
+claude_toolstack_cli-1.0.0.dist-info/METADATA,sha256=KW3l8EhygkOmLqOxI-P80Se4o2-7bfVQtbllBNSQ3TQ,12982
+claude_toolstack_cli-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+claude_toolstack_cli-1.0.0.dist-info/entry_points.txt,sha256=YxPfSezwExk8iQSvoVlxnvx1t-_ii0qebTLGN5Lproo,37
+claude_toolstack_cli-1.0.0.dist-info/top_level.txt,sha256=6--EY7lQD9tGcXclwS9ak-nTbzpVqTfhpSBBjCudeIk,4
+claude_toolstack_cli-1.0.0.dist-info/RECORD,,

claude_toolstack_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claude_toolstack_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cts = cts.cli:main

claude_toolstack_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_toolstack_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cts

cts/__init__.py

@@ -0,0 +1,3 @@
+"""cts — Claude Toolstack CLI client."""
+
+__version__ = "1.0.0"

cts/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point: python -m cts."""
+
+from cts.cli import main
+
+main()