opencodekit 0.8.0 → 0.9.1

package/dist/template/.opencode/skill/figma/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: figma
+description: Access Figma design data via Framelink MCP. Fetch layout, styles, components from Figma files/frames. Use when implementing UI from Figma designs, extracting design tokens, or downloading assets.
+mcp:
+  figma:
+    command: npx
+    args: ["-y", "figma-developer-mcp", "--stdio"]
+    env:
+      FIGMA_API_KEY: "${FIGMA_API_KEY}"
+---
+
+# Figma Design Data (MCP)
+
+Access Figma design data via the Framelink MCP server. When this skill is loaded, the `figma` MCP server auto-starts and exposes tools to fetch design data and download images.
+
+## Prerequisites
+
+Set your Figma API key as an environment variable:
+
+```bash
+export FIGMA_API_KEY="your-figma-personal-access-token"
+```
+
+To create a Figma Personal Access Token:
+
+1. Go to Figma → Settings → Account → Personal access tokens
+2. Create a new token with read access
+3. See: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke Figma tools:
+
+```
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "1234:5678"}')
+```
+
+## Available Tools
+
+### get_figma_data
+
+Fetch comprehensive Figma file data including layout, content, visuals, and component information.
+
+| Parameter | Type   | Required | Description                                                                                       |
+| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `fileKey` | string | Yes      | The Figma file key (from URL: `figma.com/file/<fileKey>/...` or `figma.com/design/<fileKey>/...`) |
+| `nodeId`  | string | No       | Specific node ID (from URL param `node-id=<nodeId>`). Format: `1234:5678` or `1234-5678`          |
+| `depth`   | number | No       | Levels deep to traverse. Only use if explicitly requested by user.                                |
+
+**Returns:** YAML-formatted design data with:
+
+- `metadata` - File/node information
+- `nodes` - Simplified node tree with layout, styles, text content
+- `globalVars` - Shared styles and variables
+
+### download_figma_images
+
+Download SVG and PNG images/icons from a Figma file.
+
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `fileKey`   | string | Yes      | The Figma file key                            |
+| `nodes`     | array  | Yes      | Array of node objects to download (see below) |
+| `localPath` | string | Yes      | Absolute path to save images                  |
+| `pngScale`  | number | No       | Export scale for PNGs (default: 2)            |
+
+**Node object structure:**
+
+```json
+{
+  "nodeId": "1234:5678",
+  "fileName": "icon-name.svg",
+  "imageRef": "optional-for-image-fills"
+}
+```
+
+## Workflow
+
+### 1. Extract File Key and Node ID from Figma URL
+
+Figma URLs follow these patterns:
+
+- `https://www.figma.com/file/<fileKey>/<fileName>?node-id=<nodeId>`
+- `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>`
+
+Example: `https://www.figma.com/design/abc123xyz/MyDesign?node-id=1234-5678`
+
+- `fileKey`: `abc123xyz`
+- `nodeId`: `1234-5678` (or `1234:5678` - both formats work)
+
+### 2. Fetch Design Data
+
+```
+# Fetch specific frame/component
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz", "nodeId": "1234:5678"}')
+
+# Fetch entire file (use sparingly - can be large)
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz"}')
+```
+
+### 3. Download Assets (Optional)
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "abc123xyz",
+  "nodes": [
+    {"nodeId": "1234:5678", "fileName": "hero-image.png"},
+    {"nodeId": "5678:9012", "fileName": "icon-arrow.svg"}
+  ],
+  "localPath": "/absolute/path/to/assets"
+}')
+```
+
+## Examples
+
+### Implement a Component from Figma
+
+```
+# User provides: https://www.figma.com/design/abc123/Dashboard?node-id=100-200
+
+# 1. Fetch the design data
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "100-200"}')
+
+# 2. Review the returned YAML for:
+#    - Layout structure (flex, grid, spacing)
+#    - Typography (font, size, weight, line-height)
+#    - Colors (fills, strokes)
+#    - Dimensions and constraints
+
+# 3. Implement the component using the extracted data
+```
+
+### Extract Design Tokens
+
+```
+# Fetch a design system file
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "designSystemKey"}')
+
+# The globalVars section contains:
+# - Color styles
+# - Typography styles
+# - Effect styles (shadows, blurs)
+```
+
+### Download Icons
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "iconLibraryKey",
+  "nodes": [
+    {"nodeId": "10:20", "fileName": "icon-home.svg"},
+    {"nodeId": "10:30", "fileName": "icon-settings.svg"},
+    {"nodeId": "10:40", "fileName": "icon-user.svg"}
+  ],
+  "localPath": "/project/src/assets/icons",
+  "pngScale": 2
+}')
+```
+
+## Data Structure
+
+The `get_figma_data` tool returns simplified, AI-optimized data:
+
+```yaml
+metadata:
+  name: "Component Name"
+  lastModified: "2024-01-15T..."
+
+nodes:
+  - id: "1234:5678"
+    name: "Button"
+    type: "FRAME"
+    layout:
+      mode: "HORIZONTAL"
+      padding: { top: 12, right: 24, bottom: 12, left: 24 }
+      gap: 8
+    size: { width: 120, height: 48 }
+    fills:
+      - type: "SOLID"
+        color: { r: 0.2, g: 0.4, b: 1, a: 1 }
+    cornerRadius: 8
+    children:
+      - id: "1234:5679"
+        name: "Label"
+        type: "TEXT"
+        content: "Click me"
+        textStyle:
+          fontFamily: "Inter"
+          fontSize: 16
+          fontWeight: 600
+
+globalVars:
+  styles:
+    "S:abc123": { name: "Primary", fills: [...] }
+```
+
+## Tips
+
+- **Always use nodeId** when provided - fetching entire files is slow and context-heavy
+- **Node IDs with `-` or `:`** both work - the MCP handles conversion
+- **Check globalVars** for reusable styles before hardcoding values
+- **Use depth parameter sparingly** - only when explicitly needed
+- **For images/icons**, identify nodes with `imageRef` in the data for proper downloading
+- **SVG vs PNG**: Use `.svg` for icons/vectors, `.png` for photos/complex images
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `FIGMA_API_KEY` environment variable is set correctly.
+
+**"File not found"**: Verify the fileKey is correct and you have access to the file.
+
+**"Node not found"**: Check the nodeId format. Try both `1234:5678` and `1234-5678`.
+
+**Large response**: Use `nodeId` to fetch specific frames instead of entire files.

