@cregis-dev/cckit 0.3.0 → 0.4.0

package/templates/ext-skills/pinchtab/TRUST.md

@@ -0,0 +1,69 @@
+# Pinchtab Security & Trust
+
+**TL;DR**: Pinchtab is a local, sandboxed browser control tool. It does not phone home, steal credentials, or exfiltrate data. Source code is public; binaries are signed and published via GitHub.
+
+## What Pinchtab Does
+
+- Launches a Chrome browser (local, under your control)
+- Exposes navigation, clicking, typing, and page inspection via HTTP API
+- Extracts the page's accessibility tree (for AI agents)
+- Runs screenshots, PDFs, and JavaScript evaluation
+
+**All of this stays local.** No telemetry. No external API calls (except to sites you navigate to).
+
+## What Pinchtab Does NOT Do
+
+- ❌ Doesn't access your saved passwords/credentials (Chrome sandboxing)
+- ❌ Doesn't exfiltrate data to remote servers
+- ❌ Doesn't inject ads, malware, or miners
+- ❌ Doesn't track browsing or send analytics
+- ❌ Doesn't modify system files outside its state directory (`~/.pinchtab`)
+
+## Builds & Verification
+
+Every release includes **checksums** alongside binaries:
+
+```bash
+# After downloading, verify:
+sha256sum -c checksums.txt
+```
+
+Binaries are built automatically from tagged commits via GitHub Actions (publicly visible at https://github.com/pinchtab/pinchtab/actions).
+
+## Open Source
+
+- **Source**: https://github.com/pinchtab/pinchtab (Apache 2.0)
+- **Releases**: https://github.com/pinchtab/pinchtab/releases
+- **Latest**: v0.7.0 (Feb 2026)
+
+If you're concerned, audit the source—it's 12MB, zero external dependencies, mostly Go stdlib.
+
+## VirusTotal Flag
+
+Pinchtab may trigger heuristic scanners on VirusTotal because:
+
+- ✓ It launches Chrome (subprocess execution — flagged by AV heuristics)
+- ✓ It runs JavaScript evaluation (eval-like operations)
+- ✓ It makes HTTP requests (network activity)
+
+These are **intentional design features**, not security flaws. Your browser does all three things by default.
+
+**False positives are common for development tools.** The VT flag is a known false positive for chromedp-based tools (subprocess + HTTP server). Always verify SHA256 checksums from GitHub releases before running.
+
+For maximum confidence, use the npm package (`npm install -g pinchtab`) or Docker image, which undergo additional validation.
+
+## Sandboxing
+
+Pinchtab runs a separate Chrome process with:
+
+- Isolated profile directory (default: `~/.pinchtab`)
+- No access to your user's home files (unless you explicitly navigate to `file://` URLs)
+- Standard Chrome security model (site isolation, CSP, etc.)
+
+Set `BRIDGE_PROFILE_DIR` to use a custom directory if needed.
+
+## Questions?
+
+- Source code: https://github.com/pinchtab/pinchtab
+- Issues/security reports: https://github.com/pinchtab/pinchtab/issues
+- Docs: https://pinchtab.com

package/templates/ext-skills/pinchtab/references/api.md

@@ -0,0 +1,297 @@
+# Pinchtab API Reference
+
+Base URL for all examples: `http://localhost:9867`
+
+> **CLI alternative:** All endpoints have CLI equivalents. Use `pinchtab help` for the full list. Examples are shown as `# CLI:` comments below.
+
+## Navigate
+
+```bash
+# CLI: pinchtab nav https://example.com [--new-tab] [--block-images]
+curl -X POST /navigate \
+  -H 'Content-Type: application/json' \
+  -d '{"url": "https://example.com"}'
+
+# With options: custom timeout, block images, open in new tab
+curl -X POST /navigate \
+  -H 'Content-Type: application/json' \
+  -d '{"url": "https://example.com", "timeout": 60, "blockImages": true, "newTab": true}'
+```
+
+## Snapshot (accessibility tree)
+
+```bash
+# CLI: pinchtab snap [-i] [-c] [-d] [-s main] [--max-tokens 2000]
+# Full tree
+curl /snapshot
+
+# Interactive elements only (buttons, links, inputs) — much smaller
+curl "/snapshot?filter=interactive"
+
+# Limit depth
+curl "/snapshot?depth=5"
+
+# Smart diff — only changes since last snapshot (massive token savings)
+curl "/snapshot?diff=true"
+
+# Text format — indented tree, ~40-60% fewer tokens than JSON
+curl "/snapshot?format=text"
+
+# Compact format — one-line-per-node, 56-64% fewer tokens than JSON (recommended)
+curl "/snapshot?format=compact"
+
+# YAML format
+curl "/snapshot?format=yaml"
+
+# Scope to CSS selector (e.g. main content only)
+curl "/snapshot?selector=main"
+
+# Truncate to ~N tokens
+curl "/snapshot?maxTokens=2000"
+
+# Combine for maximum efficiency
+curl "/snapshot?format=compact&selector=main&maxTokens=2000&filter=interactive"
+
+# Disable animations before capture
+curl "/snapshot?noAnimations=true"
+
+# Write to file
+curl "/snapshot?output=file&path=/tmp/snapshot.json"
+```
+
+Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `nodeId`.
+
+**Token optimization**: Use `?format=compact` for best token efficiency. Add `?filter=interactive` for action-oriented tasks (~75% fewer nodes). Use `?selector=main` to scope to relevant content. Use `?maxTokens=2000` to cap output. Use `?diff=true` on multi-step workflows to see only changes. Combine all params freely.
+
+## Act on elements
+
+```bash
+# CLI: pinchtab click e5 / pinchtab type e12 hello / pinchtab press Enter
+# Click by ref
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "click", "ref": "e5"}'
+
+# Type into focused element (click first, then type)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "click", "ref": "e12"}'
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "type", "ref": "e12", "text": "hello world"}'
+
+# Press a key
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "press", "key": "Enter"}'
+
+# Focus an element
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "focus", "ref": "e3"}'
+
+# Fill (set value directly, no keystrokes)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "fill", "selector": "#email", "text": "user@example.com"}'
+
+# Hover (trigger dropdowns/tooltips)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "hover", "ref": "e8"}'
+
+# Select dropdown option (by value or visible text)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "select", "ref": "e10", "value": "option2"}'
+
+# Scroll to element
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "scroll", "ref": "e20"}'
+
+# Scroll by pixels (infinite scroll pages)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "scroll", "scrollY": 800}'
+
+# Click and wait for navigation (link clicks)
+curl -X POST /action -H 'Content-Type: application/json' \
+  -d '{"kind": "click", "ref": "e5", "waitNav": true}'
+```
+
+## Batch actions
+
+```bash
+# Execute multiple actions in sequence
+curl -X POST /actions -H 'Content-Type: application/json' \
+  -d '{"actions":[{"kind":"click","ref":"e3"},{"kind":"type","ref":"e3","text":"hello"},{"kind":"press","key":"Enter"}]}'
+
+# Stop on first error (default: false)
+curl -X POST /actions -H 'Content-Type: application/json' \
+  -d '{"tabId":"TARGET_ID","actions":[...],"stopOnError":true}'
+```
+
+## Extract text
+
+```bash
+# CLI: pinchtab text [--raw]
+# Readability mode (default) — strips nav/footer/ads
+curl /text
+
+# Raw innerText
+curl "/text?mode=raw"
+```
+
+Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).
+
+## PDF export
+
+```bash
+# CLI: pinchtab pdf [-o file.pdf] [--landscape] [--scale 0.8]
+# Returns base64 JSON
+curl /pdf
+
+# Raw PDF bytes
+curl "/pdf?raw=true" -o page.pdf
+
+# Save to disk
+curl "/pdf?output=file&path=/tmp/page.pdf"
+
+# Landscape with custom scale
+curl "/pdf?landscape=true&scale=0.8&raw=true" -o page.pdf
+
+# Custom paper size (Letter: 8.5x11, A4: 8.27x11.69)
+curl "/pdf?paperWidth=8.5&paperHeight=11&marginTop=0.5&marginLeft=0.5&raw=true" -o custom.pdf
+
+# Export specific pages
+curl "/pdf?pageRanges=1-5&raw=true" -o pages.pdf
+
+# With header/footer
+curl "/pdf?displayHeaderFooter=true&headerTemplate=%3Cspan%20class=title%3E%3C/span%3E&raw=true" -o header.pdf
+
+# Accessible PDF with document outline
+curl "/pdf?generateTaggedPDF=true&generateDocumentOutline=true&raw=true" -o accessible.pdf
+
+# Honor CSS page size
+curl "/pdf?preferCSSPageSize=true&raw=true" -o css-sized.pdf
+```
+
+**Query Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `paperWidth` | float | 8.5 | Paper width in inches |
+| `paperHeight` | float | 11.0 | Paper height in inches |
+| `landscape` | bool | false | Landscape orientation |
+| `marginTop` | float | 0.4 | Top margin in inches |
+| `marginBottom` | float | 0.4 | Bottom margin in inches |
+| `marginLeft` | float | 0.4 | Left margin in inches |
+| `marginRight` | float | 0.4 | Right margin in inches |
+| `scale` | float | 1.0 | Print scale (0.1–2.0) |
+| `pageRanges` | string | all | Pages to export (e.g., `1-3,5`) |
+| `displayHeaderFooter` | bool | false | Show header and footer |
+| `headerTemplate` | string | — | HTML template for header |
+| `footerTemplate` | string | — | HTML template for footer |
+| `preferCSSPageSize` | bool | false | Honor CSS `@page` size |
+| `generateTaggedPDF` | bool | false | Generate accessible/tagged PDF |
+| `generateDocumentOutline` | bool | false | Embed document outline |
+| `output` | string | JSON | `file` to save to disk, default returns base64 |
+| `path` | string | auto | Custom file path (with `output=file`) |
+| `raw` | bool | false | Return raw PDF bytes instead of JSON |
+
+Wraps `Page.printToPDF`. Prints background graphics by default.
+
+## Download files
+
+```bash
+# Returns base64 JSON by default (uses browser session/cookies/stealth)
+curl "/download?url=https://site.com/report.pdf"
+
+# Raw bytes (pipe to file)
+curl "/download?url=https://site.com/image.jpg&raw=true" -o image.jpg
+
+# Save directly to disk
+curl "/download?url=https://site.com/export.csv&output=file&path=/tmp/export.csv"
+```
+
+## Upload files
+
+```bash
+# Upload a local file to a file input
+curl -X POST "/upload?tabId=TAB_ID" -H "Content-Type: application/json" \
+  -d '{"selector": "input[type=file]", "paths": ["/tmp/photo.jpg"]}'
+
+# Upload base64-encoded data
+curl -X POST /upload -H "Content-Type: application/json" \
+  -d '{"selector": "#avatar-input", "files": ["data:image/png;base64,iVBOR..."]}'
+```
+
+Sets files on `<input type=file>` elements via CDP. Fires `change` events. Selector defaults to `input[type=file]` if omitted.
+
+## Screenshot
+
+```bash
+# CLI: pinchtab ss [-o file.jpg] [-q 80]
+curl "/screenshot?raw=true" -o screenshot.jpg
+curl "/screenshot?raw=true&quality=50" -o screenshot.jpg
+```
+
+## Evaluate JavaScript
+
+```bash
+# CLI: pinchtab eval "document.title"
+curl -X POST /evaluate -H 'Content-Type: application/json' \
+  -d '{"expression": "document.title"}'
+```
+
+## Tab management
+
+```bash
+# CLI: pinchtab tabs / pinchtab tabs new <url> / pinchtab tabs close <id>
+# List tabs
+curl /tabs
+
+# Open new tab
+curl -X POST /tab -H 'Content-Type: application/json' \
+  -d '{"action": "new", "url": "https://example.com"}'
+
+# Close tab
+curl -X POST /tab -H 'Content-Type: application/json' \
+  -d '{"action": "close", "tabId": "TARGET_ID"}'
+```
+
+Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in POST body.
+
+## Tab locking (multi-agent)
+
+```bash
+# Lock a tab (default 30s timeout, max 5min)
+curl -X POST /tab/lock -H 'Content-Type: application/json' \
+  -d '{"tabId": "TARGET_ID", "owner": "agent-1", "timeoutSec": 60}'
+
+# Unlock
+curl -X POST /tab/unlock -H 'Content-Type: application/json' \
+  -d '{"tabId": "TARGET_ID", "owner": "agent-1"}'
+```
+
+Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.
+
+## Cookies
+
+```bash
+# Get cookies for current page
+curl /cookies
+
+# Set cookies
+curl -X POST /cookies -H 'Content-Type: application/json' \
+  -d '{"url":"https://example.com","cookies":[{"name":"session","value":"abc123"}]}'
+```
+
+## Stealth
+
+```bash
+# Check stealth status and score
+curl /stealth/status
+
+# Rotate browser fingerprint
+curl -X POST /fingerprint/rotate -H 'Content-Type: application/json' \
+  -d '{"os":"windows"}'
+# os: "windows", "mac", or omit for random
+```
+
+## Health check
+
+```bash
+curl /health
+```

