aipeek 0.2.3 → 0.2.5

package/src/server/plugin.ts

@@ -0,0 +1,493 @@
+import type { Plugin, ViteDevServer } from 'vite'
+import type { ActionArgs, ActionResult } from '../core/action'
+import type { RawState } from '../core/types'
+import { Buffer } from 'node:buffer'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { transformSync } from 'esbuild'
+import { resolveAction } from '../core/action'
+import { check } from '../core/check'
+import { compact } from '../core/compact'
+import { detail } from '../core/detail'
+import { diffState } from '../core/diff'
+import { emit, emitCheck, emitDiff, emitSummary } from '../core/emit'
+
+function readBody(req: { on: (e: string, cb: (c: unknown) => void) => void }): Promise<string> {
+    return new Promise((resolve) => {
+        let s = ''
+        req.on('data', c => s += c)
+        req.on('end', () => resolve(s))
+    })
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+// client/core sources are read at runtime (client.ts served via Vite transform,
+// client-patch.ts compiled by esbuild). Two layouts: source consumption
+// (__dirname=src/server → ../client) and published package (__dirname=dist → ../src/client).
+const clientDir = existsSync(resolve(__dirname, '../client'))
+    ? resolve(__dirname, '../client')
+    : resolve(__dirname, '../src/client')
+const clientPath = resolve(clientDir, 'client.ts')
+const patchPath = resolve(clientDir, 'client-patch.ts')
+
+// Compile patch code to JS at plugin init (synchronous, runs once)
+function compilePatch(): string {
+    const source = readFileSync(patchPath, 'utf-8')
+    const result = transformSync(source, {
+        loader: 'ts',
+        target: 'es2020',
+        format: 'iife',
+        minify: false,
+    })
+    return result.code
+}
+
+function aipeekSnippet(port: number) {
+    const base = `http://localhost:${port}/__aipeek`
+    return `
+# aipeek — Runtime Browser Inspector
+
+IMPORTANT: Before debugging any UI issue, visual bug, or runtime error, ALWAYS fetch the live app state first. Do NOT guess — look at the actual browser state.
+
+## Read state — cheapest first
+
+\`\`\`bash
+curl ${base}/screen   # state-machine projection {view, modal, focus, knobs} — START HERE
+curl ${base}/ui                  # React component tree — deep-dive when /screen isn't enough
+curl '${base}/dom?scope=ChatInput' # semantic DOM scoped to a component — UI as text, src locations
+curl ${base}          # high-density summary (ok sections → 1 line, issues → expanded)
+curl ${base}?full     # full dump: UI tree + console + network + errors + state
+curl ${base}/check    # pass/fail health check — use after code changes
+curl ${base}/console  # console logs (errors, warnings, info)
+curl ${base}/network  # fetch/XHR requests with status and timing
+curl ${base}/errors   # uncaught errors and unhandled rejections
+curl ${base}/state    # registered store snapshots
+\`\`\`
+
+\`/screen\` projects the whole UI to a few state variables — start there, not \`/ui\`. Append
+\`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
+
+To inspect or edit a component, work top-down — the full DOM is huge, a scoped view is
+accurate: \`/screen\` or \`/ui\` to find the component, then \`/dom?scope=<Name>\` (matches the
+source path) or \`/dom?sel=<css>\` for just that subtree. Each line carries its source
+location (\`@File.tsx:line\`), so the DOM view tells you exactly where to edit.
+
+## Drive the page (acts on the currently-open tab — no separate browser)
+
+\`\`\`bash
+curl '${base}/click?text=New'            # click by visible text (or sel= for CSS)
+curl '${base}/fill?sel=textarea&value=hi' # set an input/textarea/select value
+curl '${base}/press?key=Enter'           # key on focused element (e.g. Control+a)
+curl '${base}/wait?text=Done&timeout=8000' # poll until text/sel appears (add gone=1 to wait until it disappears)
+curl '${base}/screenshot?out=shot.png'   # DOM→PNG into .aipeek/ (html-to-image; lossy)
+\`\`\`
+
+\`click\`/\`fill\`/\`press\` settle the DOM and append the resulting UI tree (\`--- ui after ---\`)
+to the response — no follow-up read needed. On a miss, the response lists the reachable
+clickable elements so you can re-target. URL-encode any \`sel=\` with non-ASCII or quotes:
+\`curl -G ${base}/click --data-urlencode 'sel=button[title="知识库"]'\`.
+
+**Chain — a whole interaction in one round-trip.** POST a JSON array; runs in sequence,
+each step settles before the next, stops on first failure:
+
+\`\`\`bash
+curl -X POST ${base}/chain -d '[
+  {"type":"click","sel":"button[title=\\"知识库\\"]"},
+  {"type":"wait","text":"Done"},
+  {"type":"fill","sel":"textarea","value":"hi"},
+  {"type":"press","key":"Enter"}
+]'
+\`\`\`
+
+**Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
+JS in the page and returns the result — for anything the typed endpoints can't do.
+
+aipeek auto-detects errors after HMR and prints them to the terminal — watch for \`[aipeek]\` messages.
+`
+}
+
+export const START_TAG = '<!-- AIPEEK:START -->'
+export const END_TAG = '<!-- AIPEEK:END -->'
+
+// Marker-based injection — the block lives between START_TAG and END_TAG, so
+// re-injection is a deterministic splice (find markers, replace between) rather
+// than fuzzy line matching. New file → write markers + snippet. Existing markers
+// → replace their contents. No markers yet → append a fresh marked block.
+export function injectClaudeMd(root: string, port: number) {
+    const path = resolve(root, 'CLAUDE.md')
+    const block = `${START_TAG}\n${aipeekSnippet(port).trim()}\n${END_TAG}\n`
+    try {
+        if (!existsSync(path)) {
+            writeFileSync(path, block)
+            return
+        }
+        const content = readFileSync(path, 'utf-8')
+        const si = content.indexOf(START_TAG)
+        const ei = content.indexOf(END_TAG)
+        if (si !== -1 && ei !== -1) {
+            writeFileSync(path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length))
+            return
+        }
+        const sep = content.endsWith('\n') ? '' : '\n'
+        writeFileSync(path, `${content}${sep}\n${block}`)
+    }
+    catch {}
+}
+
+export function aipeekPlugin(): Plugin {
+    let pendingResolve: ((data: RawState) => void) | null = null
+    let server: ViteDevServer
+    let lastRaw: RawState | null = null
+    let pushTimer: ReturnType<typeof setTimeout> | undefined
+    const pendingActions = new Map<number, (r: ActionResult) => void>()
+    let actionId = 0
+
+    let pendingDom: ((dom: string) => void) | null = null
+    let pendingScreen: ((screen: string) => void) | null = null
+    const pendingEvals = new Map<number, (r: { ok: boolean, value?: string, error?: string }) => void>()
+    let evalId = 0
+
+    // Multi-tab: round one asks only the visible tab (requireVisible). If no tab is
+    // visible (user reading the terminal), nobody answers within VISIBLE_MS, so round
+    // two drops the guard and any tab replies. `arm` installs the pending slot and
+    // returns a clearer; the slot's resolve settles the promise on either round.
+    const VISIBLE_MS = 400
+    function twoPhase<T>(
+        event: string,
+        payload: Record<string, unknown>,
+        arm: (resolve: (v: T) => void) => () => void,
+        fullMs = 3000,
+    ): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            let settled = false
+            const clear = arm((v) => {
+                settled = true
+                resolve(v)
+            })
+            server.hot.send(event, { ...payload, requireVisible: true })
+            setTimeout(() => {
+                if (settled)
+                    return
+                // no visible tab answered — ask everyone
+                server.hot.send(event, { ...payload, requireVisible: false })
+                setTimeout(() => {
+                    if (settled)
+                        return
+                    clear()
+                    reject(new Error(`timeout: no client response within ${VISIBLE_MS + fullMs}ms`))
+                }, fullMs)
+            }, VISIBLE_MS)
+        })
+    }
+
+    function collectFromClient(): Promise<RawState> {
+        return twoPhase<RawState>('aipeek:collect', {}, (resolve) => {
+            pendingResolve = resolve
+            return () => {
+                pendingResolve = null
+            }
+        })
+    }
+
+    function collectDomFromClient(scope?: string, sel?: string): Promise<string> {
+        return twoPhase<string>('aipeek:collect-dom', { scope, sel }, (resolve) => {
+            pendingDom = resolve
+            return () => {
+                pendingDom = null
+            }
+        })
+    }
+
+    function collectScreenFromClient(): Promise<string> {
+        return twoPhase<string>('aipeek:collect-screen', {}, (resolve) => {
+            pendingScreen = resolve
+            return () => {
+                pendingScreen = null
+            }
+        })
+    }
+
+    function sendAction(type: string, args: ActionArgs): Promise<ActionResult> {
+        const id = ++actionId
+        // wait actions own their timeout; give the channel that long + slack
+        const fullMs = Math.max(args.timeout ?? 0, 3000) + 2000
+        return twoPhase<ActionResult>('aipeek:action', { id, type, args }, (resolve) => {
+            pendingActions.set(id, resolve)
+            return () => {
+                pendingActions.delete(id)
+            }
+        }, fullMs)
+    }
+
+    function evalInClient(code: string): Promise<{ ok: boolean, value?: string, error?: string }> {
+        const id = ++evalId
+        return twoPhase('aipeek:eval', { id, code }, (resolve) => {
+            pendingEvals.set(id, resolve)
+            return () => {
+                pendingEvals.delete(id)
+            }
+        }, 8000)
+    }
+
+    return {
+        name: 'aipeek',
+        apply: 'serve',
+
+        transformIndexHtml() {
+            const patchCode = compilePatch()
+            return [
+                // Synchronous inline script — patches console/fetch/XHR/errors
+                // BEFORE any ES modules execute
+                {
+                    tag: 'script',
+                    children: patchCode,
+                    injectTo: 'head-prepend',
+                },
+                // Module script — collectors + HMR channel (can be deferred)
+                {
+                    tag: 'script',
+                    attrs: { type: 'module' },
+                    children: `import '/@fs/${clientPath}'`,
+                    injectTo: 'body',
+                },
+            ]
+        },
+
+        configureServer(_server) {
+            server = _server
+            injectClaudeMd(server.config.root, server.config.server.port || 5173)
+
+            server.hot.on('aipeek:state', (data: RawState) => {
+                if (pendingResolve) {
+                    pendingResolve(data)
+                    pendingResolve = null
+                }
+            })
+
+            server.hot.on('aipeek:result', (data: ActionResult & { id: number }) => {
+                const resolve = pendingActions.get(data.id)
+                if (resolve) {
+                    pendingActions.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            server.hot.on('aipeek:eval-result', (data: { id: number, ok: boolean, value?: string, error?: string }) => {
+                const resolve = pendingEvals.get(data.id)
+                if (resolve) {
+                    pendingEvals.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            server.hot.on('aipeek:dom', (data: { dom: string }) => {
+                if (pendingDom) {
+                    pendingDom(data.dom)
+                    pendingDom = null
+                }
+            })
+
+            server.hot.on('aipeek:screen', (data: { screen: string }) => {
+                if (pendingScreen) {
+                    pendingScreen(data.screen)
+                    pendingScreen = null
+                }
+            })
+
+            // push mode: auto-detect errors after HMR
+            server.hot.on('vite:afterUpdate', () => {
+                clearTimeout(pushTimer)
+                pushTimer = setTimeout(async () => {
+                    try {
+                        const raw = await collectFromClient()
+                        const diff = diffState(lastRaw, raw)
+                        lastRaw = raw
+                        if (!diff.clean) {
+                            const msg = emitDiff(diff)
+                            if (msg)
+                                server.config.logger.warn(msg)
+                        }
+                    }
+                    catch {}
+                }, 500)
+            })
+
+            // /__aipeek — summary
+            // /__aipeek/{section}/{index} — detail
+            // /__aipeek/check — health check
+            server.middlewares.use('/__aipeek', async (req, res) => {
+                const url = new URL(req.url || '/', 'http://localhost')
+                const parts = url.pathname.split('/').filter(Boolean)
+                const full = url.searchParams.has('full')
+
+                try {
+                    // /__aipeek/eval — run arbitrary JS in the page. POST body = code,
+                    // or ?code=. The page evaluates it and returns the result (or thrown
+                    // error). The escape hatch for anything the typed endpoints can't do:
+                    // install event listeners, read closures, probe real event flow.
+                    if (parts[0] === 'eval') {
+                        let code = url.searchParams.get('code') || ''
+                        if (!code && req.method === 'POST')
+                            code = await readBody(req)
+                        if (!code) {
+                            res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' })
+                            res.end('eval needs ?code= or a POST body')
+                            return
+                        }
+                        const r = await evalInClient(code)
+                        res.writeHead(r.ok ? 200 : 422, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(r.ok ? (r.value ?? 'undefined') : `error: ${r.error}`)
+                        return
+                    }
+
+                    // /__aipeek/dom[?scope=Component|?sel=CSS] — semantic DOM, scoped, on-demand
+                    if (parts[0] === 'dom') {
+                        const dom = await collectDomFromClient(
+                            url.searchParams.get('scope') || undefined,
+                            url.searchParams.get('sel') || undefined,
+                        )
+                        res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(dom || '(empty)')
+                        return
+                    }
+
+                    // /__aipeek/screen — state-machine projection {view, modal, focus, knobs}
+                    if (parts[0] === 'screen') {
+                        const screen = await collectScreenFromClient()
+                        res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(screen || '(empty)')
+                        return
+                    }
+
+                    // /__aipeek/chain — POST a JSON array of actions, run them in
+                    // sequence (each settles the DOM before the next), stop on first
+                    // failure. One round-trip for a whole interaction.
+                    if (parts[0] === 'chain') {
+                        const body = await readBody(req)
+                        let steps: Array<{ type: string } & ActionArgs>
+                        try {
+                            steps = JSON.parse(body)
+                            if (!Array.isArray(steps))
+                                throw new Error('body must be a JSON array')
+                        }
+                        catch (e) {
+                            res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' })
+                            res.end(`invalid chain body: ${e instanceof Error ? e.message : String(e)}`)
+                            return
+                        }
+                        lastRaw = null
+                        const lines: string[] = []
+                        let lastUi = ''
+                        let allOk = true
+                        for (let i = 0; i < steps.length; i++) {
+                            const { type, ...args } = steps[i]
+                            const check = resolveAction(type, args)
+                            if (!check.valid) {
+                                lines.push(`[${i}] ✗ ${type}: ${check.error}`)
+                                allOk = false
+                                break
+                            }
+                            const r = await sendAction(type, args)
+                            lines.push(`[${i}] ${r.ok ? '✓' : '✗'} ${type}: ${r.ok ? (r.detail || 'ok') : r.error}`)
+                            // Per-step screen projection — captures the transition each
+                            // mutating step caused, so a view change mid-chain is visible
+                            // at its source step rather than collapsed into the final tree.
+                            if (r.screen)
+                                lines.push(r.screen.split('\n').map(l => `    ${l}`).join('\n'))
+                            if (r.ui)
+                                lastUi = r.ui
+                            if (!r.ok) {
+                                allOk = false
+                                break
+                            }
+                        }
+                        res.writeHead(allOk ? 200 : 422, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(lastUi ? `${lines.join('\n')}\n\n--- ui after ---\n${lastUi}` : lines.join('\n'))
+                        return
+                    }
+
+                    // action endpoints: /__aipeek/{click|fill|press|wait|screenshot}?...
+                    if (['click', 'fill', 'press', 'wait', 'screenshot'].includes(parts[0])) {
+                        const q = url.searchParams
+                        const args: ActionArgs = {
+                            sel: q.get('sel') || undefined,
+                            text: q.get('text') || undefined,
+                            value: q.has('value') ? q.get('value')! : undefined,
+                            key: q.get('key') || undefined,
+                            timeout: q.has('timeout') ? Number(q.get('timeout')) : undefined,
+                            gone: q.has('gone') ? q.get('gone') !== 'false' : undefined,
+                        }
+                        const check = resolveAction(parts[0], args)
+                        if (!check.valid) {
+                            res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' })
+                            res.end(check.error)
+                            return
+                        }
+                        const result = await sendAction(parts[0], args)
+                        lastRaw = null // page mutated; force fresh collect next read
+                        if (parts[0] === 'screenshot' && result.dataUrl) {
+                            const dir = resolve(server.config.root, '.aipeek')
+                            mkdirSync(dir, { recursive: true })
+                            const name = q.get('out') || `shot-${result.dataUrl.length}.png`
+                            const file = resolve(dir, name)
+                            writeFileSync(file, Buffer.from(result.dataUrl.split(',')[1], 'base64'))
+                            res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                            res.end(`saved: ${file}`)
+                            return
+                        }
+                        res.writeHead(result.ok ? 200 : 422, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        const head = result.ok ? (result.detail || 'ok') : `${result.error}${result.detail ? `\n\nclickable: ${result.detail}` : ''}`
+                        res.end(result.ui ? `${head}\n\n--- ui after ---\n${result.ui}` : head)
+                        return
+                    }
+
+                    // check endpoint
+                    if (parts[0] === 'check') {
+                        const raw = await collectFromClient()
+                        lastRaw = raw
+                        const result = check(raw)
+                        const output = emitCheck(result)
+                        res.writeHead(result.pass ? 200 : 417, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(output)
+                        return
+                    }
+
+                    // detail: /__aipeek/{section}[/{index}][?full]
+                    if (parts.length >= 1) {
+                        if (!lastRaw)
+                            lastRaw = await collectFromClient()
+                        const result = detail(lastRaw, parts[0], parts[1], full)
+                        if (result !== null) {
+                            res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                            res.end(result)
+                            return
+                        }
+                        res.writeHead(404, { 'Content-Type': 'text/plain' })
+                        res.end(`not found: ${parts.join('/')}`)
+                        return
+                    }
+
+                    // summary or full: /__aipeek[?full]
+                    const raw = await collectFromClient()
+                    lastRaw = raw
+                    if (full) {
+                        const compacted = compact(raw)
+                        const output = emit(compacted)
+                        res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(output)
+                    }
+                    else {
+                        const output = emitSummary(raw)
+                        res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
+                        res.end(output)
+                    }
+                }
+                catch (err) {
+                    res.writeHead(504, { 'Content-Type': 'text/plain' })
+                    res.end(err instanceof Error ? err.message : 'unknown error')
+                }
+            })
+        },
+    }
+}