package/dist/template/.opencode/skill/playwright/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: playwright
+description: Browser automation with Playwright MCP. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows. Use when user wants to test websites or automate browser interactions.
+mcp:
+  playwright:
+    command: npx
+    args: ["@playwright/mcp@latest"]
+---
+
+# Playwright Browser Automation (MCP)
+
+Browser automation via Playwright MCP server. When this skill is loaded, the `playwright` MCP server auto-starts and exposes browser tools.
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke browser tools:
+
+```
+skill_mcp(mcp_name="playwright", tool_name="browser_navigate", arguments='{"url": "https://example.com"}')
+```
+
+## Available Tools
+
+### Navigation & Page
+
+| Tool                 | Description            | Arguments                           |
+| -------------------- | ---------------------- | ----------------------------------- |
+| `browser_navigate`   | Navigate to URL        | `{"url": "https://..."}`            |
+| `browser_go_back`    | Go back                | `{}`                                |
+| `browser_go_forward` | Go forward             | `{}`                                |
+| `browser_wait_for`   | Wait for text/selector | `{"text": "...", "timeout": 10000}` |
+
+### Interaction
+
+| Tool                    | Description               | Arguments                                                                          |
+| ----------------------- | ------------------------- | ---------------------------------------------------------------------------------- |
+| `browser_click`         | Click element             | `{"element": "Submit button", "ref": "e123"}`                                      |
+| `browser_type`          | Type text                 | `{"element": "Search input", "ref": "e456", "text": "query"}`                      |
+| `browser_fill`          | Fill input (clears first) | `{"element": "Email field", "ref": "e789", "text": "test@example.com"}`            |
+| `browser_select_option` | Select dropdown option    | `{"element": "Country", "ref": "e012", "values": ["US"]}`                          |
+| `browser_hover`         | Hover over element        | `{"element": "Menu", "ref": "e345"}`                                               |
+| `browser_drag`          | Drag and drop             | `{"startElement": "...", "startRef": "...", "endElement": "...", "endRef": "..."}` |
+
+### Screenshots & Content
+
+| Tool                      | Description                     | Arguments                              |
+| ------------------------- | ------------------------------- | -------------------------------------- |
+| `browser_take_screenshot` | Capture screenshot              | `{"filename": "screenshot.png"}`       |
+| `browser_snapshot`        | Get page accessibility snapshot | `{}`                                   |
+| `browser_evaluate`        | Run JavaScript                  | `{"function": "() => document.title"}` |
+| `browser_pdf_save`        | Save page as PDF                | `{"filename": "page.pdf"}`             |
+
+### Viewport & Device
+
+| Tool             | Description     | Arguments                                                    |
+| ---------------- | --------------- | ------------------------------------------------------------ |
+| `browser_resize` | Resize viewport | `{"width": 375, "height": 667}` or `{"device": "iPhone 13"}` |
+
+### Tabs
+
+| Tool                 | Description    | Arguments                |
+| -------------------- | -------------- | ------------------------ |
+| `browser_tab_list`   | List open tabs | `{}`                     |
+| `browser_tab_new`    | Open new tab   | `{"url": "https://..."}` |
+| `browser_tab_select` | Switch to tab  | `{"index": 0}`           |
+| `browser_tab_close`  | Close tab      | `{"index": 0}`           |
+
+## Workflow
+
+1. **Navigate** to the target URL
+2. **Snapshot** to see page structure and element refs
+3. **Interact** using element refs from snapshot
+4. **Screenshot** to capture results
+
+## Examples
+
+### Test a Page
+
+```
+# Navigate
+skill_mcp(mcp_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000"}')
+
+# Get page snapshot (shows elements with refs)
+skill_mcp(mcp_name="playwright", tool_name="browser_snapshot")
+
+# Take screenshot
+skill_mcp(mcp_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/homepage.png"}')
+```
+
+### Fill a Form
+
+```
+# Navigate to form
+skill_mcp(mcp_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000/contact"}')
+
+# Get snapshot to find element refs
+skill_mcp(mcp_name="playwright", tool_name="browser_snapshot")
+
+# Fill fields (use refs from snapshot)
+skill_mcp(mcp_name="playwright", tool_name="browser_fill", arguments='{"element": "Name input", "ref": "e12", "text": "John Doe"}')
+skill_mcp(mcp_name="playwright", tool_name="browser_fill", arguments='{"element": "Email input", "ref": "e34", "text": "john@example.com"}')
+
+# Submit
+skill_mcp(mcp_name="playwright", tool_name="browser_click", arguments='{"element": "Submit button", "ref": "e56"}')
+```
+
+### Test Responsive Design
+
+```
+# Navigate
+skill_mcp(mcp_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000"}')
+
+# Desktop
+skill_mcp(mcp_name="playwright", tool_name="browser_resize", arguments='{"width": 1920, "height": 1080}')
+skill_mcp(mcp_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/desktop.png"}')
+
+# Tablet
+skill_mcp(mcp_name="playwright", tool_name="browser_resize", arguments='{"device": "iPad Pro 11"}')
+skill_mcp(mcp_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/tablet.png"}')
+
+# Mobile
+skill_mcp(mcp_name="playwright", tool_name="browser_resize", arguments='{"device": "iPhone 13"}')
+skill_mcp(mcp_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/mobile.png"}')
+```
+
+### Test Login Flow
+
+```
+# Navigate to login
+skill_mcp(mcp_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000/login"}')
+
+# Snapshot to get refs
+skill_mcp(mcp_name="playwright", tool_name="browser_snapshot")
+
+# Fill credentials
+skill_mcp(mcp_name="playwright", tool_name="browser_fill", arguments='{"element": "Email", "ref": "e10", "text": "test@example.com"}')
+skill_mcp(mcp_name="playwright", tool_name="browser_fill", arguments='{"element": "Password", "ref": "e20", "text": "password123"}')
+
+# Click login
+skill_mcp(mcp_name="playwright", tool_name="browser_click", arguments='{"element": "Login button", "ref": "e30"}')
+
+# Wait for redirect
+skill_mcp(mcp_name="playwright", tool_name="browser_wait_for", arguments='{"text": "Dashboard", "timeout": 10000}')
+
+# Screenshot success
+skill_mcp(mcp_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/logged-in.png"}')
+```
+
+### Run JavaScript
+
+```
+# Get page title
+skill_mcp(mcp_name="playwright", tool_name="browser_evaluate", arguments='{"function": "() => document.title"}')
+
+# Get all links
+skill_mcp(mcp_name="playwright", tool_name="browser_evaluate", arguments='{"function": "() => Array.from(document.querySelectorAll(\"a\")).map(a => a.href)"}')
+
+# Scroll to bottom
+skill_mcp(mcp_name="playwright", tool_name="browser_evaluate", arguments='{"function": "() => window.scrollTo(0, document.body.scrollHeight)"}')
+```
+
+## Server Options
+
+For advanced usage, modify the MCP args in frontmatter:
+
+```yaml
+mcp:
+  playwright:
+    command: npx
+    args: ["@playwright/mcp@latest", "--headless", "--browser=firefox"]
+```
+
+Common options:
+
+- `--headless` - Run without visible browser
+- `--browser=chrome|firefox|webkit` - Choose browser
+- `--device="iPhone 13"` - Emulate device
+- `--viewport-size=1280x720` - Set viewport
+- `--user-data-dir=/path` - Persist browser data
+
+## Tips
+
+- **Always snapshot first** to get element refs before interacting
+- **Use descriptive element names** in click/fill for clarity
+- **Save screenshots to /tmp** for easy access
+- **Use device presets** for accurate mobile emulation
+- **Chain wait_for** after navigation for dynamic pages

