Skip to content

OpenSIN-Code/SIN-Code-Bundle

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

94 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🧠 SIN-Code Bundle

Python License: MIT CI Version

The universal semantic backend for AI coding agents.

One CLI (sin) and one unified MCP server (sin-serve / sin serve) that orchestrate 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.

As of v0.9.3 (issue #28) the 6 Python subsystems (SCKG, IBD, PoC, EFM, ADW, Oracle) and the Next.js Web frontend are no longer vendored in this monorepo. They live in their own standalone OpenSIN-Code repos and are installed separately via requirements-ecosystem.txt. The Bundle has shrunk from ~50k LOC to the core glue: CLI + MCP server + VFS resolver + AST editor + sin-brain memory hooks.


⚡ 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
❌ 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)

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 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:

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):

# 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 for the full failure-mode table and security notes.

Legacy fallback (interactive username + password):

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:

// 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:

{
  "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 Upstream code knowledge graph PolyForm-Noncommercial sin gitnexus setup
Simone-MCP Advanced code intelligence + LSP Varies Auto-detected during sin bootstrap
MarkItDown Document → Markdown converter MIT sin markitdown setup
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 2 tools — unified context across SCKG + sin-brain + GitNexus + local SQLite pip install sin-code-bundle[all] sin-context-bridge serve
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 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

{
  "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.

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:

sin status

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│ sin-serve MCP server (stdio)                                │
│   19 tools exposed (5 core + 2 VFS + 2 AST + 1 arch +       │
│   2 runtime + 2 worktree + 5 memory) + 10 OPTIONAL          │
│   ecosystem tools (SCKG, IBD, PoC, EFM, ADW, Oracle + ... ) │
│   loaded only when the matching pip pkg is installed.       │
└─────────────────────────────────────────────────────────────┘
                          │
       ┌──────────────────┼──────────────────┐
       │                  │                  │
       ▼                  ▼                  ▼
┌────────────┐   ┌──────────────┐   ┌──────────────────┐
│ 7 Go tools │   │ 6+2 ECOSYSTEM│   │ 5 External       │
│ (grasp,    │   │ packages     │   │ bridges          │
│  scout,    │   │ (sckg, ibd,  │   │ (GitNexus,       │
│  discover, │   │  poc, efsm,  │   │  Simone-MCP,     │
│  execute,  │   │  adw, oracle,│   │  MarkItDown,     │
│  map,      │   │  orchestration│  │  RTK, codocs)    │
│  harvest,  │   │  review-     │   │                  │
│  orchestrate)│ │  interface)  │   │                  │
└────────────┘   └──────────────┘   └──────────────────┘
                          ▲
                          │ pip install -r
                          │   requirements-ecosystem.txt
                          │
                  ┌──────────────┐
                  │ sin-brain    │
                  │ (SQLite+FTS5 │
                  │ memory)      │
                  └──────────────┘

Ecosystem packages (SCKG, IBD, PoC, EFM, ADW, Oracle, Orchestration, Review-Interface) are NOT vendored in this monorepo anymore (issue #28). Install them from their standalone repos via requirements-ecosystem.txt. Each is a standard pip-installable package with its own README + LICENSE.

Ecosystem pkg Standalone repo Description
sin-code-sckg SIN-Code-SCKG-Tool Semantic Codebase Knowledge Graphs
sin-code-ibd SIN-Code-IBD-Tool Intent-Based Diffing
sin-code-poc SIN-Code-PoC-Tool Proof-of-Correctness
sin-code-efsm SIN-Code-EFM-Tool Ephemeral Full-Stack Mocking
sin-code-adw SIN-Code-ADW-Tool Architectural Debt Watchdog
sin-code-oracle SIN-Code-Oracle-Tool Verification Oracle

The Next.js web frontend lives in SIN-Code-Bundle-Web.


🧰 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:

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


🤝 License

MIT — see LICENSE.

Bridged tools retain their original licenses:

  • GitNexus: PolyForm-Noncommercial
  • MarkItDown: MIT
  • RTK: Apache-2.0

Part of the SIN-Code agent-engineering stack.

About

No description, website, or topics provided.

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages