@hugobatist/smartcode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmartB Diagrams Contributors
+
+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.

package/README.md

@@ -0,0 +1,292 @@
+# SmartCode
+
+**See what your AI is thinking.** A visual debugger for AI reasoning — watch your AI agent think in real-time, set breakpoints, flag mistakes, and replay sessions.
+
+[![npm version](https://img.shields.io/npm/v/smartcode.svg)](https://www.npmjs.com/package/smartcode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## Why SmartCode?
+
+AI coding tools are **black boxes**. You give Cursor, Claude Code, or Copilot a task and wait. If it goes down a wrong path, you only find out when it's done — after wasted time and tokens.
+
+SmartCode makes AI reasoning **visible and controllable**:
+
+- **See** the AI's reasoning as a live flowchart that updates in real-time
+- **Intervene** by flagging nodes mid-execution — the AI reads your feedback and course-corrects
+- **Debug** with breakpoints that pause AI execution at specific reasoning steps
+- **Understand** what the AI considered and rejected via ghost paths
+- **Analyze** patterns with session replay and heatmaps
+
+It's the **Datadog for AI reasoning** — not another AI tool, but a plugin that makes your existing tools transparent.
+
+## Quick Start
+
+```bash
+npm install -g smartcode
+smartcode init
+smartcode serve
+```
+
+Your browser opens with a live diagram viewer. Edit any `.mmd` file and see changes instantly.
+
+## Key Features
+
+### Real-Time AI Observability
+
+AI agents write Mermaid diagrams via MCP tools. A file watcher detects changes and pushes updates to your browser via WebSocket — all within 100ms.
+
+### Interactive Canvas
+
+Custom SVG renderer with dagre layout engine. Select, drag, edit, delete, and connect nodes directly on the canvas. Full undo/redo support (Ctrl+Z / Ctrl+Shift+Z).
+
+### AI Breakpoints
+
+Set breakpoints on diagram nodes. When the AI reaches that node, it **pauses** and waits for you to review. Click "Continue" when ready — just like a code debugger, but for AI reasoning.
+
+### Ghost Paths
+
+See the reasoning branches the AI considered but **rejected**. Rendered as dashed translucent edges, ghost paths reveal the "deleted scenes" of AI thinking — information normally invisible.
+
+### Developer Flags
+
+Click any node to flag it with a message. The AI reads your flag via MCP, gets structured correction context, and adjusts its approach. Bidirectional human-AI communication embedded in the diagram.
+
+### Session Recording & Replay
+
+Every AI reasoning session is recorded as JSONL. Replay sessions with a timeline scrubber at 1x/2x/4x speed. Diff highlighting shows what changed between frames.
+
+### Risk Heatmap
+
+Color-code nodes by visit frequency (cold blue to hot red). Identify which reasoning steps the AI revisits most — potential confusion points or bottlenecks.
+
+### Node Status Tracking
+
+Color-coded progress: green (ok), yellow (in-progress), red (problem), gray (discarded). See at a glance where the AI succeeded and where it struggled.
+
+## CLI Reference
+
+### `smartcode init`
+
+Initialize a SmartCode project.
+
+```bash
+smartcode init [--dir <path>] [--force]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--dir <path>` | `.` | Project directory |
+| `--force` | `false` | Overwrite existing config |
+
+### `smartcode serve`
+
+Start the diagram viewer server.
+
+```bash
+smartcode serve [--port <number>] [--dir <path>] [--no-open]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port <number>` | `3333` | Server port |
+| `--dir <path>` | `.` | Project directory |
+| `--no-open` | `false` | Don't open browser automatically |
+
+### `smartcode status`
+
+Check server health.
+
+```bash
+smartcode status [--port <number>]
+```
+
+Shows uptime, diagram count, connected clients, and active flags.
+
+### `smartcode mcp`
+
+Start the MCP server for AI tool integration.
+
+```bash
+smartcode mcp [--dir <path>] [--serve] [--port <number>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--dir <path>` | `.` | Project directory |
+| `--serve` | `false` | Co-host HTTP+WS server for browser viewing |
+| `--port <number>` | `3333` | HTTP server port (requires `--serve`) |
+
+## MCP Integration
+
+### Setup with Claude Code
+
+One command:
+
+```bash
+claude mcp add --transport stdio smartcode -- npx -y smartcode mcp --dir .
+```
+
+Or add a `.mcp.json` to your project root:
+
+```json
+{
+  "mcpServers": {
+    "smartcode": {
+      "command": "npx",
+      "args": ["-y", "smartcode", "mcp", "--dir", "."]
+    }
+  }
+}
+```
+
+### Setup with Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "smartcode": {
+      "command": "npx",
+      "args": ["-y", "smartcode", "mcp", "--dir", "/path/to/project"]
+    }
+  }
+}
+```
+
+### With Browser Viewer
+
+Run MCP and browser viewer in a single process:
+
+```bash
+smartcode mcp --dir . --serve --port 3333
+```
+
+AI tool calls and browser updates share the same `DiagramService` — zero-latency sync.
+
+## MCP Tools
+
+SmartCode exposes 11 tools via the Model Context Protocol:
+
+| Tool | Description |
+|------|-------------|
+| `update_diagram` | Create or update a `.mmd` file |
+| `read_flags` | Read developer feedback annotations |
+| `get_diagram_context` | Get full diagram state (content, flags, statuses, validation) |
+| `update_node_status` | Set node status: `ok` / `problem` / `in-progress` / `discarded` |
+| `get_correction_context` | Get structured correction prompt for a flagged node |
+| `check_breakpoints` | Check if AI should pause at the current node |
+| `record_ghost_path` | Record a discarded reasoning branch |
+| `start_session` | Begin a recording session |
+| `record_step` | Record a node visit in the active session |
+| `end_session` | End session and get summary statistics |
+| `set_risk_level` | Set risk annotation (high/medium/low) on a node |
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Z` | Undo |
+| `Ctrl+Shift+Z` | Redo |
+| `Ctrl+C` / `Ctrl+V` | Copy / Paste |
+| `Ctrl+D` | Duplicate |
+| `Ctrl+F` | Search nodes |
+| `Delete` | Delete selected |
+| `Escape` | Deselect |
+| Mouse wheel | Zoom |
+| Click + drag | Pan |
+
+## AI Diagram Conventions
+
+### Diagram Direction
+
+- `flowchart TD` for sequential reasoning (top to bottom)
+- `flowchart LR` for parallel or branching logic (left to right)
+
+### Node Naming
+
+- IDs: lowercase-hyphenated (`analyze-requirements`)
+- Labels: short action phrases (`["Analyze Requirements"]`)
+
+### Status Annotations
+
+```
+%% @status analyze-requirements ok            -- completed (green)
+%% @status design-schema in-progress          -- working (yellow)
+%% @status implement-api problem              -- issue found (red)
+%% @status abandoned-approach discarded       -- abandoned (gray)
+```
+
+### Developer Flags
+
+```
+%% @flag design-schema "Consider normalized schema instead"
+```
+
+### Example CLAUDE.md Integration
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## SmartCode
+
+- Use `update_diagram` to create/update .mmd reasoning diagrams
+- Use `flowchart TD` for sequential steps, node IDs lowercase-hyphenated
+- Set nodes to `in-progress` when starting, `ok` when done, `problem` on issues
+- Check `read_flags` before starting — respond to developer feedback
+- Use `get_correction_context` when flags exist for structured guidance
+```
+
+## Architecture
+
+```
+Developer's Machine (single process)
++-----------------------------------------------+
+|  smartcode serve / smartcode mcp --serve             |
+|                                                |
+|  +------------------+  +-------------------+   |
+|  | MCP Server       |  | HTTP Server       |   |
+|  | (stdio transport)|  | (port 3333)       |   |
+|  +--------+---------+  +--------+----------+   |
+|           |                      |              |
+|           v                      v              |
+|  +------------------------------------------+  |
+|  |          DiagramService (shared)          |  |
+|  |  parse | validate | annotate | serialize  |  |
+|  +------------------------------------------+  |
+|           |                      |              |
+|           v                      v              |
+|  +----------------+    +------------------+     |
+|  | File Watcher   |--->| WebSocket Server |     |
+|  | (.mmd files)   |    | (broadcast)      |     |
+|  +----------------+    +------------------+     |
++-----------------------------------------------+
+          |                        |
+          v                        v
+   .mmd files on disk       Browser / VS Code
+   (source of truth)         (live viewer)
+```
+
+## Requirements
+
+- Node.js >= 18.17
+- npm or npx
+
+## Contributing
+
+Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+
+```bash
+git clone https://github.com/Hugobatist/smartcode.git
+cd smartcode
+npm install
+npm run build
+npm test
+```
+
+## License
+
+[MIT](LICENSE)