package/dist/template/.opencode/skill/polar/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: polar
+description: Polar payment platform integration for monetization, subscriptions, and license keys. Use when implementing checkout, managing products, or building customer portals.
+---
+
+# Polar Integration
+
+Polar is a merchant-of-record platform for digital products, subscriptions, and license keys.
+
+## What I Do
+
+- Guide implementation of Polar checkout and payments
+- Help with subscription management and billing
+- Assist with license key validation
+- Set up webhook handlers for payment events
+
+## When to Use Me
+
+- Implementing checkout flow for a product
+- Adding subscription billing to an app
+- Setting up license key validation
+- Building a customer portal
+- Handling payment webhooks
+
+## Quick Start
+
+```bash
+npm install @polar-sh/sdk
+```
+
+```typescript
+import { Polar } from "@polar-sh/sdk";
+
+const polar = new Polar({
+  accessToken: process.env.POLAR_ACCESS_TOKEN!,
+  server: "production", // or "sandbox"
+});
+```
+
+## Key APIs
+
+| API                     | Purpose                           |
+| ----------------------- | --------------------------------- |
+| `polar.products.*`      | Create/manage products and prices |
+| `polar.checkouts.*`     | Create checkout sessions          |
+| `polar.subscriptions.*` | Manage subscriptions              |
+| `polar.orders.*`        | View order history                |
+| `polar.customers.*`     | Customer management               |
+| `polar.licenseKeys.*`   | Issue and validate licenses       |
+
+## Environment Variables
+
+| Variable               | Description                     |
+| ---------------------- | ------------------------------- |
+| `POLAR_ACCESS_TOKEN`   | Organization Access Token (OAT) |
+| `POLAR_WEBHOOK_SECRET` | Webhook signing secret          |
+
+## Common Patterns
+
+### Create Checkout
+
+```typescript
+const checkout = await polar.checkouts.create({
+  productId: "prod_xxx",
+  successUrl: "https://myapp.com/success",
+});
+// Redirect to checkout.url
+```
+
+### Validate License Key
+
+```typescript
+const result = await polar.licenseKeys.validate({
+  key: "XXXX-XXXX-XXXX-XXXX",
+  organizationId: "org_xxx",
+});
+```
+
+### Handle Webhook
+
+```typescript
+import { validateEvent } from "@polar-sh/sdk/webhooks";
+
+const event = validateEvent(body, signature, process.env.POLAR_WEBHOOK_SECRET!);
+// event.type: "subscription.created", "order.created", etc.
+```
+
+## Links
+
+- [Dashboard](https://polar.sh)
+- [API Docs](https://docs.polar.sh/api-reference)
+- [SDK](https://www.npmjs.com/package/@polar-sh/sdk)

package/package.json

@@ -1,53 +1,65 @@
 {
-	"name": "opencodekit",
-	"version": "0.8.0",
-	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
-	"type": "module",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/opencodekit/opencodekit-template.git"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org"
-	},
-	"bin": {
-		"ock": "dist/index.js"
-	},
-	"files": ["dist", "README.md"],
-	"scripts": {
-		"dev": "bun run src/index.ts",
-		"build": "bun build src/index.ts --outdir dist --target node && mkdir -p dist/template && rsync -av --exclude=node_modules --exclude=dist --exclude=.git --exclude=coverage --exclude=.next --exclude=.turbo --exclude=logs --exclude=package-lock.json .opencode/ dist/template/.opencode/",
-		"compile": "bun build src/index.ts --compile --outfile ock",
-		"compile:binary": "bun build src/index.ts --compile --outfile bin/ock",
-		"typecheck": "tsc --noEmit",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"lint": "biome check .",
-		"lint:fix": "biome check --fix ."
-	},
-	"keywords": ["cli", "opencodekit", "template", "agents", "mcp", "opencode"],
-	"author": "OpenCodeKit",
-	"license": "MIT",
-	"engines": {
-		"bun": ">=1.3.2"
-	},
-	"dependencies": {
-		"@clack/prompts": "^0.7.0",
-		"@opencode-ai/plugin": "^1.0.141",
-		"beads-village": "^1.3.3",
-		"cac": "^6.7.14",
-		"cli-table3": "^0.6.5",
-		"ora": "^9.0.0",
-		"picocolors": "^1.1.1",
-		"zod": "^3.23.8"
-	},
-	"devDependencies": {
-		"@beads/bd": "^0.29.0",
-		"@biomejs/biome": "^1.9.4",
-		"@types/bun": "latest",
-		"@types/node": "^22.10.1",
-		"typescript": "^5.7.2"
-	},
-	"trustedDependencies": ["@beads/bd"]
+  "name": "opencodekit",
+  "version": "0.9.1",
+  "description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opencodekit/opencodekit-template.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "ock": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target node && mkdir -p dist/template && rsync -av --exclude=node_modules --exclude=dist --exclude=.git --exclude=coverage --exclude=.next --exclude=.turbo --exclude=logs --exclude=package-lock.json .opencode/ dist/template/.opencode/",
+    "compile": "bun build src/index.ts --compile --outfile ock",
+    "compile:binary": "bun build src/index.ts --compile --outfile bin/ock",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix ."
+  },
+  "keywords": [
+    "cli",
+    "opencodekit",
+    "template",
+    "agents",
+    "mcp",
+    "opencode"
+  ],
+  "author": "OpenCodeKit",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.2"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "@opencode-ai/plugin": "^1.0.141",
+    "beads-village": "^1.3.3",
+    "cac": "^6.7.14",
+    "cli-table3": "^0.6.5",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@beads/bd": "^0.29.0",
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "latest",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "trustedDependencies": [
+    "@beads/bd"
+  ]
 }