codemind-sh 0.1.0__tar.gz

codemind_sh-0.1.0/LICENSE

@@ -0,0 +1,91 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             OnixSolutions (onixsolutions.net)
+Licensed Work:        CodeMind Version 0.1.0 or later. The Licensed Work is (c) 2026
+                      OnixSolutions
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to third
+                      parties on a hosted or embedded basis in order to compete with
+                      OnixSolutions's paid version(s) of the Licensed Work. For
+                      purposes of this license:
+
+                      A "competitive offering" is a Product that is offered to third
+                      parties on a paid basis, including through paid support
+                      arrangements, that significantly overlaps with the capabilities
+                      of OnixSolutions's paid version(s) of the Licensed Work. If
+                      Your Product is not a competitive offering when You first make
+                      it generally available, it will not become a competitive
+                      offering later due to OnixSolutions releasing a new version of
+                      the Licensed Work with additional capabilities. In addition,
+                      Products that are not provided on a paid basis are not
+                      competitive offerings.
+
+                      "Product" means software that is offered to end users to manage
+                      in their own environments or offered as a service on a hosted
+                      basis.
+
+                      "Embedded" means including the source code or executable code
+                      from the Licensed Work in a competitive offering. "Embedded"
+                      also means packaging the competitive offering in such a way
+                      that the Licensed Work must be accessed or downloaded for the
+                      competitive offering to operate.
+
+                      Hosting or using the Licensed Work(s) for internal purposes
+                      within an organization is not considered a competitive
+                      offering. OnixSolutions considers your organization to include
+                      all of your affiliates under common control.
+
+Change Date:          Four years from the date the Licensed Work is first publicly
+                      distributed under this License.
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@onixsolutions.net.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

