superacli 1.1.6 → 1.1.8

package/docs/mcp-cheatsheet.md

@@ -1,324 +0,0 @@
-# MCP Server Cheatsheet: SSE/HTTP Implementation in Node.js (Pure, No SDKs - Spec v2025-06-18)
-
-<div style="border: 1px solid #ccc; padding: 20px; margin: 10px 0; background-color: #f9f9f9; border-radius: 8px;">
-  <strong>Artifact Note:</strong> This is a pure Node.js implementation cheatsheet for an SSE/HTTP-capable MCP server. It uses only built-in modules (e.g., `http`, `https`, `url`, `querystring`) for bidirectional streaming via JSON-RPC 2.0. No external SDKs or npm packages—ideal for lightweight setups. Expand sections for details.
-</div>
-
-## Overview
-- **MCP Purpose**: Open protocol for AI apps (e.g., LLMs) to access external tools/resources via JSON-RPC 2.0.
-- **Focus**: Pure Node.js server for bidirectional streaming (client-to-server via POST, server-to-client via SSE GET).
-- **Transports**: SSE + HTTP (streamable; single endpoint preferred) or stdio (local-only). SSE enables real-time server pushes like tool calls/notifications.
-- **Key Benefits**: Resumable streams, session management, secure (Origin validation, auth).
-- **Node.js Notes**: Uses `http.Server` for endpoints; manual JSON-RPC parsing; EventEmitter for internal messaging.
-
-<details>
-<summary><strong>Prerequisites (Click to Expand)</strong></summary>
-
-- **Runtime**: Node.js 20+ (LTS recommended for stability).
-- **Modules**: Built-ins only: `http`, `https`, `url`, `querystring`, `crypto` (for sessions), `events` (for pub/sub).
-- **Tools**: Familiarity with JSON-RPC, HTTP/SSE; editor like VS Code.
-- **Security**: Use `https` in prod; validate origins to prevent rebinding. Run with `node server.js`.
-
-</details>
-
-## Transport Types: SSE/HTTP
-| Type | Description | Pros | Cons |
-|------|-------------|------|------|
-| **Streamable HTTP + SSE** | Single endpoint (`/mcp`) for POST (client → server) & GET (SSE stream server → client). | Bidirectional, resumable, efficient for remote. | Manual SSE flushing; manage sessions. |
-| **HTTP Only** | POST for all; no streaming. | Simple. | No real-time pushes. |
-| **Stdio** | Local stdin/stdout (not HTTP). | Fast for desktop. | Non-remote. |
-
-- **Protocol Version**: Client sends `MCP-Protocol-Version: 2025-06-18` header; server rejects invalid (400 Bad Request).
-
-<details>
-<summary><strong>Server Setup Steps (Click to Expand)</strong></summary>
-
-1. **Init Project**:  
-   Create `server.js` and `package.json` (for scripts, no deps):  
-   ```json
-   // package.json
-   {"name": "mcp-server", "scripts": {"start": "node server.js"}}
-   ```
-
-2. **Create HTTP Server Instance**:  
-   ```javascript
-   const http = require('http');
-   const url = require('url');
-   const { EventEmitter } = require('events');
-   const crypto = require('crypto');
-
-   const server = http.createServer(handleRequest);
-   const emitter = new EventEmitter();  // For internal pub/sub (e.g., server pushes)
-
-   function handleRequest(req, res) {
-     const parsedUrl = url.parse(req.url, true);
-     const method = req.method;
-     const pathname = parsedUrl.pathname;
-
-     // Validate protocol version
-     if (!req.headers['mcp-protocol-version'] || req.headers['mcp-protocol-version'] !== '2025-06-18') {
-       res.writeHead(400, { 'Content-Type': 'application/json' });
-       res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Protocol Version' } }));
-       return;
-     }
-
-     if (pathname === '/mcp' || pathname === '/messages/') {
-       if (method === 'POST') {
-         handlePost(req, res, emitter);
-       } else if (method === 'GET') {
-         handleSSE(req, res, emitter);
-       } else if (method === 'DELETE') {
-         handleDelete(req, res);
-       } else {
-         res.writeHead(405);
-         res.end();
-       }
-     } else {
-       res.writeHead(404);
-       res.end();
-     }
-   }
-   ```
-
-3. **Define Tools/Resources** (Manual Dispatch):  
-   Use a map for methods (tools/resources).  
-   ```javascript
-   const tools = {
-     example_tool: async (params) => `Processed: ${params.param}`,
-     // Add async funcs for I/O
-   };
-
-   const resources = {
-     'example://{id}': (id) => `Resource data for ${id}`,
-   };
-
-   // In handlePost: Parse method, dispatch
-   async function dispatchMethod(method, params, id, sessionId) {
-     if (tools[method]) {
-       try {
-         const result = await tools[method](params);
-         return { jsonrpc: '2.0', result, id };
-       } catch (e) {
-         return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
-       }
-     } else if (method.startsWith('resources/')) {
-       // Handle resources similarly
-     }
-     return { jsonrpc: '2.0', error: { code: -32601, message: 'Method Not Found' }, id };
-   }
-   ```
-
-4. **Setup SSE Transport**:  
-   Manual SSE handling with keep-alives.  
-   ```javascript
-   function handleSSE(req, res, emitter) {
-     const sessionId = req.headers['mcp-session-id'];
-     if (!sessionId) {
-       res.writeHead(401);
-       res.end('Missing Session ID');
-       return;
-     }
-
-     res.writeHead(200, {
-       'Content-Type': 'text/event-stream',
-       'Cache-Control': 'no-cache',
-       'Connection': 'keep-alive',
-       'Access-Control-Allow-Origin': req.headers.origin || '*',  // Validate in prod
-     });
-
-     let lastEventId = req.headers['last-event-id'] || '0';
-     // Resume logic: Replay events > lastEventId (store in session map)
-
-     const heartbeat = setInterval(() => {
-       res.write(`: heartbeat\n\n`);  // Keep-alive
-     }, 15000);
-
-     // Listen for server pushes
-     const listener = (msg) => {
-       if (msg.sessionId === sessionId && msg.eventId > parseInt(lastEventId)) {
-         res.write(`id: ${msg.eventId}\ndata: ${JSON.stringify(msg.data)}\n\n`);
-         lastEventId = msg.eventId.toString();
-       }
-     };
-     emitter.on('push', listener);
-
-     req.on('close', () => {
-       clearInterval(heartbeat);
-       emitter.off('push', listener);
-       res.end();
-     });
-   }
-   ```
-
-5. **Handle POST (Client Messages)**:  
-   Parse JSON-RPC, dispatch, respond or push via SSE.  
-   ```javascript
-   function handlePost(req, res, emitter) {
-     let body = '';
-     req.on('data', chunk => body += chunk);
-     req.on('end', async () => {
-       try {
-         const msg = JSON.parse(body);
-         if (!msg.jsonrpc || msg.jsonrpc !== '2.0') throw new Error('Invalid JSON-RPC');
-
-         const sessionId = req.headers['mcp-session-id'] || generateSessionId();
-         res.setHeader('Mcp-Session-Id', sessionId);
-
-         if (msg.id !== undefined) {  // Request
-           const response = await dispatchMethod(msg.method, msg.params || {}, msg.id, sessionId);
-           res.writeHead(202, { 'Content-Type': 'application/json' });
-           res.end(JSON.stringify(response));
-         } else {  // Notification
-           await dispatchMethod(msg.method, msg.params || {}, null, sessionId);  // Fire-and-forget
-           res.writeHead(202);
-           res.end();
-         }
-
-         // For server-initiated pushes (e.g., notifications)
-         emitter.emit('push', { sessionId, eventId: Date.now(), data: { /* response */ } });
-       } catch (e) {
-         res.writeHead(400, { 'Content-Type': 'application/json' });
-         res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse Error' } }));
-       }
-     });
-   }
-
-   function generateSessionId() {
-     return crypto.randomUUID();
-   }
-   ```
-
-6. **Run Server**:  
-   ```javascript
-   server.listen(8000, '127.0.0.1', () => {
-     console.log('MCP Server running on http://127.0.0.1:8000');
-   });
-   ```
-   - For HTTPS: Replace `http` with `https`, provide key/cert.
-
-</details>
-
-## Endpoints
-| Method | Path | Purpose | Headers/Body |
-|--------|------|---------|--------------|
-| **POST** | `/mcp` (or `/messages/`) | Client sends JSON-RPC (requests/notifications). | `Accept: application/json, text/event-stream`<br>Body: JSON-RPC msg |
-| **GET** | `/mcp` (or `/sse/`) | Open SSE stream for server pushes (requests/notifications). | `Accept: text/event-stream`<br>`Last-Event-ID` (for resume) |
-| **DELETE** | `/mcp` | Terminate session. | `Mcp-Session-Id` header |
-
-- **Responses**:  
-  - POST: 202 Accepted (no body) or JSON.  
-  - Errors: 400/404/500 with JSON-RPC error body (no `id` for non-requests).  
-- **Keep-Alives**: SSE heartbeats every 15s; close after response.
-
-<details>
-<summary><strong>Message Formats (JSON-RPC 2.0) (Click to Expand)</strong></summary>
-
-- **Request** (Client → Server):  
-  ```json
-  {"jsonrpc": "2.0", "method": "tool_name", "params": {"key": "value"}, "id": 1}
-  ```
-- **Notification** (No response expected): Omit `id`.  
-- **Response** (Server → Client):  
-  ```json
-  {"jsonrpc": "2.0", "result": "value", "id": 1}
-  ```
-- **Error**:  
-  ```json
-  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": 1}
-  ```
-- **SSE Events**: `data: <JSON>\n\n` (UTF-8); unique `id` for resumability.  
-- **Session**: Server assigns `Mcp-Session-Id` in response header; client echoes in headers.
-
-</details>
-
-## Security & Authentication
-- **Basics**: Use `https.createServer` in prod; validate `Origin` header (reject mismatches).  
-  ```javascript
-  // In handleRequest
-  if (req.headers.origin !== 'https://trusted-client.com') {
-    res.writeHead(403);
-    res.end();
-    return;
-  }
-  ```
-- **Auth**:  
-  - API keys in headers (e.g., `Authorization: Bearer <token>`—verify manually).  
-  - Sessions: Store in Map (e.g., `sessions.set(sessionId, { expires: Date.now() + 3600000 })`); expire after 1h inactivity (404).  
-- **Best Practices**: User approval for tools; no embedded newlines in msgs; log to console.error.
-
-<details>
-<summary><strong>Error Handling (Click to Expand)</strong></summary>
-
-- **Common Codes**: -32600 (Invalid Req), -32601 (Method Not Found), -32700 (Parse Error).  
-- **Implementation**:  
-  ```javascript
-  try {
-    // Tool logic (e.g., fetch)
-    const response = await fetch(url, { timeout: 30000 });
-    if (!response.ok) throw new Error('HTTP Error');
-    return await response.json();
-  } catch (e) {
-    return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
-  }
-  ```
-- **Disconnections**: Don't cancel on close; require explicit `CancelledNotification`. Resume via `Last-Event-ID` (store events per session in a Map).
-
-</details>
-
-<details>
-<summary><strong>Example: Full Pure Node.js SSE MCP Server (Click to Expand)</strong></summary>
-
-```javascript
-// server.js
-const http = require('http');
-const url = require('url');
-const { EventEmitter } = require('events');
-const crypto = require('crypto');
-
-const emitter = new EventEmitter();
-const sessions = new Map();  // Simple session store
-
-const server = http.createServer(handleRequest);
-server.listen(8000, '127.0.0.1', () => console.log('MCP Server on http://127.0.0.1:8000'));
-
-const tools = {
-  echo: async (params) => `Echo: ${params.message}`,
-};
-
-async function dispatchMethod(method, params, id, sessionId) {
-  if (tools[method]) {
-    try {
-      const result = await tools[method](params);
-      emitter.emit('push', { sessionId, eventId: Date.now(), data: { jsonrpc: '2.0', result, id } });
-      return { jsonrpc: '2.0', result, id };
-    } catch (e) {
-      return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
-    }
-  }
-  return { jsonrpc: '2.0', error: { code: -32601, message: 'Method Not Found' }, id };
-}
-
-function handleRequest(req, res) {
-  // ... (as in steps above)
-  // Integrate dispatchMethod, handlePost, handleSSE
-}
-
-function handlePost(req, res, emitter) {
-  // ... (as in steps above)
-}
-
-function handleSSE(req, res, emitter) {
-  // ... (as in steps above)
-}
-
-function generateSessionId() {
-  return crypto.randomUUID();
-}
-```
-- **Test**: POST to `/mcp` with JSON-RPC (e.g., via curl: `curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"echo","params":{"message":"hi"},"id":1}' http://localhost:8000/mcp`); GET `/mcp` for SSE. Config client: `{"url": "http://localhost:8000/mcp"}`.
-
-For HTTPS or advanced deployment (e.g., PM2), extend with `https` module.
-
-</details>
-
----

