Metadata-Version: 2.4
Name: sin-code-bundle
Version: 0.9.2
Summary: Structural intelligence for AI coding agents: impact analysis, semantic diff, architectural-debt breaker, and an independent verification Oracle — over MCP.
Author: OpenSIN-Code
License: Apache-2.0
Project-URL: Homepage, https://github.com/OpenSIN-Code/SIN-Code-Bundle
Project-URL: Issues, https://github.com/OpenSIN-Code/SIN-Code-Bundle/issues
Keywords: mcp,ai-agents,coding-agent,opencode,codex,lsp,swe-bench
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Provides-Extra: lsp
Requires-Dist: multilspy>=0.0.10; extra == "lsp"
Requires-Dist: tree-sitter>=0.23; extra == "lsp"
Requires-Dist: tree-sitter-python>=0.23; extra == "lsp"
Requires-Dist: tree-sitter-javascript>=0.23; extra == "lsp"
Requires-Dist: tree-sitter-typescript>=0.23; extra == "lsp"
Requires-Dist: tree-sitter-go>=0.23; extra == "lsp"
Provides-Extra: bench
Requires-Dist: datasets>=2.19; extra == "bench"
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.2; extra == "mcp"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.25; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.25; extra == "otel"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Provides-Extra: all
Requires-Dist: sin-code-bundle[bench,dev,lsp,mcp,otel]; extra == "all"
Dynamic: license-file

# 🧠 SIN-Code Bundle

