diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index db84e57c..c5233d2b 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -795,6 +795,18 @@ "authentication": "ON_INSTALL" }, "category": "Tooling" + }, + { + "name": "dev3000", + "source": { + "source": "local", + "path": "./plugins/dev3000" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tooling" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 168d892a..fc18e574 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -730,6 +730,14 @@ "keywords": ["nostics", "diagnostics", "error-handling", "typescript", "javascript"], "tags": ["skills", "vercel"], "source": "./plugins/nostics" + }, + { + "name": "dev3000", + "description": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging.", + "category": "tooling", + "keywords": ["dev3000", "d3k", "debugging", "web", "logs", "screenshots"], + "tags": ["skills", "vercel"], + "source": "./plugins/dev3000" } ] } diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 38a28236..cd7e3363 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -60,5 +60,6 @@ "plugins/vercel-sandbox": "1.1.0", "plugins/eve": "1.1.0", "plugins/skill-optimizer": "1.1.0", - "plugins/nostics": "1.0.0" + "plugins/nostics": "1.0.0", + "plugins/dev3000": "1.0.0" } diff --git a/README.md b/README.md index b7d8c316..7be7335e 100644 --- a/README.md +++ b/README.md @@ -411,6 +411,12 @@ Structured diagnostic code library for JavaScript/TypeScript. Turns errors into **Install:** `/plugin install nostics@pleaseai` | **Source:** [plugins/nostics](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/nostics) +#### dev3000 + +dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging. Bootstraps d3k as the dev runtime and drives its monitored browser instead of running npm/bun dev directly. + +**Install:** `/plugin install dev3000@pleaseai` | **Source:** [plugins/dev3000](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/dev3000) + ## Quick Start The fastest way to get started — install the marketplace and let the plugin recommender auto-detect what you need: @@ -549,6 +555,7 @@ Once the marketplace is added (or files copied), the following plugins are avail /plugin install portone@pleaseai /plugin install google-workspace@pleaseai /plugin install skill-optimizer@pleaseai +/plugin install dev3000@pleaseai ``` ## What Are Claude Code Plugins? diff --git a/plugins/dev3000/.agents/skills/d3k/PUBLISH.md b/plugins/dev3000/.agents/skills/d3k/PUBLISH.md new file mode 100644 index 00000000..254bb3dd --- /dev/null +++ b/plugins/dev3000/.agents/skills/d3k/PUBLISH.md @@ -0,0 +1,46 @@ +# Publish Notes (skills.sh) + +## Skill Path + +- Local folder: `skills/d3k` +- Skill id: `d3k` + +## Publish Copy (ready to paste) + +### Title + +`d3k` + +### Short description + +`Bootstraps d3k runtime for standalone AI apps` + +### Long description + +`Installs/initializes dev3000 (d3k) for standalone agent shells (Codex, Cursor, Claude Code), starts d3k as the default runtime, and uses unified logs plus CDP browser control instead of raw npm/bun dev.` + +### Default prompt + +`Use $d3k to initialize d3k, start the correct runtime, and drive debugging with unified logs and CDP browser controls.` + +## Source URL + +Use the GitHub path to this skill folder in your repo: + +`https://github.com/vercel-labs/dev3000/tree/main/skills/d3k` + +If you publish from another branch/ref, replace `main` with that ref. + +## Test Install (Codex) + +From Codex skill installer flow, install from URL: + +`https://github.com/vercel-labs/dev3000/tree/main/skills/d3k` + +Then restart Codex and invoke: + +`$d3k` + +## Smoke Test Prompt + +`Use $d3k in this repo and initialize d3k for me.` diff --git a/plugins/dev3000/.agents/skills/d3k/SKILL.md b/plugins/dev3000/.agents/skills/d3k/SKILL.md new file mode 100644 index 00000000..2ea8fd9e --- /dev/null +++ b/plugins/dev3000/.agents/skills/d3k/SKILL.md @@ -0,0 +1,147 @@ +--- +name: "d3k" +description: "Bootstrap d3k in standalone AI apps (Codex, Cursor, Claude Code): detect/install dev3000, start d3k as the runtime, and use unified logs plus CDP browser control instead of running npm/bun dev directly." +--- + +# d3k Standalone Bootstrap + +Use this skill when working in a standalone AI app and you need reliable local web debugging with browser + server context. + +## Why d3k-first + +- `d3k` captures server logs, browser console, network events, and screenshots in one timeline. +- `d3k` exposes a stable CDP endpoint so the agent can control the same browser session being monitored. +- Running `npm run dev` or `bun run dev` directly omits this unified telemetry and usually leads to weaker diagnoses. + +## Bootstrap Workflow + +1. Confirm whether `d3k` is installed: +```bash +command -v d3k >/dev/null && d3k --version +``` + +2. If `d3k` is missing, install dev3000 globally (prefer Bun): +```bash +bun install -g dev3000 +``` +Fallback if Bun is unavailable: +```bash +npm install -g dev3000 +``` + +3. Start d3k as the runtime (preferred default in agent shells): +```bash +d3k --no-agent --no-tui -t +``` + +4. Keep d3k running while editing code. Do not start a second dev server with `npm/bun dev`. + +## Codex Fresh Browser/Profile Startup + +Use this workflow when the user asks Codex to start d3k with a fresh browser/profile. + +1. Close any stale `agent-browser` daemon before launching with `--profile`. Otherwise `agent-browser` will reuse the existing daemon and print `--profile ignored`. + ```bash + d3k agent-browser close --all + ``` + +2. Start the app through d3k in `servers-only` mode and keep that command running. In Codex, this is more reliable than asking d3k to launch the browser itself when a fresh profile is required. + ```bash + d3k --no-agent --no-skills --servers-only --command "npm run dev -- -H 127.0.0.1 -p 3000" --port 3000 --startup-timeout 90 --no-tui + ``` + + Adjust the package-manager command and port for the project. Prefer `--command` over `--script` when passing framework flags. For npm scripts, put flags after `--`; otherwise tools like Next.js can interpret the port as a project directory. + +3. Verify the server before opening more browser windows: + ```bash + curl -I http://127.0.0.1:3000 + ``` + +4. Open the fresh profile as a separate browser step: + ```bash + d3k agent-browser --profile /tmp/d3k-fresh-profile --headed open http://127.0.0.1:3000 + ``` + +5. Sanity-check the opened page: + ```bash + d3k agent-browser get title + d3k agent-browser snapshot -i + d3k errors + ``` + +Practical rules: + +- Prefer `127.0.0.1` for this workflow. If `localhost` hangs or flips between IPv4/IPv6 behavior, do not keep retrying browser launches. +- If `curl -I` hangs, the server is wedged even if the port appears occupied; restart the d3k server process before opening a browser. +- In `servers-only` mode there is no d3k-monitored CDP browser. Use regular `d3k agent-browser` commands, not `d3k cdp-port`. +- In sandboxed agent environments, rerun local-network checks and `agent-browser` opens outside the sandbox when sandbox networking blocks access to `127.0.0.1`. + +## Debugging Commands + +Use these first before ad-hoc log scraping: + +```bash +d3k errors --context +d3k logs -n 200 +d3k logs --type browser +d3k logs --type server +``` + +## CDP Browser Control + +Use the already-monitored browser session instead of launching a separate automation browser. + +```bash +d3k agent-browser open http://localhost:3000 +d3k agent-browser snapshot -i +d3k agent-browser click @e2 +d3k agent-browser screenshot /tmp/d3k-current.png +``` + +`d3k agent-browser` auto-connects to the active session's browser via CDP. To target a different browser, run `d3k agent-browser connect ` first. + +## Browser Tool Choice + +Use the browser tool that matches the task instead of treating them as interchangeable: + +- `agent-browser` + - Default choice. + - Best for generic web apps and for driving the exact headed browser session that d3k is already monitoring via CDP. + - Use it when you need `snapshot`, ref-based `click`, `fill`, or to reproduce what the user sees in the monitored tab. +- `next-browser` + - Next.js-specific tool. + - Best for React/Next introspection: `tree`, `errors`, `logs`, `routes`, `project`, PPR inspection, and related Next dev-server signals. + - It is not a drop-in replacement for `agent-browser`: no accessibility `snapshot`, no ref-based `click`, and no `fill`. + - It launches its own daemon/browser flow and does not use the d3k session's CDP port. + +Practical rule: + +- Need to drive the same browser d3k is monitoring: use `agent-browser`. +- Need Next.js component tree or Next-specific diagnostics: use `next-browser`. + +Examples: + +```bash +# Same monitored browser session +d3k agent-browser snapshot -i +d3k agent-browser click @e2 + +# Next.js-specific inspection +d3k next-browser open http://localhost:3000 +d3k next-browser tree +d3k next-browser errors +d3k next-browser logs +``` + +## Artifacts to Read + +- `~/.d3k/{project}/d3k.log` +- `~/.d3k/{project}/logs/` +- `~/.d3k/{project}/screenshots/` +- `~/.d3k/{project}/session.json` + +## Operating Rules + +- Prefer headed mode for interactive debugging. +- Use `--headless` only for CI or when explicitly requested. +- Use `--servers-only` only when browser monitoring is intentionally disabled. diff --git a/plugins/dev3000/.agents/skills/d3k/agents/openai.yaml b/plugins/dev3000/.agents/skills/d3k/agents/openai.yaml new file mode 100644 index 00000000..377b0e39 --- /dev/null +++ b/plugins/dev3000/.agents/skills/d3k/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "d3k" + short_description: "Bootstraps d3k runtime for standalone AI apps" + default_prompt: "Use $d3k to initialize d3k, start the correct runtime, and drive debugging with unified logs and CDP browser controls." diff --git a/plugins/dev3000/.claude-plugin/plugin.json b/plugins/dev3000/.claude-plugin/plugin.json new file mode 100644 index 00000000..60583520 --- /dev/null +++ b/plugins/dev3000/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "name": "dev3000", + "version": "1.0.0", + "description": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging. Bootstraps d3k as the dev runtime and drives its monitored browser instead of running npm/bun dev directly.", + "author": { + "name": "Vercel Labs", + "url": "https://github.com/vercel-labs" + }, + "homepage": "https://github.com/vercel-labs/dev3000", + "repository": "https://github.com/vercel-labs/dev3000", + "license": "MIT", + "keywords": [ + "dev3000", + "d3k", + "debugging", + "web", + "logs", + "screenshots" + ], + "skills": "./.agents/skills/" +} diff --git a/plugins/dev3000/.codex-plugin/plugin.json b/plugins/dev3000/.codex-plugin/plugin.json new file mode 100644 index 00000000..a52e550d --- /dev/null +++ b/plugins/dev3000/.codex-plugin/plugin.json @@ -0,0 +1,34 @@ +{ + "name": "dev3000", + "version": "1.0.0", + "description": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging. Bootstraps d3k as the dev runtime and drives its monitored browser instead of running npm/bun dev directly.", + "author": { + "name": "Vercel Labs", + "url": "https://github.com/vercel-labs" + }, + "interface": { + "displayName": "Dev3000", + "shortDescription": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped tim...", + "longDescription": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging. Bootstraps d3k as the dev runtime and drives its monitored browser instead of running npm/bun dev directly.", + "developerName": "Vercel Labs", + "category": "Tooling", + "capabilities": [ + "Skill" + ], + "defaultPrompt": [ + "Help me use Dev3000 for my current task." + ], + "websiteURL": "https://github.com/vercel-labs/dev3000" + }, + "homepage": "https://github.com/vercel-labs/dev3000", + "repository": "https://github.com/vercel-labs/dev3000", + "license": "MIT", + "keywords": [ + "dev3000", + "d3k", + "debugging", + "web", + "logs", + "screenshots" + ] +} diff --git a/plugins/dev3000/plugin.json b/plugins/dev3000/plugin.json new file mode 100644 index 00000000..53de0387 --- /dev/null +++ b/plugins/dev3000/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "dev3000", + "version": "1.0.0", + "description": "dev3000 (d3k) debugging assistant — captures server logs, browser events, console messages, network requests, and screenshots into a unified, timestamped timeline for AI debugging. Bootstraps d3k as the dev runtime and drives its monitored browser instead of running npm/bun dev directly.", + "author": { + "name": "Vercel Labs", + "url": "https://github.com/vercel-labs" + }, + "homepage": "https://github.com/vercel-labs/dev3000", + "repository": "https://github.com/vercel-labs/dev3000", + "license": "MIT", + "keywords": [ + "dev3000", + "d3k", + "debugging", + "web", + "logs", + "screenshots" + ] +} diff --git a/plugins/dev3000/skills-lock.json b/plugins/dev3000/skills-lock.json new file mode 100644 index 00000000..c654ad23 --- /dev/null +++ b/plugins/dev3000/skills-lock.json @@ -0,0 +1,11 @@ +{ + "version": 1, + "skills": { + "d3k": { + "source": "vercel-labs/dev3000", + "sourceType": "github", + "skillPath": "skills/d3k/SKILL.md", + "computedHash": "ef9c69719d6a84cc71d3183d95854e5b49478a45c84f3ffbc1142d901ed4e09c" + } + } +} diff --git a/release-please-config.json b/release-please-config.json index 6d0c30c6..edf7d37a 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -953,6 +953,27 @@ "jsonpath": "$.version" } ] + }, + "plugins/dev3000": { + "release-type": "simple", + "component": "dev3000", + "extra-files": [ + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" + }, + { + "type": "json", + "path": ".codex-plugin/plugin.json", + "jsonpath": "$.version" + }, + { + "type": "json", + "path": "plugin.json", + "jsonpath": "$.version" + } + ] } }, "release-type": "node",