package/docs/visual-overview.md

@@ -1,21 +0,0 @@
-# dcli visual overview
-
-The architecture blueprint for dcli lives in the self-contained HTML artifact generated via the `visual-explainer` plugin.
-
-- **File**: `~/.agent/diagrams/dcli-visual-architecture.html`
-- **Open**: `xdg-open ~/.agent/diagrams/dcli-visual-architecture.html`
-- **Source**: Created with `supercli skills get visual-explainer:visual-explainer.skill` guidance.
-
-## What the HTML covers
-
-1. **Skill routing pipeline** – Mermaid snapshot of `cli/supercli.js`, the skills catalog, plugin harness manager, server APIs, and adapters. Includes zoom, pan, and expand controls per the visual-explainer requirements.
-2. **Runtime pillars** – Card grid summarizing the CLI runtime, catalog, plugin manager, and Express backend with file references such as `cli/plugins-manager.js` and `server/app.js`.
-3. **Plugin & skill lifecycle** – Timeline of registry discovery → install → catalog sync → execution, tying back to commands like `supercli skills list --catalog`.
-4. **Capability matrix** – HTML table comparing bundled harnesses, built-in adapters, remote providers, and the server API, highlighting when to use commands such as `supercli sync`.
-5. **Operational cues** – Details blocks that document behaviors like plan building and storage fallbacks.
-
-## Regenerating or extending
-
-1. Ensure the `visual-explainer` provider is installed (`supercli plugins install visual-explainer`).
-2. Re-open the reference templates (`visual-explainer:visual-explainer.templates.architecture`, `...templates.data-table`, etc.) to stay within the mandated aesthetics.
-3. Update the HTML under `~/.agent/diagrams/` and refresh this markdown with any new sections you add. Keep this file as the only place in the repo that references the artifact’s path.