package/templates/ext-skills/pinchtab/references/env.md

@@ -0,0 +1,45 @@
+# Pinchtab Environment Variables
+
+## Core runtime
+
+| Var | Default | Description |
+|---|---|---|
+| `BRIDGE_BIND` | `127.0.0.1` | Bind address. Set `0.0.0.0` for network access |
+| `BRIDGE_PORT` | `9867` | HTTP port |
+| `BRIDGE_HEADLESS` | `true` | Run Chrome headless |
+| `BRIDGE_TOKEN` | (none) | Bearer auth token (recommended with `0.0.0.0`) |
+| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |
+| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |
+| `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup |
+| `BRIDGE_STEALTH` | `light` | Stealth level: `light` or `full` |
+| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |
+| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |
+| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |
+| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |
+| `BRIDGE_TIMEZONE` | (none) | Force browser timezone (IANA tz) |
+| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version for fingerprint rotation |
+| `BRIDGE_USER_AGENT` | (none) | Custom User-Agent string; also overrides Sec-Ch-Ua client hints via CDP |
+| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |
+| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) |
+| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |
+| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |
+| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |
+| `CDP_URL` | (none) | Connect to existing Chrome DevTools |
+| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard endpoints on instance processes |
+
+## CLI client
+
+| Var | Default | Description |
+|---|---|---|
+| `PINCHTAB_URL` | `http://localhost:9867` | Pinchtab server URL for CLI commands |
+| `PINCHTAB_TOKEN` | (none) | Auth token for CLI (sent as `Authorization: Bearer`) |
+
+## Dashboard mode (`pinchtab dashboard`)
+
+| Var | Default | Description |
+|---|---|---|
+| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch default profile at startup |
+| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name for auto-launch |
+| `PINCHTAB_DEFAULT_PORT` | `9867` | Port for auto-launched profile |
+| `PINCHTAB_HEADED` | (unset) | If set, auto-launched profile is headed |
+| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | Base URL for `pinchtab connect` |