codemind_sh-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: codemind-sh
+Version: 0.1.0
+Summary: Local-first knowledge graph for software projects. Gives AI tools structural facts about your codebase via 11 MCP tools.
+License: MIT
+License-File: LICENSE
+Keywords: ai,developer-tools,codebase,mcp,context,architecture
+Author: Mohammed
+Author-email: mohammed@onixsolutions.net
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Provides-Extra: ai
+Provides-Extra: all
+Requires-Dist: anthropic (>=0.40) ; extra == "ai" or extra == "all"
+Requires-Dist: click (>=8.1)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: mcp (>=1.0)
+Requires-Dist: pyperclip (>=1.9)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: rich (>=13.7)
+Requires-Dist: tree-sitter (>=0.22)
+Requires-Dist: tree-sitter-java (>=0.23)
+Requires-Dist: tree-sitter-python (>=0.23)
+Requires-Dist: tree-sitter-typescript (>=0.23)
+Requires-Dist: typer[all] (>=0.12)
+Requires-Dist: watchdog (>=4.0)
+Project-URL: Documentation, https://codemind.sh/docs
+Project-URL: Homepage, https://codemind.sh
+Project-URL: Repository, https://github.com/onixsolutions/codemind
+Description-Content-Type: text/markdown
+
+# CodeMind
+
+**Your codebase finally knows what connects to what — and it never leaves your machine.**
+
+CodeMind is a local-first knowledge graph for software projects. It lives inside your project as `.codemind/` (like `.git/`) and builds a precise, always-current graph of every component and every typed connection. When you use AI coding tools (Claude Code, Cursor, Copilot), CodeMind exposes 11 structural MCP tools — so the AI answers *"what calls X?"*, *"what breaks if I change Y?"*, and *"which Angular service calls `/api/offers`?"* with facts from the graph, not guesses.
+
+## Why?
+
+Every AI coding tool has amnesia. Claude Code, Cursor, Copilot — they read your files, help you code, and forget everything the moment the session ends. You waste 10–30 minutes per session re-explaining your architecture.
+
+CodeMind fixes this — and goes further: it maps every component and connection so the AI understands your project structurally, not just textually.
+
+## Quick Start
+
+```bash
+pip install codemind
+
+cd your-project/
+codemind init
+codemind scan
+```
+
+```
+✓ graph.json built
+
+  Graph summary
+    Components (nodes): 428
+    Connections (edges): 1,138
+    Cross-layer (frontend→backend): 20
+    Languages: java, typescript
+    Types: 118 interface, 92 class, 69 service, 44 component,
+           23 controller, 20 repository, 19 entity, 24 enum ...
+```
+
+That's it. Your project now has a living knowledge graph.
+
+## Use With Claude Code, Cursor, or Claude Desktop (MCP)
+
+`codemind init` automatically registers CodeMind with every AI coding tool it detects on your machine. No manual config editing required.
+
+If you need to re-register later (e.g. after installing a new tool):
+
+```bash
+codemind connect              # auto-detect and register all installed AI tools
+codemind connect --tool claude  # Claude Code only
+codemind connect --global     # write to global config instead of project-level
+```
+
+This creates `.mcp.json` at your project root (the format Claude Code requires):
+
+```json
+{
+  "mcpServers": {
+    "codemind": {
+      "command": "/path/to/codemind",
+      "args": ["serve", "--path", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+`codemind serve` always includes the file watcher — graph.json is kept current on every save so the AI always answers with structural facts, never stale data.
+
+## The 11 MCP Tools
+
+Once connected, Claude Code (or any MCP-compatible tool) can use:
+
+| Tool | What it answers |
+|------|----------------|
+| `get_connections(component)` | What it injects, calls, extends, implements — and what depends on it. Includes cross-layer edges (frontend→backend). |
+| `impact_analysis(component)` | Everything that breaks if this component changes. BFS, sorted by distance. |
+| `find_components(query)` | Free-text search across names, packages, method names. Auto-discovers unindexed files when nothing found. |
+| `find_for_task(description)` | Relevant existing components + gaps for a stated feature. |
+| `get_pattern()` | Best existing full-stack domain as a copy-me template. |
+| `trace_request(path)` | Trace an HTTP path from frontend to backend. `/api/offers` → `OfferService` → `OfferController`. |
+| `record_decision(...)` | Write a decision record after completing a task. |
+| `get_decisions(limit)` | Read recent decisions at session start — the AI never starts from zero. |
+| `enrich_node(component, notes)` | Attach AI-discovered notes to a graph node — persists across sessions. |
+| `index_file(path)` | Read any source file (Dart, Kotlin, Swift, Go…) and return it with extraction instructions. |
+| `add_component(name, type, file, language, …)` | Persist a component extracted from `index_file` to the graph permanently. |
+
+### Example session (Claude Code with CodeMind connected)
+
+```
+You: "What would break if I change ThresholdEvaluator?"
+
+Claude → impact_analysis("ThresholdEvaluator")
+→ Direct dependents (distance 1): KpiCalculationService, KpiAlertService
+→ Indirect dependents (distance 2): KpiController, ReportsService
+→ 4 components affected — 2 controllers + 2 services
+
+You: "Which Angular service calls /api/kpi-builder?"
+
+Claude → trace_request("/api/kpi-builder")
+→ Frontend: KpiService (service) — calls this endpoint
+→ Backend: KpiBuilderController (controller) — route: /api/kpi-builder
+→ Cross-layer connection: KpiService → KpiBuilderController
+```
+
+## What `.codemind/` Contains
+
+```
+your-project/
+└── .codemind/
+    ├── graph.json          ← The knowledge graph (auto-updated on every save)
+    ├── ARCHITECTURE.md     ← System overview, module map (auto-generated)
+    ├── modules/            ← Per-domain docs: auth.md, kpi.md, ...
+    ├── decisions/          ← Why things were built this way
+    │   └── 2026-02-15-add-kpi-alert.md
+    ├── tasks/              ← Implementation checklists (from scaffold)
+    └── config.yml          ← Project settings
+```
+
+Everything is human-readable. Git-friendly. Private.
+
+## Scaffold — Generate Code From Your Graph
+
+CodeMind learns your project's package structure, naming conventions, and injection patterns from the graph, then generates new code that matches:
+
+```bash
+codemind scaffold service KpiAlert     # KpiAlertService.java + test
+codemind scaffold module Attendance    # Full stack: service + controller + entity + repository + test
+codemind scaffold api ReportExport     # Controller + service + test
+codemind scaffold component Dashboard  # Angular/TypeScript service
+
+# Preview without writing:
+codemind scaffold module Attendance --dry-run
+```
+
+Generated files use your real package (`com.app.kpi.business.kpialert`), your real API path (`/api/kpi-alert`), and your real table name (`kpi_alert`) — all derived from the graph.
+
+## Health Checks
+
+```bash
+codemind check             # Full check: naming, layer violations, missing tests, orphans, domains
+codemind check --quick     # Fast: naming + layer violations only
+codemind check --pre-commit  # Git hook mode: exit 1 on errors
+```
+
+Five checks, all driven by the graph:
+- **naming** — component names match their type (`KpiService` should end in `Service`)
+- **layer_violation** — controllers injecting repositories directly (error)
+- **missing_test** — services/controllers without a test class
+- **orphan** — structural nodes with no connections (dead code?)
+- **domain_incomplete** — domains missing key layers
+
+Install as a git pre-commit hook:
+```bash
+codemind install-hook
+```
+
+## Decision Tracking
+
+```bash
+codemind decide "Add KPI threshold alert"   # Interactive — prompts for components + reason
+codemind decisions                          # List recent decisions
+codemind decisions show kpi-threshold       # Print full decision
+```
+
+At session start, Claude calls `get_decisions` automatically and knows what was built and why. No re-explaining.
+
+## Team Reports (BYOK)
+
+When you ask Claude about your codebase in a session, the answer disappears when the session ends.
+These three commands generate **persistent markdown reports** that live in your repo — readable by
+the whole team, committable, and shareable without anyone needing an active AI session.
+
+```bash
+codemind review                           # Architectural review → .codemind/REVIEW.md
+codemind brief                            # Onboarding brief   → .codemind/BRIEF.md
+codemind impact ThresholdEvaluator --ai   # Risk badge         → printed + committable
+```
+
+**`codemind review`** — compresses your entire graph (all components, health check results,
+connection counts) into a structured architectural review: strengths, risks, recommendations,
+key metrics. Commit `REVIEW.md` so every teammate sees the same picture.
+
+**`codemind brief`** — generates an onboarding doc: what the system does, the 5 most important
+components, the 3 domains to understand first, key patterns, and a glossary of domain terms
+extracted from your component names. A new developer reads it before their first session —
+onboarded before they open Claude Code.
+
+**`codemind impact <component> --ai`** — runs a full BFS across the entire graph first (not
+just what's in your current context), then asks Claude to assess risk level (🟢/🟡/🔴) with
+specific high-risk callers named. Useful in CI: block a PR when blast radius is 🔴 HIGH.
+
+All three require `ANTHROPIC_API_KEY` (set once in your shell). Results are cached in
+`.codemind/ai-cache/` keyed by graph content — running them twice on the same graph costs
+nothing. One `codemind review` (~$0.003) generates a report the whole team benefits from.
+
+> **Any-language support needs no API key.** `index_file` + `add_component` index Dart,
+> Kotlin, Swift, Go, C#, Ruby, Rust and any other language at zero cost — they use your
+> existing Claude Code session, not a separate key.
+
+## CLI Reference
+
+```bash
+# Core
+codemind init                   # Initialize .codemind/ (1 project free)
+codemind scan                   # Parse codebase → graph.json + ARCHITECTURE.md + modules/
+codemind status                 # Graph stats overview
+
+# AI tool integration
+codemind connect                # Auto-register MCP with Claude Code/Cursor/Claude Desktop
+codemind connect --tool claude  # Claude Code only
+codemind connect --global       # Global config (all projects)
+
+# Keep graph live
+codemind watch                  # File watcher only (CLI workflow)
+codemind serve                  # MCP server + file watcher (AI tool integration)
+
+# Query
+codemind query "email on KPI drop"             # find_for_task
+codemind query "" --connections KpiService     # get_connections
+codemind query "" --impact ThresholdEvaluator  # impact_analysis
+codemind query "" --pattern                    # get_pattern
+
+# Pro AI (requires ANTHROPIC_API_KEY)
+codemind review                 # Architectural review
+codemind brief                  # Onboarding brief
+codemind impact <component> --ai  # Impact + AI risk assessment
+
+# Scaffold
+codemind scaffold service|module|api|component <name>
+codemind scaffold module Attendance --dry-run   # Preview
+
+# Health
+codemind check
+codemind check --quick
+codemind install-hook            # Install as git pre-commit hook
+
+# Decisions
+codemind decide "What was built"
+codemind decisions
+codemind decisions show <slug>
+```
+
+## Supported Stacks
+
+### Native parsers — fully offline, no API key ever
+
+| Language | Frameworks | Edges extracted |
+|----------|-----------|----------------|
+| Java | Spring Boot, Jakarta EE, Lombok, JPA | injects, calls, extends, implements |
+| TypeScript | Angular, React, Next.js, NestJS | injects, calls, extends, implements |
+| Python | FastAPI, Django, Flask, Pydantic, SQLAlchemy | injects, calls, extends |
+
+**Fullstack cross-layer routing:** Spring Boot + Angular, Spring Boot + React. CodeMind detects frontend HTTP calls and backend routes, then creates cross-layer edges — so `trace_request("/api/offers")` shows the full path from Angular service to Spring controller.
+
+### Any other language — via `index_file` + `add_component` — free, no API key
+
+When `find_components` finds nothing for a Dart / Kotlin / Swift / Go file, CodeMind automatically reads the file and returns it to your AI session with extraction instructions. Claude Code analyses it using your existing subscription and calls `add_component` to persist each class to `graph.json` permanently — available offline from that point forward.
+
+| Language | Cost |
+|----------|------|
+| Dart / Flutter | $0 — uses your Claude Code session |
+| Kotlin / Android | $0 — uses your Claude Code session |
+| Swift / iOS | $0 — uses your Claude Code session |
+| Go / Gin | $0 — uses your Claude Code session |
+| C# / ASP.NET Core | $0 — uses your Claude Code session |
+| Ruby / Rails | $0 — uses your Claude Code session |
+| Rust, PHP, Elixir, … | $0 — uses your Claude Code session |
+
+## Privacy
+
+**Everything stays on your machine.** No cloud. No external database. No telemetry.
+
+- `graph.json` — stays local
+- `decisions/*.md` — stays local
+- Your source code — never leaves your machine
+- MCP tools run over local stdio — no network
+
+The optional BYOK AI enricher (gap-filling injection edges) sends only small structural samples to the Claude API and is strictly opt-in via `ANTHROPIC_API_KEY`. All other features — including any-language indexing via `index_file` — run entirely offline using your existing AI tool session.
+
+## Links
+
+- **Website:** [codemind.sh](https://codemind.sh)
+- **Docs:** [codemind.sh/docs](https://codemind.sh/docs)
+- **GitHub:** [github.com/onixsolutions/codemind](https://github.com/onixsolutions/codemind)
+
+## License
+
+Business Source License 1.1 (BSL) — source visible, not for commercial redistribution.
+Converts to MIT after 4 years.
+Personal and evaluation use permitted.
+
+Built by [OnixSolutions](https://onixsolutions.net)
+