package/ref-monty/.cargo/config.toml

@@ -1,3 +0,0 @@
-[env]
-# Use the project's venv Python for PyO3 builds
-PYO3_PYTHON = { value = ".venv/bin/python3", relative = true }

package/ref-monty/.claude/settings.json

@@ -1,60 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(cargo:*)",
-      "Bash(timeout 30s cargo:*)",
-      "Bash(timeout 10s cargo:*)",
-      "Bash(timeout 15s cargo:*)",
-      "Bash(RUST_BACKTRACE=1 cargo:*)",
-      "Bash(make:*)",
-      "Bash(INLINE_SNAPSHOT_DEFAULT_FLAGS=disable make:*)",
-      "Bash(mkdir:*)",
-      "Bash(uv:*)",
-      "Bash(echo:*)",
-      "Bash(rg:*)",
-      "Bash(sed:*)",
-      "Bash(grep:*)",
-      "Bash(fastmod:*)",
-      "Bash(find:*)",
-      "Bash(ls:*)",
-      "Bash(cat:*)",
-      "Bash(python3:*)",
-      "Bash(git show:*)",
-      "Bash(git diff:*)",
-      "Bash(git add:*)",
-      "Bash(git stash:*)",
-      "Bash(git checkout:*)",
-      "Bash(git mv:*)",
-      "Bash(git log:*)",
-      "Bash(git grep:*)",
-      "Bash(git status:*)",
-      "Bash(gh pr view:*)",
-      "Bash(gh api:*)",
-      "Bash(gh run view:*)",
-      "Bash(gh issue view:*)",
-      "Skill(python-playground)",
-      "Skill(fastmod)",
-      "Skill(coverage)",
-      "Bash(wc:*)",
-      "Bash(xxd:*)",
-      "Bash(head:*)",
-      "Bash(rustup show:*)",
-      "Bash(xargs:*)",
-      "Bash(perl:*)",
-      "Bash(du:*)",
-      "Bash(npm run:*)",
-      "Bash(mkdir:*)",
-      "WebSearch",
-      "WebFetch(domain:pypi.org)",
-      "WebFetch(domain:docs.anthropic.com)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:15r10nk.github.io)",
-      "WebFetch(domain:docs.rs)",
-      "WebFetch(domain:pyo3.rs)",
-      "WebFetch(domain:napi.rs)",
-      "WebFetch(domain:app.codecov.io)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/ref-monty/.claude/skills/fastmod/SKILL.md

