Merge pull request #14 from deeleeramone/claude/fervent-shamir-84a4fd

Add Claude Code Plugin

Author: deeleeramone

.github/workflows/plugin-manifest.yml

@@ -0,0 +1,126 @@
+name: Claude plugin manifests
+
+on:
+  pull_request:
+    paths:
+      - 'claude/**'
+      - '.github/workflows/plugin-manifest.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'claude/**'
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate plugin manifests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so the CHANGELOG-diff check below can reach the
+          # PR base without needing to re-fetch.
+          fetch-depth: 0
+
+      - name: Check manifests parse and versions match
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 <<'PY'
+          import json, sys, pathlib
+
+          repo = pathlib.Path(".")
+          marketplace = repo / "claude" / ".claude-plugin" / "marketplace.json"
+          if not marketplace.exists():
+              sys.exit(f"::error::{marketplace} missing")
+          try:
+              mk = json.loads(marketplace.read_text(encoding="utf-8"))
+          except json.JSONDecodeError as e:
+              sys.exit(f"::error file={marketplace}::invalid JSON: {e}")
+
+          plugins = mk.get("plugins") or []
+          if not plugins:
+              sys.exit(f"::error file={marketplace}::no plugins listed")
+
+          failures = []
+          for entry in plugins:
+              name = entry.get("name")
+              source = entry.get("source", "")
+              entry_version = entry.get("version")
+              if not name or not source or not entry_version:
+                  failures.append(f"{entry}: missing name/source/version")
+                  continue
+              if not isinstance(source, str) or not source.startswith("./"):
+                  failures.append(f"{name}: source must be a './plugins/...' relative path")
+                  continue
+              plugin_root = (repo / "claude" / source[2:]).resolve()
+              if not plugin_root.exists():
+                  failures.append(f"{name}: source path does not exist: {plugin_root}")
+                  continue
+              pj = plugin_root / ".claude-plugin" / "plugin.json"
+              if not pj.exists():
+                  failures.append(f"{name}: missing {pj}")
+                  continue
+              try:
+                  pm = json.loads(pj.read_text(encoding="utf-8"))
+              except json.JSONDecodeError as e:
+                  failures.append(f"{name}: {pj} invalid JSON: {e}")
+                  continue
+              if pm.get("version") != entry_version:
+                  failures.append(
+                      f"{name}: version mismatch — plugin.json={pm.get('version')!r}, "
+                      f"marketplace.json={entry_version!r}"
+                  )
+              if pm.get("name") != name:
+                  failures.append(
+                      f"{name}: plugin.json name={pm.get('name')!r} != "
+                      f"marketplace entry name={name!r}"
+                  )
+              # .mcp.json must parse if present
+              mcp = plugin_root / ".mcp.json"
+              if mcp.exists():
+                  try:
+                      json.loads(mcp.read_text(encoding="utf-8"))
+                  except json.JSONDecodeError as e:
+                      failures.append(f"{name}: {mcp} invalid JSON: {e}")
+              # hooks.json must parse if present
+              hooks = plugin_root / "hooks" / "hooks.json"
+              if hooks.exists():
+                  try:
+                      json.loads(hooks.read_text(encoding="utf-8"))
+                  except json.JSONDecodeError as e:
+                      failures.append(f"{name}: {hooks} invalid JSON: {e}")
+
+          if failures:
+              for f in failures:
+                  print(f"::error::{f}")
+              sys.exit(1)
+          print(f"ok — {len(plugins)} plugin(s) validated")
+          PY
+
+      - name: Check CHANGELOG was updated when plugin.json version changes
+        if: github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          set -euo pipefail
+          base_sha="${{ github.event.pull_request.base.sha }}"
+          # Two-dot diff: list files that differ between the PR base and
+          # HEAD without needing a merge-base. fetch-depth: 0 above makes
+          # both commits available locally.
+          changed=$(git diff --name-only "$base_sha" HEAD -- 'claude/plugins/*/.claude-plugin/plugin.json')
+          if [[ -z "$changed" ]]; then
+            echo "No plugin.json changes — nothing to check."
+            exit 0
+          fi
+          missing=0
+          for pj in $changed; do
+            plugin_dir=$(dirname "$(dirname "$pj")")
+            changelog="$plugin_dir/CHANGELOG.md"
+            if ! git diff --name-only "$base_sha" HEAD -- "$changelog" | grep -q .; then
+              echo "::error file=$changelog::CHANGELOG.md not updated alongside $pj"
+              missing=1
+            fi
+          done
+          exit $missing

.gitignore