package/templates/ext-skills/pinchtab/references/profiles.md

@@ -0,0 +1,107 @@
+# Profile Management (Dashboard Mode)
+
+When running `pinchtab dashboard`, profiles are managed via the dashboard API on port 9867.
+
+## List profiles
+
+```bash
+curl http://localhost:9867/profiles
+```
+
+Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.
+
+## Start a profile
+
+```bash
+# Auto-allocate port (recommended)
+curl -X POST http://localhost:9867/profiles/<ID>/start
+
+# With specific port and headless mode
+curl -X POST http://localhost:9867/profiles/<ID>/start \
+  -H 'Content-Type: application/json' \
+  -d '{"port": "9868", "headless": true}'
+
+# Short alias
+curl -X POST http://localhost:9867/start/<ID>
+```
+
+Returns instance info including allocated `port`. Use that port for all subsequent API calls.
+
+## Stop a profile
+
+```bash
+curl -X POST http://localhost:9867/profiles/<ID>/stop
+
+# Short alias
+curl -X POST http://localhost:9867/stop/<ID>
+```
+
+## Check instance status
+
+```bash
+# By profile ID (recommended)
+curl http://localhost:9867/profiles/<ID>/instance
+
+# By profile name
+curl http://localhost:9867/profiles/My%20Profile/instance
+```
+
+## Launch by name
+
+```bash
+curl -X POST http://localhost:9867/instances/launch \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "work", "port": "9868"}'
+```
+
+## CLI usage with profiles
+
+The CLI doesn't have profile subcommands yet — use `curl` for profile management.
+Once a profile instance is running, point the CLI at it:
+
+```bash
+# Get the instance port, then use CLI
+PINCHTAB_URL=http://localhost:9868 pinchtab snap -i
+```
+
+## Typical agent flow
+
+```bash
+# 1. List profiles
+PROFILES=$(curl -s http://localhost:9867/profiles)
+
+# 2. Start profile (auto-allocates port)
+INSTANCE=$(curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/start)
+PORT=$(echo $INSTANCE | jq -r .port)
+
+# 3. Use the instance
+curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json' \
+  -d '{"url": "https://mail.google.com"}'
+curl http://localhost:$PORT/snapshot?maxTokens=4000
+
+# 4. Stop when done
+curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/stop
+```
+
+## Profile IDs
+
+Each profile gets a stable 12-char hex ID (SHA-256 of name, truncated) stored in `profile.json`. IDs are URL-safe and never change — use them instead of names in automation.
+
+## Headed mode
+
+Headed mode = real visible Chrome window managed by Pinchtab.
+
+- Human can log in, pass 2FA/captcha, validate state
+- Agent calls HTTP APIs against the same running instance
+- Session state persists in profile directory (cookies/storage carry over)
+
+Recommended human + agent flow:
+
+```bash
+# Human starts dashboard and sets up profile
+pinchtab dashboard
+
+# Agent resolves the profile endpoint
+PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"
+curl "$PINCHTAB_BASE_URL/health"
+```

package/templates/plugins/claude-code-setup/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "claude-code-setup",
+  "description": "Analyze codebases and recommend tailored Claude Code automations such as hooks, skills, MCP servers, and subagents.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Anthropic",
+    "email": "support@anthropic.com"
+  }
+}