@@ -1,22 +0,0 @@
----
-name: fastmod
-description: Use fastmod to make mass code updates to avoid many repetitive changes.
----
-
-# fastmod
-
-## Instructions
-
-You can occasionally use `fastmod` or `sed` to make mass updates to the codebase and avoid wasting tokens changing each case one at a time.
-
-Before making many repetitive changes to the codebase, consider using `fastmod --accept-all`.
-
-THINK HARD about how best to use `fastmod` as it can dramatically improve your productivity.
-
-## Examples
-
-Example of switching the `py_type` function to use `impl ResourceTracker` instead of `T: ResourceTracker`:
-
-```bash
-fastmod --accept-all 'fn py_type<T: ResourceTracker>(\(.+?)<T>' 'fn py_type$1<impl ResourceTracker>'
-```

package/ref-monty/.claude/skills/python-playground/SKILL.md

@@ -1,47 +0,0 @@
----
-name: python-playground
-description: Run and test Python code in a dedicated playground directory. Use when you need to execute Python scripts, test code snippets, investigate CPython behavior, or experiment with Python without affecting the main codebase.
----
-
-# Python Playground
-
-Run Python code in an isolated playground directory for testing and experimentation.
-
-## Instructions
-
-1. First, ensure the playground directory exists: `mkdir -p playground`
-2. Use the Write tool to create the Python file at `playground/test.py`
-3. Run with: `uv run playground/test.py` to test cpython behavior or `cargo run -- playground/test.py` to test monty behavior
-
-IMPORTANT: Use separate tool calls for each step - do NOT chain commands with `&&` or use heredocs. This allows the pre-approved commands to work without prompting.
-
-## Example workflow
-
-Step 1 - Create directory (Bash, already allowed):
-```bash
-mkdir -p playground
-```
-
-Step 2 - Write code (use Write tool, not cat):
-Write to `playground/test.py`:
-```python
-def foo():
-    raise ValueError('test')
-
-foo()
-```
-
-Step 3 - Run script (Bash, already allowed):
-```bash
-uv run playground/test.py
-```
-
-## Guidelines
-
-- The `playground/` directory is gitignored
-- Use a different file name for each test you want to run, give the files recognizable names like `test_value_error.py`
-- Use `uv run ...` to run scripts (uses project Python)
-- Or, `cargo run -- ...` to run scripts using Monty
-- Use Write tool for creating files (avoids permission prompts)
-- Run mkdir and uv as separate commands (not chained)
-- do NOT delete files from playground after you've finished testing