@@ -213,3 +213,4 @@ docs/site/*
 # Generated frontend assets (downloaded by pywry/build_assets.py at build/install time)
 pywry/pywry/frontend/assets/*.js.gz
 pywry/pywry/frontend/assets/*.css.gz
+.hatch_build/

README.md

@@ -1,6 +1,9 @@
 <div align="center">
 
-![PyWry](https://github.com/deeleeramone/PyWry/blob/82db0c977a8ec812bf8652c0be14bf62b66b66a1/pywry/pywry/frontend/assets/PyWry.png?raw=true)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="pywry/pywry/frontend/assets/PyWry-dark.svg">
+  <img src="pywry/pywry/frontend/assets/PyWry-light.svg" alt="PyWry" width="640">
+</picture>
 
 </div>
 
@@ -12,6 +15,12 @@ PyWry is a cross-platform rendering engine and desktop UI toolkit for Python. On
 
 **Build Once, Render Anywhere:** Prototype interactive data apps in a Jupyter Notebook, easily deploy them as web apps, and seamlessly compile them into secure, lightweight standalone desktop executables via `pywry[freeze]`.
 
+<div align="center">
+
+![PyWry — live TradingView chart driving a streaming chat widget](pywry_tv_chat_screencap_lg.gif)
+
+</div>
+
 ## Installation
 
 Python 3.10–3.14, virtual environment recommended.
@@ -128,7 +137,43 @@ pip install 'pywry[mcp]'
 pywry mcp --transport stdio
 ```
 
-See the [MCP docs](https://deeleeramone.github.io/PyWry/mcp/) for Claude Desktop setup and tool reference.
+Widget-creating tools — `create_widget`, `show_plotly`, `show_dataframe`, `show_tvchart`, `create_chat_widget` — return an **`AppArtifact`**: a self-contained HTML snapshot delivered as an MCP `EmbeddedResource` with `mimeType: text/html` and URI `pywry-app://<widget_id>/<revision>`. Clients that render HTML resources (Claude Desktop's artifact pane, mcp-ui clients, PyWry's own chat widget) show the app inline.
+
+Each render bumps a per-widget revision. The latest revision keeps a live WebSocket bridge to Python; older revisions freeze at their last known state. Call `get_widget_app(widget_id)` to re-snapshot after a mutation.
+
+See the [MCP docs](https://deeleeramone.github.io/PyWry/mcp/) for tool reference and client setup.
+
+## Claude Code Plugin
+
+Installable under [`claude/plugins/pywry/`](claude/plugins/pywry/) as one `/plugin install` unit. Ships:
+
+- **MCP server** — same 66 tools as above, auto-connected
+- **`pywry-orientation` skill** — teaches the agent when to reach for PyWry tools
+- **Slash commands** — `/pywry:doctor`, `/pywry:scaffold`, `/pywry:examples`
+- **`pywry-builder` subagent** — for multi-step widget construction
+- **Post-edit hook** — runs `ruff format` on touched `.py` files
+
+**Install:**
+
+```
+/plugin marketplace add deeleeramone/PyWry --path claude/.claude-plugin/marketplace.json
+/plugin install pywry@pywry
+```
+
+**Prerequisite:** `pip install 'pywry[dev]'` (or `pywry[all]`). Then `/pywry:doctor` to verify.
+
+**PyPI-bundled install** (skips the GitHub round-trip once pywry is already installed):
+
+```bash
+pywry plugin-path          # prints the bundled plugin root
+```
+
+```
+/plugin marketplace add $(pywry plugin-path)
+/plugin install pywry@pywry
+```
+
+See [claude/README.md](claude/README.md) for the full install-path matrix, mono-repo layout, and versioning policy.
 
 ## Standalone Executables
 

claude/.claude-plugin/marketplace.json

@@ -0,0 +1,47 @@
+{
+  "name": "pywry",
+  "owner": {
+    "name": "PyWry",
+    "email": "pywry2@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "pywry",
+      "source": "./plugins/pywry/",
+      "description": "Native Claude Code integration for PyWry — MCP tools for generating and rendering HTML components, chat artifacts, and building native, web, or Jupyter applications with live preview. Built-in support for AgGrid, Plotly, TradingView, and more.",
+      "version": "0.1.0",
+      "author": {
+        "name": "PyWry",
+        "email": "pywry2@gmail.com",
+        "url": "https://github.com/deeleeramone/PyWry"
+      },
+      "license": "Apache-2.0",
+      "homepage": "https://github.com/deeleeramone/PyWry",
+      "repository": "https://github.com/deeleeramone/PyWry",
+      "category": "data-visualization",
+      "keywords": [
+        "pywry",
+        "webview",
+        "tauri",
+        "plotly",
+        "tradingview",
+        "aggrid",
+        "dashboard",
+        "charting",
+        "visualization",
+        "data-science",
+        "finance",
+        "interactive",
+        "real-time",
+        "chat",
+        "llm",
+        "agent",
+        "artifact",
+        "jupyter",
+        "notebook",
+        "python",
+        "mcp"
+      ]
+    }
+  ]
+}

claude/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing to the PyWry Claude Code plugin
+
+This document covers the mechanics of changing anything under `claude/`.
+For general PyWry development see the top-level [CLAUDE.md](../CLAUDE.md)
+and the PyWry contributing guide.
+
+## What lives here
+
+- **`claude/.claude-plugin/marketplace.json`** — the single, canonical
+  marketplace manifest for this repo. It lists every plugin under
+  `claude/plugins/*`. Discovered automatically when a Claude Code user
+  adds `deeleeramone/PyWry --path claude/.claude-plugin/marketplace.json`
+  as a marketplace.
+- **`claude/plugins/<name>/`** — one plugin each. Every plugin has its
+  own `.claude-plugin/plugin.json`, `.mcp.json`, assets, CHANGELOG, and
+  README.
+
+## Versioning
+
+Every plugin follows [semver](https://semver.org/) independently of the
+PyWry Python package.
+
+| Bump | When |
+|---|---|
+| **Patch** (0.1.0 → 0.1.1) | Bug fixes, doc tweaks, tightening a skill, renaming an internal helper |
+| **Minor** (0.1.0 → 0.2.0) | New slash command, new skill, new subagent, new hook, new MCP tool surfaced |
+| **Major** (0.1.0 → 1.0.0) | Renaming the plugin, changing the marketplace name, removing a command/skill/tool, bumping the minimum required PyWry version |
+
+The version appears in **two** places and they **must match**:
+
+1. `claude/plugins/<name>/.claude-plugin/plugin.json` → `version`
+2. `claude/.claude-plugin/marketplace.json` → `plugins[…].version`
+
+CI ([.github/workflows/plugin-manifest.yml](../.github/workflows/plugin-manifest.yml))
+fails PRs that leave those out of sync or change any `claude/plugins/<name>/`
+file without bumping the plugin's version.
+
+## Release checklist
+
+Use [RELEASING.md](plugins/pywry/RELEASING.md) for the step-by-step —
+summary below:
+
+1. Land all pending changes on `main`.
+2. Bump the version in both manifest files.
+3. Update `claude/plugins/<name>/CHANGELOG.md` with the release notes
+   (keep a `## [Unreleased]` section at the top).
+4. Commit with a message like
+   `Release claude/plugins/pywry v0.2.0`.
+5. Tag:
+   ```bash
+   git tag -a plugin-pywry-v0.2.0 -m "pywry plugin v0.2.0"
+   git push origin plugin-pywry-v0.2.0
+   ```
+6. Users pin with `/plugin install pywry@pywry --version plugin-pywry-v0.2.0`
+   to avoid tracking `main`.
+
+## Adding a new plugin
+
+```
+claude/plugins/<new-plugin-name>/
+├── .claude-plugin/
+│   └── plugin.json           # {name, version, description, author, ...}
+├── .mcp.json                 # (optional) MCP server declaration
+├── agents/                   # (optional)
+├── commands/                 # (optional)
+├── hooks/                    # (optional)
+├── skills/                   # (optional)
+├── README.md
+└── CHANGELOG.md
+```
+
+Then append an entry to `claude/.claude-plugin/marketplace.json`:
+
+```json
+{
+  "name": "<new-plugin-name>",
+  "source": "./plugins/<new-plugin-name>/",
+  "description": "...",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/deeleeramone/PyWry",
+  "keywords": ["..."]
+}
+```
+
+CI will reject the PR if:
+
+- `.claude-plugin/plugin.json` or `.mcp.json` is malformed JSON.
+- The plugin version in the plugin manifest doesn't match the
+  marketplace entry.
+- A referenced skill/command/agent/hook file is missing.
+- Any `source` path in `marketplace.json` doesn't exist on disk.
+
+## Running the plugin locally during development
+
+```bash
+# From the repo root, in the worktree or main checkout:
+pip install -e './pywry[dev]'                                    # install worktree pywry
+/plugin marketplace add $(pwd)/claude                            # absolute path
+/plugin install pywry@pywry
+```
+
+Then `/pywry:doctor` to verify.