[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![CI](https://img.shields.io/badge/CI-A%2B%20(100%2F100)-brightgreen)](#)
[![Version](https://img.shields.io/badge/Version-0.8.1-blue)](#)

**The universal semantic backend for AI coding agents.**

One CLI (`sin`) and one unified MCP server (`sin-serve` / `sin serve`) that
orchestrate **8 Python subsystems, 7 Go tools, and 5 external bridges** — giving
AI agents the signals they actually lack: structural knowledge, semantic diffs,
correctness proofs, ephemeral test environments, debt guardrails, and
persistent memory.

---

## ⚡ Why SIN-Code? (The Anti-Dreck Promise)

Most coding agents operate blind — fragile string replacements, blind bash
execution, no memory between sessions. SIN-Code replaces native agent tools
with semantically aware, verifiable alternatives.

| The Old Way (Dreck) | The SIN-Code Way |
|---|---|
| ❌ Fragile `str_replace` (whitespace errors, stale files) | ✅ `sin_edit`: Hashline-anchored, content-hash verified patching (line-shift resilient) |
| ❌ Blind `read` (dumps 2000 lines of context) | ✅ `sin_read`: Deep structural analysis OR semantic URIs (`sckg://module/auth/neighbors`) — size-safe with summarize mode |
| ❌ Dangerous `bash` (secret leaks, infinite loops) | ✅ `sin_bash`: Secret-redaction + strict timeouts + structured JSON (safety_check, retry_info) |
| ❌ Stateless amnesia (forgets user prefs every session) | ✅ `recall_tool`/`remember_tool`: Persistent 4-tier memory (SQLite+FTS5) via [sin-brain](https://github.com/OpenSIN-Code/SIN-Brain) |
| ❌ Architectural drift (agents spaghetti-fy the code) | ✅ `sin_check_architecture`: Pre-flight ADW rule enforcement — blocks hardcoded secrets, eval/exec, frontend-DB imports |
| ❌ Sequential exploration (one slow task at a time) | ✅ `sin_create_worktree`: Isolated git worktrees for parallel agent tasks without conflicts |
| ❌ Static analysis only (no runtime insight) | ✅ `sin_runtime_trace`: DAP debug session attachment (debugpy/dlv/node) |

---

## 🚀 Quickstart (2-5 minutes)

```bash
git clone https://github.com/OpenSIN-Code/SIN-Code-Bundle.git
cd SIN-Code-Bundle
bash install.sh        # Bootstraps 7 Go tools + Python bundle + MCP config + 5 external bridges
sin status            # Show what's installed
sin bootstrap /path/to/your/repo   # Initialize graphs, baselines, ledgers
sin-serve             # Start the unified MCP server (or: sin serve)
```

Pair commands (symmetric to `install.sh`):

```bash
bash uninstall.sh     # Remove everything bash install.sh installed
bash update.sh        # Update in-place without full reinstall
```

Flags: `--help`, `--dry-run`, `--verbose`, `--force`, `--skip-go`, `--skip-external`, `--with-externals`

`--with-externals` upgrades the install from "check only" to actually
auto-installing the external bridges: GitNexus (npm), MarkItDown (pipx/pip),
RTK (brew), and Simone-MCP (npm in `~/dev/Simone-MCP`). Without this flag,
those tools are only verified/registered — the user must run `sin xxx setup`
manually for each one.

Environment overrides:
```bash
SIN_CODE_BIN_DIR=~/custom-bin SIN_CODE_REPOS_DIR=~/my-repos bash install.sh
SIN_CODE_BIN_DIR=~/custom-bin bash install.sh --with-externals
```

### Publishing to PyPI (one-time setup)

The `release.yml` workflow uses **PyPI Trusted Publishing** (no API tokens, no
manual uploads). To enable it for the first time, the maintainer must
register the publisher once.

**Recommended (non-interactive, API token):**

```bash
# 1. Generate a PyPI API token at https://pypi.org/manage/account/token/
#    (scope: "Entire account" works, or scope to a single project)
# 2. Run:
export PYPI_API_TOKEN="pypi-..."
python -m sin_code_bundle.tools.pypi_setup --api-token "$PYPI_API_TOKEN"
# 3. Check your email, click the magic link PyPI sent
```

This is the **1-click** path: no TTY, no prompts, no 2FA dance. It works in
CI scripts, agents, and headless servers. See
[`pypi_setup.doc.md`](./src/sin_code_bundle/tools/pypi_setup.doc.md) for
the full failure-mode table and security notes.

**Legacy fallback (interactive username + password):**

```bash
bash tools/setup_pypi_publisher.sh
# Follow the prompts, check email, click the magic link
```

Kept for maintainers who do not have a PyPI API token. Does not work in
CI / non-TTY environments.

After this one-time setup, every `git tag v0.X.Y && git push origin v0.X.Y`
triggers:

1. Build sdist + wheel
2. Verify install in a clean venv
3. Publish to PyPI via Trusted Publisher (tokenless OIDC)
4. Attach assets to GitHub Release

**Manual fallback:** <https://pypi.org/manage/account/publishing/> — Add pending publisher:

- Project: `sin-code-bundle` (PEP 503 normalised)
- Owner: `OpenSIN-Code`
- Repo: `SIN-Code-Bundle`
- Workflow filename: `release.yml`
- Environment name: `pypi`

---

## 🛠️ Agent Usage Example

Instead of guessing file structures, agents query the Semantic Codebase
Knowledge Graph (SCKG) directly via stable URI schemes:

```json
// Agent tool call
{
  "name": "sin_read",
  "arguments": {
    "path": "sckg://module/auth-service/dependencies",
    "summarize": true
  }
}
```

The VFS resolver translates this into a structured JSON response of exact
module dependencies — saving hundreds of tokens and preventing hallucination.

To disable native opencode tools and force SIN-Code usage, add to
`~/.config/opencode/opencode.json`:

```json
{
  "tools": {
    "read": false, "write": false, "edit": false, "bash": false,
    "search": false, "find": false, "grep": false, "glob": false,
    "list": false, "webfetch": false, "task": false
  },
  "mcp": {
    "sin-code-bundle": {
      "type": "local",
      "command": ["sin", "serve"],
      "enabled": true
    }
  }
}
```

---

## 📦 Unified MCP Tool Inventory (37 Tools)

When `sin-serve` is running, agents get **37 tools**. Native opencode tools
should be **disabled** to enforce SIN-Code usage.

### Core File Operations (5) — Replace native read/write/edit/bash/search

| Tool | Replaces | What it does | Why better than native |
|---|---|---|---|
| `sin_read` | `read` | URI-aware file read with size-safety + summarize mode | Native dumps 10MB+ into context; sin_read truncates + supports `sckg://`, `poc://`, `ibd://`, `adw://`, `efsm://`, `oracle://`, `conflict://` URIs |
| `sin_write` | `write` | Atomic write + syntax pre-validation (.py/.ts/.js/.go) + auto-backup | Native creates half-written files on crash; sin_write is atomic + compiles before writing |
| `sin_edit` | `edit` | Hashline-anchored semantic patches (content-hash, not line numbers) | Native edit breaks on reformat/race; sin_edit survives line shifts |
| `sin_bash` | `bash` | Safe shell exec via Go `execute` binary | Native leaks secrets; sin_bash redacts tokens/keys + enforces timeout |
| `sin_search` | `search`/`find`/`grep`/`glob` | Scout (Go) + Python-regex fallback | Native has 4 separate tools; sin_search unifies all 4 with semantic mode |

### Virtual Filesystem — URI Schemes (2)

| Tool | What it does |
|---|---|
| `sin_vfs_resolve` | Resolve `sckg://`, `poc://`, `ibd://`, `adw://`, `efsm://`, `oracle://`, `conflict://` URIs to structured content |
| `sin_vfs_schemes` | List all available URI schemes |

### Code Structure — AST + Hashline (2)

| Tool | What it does |
|---|---|
| `sin_ast_edit` | Tree-sitter AST-based edit with POC verification (falls back to hashline) |
| `sin_hashline_validate` | Validate a previously-created hashline patch can still be applied |

### Architectural Enforcement (1)

| Tool | What it does |
|---|---|
| `sin_check_architecture` | Pre-flight ADW rule check — blocks hardcoded secrets, eval/exec, frontend-DB imports |

### Consolidation Tools (3) — v0.7.0 — Replace 3-4 separate calls with 1

| Tool | Replaces | What it does |
|---|---|---|
| `sin_preflight` | `sin_check_architecture` + `sin_bash("sin codocs check")` + `sin_bash("git status")` + `sin_bash("pytest --collect-only")` | Pre-flight safety gate: policy + docs + git + tests in 1 call. Returns `{allowed, policy_ok, docs_ok, git_clean, tests_status, estimated_risk}` |
| `sin_symbol_resolve` | `gitnexus_query` + `gitnexus_context` + `gitnexus_impact` + `gitnexus_detect_changes` | Unified code archaeology for a symbol. Fans out to 4 gitnexus primitives + optional sin-context-bridge. Returns unified graph view with `sources_queried` list |
| `sin_checkpoint` | `rollback_snapshot` + `sin_bash("sin codocs check")` + `sin_bash("git status")` + `sin_search("X", type="usage")` + `sin_bash("pytest --collect-only")` | Pre-refactor checkpoint: recoverable snapshot + state report in 1 call. Idempotent on `name`. Returns `{snapshot_id, docs_broken, git_clean, usages_found, tests_status, tests_collected}` |

### Runtime Debugging — DAP (2)

| Tool | What it does |
|---|---|
| `sin_runtime_trace` | Start a DAP debug session for a function (debugpy for Python, dlv for Go, node --inspect for Node) |
| `sin_stop_trace` | Stop an active DAP session |

### Parallel Task Execution (2)

| Tool | What it does |
|---|---|
| `sin_create_worktree` | Create an isolated git worktree for parallel agent tasks |
| `sin_cleanup_worktree` | Clean up worktree (optionally merge back to main) |

### Subsystem Tools (10) — Require subsystem packages via `pip install -e ".[all]"`

| Tool | Subsystem | What it does |
|---|---|---|
| `impact` | sin_code_sckg | Blast-radius impact analysis for a symbol |
| `semantic_diff` | sin_code_ibd | Semantic intent diff between two files |
| `semantic_review` | sin_code_ibd | Intent + risk score in one call |
| `architectural_debt` | sin_code_adw | Current architectural debt score (god modules, circular imports, hot paths without tests) |
| `verify_tests` | sin_code_oracle | Verify agent-generated code (security/perf/correctness — OWASP Top 10, CWE Top 25) |
| `prove` | sin_code_poc | Generate and verify proofs of correctness (Hoare-style pre/post-conditions) |
| `mock_env` | sin_code_efsm | Manage ephemeral full-stack mock environment (Postgres + Redis + API server in 10s) |
| `orchestrate` | sin_code_orchestration | Submit a task to the multi-agent orchestrator (dependency-graph aware) |
| `task_status` | sin_code_orchestration | Get status of an orchestrated task |
| `review` | sin_code_review_interface | SOTA review on a single file (diff + debt + tests + style) |

### Memory Tools (5) — Require `sin-brain` via `pip install -e ".[memory]"`

| Tool | What it does |
|---|---|
| `recall_tool` | Search memory tiers (recall/archival/graph) — 4-tier SQLite+FTS5 storage |
| `remember_tool` | Persist a memory (decision/convention/fix/pitfall/preference) |
| `forget_tool` | Delete a memory entry by id |
| `pin_tool` | Pin a memory entry (never evicted) |
| `link_evidence_tool` | Attach a subsystem verdict to a memory |

### External Bridges (5)

| Tool | Source | What it does |
|---|---|---|
| `gitnexus_context` | GitNexus (PolyForm-Noncommercial) | Structural graph context for a symbol |
| `gitnexus_impact` | GitNexus | Blast-radius impact via graph (auto-indexes) |
| `gitnexus_ai_context` | GitNexus | Task-scoped, graph-aware context bundle |
| `markitdown_convert` | MarkItDown (MIT) | Convert PDF/DOCX/PPTX/XLSX/image → Markdown |
| `codocs_check` | codocs (built-in) | Find broken co-located `.doc.md` references |

**Total: 34 tools** = 5 core + 2 VFS + 2 AST + 1 arch + 2 runtime + 2 worktree + 10 subsystem + 5 memory + 5 external

---

## 🔌 Bridged External Tools (Never Vendored)

To keep the bundle MIT-licensed and lightweight, these upstream tools are
**bridged** (installed and updated independently, never vendored):

| Tool | Purpose | License | Setup |
|---|---|---|---|
| **[GitNexus](https://github.com/abhigyanpatwari/GitNexus)** | Upstream code knowledge graph | PolyForm-Noncommercial | `sin gitnexus setup` |
| **[Simone-MCP](https://github.com/OpenSIN-Code/Simone)** | Advanced code intelligence + LSP | Varies | Auto-detected during `sin bootstrap` |
| **[MarkItDown](https://github.com/microsoft/markitdown)** | Document → Markdown converter | MIT | `sin markitdown setup` |
| **[RTK](https://github.com/rtk-ai/rtk)** | Token-saving shell proxy (60-90% reduction) | Apache-2.0 | `sin rtk setup` |

---

## 🧩 Companion Skills (Separate MCP Servers)

The Bundle exposes 37 tools via `sin serve`. Several **companion skills** ship
as *separate* MCP servers — they are not part of the bundle core, but
register cleanly alongside it in any opencode / Claude Code / Cursor config.

| Companion | Tools | Install | Run |
|---|---|---|---|
| **[sin-context-bridge](https://github.com/OpenSIN-Code/SIN-Code-Bundle)** | 2 tools — unified context across SCKG + sin-brain + GitNexus + local SQLite | `pip install sin-code-bundle[all]` | `sin-context-bridge serve` |
| **[sin-honcho-rollback](https://github.com/OpenSIN-Code/sin-honcho-rollback)** | 4 MCP tools + CLI — snapshot, rollback, audit log for sin-brain memory | `pip install sin-honcho-rollback` | `sin-honcho-rollback serve` |
| **[symfony-lens](https://github.com/OpenSIN-Code/SIN-Code-Symfony-Lens)** | 8 tools — Symfony-specific static analysis (services, routes, entities, Twig, migrations, PHPStan) | `pip install sin-code-symfony-lens` | `python -m symfony_lens.server` |

### Wire them into opencode

```jsonc
{
  "mcp": {
    "sin-code-bundle":     { "type": "local", "command": ["sin", "serve"] },
    "sin-context-bridge":  { "type": "local", "command": ["sin-context-bridge", "serve"] },
    "sin-honcho-rollback": { "type": "local", "command": ["sin-honcho-rollback", "serve"] },
    "symfony-lens":        { "type": "local", "command": ["symfony-lens"] }
  }
}
```

All three companions follow the Bundle's graceful-degradation contract: if
the server isn't running, the consumer falls back to local-only behaviour
without crashing.

---

## 🛡️ Graceful Degradation

Every subsystem is an **optional** dependency. If a subsystem is missing, the
MCP server detects it and gracefully falls back. The bundle never crashes on
a missing optional dep.

```bash
pip install -e ".[all]"     # All 8 Python subsystems + sin-brain + LSP
pip install -e ".[memory]"  # Just sin-brain (memory tools)
pip install -e ".[lsp]"     # tree-sitter + 4 parsers (Python <3.14 only)
pip install -e "."          # Minimal — uses graceful fallbacks
```

Check what's installed:
```bash
sin status
```

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ sin-serve MCP server (stdio)                                │
│   34 tools exposed (5 core + 2 VFS + 2 AST + 1 arch +       │
│   2 runtime + 2 worktree + 10 subsystem + 5 memory +        │
│   5 external bridges)                                       │
└─────────────────────────────────────────────────────────────┘
                          │
       ┌──────────────────┼──────────────────┐
       │                  │                  │
       ▼                  ▼                  ▼
┌────────────┐   ┌──────────────┐   ┌──────────────────┐
│ 7 Go tools │   │ 8 Python     │   │ 5 External       │
│ (grasp,    │   │ subsystems   │   │ bridges          │
│  scout,    │   │ (sckg, ibd,  │   │ (GitNexus,       │
│  discover, │   │  poc, efsm,  │   │  Simone-MCP,     │
│  execute,  │   │  adw, oracle,│   │  MarkItDown,     │
│  map,      │   │  orchestration│  │  RTK, codocs)    │
│  harvest,  │   │  review-     │   │                  │
│  orchestrate)│ │  interface)  │   │                  │
└────────────┘   └──────────────┘   └──────────────────┘
                          │
                          ▼
                  ┌──────────────┐
                  │ sin-brain    │
                  │ (SQLite+FTS5 │
                  │ memory)      │
                  └──────────────┘
```

---

## 🧰 CLI Commands

| Command | Description |
|---|---|
| `sin status` | Show which subsystems are installed/available |
| `sin bootstrap [repo]` | Initialize available subsystems (graph, baselines, ledger) |
| `sin review <a> <b>` | Semantic review of a change (IBD) |
| `sin verify <module> <fn>` | Proof-of-correctness for a function (POC) |
| `sin debt [root]` | Architectural debt overview (ADW) |
| `sin preflight [root]` | Ensure GitNexus graph context is fresh before agents code |
| `sin gitnexus setup` | Wire GitNexus MCP into OpenCode / Codex / Hermes |
| `sin gitnexus index\|status\|doctor\|context\|impact\|ai-context` | GitNexus graph operations |
| `sin markitdown setup\|doctor\|convert` | Wire/convert via MarkItDown (doc → Markdown) |
| `sin rtk setup\|doctor\|gain` | Wire RTK token-saving proxy into agents |
| `sin codocs check [root]` | Validate co-located `.doc.md` references (built-in) |
| `sin codocs list [root]` | List all CoDocs references and whether they resolve |
| `sin codocs install-skill` | Install the CoDocs agent skill (Hermes / OpenCode) |
| `sin sin-code run <tool> [args]` | Run a SIN-Code Go tool (discover, execute, map, grasp, scout, harvest, orchestrate) |
| `sin sin-code agents-md` | Generate AGENTS.md with SIN-Code Tool Suite rules |
| `sin serve` | Unified MCP server across available subsystems |

---

## 🦫 SIN-Code Go Tools (v2)

The next-generation SIN-Code tools are Go binaries that replace OpenCode's
built-in tools (auto-installed by `install.sh`):

| Tool | Purpose | Version |
|---|---|---|
| `discover` | File discovery with pattern matching, relevance scoring, dependency mapping | v0.2.5 |
| `execute` | Safe command execution with secret redaction, timeout, error analysis | v0.2.4 |
| `map` | Architecture analysis with module mapping, entry points, hot paths | v0.2.5 |
| `grasp` | Single-file deep analysis with structure, dependencies, context | v0.2.4 |
| `scout` | Code search with regex, semantic, symbol, usage modes | v0.1.5 |
| `harvest` | URL/API fetching with caching, structure extraction, auth management | v0.1.4 |
| `orchestrate` | Task management with dependencies, parallel execution, rollback | v0.1.6 |

Install manually:
```bash
go install github.com/OpenSIN-Code/SIN-Code-Discover-Tool/cmd/discover@latest
go install github.com/OpenSIN-Code/SIN-Code-Execute-Tool/cmd/execute@latest
go install github.com/OpenSIN-Code/SIN-Code-Map-Tool/cmd/map@latest
go install github.com/OpenSIN-Code/SIN-Code-Grasp-Tool/cmd/grasp@latest
go install github.com/OpenSIN-Code/SIN-Code-Scout-Tool/cmd/scout@latest
go install github.com/OpenSIN-Code/SIN-Code-Harvest-Tool/cmd/harvest@latest
go install github.com/OpenSIN-Code/SIN-Code-Orchestrate-Tool/cmd/orchestrate@latest
```

---

## 📚 Documentation

- [INSTALL.md](./INSTALL.md) — Detailed installation and troubleshooting
- [CHANGELOG.md](./CHANGELOG.md) — Version history
- [docs/USAGE.md](./docs/USAGE.md) — Deep dive into CLI + MCP tool usage
- [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) — Configuration reference
- [docs/EXTERNAL_TOOLS.md](./docs/EXTERNAL_TOOLS.md) — Full compatibility matrix
- [docs/GITNEXUS.md](./docs/GITNEXUS.md) — How to wire the mandatory graph context
- [docs/CODOCS.md](./docs/CODOCS.md) — Co-located `.doc.md` standard
- [docs/adr/](./docs/adr/) — Architecture Decision Records
- [CONTRIBUTING.md](./CONTRIBUTING.md) — How to contribute

---

## 🤝 License

MIT — see [LICENSE](./LICENSE).

Bridged tools retain their original licenses:
- GitNexus: PolyForm-Noncommercial
- MarkItDown: MIT
- RTK: Apache-2.0

Part of the [SIN-Code](https://github.com/OpenSIN-Code) agent-engineering stack.