package/ref-monty/.codecov.yml

@@ -1,12 +0,0 @@
-codecov:
-  require_ci_to_pass: false
-
-coverage:
-  precision: 2
-  # range: [90, 100]
-  status:
-    patch: false
-    project: false
-
-comment:
-  layout: 'header, diff, flags, files, footer'

package/ref-monty/.github/actions/build-pgo-wheel/action.yml

@@ -1,72 +0,0 @@
-name: Build PGO wheel
-description: Builds a PGO-optimized wheel for pydantic-monty
-
-inputs:
-  interpreter:
-    description: 'Interpreter(s) to build the wheel for'
-    required: true
-  rust-toolchain:
-    description: 'Rust toolchain to use'
-    required: true
-
-outputs:
-  wheel-dir:
-    description: 'Path to the directory containing built wheels'
-    value: ${{ steps.find_wheel.outputs.dir }}
-
-runs:
-  using: "composite"
-  steps:
-    - name: prepare profiling directory
-      shell: bash
-      run: mkdir -p ${{ github.workspace }}/profdata
-
-    - name: build initial wheel (instrumented)
-      uses: PyO3/maturin-action@v1
-      with:
-        manylinux: auto
-        args: >
-          --release
-          --out pgo-wheel
-          --interpreter 3.12
-        rust-toolchain: ${{ inputs.rust-toolchain }}
-        docker-options: -e CI
-        working-directory: crates/monty-python
-      env:
-        RUSTFLAGS: '-Cprofile-generate=${{ github.workspace }}/profdata'
-
-    - name: detect rust host
-      run: echo RUST_HOST=$(rustc -Vv | grep host | cut -d ' ' -f 2) >> "$GITHUB_ENV"
-      shell: bash
-
-    - name: generate pgo data
-      run: |
-        pip install pydantic-monty --no-index --no-deps --find-links pgo-wheel --force-reinstall
-        python exercise.py
-        rustup run ${{ inputs.rust-toolchain }} bash -c 'echo LLVM_PROFDATA=$RUSTUP_HOME/toolchains/$RUSTUP_TOOLCHAIN/lib/rustlib/$RUST_HOST/bin/llvm-profdata >> "$GITHUB_ENV"'
-      shell: bash
-      working-directory: crates/monty-python
-
-    - name: merge pgo data
-      # PowerShell handles paths on Windows better, and works well enough on Unix
-      run: ${{ env.LLVM_PROFDATA }} merge -o ${{ github.workspace }}/merged.profdata ${{ github.workspace }}/profdata
-      shell: pwsh
-
-    - name: build pgo-optimized wheel
-      uses: PyO3/maturin-action@v1
-      with:
-        manylinux: auto
-        args: >
-          --release
-          --out dist
-          --interpreter ${{ inputs.interpreter }}
-        rust-toolchain: ${{ inputs.rust-toolchain }}
-        docker-options: -e CI
-        working-directory: crates/monty-python
-      env:
-        RUSTFLAGS: '-Cprofile-use=${{ github.workspace }}/merged.profdata'
-
-    - name: find built wheels
-      id: find_wheel
-      run: echo "dir=crates/monty-python/dist" >> "$GITHUB_OUTPUT"
-      shell: bash