kapi-ui 0.2.1 → 0.3.0

package/dist/node/codex-agent.js

@@ -0,0 +1,138 @@
+// Mirrors claude-agent.ts's workflow: one session is established at server
+// start (the KAPI_SESSION_PROMPT turn) and every later submission resumes it,
+// so all tabs share one continuous session in submission order. The one thing
+// codex can't do that Claude can: `codex exec` is one-shot (no stdin-driven
+// warm process), so each turn still pays process cold-start — session
+// continuity is preserved via `exec resume <id>`, but the process isn't warm.
+// ponytail: cold-start per turn is inherent to `codex exec`; only a codex
+// server/stdin mode could remove it — none exists in the CLI today.
+import { spawn } from 'child_process';
+const KAPI_SESSION_PROMPT = "You're applying UI edits from visual comments. Each comment gives the exact file:line:col — go straight there, don't search for it. Make only the requested edit. " +
+    'Before finishing, check whether a higher-precedence rule on the same element would override the property you just changed — an inline `style` attribute, `!important`, a more specific selector, or a utility class applied after it. You have no way to see the rendered result, so if such a conflict exists, edit the highest-precedence source instead of (or in addition to) the one you found first, so the change actually takes visible effect. ' +
+    'Stay terse: no narration between steps, and finish with at most one short sentence.';
+function startSession(cwd, prompt) {
+    return spawn('codex', ['exec', '--json', '--skip-git-repo-check', '--sandbox', 'workspace-write', '--cd', cwd, prompt], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+function resumeSession(activeSession, prompt) {
+    return spawn('codex', ['exec', 'resume', activeSession.id, '--json', '--skip-git-repo-check', prompt], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+function sessionIdFromEvent(event) {
+    return typeof event?.thread_id === 'string' ? event.thread_id : null;
+}
+function describeEvent(event) {
+    const item = event?.item;
+    if (item?.type === 'command_execution' && item.command)
+        return `Running: ${String(item.command).slice(0, 60)}`;
+    if (item?.type === 'agent_message' && item.text)
+        return String(item.text).slice(0, 120);
+    if (item?.type === 'file_change' && item.path)
+        return `Editing ${item.path}`;
+    return null;
+}
+let cwd = process.cwd();
+let session = null;
+let child = null;
+let busy = false; // a turn is currently running
+// Which client to notify when the running turn finishes. Null for the startup
+// turn that sends KAPI_SESSION_PROMPT — there's no tab yet.
+let activeClient = null;
+// FIFO queue of turns waiting for the current one to finish. The first entry,
+// queued at server startup, is the KAPI_SESSION_PROMPT itself.
+const pendingPrompts = [];
+function processQueue() {
+    if (busy || pendingPrompts.length === 0)
+        return;
+    const next = pendingPrompts.shift();
+    busy = true;
+    activeClient = next.client;
+    next.client?.send('kapi:processing', { status: session ? 'Continuing session...' : 'Starting Codex...' });
+    const proc = session ? resumeSession(session, next.prompt) : startSession(cwd, next.prompt);
+    child = proc;
+    let buffer = '';
+    let failed = false;
+    const handleEvent = (event) => {
+        const nextSessionId = sessionIdFromEvent(event);
+        if (nextSessionId && nextSessionId !== session?.id) {
+            session = { agent: 'codex', id: nextSessionId };
+            console.log(`[kapi] codex session started: ${nextSessionId}`);
+        }
+        const status = describeEvent(event);
+        if (status)
+            activeClient?.send('kapi:processing', { status });
+    };
+    proc.stdout.on('data', (chunk) => {
+        buffer += chunk.toString();
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (!line)
+                continue;
+            try {
+                handleEvent(JSON.parse(line));
+            }
+            catch {
+                // Ignore non-JSON progress from a CLI and continue reading its stream.
+            }
+        }
+    });
+    proc.stderr.pipe(process.stderr);
+    proc.on('error', (error) => {
+        failed = true;
+        activeClient?.send('kapi:error', { message: error.message });
+    });
+    proc.on('close', (code) => {
+        if (buffer.trim()) {
+            try {
+                handleEvent(JSON.parse(buffer));
+            }
+            catch {
+                // A final non-JSON line is only CLI output, not a Kapi protocol event.
+            }
+        }
+        if (code !== 0 && !proc.killed && !failed) {
+            activeClient?.send('kapi:error', { message: `codex exited with code ${code}.` });
+        }
+        else if (!failed) {
+            activeClient?.send('kapi:done');
+        }
+        if (child === proc)
+            child = null;
+        busy = false;
+        activeClient = null;
+        processQueue();
+    });
+}
+export const codexAgent = {
+    start(startCwd) {
+        cwd = startCwd;
+        // Establish the session up front (before any tab connects) so the user's
+        // first real submission resumes an existing session instead of creating one.
+        pendingPrompts.push({ prompt: KAPI_SESSION_PROMPT, client: null });
+        processQueue();
+    },
+    submit(prompt, client) {
+        pendingPrompts.push({ prompt, client });
+        processQueue();
+    },
+    stop(client) {
+        // Drop anything this client queued but hasn't started.
+        for (let i = pendingPrompts.length - 1; i >= 0; i--) {
+            if (pendingPrompts[i].client === client)
+                pendingPrompts.splice(i, 1);
+        }
+        // Kill the running turn only if it's this client's. The close handler
+        // clears state and starts the next queued turn (resuming the session).
+        if (activeClient === client && child) {
+            console.log('[kapi] stopping codex process');
+            child.kill();
+        }
+    },
+    onClose(client) {
+        codexAgent.stop(client);
+    },
+};

package/dist/node/nuxt-module.js

@@ -0,0 +1,34 @@
+import { defineNuxtModule, addVitePlugin } from '@nuxt/kit';
+import kapiVitePlugin from './vite-plugin.js';
+export default defineNuxtModule({
+    meta: {
+        name: 'kapi-ui',
+        configKey: 'kapi',
+    },
+    setup(options, nuxt) {
+        var _a;
+        if (!nuxt.options.dev)
+            return;
+        // The vite plugin does everything now — instrumentation, the overlay
+        // module, and wiring the agent onto Vite's HMR websocket (its
+        // configureServer hook). Registering it here means Nuxt's Vite server
+        // gets that wiring too; the overlay talks back over the same HMR channel
+        // Nitro already proxies, so there's no separate port to inject.
+        addVitePlugin(kapiVitePlugin(options));
+        // Nitro renders HTML, not Vite's transformIndexHtml, so the overlay script
+        // still has to be injected here via unhead. Nuxt mounts Vite's dev
+        // middleware under app.buildAssetsDir (e.g. /_nuxt/), not at the site
+        // root, so request it from under that prefix or Nitro's page renderer
+        // intercepts it before Vite ever sees it.
+        (_a = nuxt.options.app.head).script || (_a.script = []);
+        // Tell the overlay the agent session is off so it hides the AI button.
+        // Classic inline script runs before the deferred overlay module reads it.
+        if (options.agent === false) {
+            nuxt.options.app.head.script.push({ innerHTML: 'window.__KAPI_AGENT_ENABLED__=false' });
+        }
+        nuxt.options.app.head.script.push({
+            src: `${nuxt.options.app.buildAssetsDir}@kapi-ui/overlay`,
+            type: 'module',
+        });
+    },
+});

package/dist/node/types.js

@@ -0,0 +1,4 @@
+// Shared type definitions for the node tier (vite plugin, nuxt module,
+// agents). `KapiOptions` and `KapiAgent` are re-exported by vite-plugin.ts as
+// part of the package's public API.
+export {};

package/dist/node/vite-plugin.js

@@ -0,0 +1,213 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { searchForWorkspaceRoot } from 'vite';
+import { walk } from 'estree-walker';
+import MagicString from 'magic-string';
+import { SourceMapConsumer } from 'source-map-js';
+import { claudeAgent } from './claude-agent.js';
+import { codexAgent } from './codex-agent.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const overlayPath = path.resolve(__dirname, '../browser/overlay.js');
+const traceRecordPath = path.resolve(__dirname, '../browser/trace-record.js');
+// Names Vue's SFC compiler emits in a component's compiled render function
+// for every vnode it creates. Wrapping calls to these — rather than parsing
+// the original template — means coverage always matches whatever Vue itself
+// just compiled, including dynamic `h()` calls a template-source parser would
+// never see.
+const VNODE_FUNCTIONS = [
+    'h',
+    '_createElementVNode',
+    '_createElementBlock',
+    '_createBlock',
+    '_createVNode',
+    '_createStaticVNode',
+];
+const vnodeCallRe = new RegExp(`\\b(?:${VNODE_FUNCTIONS.join('|')})\\(`);
+const INSTRUMENTED_MARKER = '/* kapi-ui:instrumented */';
+// Byte offset of the start of each line (line 1 starts at offset 0). Built
+// once per file so looking up a call's line/column is a binary search
+// instead of re-scanning from the start of the file for every vnode call.
+function buildLineOffsets(code) {
+    const offsets = [0];
+    for (let i = 0; i < code.length; i++) {
+        if (code[i] === '\n')
+            offsets.push(i + 1);
+    }
+    return offsets;
+}
+function offsetToPos(lineOffsets, index) {
+    let lo = 0;
+    let hi = lineOffsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineOffsets[mid] <= index)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo + 1, column: index - lineOffsets[lo] };
+}
+function createUniqueIdentifier(base, identifiers) {
+    let identifier = base;
+    let suffix = 1;
+    while (identifiers.has(identifier)) {
+        identifier = `${base}_${suffix++}`;
+    }
+    identifiers.add(identifier);
+    return identifier;
+}
+// Normalize + validate the `agent` option once, up front. `agent` is required
+// (no default): a missing or bad value throws at dev-server startup with a
+// clear message instead of silently falling back to Claude — which would be
+// especially confusing for a value the user meant as "off" (e.g. 'none').
+function resolveAgent(agent) {
+    if (agent === undefined) {
+        throw new Error("[kapi-ui] The `agent` option is required. Set it to 'claude', 'codex', or false (manual copy/paste).");
+    }
+    if (agent === false)
+        return false; // manual copy/paste
+    if (agent === 'claude' || agent === 'codex')
+        return agent;
+    throw new Error(`[kapi-ui] Invalid \`agent\` option: ${JSON.stringify(agent)}. Use 'claude', 'codex', or false (manual copy/paste).`);
+}
+export default function kapi(options) {
+    const agent = resolveAgent(options?.agent);
+    let started = false;
+    return {
+        name: 'kapi-ui',
+        // Must run after @vitejs/plugin-vue has compiled templates into
+        // vnode-creation calls — this transform rewrites that compiled output,
+        // not the raw SFC source.
+        enforce: 'post',
+        apply: 'serve',
+        config() {
+            return {
+                server: {
+                    fs: {
+                        allow: [searchForWorkspaceRoot(process.cwd()), path.dirname(overlayPath)],
+                    },
+                },
+            };
+        },
+        // Ride Vite's own HMR websocket instead of standing up a second server on
+        // its own port: the overlay talks to us via custom HMR events (see
+        // browser/socket.ts), and we dispatch them to the configured agent. In
+        // Nuxt this runs too, since nuxt-module.ts registers this same plugin.
+        configureServer(server) {
+            if (agent === false)
+                return; // manual copy/paste only — no agent session
+            if (started)
+                return; // configureServer can fire more than once; agent.start() must not
+            started = true;
+            const cwd = process.cwd();
+            const runtime = agent === 'codex' ? codexAgent : claudeAgent;
+            runtime.start(cwd);
+            // Vite hands the event handler a fresh WebSocketClient wrapper but a
+            // stable underlying `.socket` per connection; key one AgentClient per
+            // socket so submit/stop/close all agree on identity and share a sender.
+            const clients = new Map();
+            const clientFor = (c) => {
+                let existing = clients.get(c.socket);
+                if (!existing) {
+                    existing = { send: (event, data) => c.send(event, data) };
+                    clients.set(c.socket, existing);
+                }
+                return existing;
+            };
+            server.ws.on('kapi:submit', (data, client) => runtime.submit(data.prompt, clientFor(client), cwd));
+            server.ws.on('kapi:stop', (_data, client) => runtime.stop(clientFor(client)));
+            server.ws.on('connection', (socket) => {
+                socket.on('close', () => {
+                    const existing = clients.get(socket);
+                    if (existing) {
+                        runtime.onClose(existing);
+                        clients.delete(socket);
+                    }
+                });
+            });
+        },
+        resolveId(id) {
+            if (id === '/@kapi-ui/overlay')
+                return overlayPath;
+            if (id === '/@kapi-ui/trace-record')
+                return traceRecordPath;
+        },
+        transform(code, id) {
+            // `this.environment` only exists on Vite 6+ (the Environment API); vite
+            // is a devDependency here, not a peerDependency, so kapi has no control
+            // over the Vite version in the host project. Treat its absence as
+            // "client" so pre-6 Vite still runs the transform instead of throwing
+            // on every module.
+            if (this.environment && this.environment.name !== 'client')
+                return;
+            if (id.includes('/node_modules/'))
+                return;
+            // Only Vue SFC compiled output contains this — cheap enough to check
+            // before parsing every transformed module in the project.
+            if (!code.includes('_sfc_render('))
+                return;
+            if (!vnodeCallRe.test(code))
+                return;
+            if (code.includes(INSTRUMENTED_MARKER))
+                return;
+            const map = this.getCombinedSourcemap();
+            const consumer = new SourceMapConsumer(map);
+            const s = new MagicString(code);
+            const ast = this.parse(code);
+            const lineOffsets = buildLineOffsets(code);
+            const identifiers = new Set();
+            let hit = false;
+            walk(ast, {
+                enter(node) {
+                    if (node.type === 'Identifier')
+                        identifiers.add(node.name);
+                },
+            });
+            // Vue's compiled render function shares the module's lexical scope, so
+            // reserve names not used anywhere in the parsed module before injecting
+            // either the import binding or the tracer helper.
+            const recordPositionIdentifier = createUniqueIdentifier('__kapiRecordPosition', identifiers);
+            const tracerIdentifier = createUniqueIdentifier('__kapiTracer', identifiers);
+            walk(ast, {
+                enter(node) {
+                    if (node.type !== 'CallExpression' || node.callee.type !== 'Identifier')
+                        return;
+                    if (!VNODE_FUNCTIONS.includes(node.callee.name))
+                        return;
+                    const { start, end } = node;
+                    const original = consumer.originalPositionFor(offsetToPos(lineOffsets, start));
+                    if (original.source === null)
+                        return;
+                    hit = true;
+                    s.appendLeft(start, `${tracerIdentifier}(${original.line},${original.column},`);
+                    s.appendRight(end, ')');
+                },
+            });
+            if (!hit)
+                return;
+            const relativeFile = path.relative(process.cwd(), id.split('?')[0]);
+            s.prepend(`${INSTRUMENTED_MARKER}\nimport { recordPosition as ${recordPositionIdentifier} } from "/@kapi-ui/trace-record"\n`);
+            s.append(`\nfunction ${tracerIdentifier}(line, column, vnode) { return ${recordPositionIdentifier}(${JSON.stringify(relativeFile)}, line, column, vnode) }\n`);
+            return { code: s.toString(), map: s.generateMap({ hires: true }) };
+        },
+        transformIndexHtml() {
+            const tags = [
+                {
+                    tag: 'script',
+                    attrs: { type: 'module', src: '/@kapi-ui/overlay' },
+                    injectTo: 'body',
+                },
+            ];
+            // Tell the overlay the agent session is off so it hides the AI button.
+            // Classic inline script runs before the deferred overlay module reads it.
+            if (agent === false) {
+                tags.unshift({
+                    tag: 'script',
+                    children: 'window.__KAPI_AGENT_ENABLED__=false',
+                    injectTo: 'body',
+                });
+            }
+            return tags;
+        },
+    };
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "kapi-ui",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Visually prompt your UI",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run copy:css",
+    "copy:css": "mkdir -p dist/browser/styles && cp src/browser/styles/*.css dist/browser/styles/",
+    "dev": "npm run copy:css && (node -e \"require('fs').watch('src/browser/styles',()=>require('child_process').execSync('npm run copy:css'))\" & tsc --watch --preserveWatchOutput)",
     "prepublishOnly": "npm run build"
   },
   "files": [
     "dist"
   ],
   "bin": {
-    "kapi-ui": "dist/setup.js"
+    "kapi-ui": "dist/cli/setup.js"
   },
   "exports": {
-    "./vite-plugin": "./dist/vite-plugin.js",
-    "./nuxt": "./dist/nuxt-module.js"
+    "./vite-plugin": "./dist/node/vite-plugin.js",
+    "./nuxt": "./dist/node/nuxt-module.js"
   },
   "repository": {
     "type": "git",
@@ -23,7 +25,7 @@
   "keywords": [
     "ai",
     "design",
-    "fronend"
+    "frontend"
   ],
   "author": "James Bermudo",
   "license": "ISC",
@@ -35,15 +37,14 @@
   "devDependencies": {
     "@nuxt/schema": "^3.14.0",
     "@types/node": "^26.1.0",
-    "@types/prompts": "^2.4.9",
-    "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vite": "^8.1.3"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.14.0",
+    "@nuxt/kit": "^4.4.8",
+    "estree-walker": "^2.0.2",
+    "magic-string": "^0.30.21",
     "magicast": "^0.5.3",
-    "prompts": "^2.4.2",
-    "ws": "^8.21.0"
+    "source-map-js": "^1.2.1"
   }
 }