From 07c434a969b4031012a54989bf5760d9c402b9eb Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 20 Jun 2026 12:50:31 -0700 Subject: [PATCH] Add Codex plugin metadata --- .agents/plugins/marketplace.json | 20 ++++++++++ README.md | 26 +++++++++---- plugins/sidemantic/.codex-plugin/plugin.json | 39 +++++++++++++++++++ .../sidemantic/skills/webapp-builder/SKILL.md | 22 ++++++----- .../references/webapp-patterns.md | 12 +++--- .../scripts/verify_static_interactions.mjs | 4 +- 6 files changed, 97 insertions(+), 26 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 plugins/sidemantic/.codex-plugin/plugin.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 00000000..8520b595 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "sidequery", + "interface": { + "displayName": "Sidequery" + }, + "plugins": [ + { + "name": "sidemantic", + "source": { + "source": "local", + "path": "./plugins/sidemantic" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Data & Analytics" + } + ] +} diff --git a/README.md b/README.md index ffb51cf8..9597b624 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ The universal metrics layer for consistent metrics across your data stack. Compa ![Jupyter Widget Preview](preview.png) -Sidemantic ships a Claude Code plugin with two skills (`modeler` and `webapp-builder`). See [Agent Plugin](#agent-plugin) below to install. +Sidemantic ships Claude Code and Codex plugin metadata for two skills (`modeler` and `webapp-builder`). See [Agent Plugin](#agent-plugin) below to install. ## Quickstart @@ -375,25 +375,35 @@ curl -s http://localhost:4400/sql \ ## Agent Plugin -Sidemantic ships a [Claude Code plugin](plugins/sidemantic/) with two skills: +Sidemantic ships a [plugin bundle](plugins/sidemantic/) with Claude Code and Codex metadata for two skills: -- **`modeler`** — build, validate, and query semantic models (`/sidemantic:modeler`) -- **`webapp-builder`** — generate analytics webapps from your models (`/sidemantic:webapp-builder`) +- **`modeler`** — build, validate, and query semantic models +- **`webapp-builder`** — generate analytics webapps from your models **Install in Claude Code:** +```bash +claude plugin marketplace add sidequery/sidemantic && claude plugin install sidemantic@sidequery ``` -/plugin marketplace add sidequery/sidemantic -/plugin install sidemantic@sidequery + +**Install in Codex:** + +```bash +codex plugin marketplace add sidequery/sidemantic && codex plugin add sidemantic@sidequery ``` -**Try it locally without installing** (from a clone): +**Use a local clone while developing:** ```bash claude --plugin-dir ./plugins/sidemantic +codex plugin marketplace add . && codex plugin add sidemantic@sidequery ``` -The skills also work with Codex and other `SKILL.md`-compatible agents by pointing them at `plugins/sidemantic/skills/`. +The Claude Code plugin manifest lives at `plugins/sidemantic/.claude-plugin/plugin.json`, and its marketplace lives at `.claude-plugin/marketplace.json`. + +The Codex plugin manifest lives at `plugins/sidemantic/.codex-plugin/plugin.json`, and its repo-local marketplace lives at `.agents/plugins/marketplace.json`. + +The skills also work with other `SKILL.md`-compatible agents by pointing them at `plugins/sidemantic/skills/`. ## How mature is Sidemantic? diff --git a/plugins/sidemantic/.codex-plugin/plugin.json b/plugins/sidemantic/.codex-plugin/plugin.json new file mode 100644 index 00000000..eda34622 --- /dev/null +++ b/plugins/sidemantic/.codex-plugin/plugin.json @@ -0,0 +1,39 @@ +{ + "name": "sidemantic", + "description": "Build, validate, and query Sidemantic semantic models, and generate analytics webapps from them.", + "version": "1.0.0", + "author": { + "name": "Sidemantic", + "email": "hello@sidemantic.com", + "url": "https://sidemantic.com" + }, + "homepage": "https://sidemantic.com", + "repository": "https://github.com/sidequery/sidemantic", + "license": "Apache-2.0", + "keywords": [ + "analytics", + "semantic-layer", + "sql", + "dashboard" + ], + "skills": "./skills/", + "interface": { + "displayName": "Sidemantic", + "shortDescription": "Model metrics and build analytics webapps from semantic SQL.", + "longDescription": "Sidemantic helps Codex build, validate, query, and migrate SQL-first semantic models, then turn those models into analytics dashboards and app surfaces.", + "developerName": "Sidemantic", + "category": "Data & Analytics", + "capabilities": [ + "Semantic modeling", + "SQL generation", + "Analytics webapps" + ], + "websiteURL": "https://sidemantic.com", + "defaultPrompt": [ + "Create a Sidemantic model from my schema.", + "Validate these metrics and dimensions.", + "Build a dashboard from my Sidemantic models." + ], + "brandColor": "#2563EB" + } +} diff --git a/plugins/sidemantic/skills/webapp-builder/SKILL.md b/plugins/sidemantic/skills/webapp-builder/SKILL.md index f5b42728..cfdd5ea7 100644 --- a/plugins/sidemantic/skills/webapp-builder/SKILL.md +++ b/plugins/sidemantic/skills/webapp-builder/SKILL.md @@ -7,6 +7,8 @@ description: Build interactive analytics webapps, demos, dashboards, or embedded Build webapps around a validated Sidemantic semantic layer. Default to project-owned source components copied from this skill, then adapt them to the target app and wire them to inspected Sidemantic query contracts. +In command examples, set `SIDEMANTIC_PLUGIN_ROOT` to the installed `sidemantic` plugin directory. + ## Component-First Pattern Treat `assets/components/` like a small shadcn-style source library for analytics primitives. Copy components into the target project, then edit those copied files as normal app code. Do not retype component source into the answer or keep it as a hidden runtime dependency. @@ -14,7 +16,7 @@ Treat `assets/components/` like a small shadcn-style source library for analytic Copy React + Tailwind components for product apps: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ --kind react-tailwind \ --target src/components/sidemantic ``` @@ -22,7 +24,7 @@ uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ Copy the static component files for plain HTML demos or generated scaffolds: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ --kind static \ --target public/sidemantic-components ``` @@ -59,7 +61,7 @@ Use those static helpers before writing one-off DOM wiring. They are intentional ```bash uv run sidemantic info path/to/models -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \ --db path/to/data.duckdb \ --require-execute ``` @@ -67,7 +69,7 @@ uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path 2. Generate an app inventory: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \ --db path/to/data.duckdb \ --require-execute \ --output docs/sidemantic-app-spec.json @@ -78,7 +80,7 @@ Use `--leaderboard-dimension field_name` when domain judgment says one dimension 3. Copy component source into the project before building UI: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ --kind react-tailwind \ --target src/components/sidemantic ``` @@ -88,7 +90,7 @@ Adapt imports, class names, and styling conventions after copying. Preserve the For a minimal static app scaffold from the executed spec: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/scaffold_static_app.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/scaffold_static_app.py \ docs/sidemantic-app-spec.json \ --output dist/sidemantic-dashboard \ --title "Metrics Dashboard" @@ -131,10 +133,10 @@ If a control is visible, it must change the app state or data. Do not satisfy in ```bash uv run sidemantic info path/to/models -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models --db path/to/data.duckdb --require-execute +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models --db path/to/data.duckdb --require-execute uv run sidemantic query "SELECT metric_name FROM model_name LIMIT 5" --models path/to/models --db path/to/data.duckdb -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_app.py dist/sidemantic-dashboard -bunx --bun -p playwright node ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:5174/ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_app.py dist/sidemantic-dashboard +bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:5174/ bun run build ``` @@ -152,7 +154,7 @@ For static dashboards that use the bundled component contracts, use the smoke-te ```bash bunx --bun -p playwright playwright install chromium # first run only, if Playwright reports a missing browser -bunx --bun -p playwright node ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs \ +bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs \ --url http://127.0.0.1:4519/ ``` diff --git a/plugins/sidemantic/skills/webapp-builder/references/webapp-patterns.md b/plugins/sidemantic/skills/webapp-builder/references/webapp-patterns.md index 564dc768..4f9087dc 100644 --- a/plugins/sidemantic/skills/webapp-builder/references/webapp-patterns.md +++ b/plugins/sidemantic/skills/webapp-builder/references/webapp-patterns.md @@ -7,7 +7,7 @@ Use this reference when implementing the concrete UI/data layer after the skill Default to copied component source instead of regenerating dashboard primitives. Copy from the skill, then edit the copied files inside the target project: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ --kind react-tailwind \ --target src/components/sidemantic ``` @@ -15,7 +15,7 @@ uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ For static or no-build demos: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \ --kind static \ --target dist/sidemantic-dashboard ``` @@ -182,7 +182,7 @@ CLI path: ```bash uv run sidemantic info models -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py models --db data.duckdb --require-execute +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py models --db data.duckdb --require-execute uv run sidemantic query "SELECT revenue, status FROM orders" --models models --db data.duckdb ``` @@ -206,7 +206,7 @@ For static apps that follow the bundled component contracts, run: ```bash bunx --bun -p playwright playwright install chromium # first run only, if needed -bunx --bun -p playwright node ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs \ +bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs \ --url http://127.0.0.1:4519/ ``` @@ -224,10 +224,10 @@ Fallback when browser tooling is unavailable: For a quick working artifact from an executed spec: ```bash -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/scaffold_static_app.py docs/sidemantic-app-spec.json \ +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/scaffold_static_app.py docs/sidemantic-app-spec.json \ --output dist/sidemantic-dashboard \ --title "Metrics Dashboard" -uv run ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_app.py dist/sidemantic-dashboard +uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_app.py dist/sidemantic-dashboard ``` The scaffold intentionally stays plain HTML/CSS/JS and consumes copied files from `assets/templates/static-dashboard/` plus the static component files. Use it as a proof point, demo baseline, or fixture before adapting the same query contract into an existing product app. diff --git a/plugins/sidemantic/skills/webapp-builder/scripts/verify_static_interactions.mjs b/plugins/sidemantic/skills/webapp-builder/scripts/verify_static_interactions.mjs index e712fa67..e0319861 100644 --- a/plugins/sidemantic/skills/webapp-builder/scripts/verify_static_interactions.mjs +++ b/plugins/sidemantic/skills/webapp-builder/scripts/verify_static_interactions.mjs @@ -2,7 +2,7 @@ // Browser smoke tests for Sidemantic static dashboards. // // Run with Playwright available, for example: -// bunx --bun -p playwright node ${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:4519/ +// bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:4519/ import process from "node:process"; @@ -30,7 +30,7 @@ function parseArgs(argv) { function usage() { return `Usage: - bunx --bun -p playwright node \${CLAUDE_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:4519/ + bunx --bun -p playwright node \${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:4519/ Options: --url App URL to test.