{"_id":"@adamancyzhang/agent-vuetools","_rev":"3-c39d410d188f4aec68ba562fee067de9","name":"@adamancyzhang/agent-vuetools","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@adamancyzhang/agent-vuetools","version":"0.1.0","keywords":["vue","vue3","cdp","devtools","cli","agent","inspect","browser"],"license":"MIT","_id":"@adamancyzhang/agent-vuetools@0.1.0","maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"homepage":"https://github.com/adamancyzhang/agent-vuetools#readme","bugs":{"url":"https://github.com/adamancyzhang/agent-vuetools/issues"},"bin":{"agent-vuetools":"dist/cli.js"},"dist":{"shasum":"fa13a429437591c1299b72381d880c05cdd4fda6","tarball":"https://registry.npmjs.org/@adamancyzhang/agent-vuetools/-/agent-vuetools-0.1.0.tgz","fileCount":4,"integrity":"sha512-JPypEZjoaHFBkYHpAlBOS2ohQm/Qg1ENWQwj4u7GZhRQ/T7XXHAnqv7VydIwCUoWHijkVjDkWkaDmBYUQTLI+w==","signatures":[{"sig":"MEUCIEhLbVzraCNmHpIYR7us9nQ0QsbYpdgOSVrUwTh9LHiQAiEA9PQ/vVdIj11x/MYfGNxho+8d6x5gyblm7BxEYyWGRms=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64216},"type":"module","engines":{"node":">=18"},"gitHead":"a76ac4f5407442dcb2679b7d49180cce57750ddc","scripts":{"test":"vitest run test/unit","build":"npm run typecheck && node scripts/build.mjs","test:e2e":"npm run build && vitest run test/e2e","typecheck":"tsc --noEmit","fixture:serve":"vite dev test/fixtures/vue-app --port 4173 --strictPort"},"_npmUser":{"name":"adamancyzhang","email":"adamancyzhang@163.com"},"repository":{"url":"git+https://github.com/adamancyzhang/agent-vuetools.git","type":"git"},"_npmVersion":"11.19.0","description":"Inspect Vue 3 component tree, props and setup state in a live browser over CDP — no vue-devtools extension needed.","directories":{},"_nodeVersion":"22.21.1","dependencies":{"ws":"^8.18.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vue":"^3.5.13","vite":"^6.0.0","jsdom":"^26.0.0","vitest":"^3.0.0","esbuild":"^0.25.0","@types/ws":"^8.5.13","typescript":"^5.7.0","@types/node":"^22.10.0","@vitejs/plugin-vue":"^5.2.1"},"_npmOperationalInternal":{"tmp":"tmp/agent-vuetools_0.1.0_1788327761805_0.4836516446941814","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@adamancyzhang/agent-vuetools","version":"0.1.1","keywords":["vue","vue3","cdp","devtools","cli","agent","inspect","browser"],"license":"MIT","_id":"@adamancyzhang/agent-vuetools@0.1.1","maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"homepage":"https://github.com/adamancyzhang/agent-vuetools#readme","bugs":{"url":"https://github.com/adamancyzhang/agent-vuetools/issues"},"bin":{"agent-vuetools":"dist/cli.js"},"dist":{"shasum":"45d232ed99c677b61d983ec71a6e03243461ce38","tarball":"https://registry.npmjs.org/@adamancyzhang/agent-vuetools/-/agent-vuetools-0.1.1.tgz","fileCount":6,"integrity":"sha512-PGdEfBTBKObpT5kf/i+5m1d8qMNYfXCar+M4dnDLpdAORUNnXllWmFm4UrKawEVMgUbfmDRugcZZ0rmElzymEA==","signatures":[{"sig":"MEQCIAvhm8wl14fQYBvnL2jMwNyiaWMtlKYUzLZ9rizgSSAXAiAV6nsVK8ZYHyRWeNM1mKtqa5ak2C7Wo7pTKS+B59I/uA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":77858},"type":"module","engines":{"node":">=18"},"gitHead":"3a0cbb39a2694e8b6046af061e47e87a66d2c195","scripts":{"test":"vitest run test/unit","build":"npm run typecheck && node scripts/build.mjs","test:e2e":"npm run build && vitest run test/e2e","typecheck":"tsc --noEmit","fixture:serve":"vite dev test/fixtures/vue-app --port 4173 --strictPort"},"_npmUser":{"name":"adamancyzhang","email":"adamancyzhang@163.com"},"repository":{"url":"git+https://github.com/adamancyzhang/agent-vuetools.git","type":"git"},"_npmVersion":"11.19.0","description":"Inspect Vue 3 component tree, props and setup state in a live browser over CDP — no vue-devtools extension needed.","directories":{},"_nodeVersion":"22.21.1","dependencies":{"ws":"^8.18.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vue":"^3.5.13","vite":"^6.0.0","jsdom":"^26.0.0","vitest":"^3.0.0","esbuild":"^0.25.0","@types/ws":"^8.5.13","typescript":"^5.7.0","@types/node":"^22.10.0","@vitejs/plugin-vue":"^5.2.1"},"_npmOperationalInternal":{"tmp":"tmp/agent-vuetools_0.1.1_1788335428546_0.42360695220268507","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@adamancyzhang/agent-vuetools","version":"0.1.2","description":"Inspect Vue 3 component tree, props and setup state in a live browser over CDP — no vue-devtools extension needed.","type":"module","bin":{"agent-vuetools":"dist/cli.js"},"engines":{"node":">=18"},"repository":{"type":"git","url":"git+https://github.com/adamancyzhang/agent-vuetools.git"},"license":"MIT","keywords":["vue","vue3","cdp","devtools","cli","agent","inspect","browser"],"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"prepublishOnly":"npm run build","build":"npm run typecheck && node scripts/build.mjs","typecheck":"tsc --noEmit","test":"vitest run test/unit","test:e2e":"npm run build && vitest run test/e2e","fixture:serve":"vite dev test/fixtures/vue-app --port 4173 --strictPort"},"dependencies":{"ws":"^8.18.0"},"devDependencies":{"@types/node":"^22.10.0","@types/ws":"^8.5.13","@vitejs/plugin-vue":"^5.2.1","esbuild":"^0.25.0","jsdom":"^26.0.0","typescript":"^5.7.0","vite":"^6.0.0","vitest":"^3.0.0","vue":"^3.5.13"},"gitHead":"6e3acd8e6902572e61300b989df736de5b2d7046","_id":"@adamancyzhang/agent-vuetools@0.1.2","bugs":{"url":"https://github.com/adamancyzhang/agent-vuetools/issues"},"homepage":"https://github.com/adamancyzhang/agent-vuetools#readme","_nodeVersion":"22.21.1","_npmVersion":"11.19.0","dist":{"integrity":"sha512-JbnMLFlxd7pnrYwcKUY8LS/7Kod1rvfWu8k+bQiBNMius+cG+RD7BGIPLZhk8LlWrEl/Ncbs0yDcFi5uJTkouA==","shasum":"daa8ebfdbfd223fc5f63de00a6c145a9e31ae050","tarball":"https://registry.npmjs.org/@adamancyzhang/agent-vuetools/-/agent-vuetools-0.1.2.tgz","fileCount":6,"unpackedSize":77897,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDNKR7HutZY7NY9RKs3P7umXGgGYBH73JMQIKYQh98z9gIgZsg+P3r+gophZmUgAE+uYLSyhe1unXKctYyhGiAY3kc="}]},"_npmUser":{"name":"adamancyzhang","email":"adamancyzhang@163.com"},"directories":{},"maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-vuetools_0.1.2_1788336062516_0.5042063163237367"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T05:42:41.647Z","modified":"2026-09-02T08:01:02.806Z","0.1.0":"2026-09-02T05:42:41.937Z","0.1.1":"2026-09-02T07:50:28.675Z","0.1.2":"2026-09-02T08:01:02.663Z"},"bugs":{"url":"https://github.com/adamancyzhang/agent-vuetools/issues"},"license":"MIT","homepage":"https://github.com/adamancyzhang/agent-vuetools#readme","keywords":["vue","vue3","cdp","devtools","cli","agent","inspect","browser"],"repository":{"type":"git","url":"git+https://github.com/adamancyzhang/agent-vuetools.git"},"description":"Inspect Vue 3 component tree, props and setup state in a live browser over CDP — no vue-devtools extension needed.","maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"readme":"# agent-vuetools\n\nInspect Vue 3 components in a live browser over CDP — no vue-devtools extension needed. Built for AI agents: stable machine-readable output, plus a human-readable text format.\n\n[![npm version](https://img.shields.io/npm/v/%40adamancyzhang%2Fagent-vuetools)](https://www.npmjs.com/package/@adamancyzhang/agent-vuetools)\n[![license](https://img.shields.io/npm/l/%40adamancyzhang%2Fagent-vuetools)](LICENSE)\n[![node](https://img.shields.io/badge/node-%3E%3D18-green)](package.json)\n\n## What it does\n\nThe Vue 3 runtime exposes `__vue_app__` / `__vueParentComponent` markers on DOM elements. agent-vuetools connects to the browser via the Chrome DevTools Protocol (CDP), injects a probe script that walks component instances (`subTree` → `component.props` / `setupState` / `computed` / `__file`), serializes cycle-safely in-page, and returns the result as JSON or a text tree.\n\n```bash\nagent-vuetools tree                      # component tree of the page\nagent-vuetools inspect Counter --json    # props, setup state, computed of one component\nagent-vuetools query '//a[contains(@class, \"nav\")]'   # collect DOM matches + owning components\nagent-vuetools style '#submit-btn'       # computed style of an element\n```\n\n## Installation\n\n### Global (recommended)\n\n```bash\nnpm install -g @adamancyzhang/agent-vuetools\n```\n\nRequires Node >= 18. No other dependencies — the only runtime dependency is `ws`.\n\n### From source\n\n```bash\ngit clone https://github.com/adamancyzhang/agent-vuetools.git\ncd agent-vuetools\nnpm install\nnpm run build\nnpm link\n```\n\n### Requirements\n\nA Chrome/Edge with a debugging port (default `127.0.0.1:9222`):\n\n```bash\n\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" --remote-debugging-port=9222\n```\n\nThat's it. Open your Vue page (dev server recommended for the richest output) and run any command.\n\n## Quick Start\n\n```bash\nagent-vuetools tree                        # component tree\nagent-vuetools inspect Counter             # deep-dive by component name\nagent-vuetools inspect src/components/     # by __file path substring\nagent-vuetools inspect \"#submit-btn\"       # by CSS selector\nagent-vuetools inspect '//*[text()[contains(., \"Submit\")]]'   # by XPath\nagent-vuetools inspect \"Back to list\"      # by visible text\nagent-vuetools find NavLink                # locate + parent chains\nagent-vuetools query '.nav a' --limit 20   # collect DOM matches\nagent-vuetools style '.ant-btn-primary'    # computed style + full class\n```\n\n## Commands\n\n### tree\n\n```\nagent-vuetools tree [--depth N] [--fields ...] [--compact] [--json]\n```\n\nPrints the component + element tree. Component nodes carry a `[DOM]` bracket, prop values, a setup-state summary, and the `__file` path (dev builds).\n\n| Flag | Description |\n|---|---|\n| `--depth <n>` | Max tree depth. Default 8, no upper limit (5000-node cap still applies) |\n| `--fields <list>` | Comma-separated: `props,setupState,computed,data,exposed,attrs,slots,emitted,provides,file,dom` (default: `props,setupState,file,dom`) |\n| `--compact` | Name and DOM only |\n\n```\n# 2 Vue apps found on this page\n└─ App {setup: title=\"agent-vuetools fixture\", count=3} [DIV#app-root.app-shell] (src/App.vue)\n├─ h1 [H1] \"agent-vuetools fixture\"\n├─ Counter {step: 1, count: 3, label: \"Count\"} {setup: props=\"[Props]\", emit=\"[Emit]\", doubled=6, local=7} [DIV#counter-box] (src/components/Counter.vue)\n├─ TeleportBox (src/components/TeleportBox.vue)\n│  └─ Teleport\n│     └─ div [DIV#tp-box.teleported] \"teleported content\"\n└─ MultiRoot (src/components/MultiRoot.vue)\n   └─ Fragment\n      ├─ p [P#mr-1] \"root one\"\n      └─ p [P#mr-2] \"root two\"\n```\n\nA component's own root-element line is elided (its DOM is already in the bracket); multi-root components show a `Fragment` node.\n\n### inspect\n\n```\nagent-vuetools inspect <query> [--fields ...] [--json]\n```\n\nDeep-dives one component. Resolution order: **component name** → `__file` path substring (case-insensitive) → **CSS selector** → **XPath expression** → **visible text**.\n\nOutput: prop definitions (type/required/default) + resolved values, setupState (refs unwrapped; script-setup's `props`/`emit`/`expose` bindings are collapsed to `[Props]`/`[Emit]`/`[Expose]` markers), computed, data, exposed, slots, attrs, provides, declared emits, and the parent chain.\n\n```\nCounter (src/components/Counter.vue)\n  DOM: <div#counter-box>\n  Parent chain: App\n\n  props:\n    step: 1  (Number, required)\n    count: 3  (Number, default 0)\n    label: \"Count\"  (String, default \"Count\")\n\n  setupState:\n    props: \"[Props]\"\n    emit: \"[Emit]\"\n    doubled: 6\n    local: 7\n```\n\n### find\n\n```\nagent-vuetools find <name|path-substring>\n```\n\nLocates components in the tree and prints each match with its parent chain:\n\n```\nNavLink (src/components/NavLink.vue)\n  at: App → Header → NavLink\n```\n\n### query\n\n```\nagent-vuetools query <xpath|css> [--limit N] [--json]\n```\n\nCollects DOM elements (XPath expression or CSS selector). Each match reports the element descriptor plus its owning component (name/`__file`, or null for plain DOM). Capped at 50 matches by default. Works on non-Vue pages too.\n\n```\n# 2 of 2 matches for \"//button[contains(@class, \"q-btn\")]\"\n[BUTTON#q-btn-1.q-btn] \"Submit order\" — QueryApp\n[BUTTON#q-btn-2.q-btn] \"Cancel\" — QueryApp\n```\n\n### style\n\n```\nagent-vuetools style <xpath|css> [--all] [--json]\n```\n\nDumps an element's computed style (a curated ~40 layout/typography/color properties by default, `--all` for every property), inline style, and explicit `tag` / `id` / **full untruncated `class`** / `text` fields — the class attribute is the primary hook for style debugging. Works on non-Vue pages too.\n\n```\ntag: span\nclass: \"oio-action-content\"\ntext: \"Back to member list\"\ncomputed style:\n  display: inline-block\n  position: static\n  width: 98px\n```\n\n### Selectors\n\n`inspect` resolves its query in a fixed chain (name → `__file` → CSS → XPath → visible text); `query` and `style` accept XPath or CSS directly. XPath expressions are evaluated by the browser's native engine (XPath 1.0).\n\n> `contains(text(), 'q')` only checks the **first** text node — elements whose text is split by template interpolation won't match. To match any direct text node, use `//*[text()[contains(., 'q')]]`. See [skills/agent-vuetools/references/xpath.md](skills/agent-vuetools/references/xpath.md) for the full XPath reference.\n\n## Agent Mode\n\n`--json` prints a single-line envelope on stdout — errors included:\n\n```json\n{\"ok\":true,\"command\":\"tree\",\"page\":{\"title\":\"…\",\"url\":\"…\"},\n \"vue\":{\"version\":\"3.5.42\",\"apps\":1,\"truncated\":false},\n \"data\":{\"roots\":[{\"name\":\"App\",\"kind\":\"component\",\"file\":\"src/App.vue\",\"dom\":{\"tag\":\"div\",\"id\":\"app\"},\n   \"props\":{\"msg\":\"hi\"},\"setupState\":{\"count\":3},\"children\":[…]}]}}\n```\n\nError envelope: `{\"ok\":false,\"error\":{\"code\":\"…\",\"message\":\"…\",\"hint\":\"…\"}}` with a stable `code`:\n\n| Code | Meaning |\n|---|---|\n| `no-vue` | No Vue 3 app on the selected page (may still be loading — retry) |\n| `vue2` | Vue 2 detected — not supported |\n| `not-found` | No component/element matches the query |\n| `bad-query` | Invalid XPath / CSS expression |\n| `no-browser` | No reachable CDP endpoint |\n| `ambiguous-tab` | Multiple tabs, none selected — error lists them |\n| `bad-tab` | `--tab` selector matched nothing |\n\nExit codes: `0` success / `1` runtime error / `2` usage error. With `--json`, the error JSON goes to stdout and the human-readable explanation to stderr.\n\n## Connecting\n\n1. **`--cdp <port|host:port|http(s)://url|ws(s)://url>`** — explicit debugging endpoint\n2. **Fallback probe of `127.0.0.1:9222`**\n\nMultiple tabs: pick with `--tab` (`t1`/`t2`… 1-based, exact title, or URL substring). Prefer URL substrings — `Target.getTargets` order is not guaranteed. With multiple tabs and no `--tab`, the CLI errors and lists the options.\n\n## Browser operations\n\nagent-vuetools inspects but never drives the page. For browser control — opening URLs, clicking, filling forms, screenshots — pair it with [agent-browser](https://github.com/vercel-labs/agent-browser), which manages a Chrome instance over the same CDP protocol:\n\n```bash\nnpm i -g agent-browser\nagent-browser install                  # first time only\nagent-browser open http://localhost:5173\n\nagent-vuetools tree --cdp \"$(agent-browser get cdp-url)\"   # inspect its browser\nagent-browser click \"#submit\"                               # drive the UI\nagent-vuetools inspect SubmitButton --cdp \"$(agent-browser get cdp-url)\" --fields props,setupState,computed\n```\n\n`agent-browser get cdp-url` bridges the two tools: it prints the ws URL of agent-browser's Chrome, which agent-vuetools accepts directly via `--cdp`.\n\n## Limits & Caveats\n\n- **Vue 3 only** (Vue 2 → `vue2` error; the probe is pluggable — contributions welcome).\n- **Production builds** lose `__file`, component names, and script-setup computed names (fall back to `Anonymous`) — the same limits vue-devtools has. Dev builds give the richest output.\n- **iframes**: main frame only. **KeepAlive** cached components are not expanded (cycle guard); **Suspense** only walks the resolved branch.\n- **Huge pages**: tree caps at 5000 nodes (`truncated: true`). For deep content, use `inspect`/`query` with XPath or text targeting instead of the tree.\n- Reading computed values triggers their getters (side-effect-free by convention — standard for component inspection tools).\n\n## Skill for AI Coding Assistants\n\nInstall the agent-vuetools skill with the [skills](https://skills.sh) CLI, directly from GitHub:\n\n```bash\nnpx skills add adamancyzhang/agent-vuetools\n```\n\nThe skill is fetched from this repository (`skills/agent-vuetools/SKILL.md`), so it stays up to date automatically. Works with Claude Code, Codex, Cursor, Gemini CLI, and other skills-aware assistants. Do not copy `SKILL.md` from `node_modules` — it will become stale.\n\nManual install for Claude Code:\n\n```bash\nmkdir -p .claude/skills\ncp -r skills/agent-vuetools .claude/skills/\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build          # typecheck + esbuild bundle to dist/cli.js\nnpm run test           # unit tests (ws.Server for the CDP layer; jsdom + Vue runtime for the probe)\nnpm run test:e2e       # E2E: real headless Chrome + Vite dev fixture (requires local Chrome)\nnpm run fixture:serve  # serve the fixture dev server manually (port 4173)\n```\n\nLayout: `src/cdp/` (minimal CDP client, endpoint discovery, tab attach) · `src/probe/probe.js` (the injected page probe, embedded into the bundle as a string at build time) · `src/commands/` (tree/inspect/find/query/style) · `src/output/text.ts` (text rendering) · `test/fixtures/vue-app/` (Vite + Vue 3 fixture) · `skills/` (agent skill docs).\n\n## Roadmap\n\n- Vue 2 support (probe adapter layer already in place)\n- iframe / shadow DOM traversal\n- Live emitted-event stream\n- MCP server mode\n\n## License\n\n[MIT](LICENSE) © 2026 Adamancy Zhang\n","readmeFilename":"README.md"}