awel 0.1.0

package/dist/cli/babel-setup.js

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BABEL_CONFIG_FILES = [
+    'babel.config.js',
+    'babel.config.cjs',
+    'babel.config.mjs',
+    '.babelrc',
+    '.babelrc.json',
+    '.babelrc.js',
+    '.babelrc.cjs',
+];
+function getPluginPath() {
+    // babel-plugin-awel-source.cjs lives at the root of the cli package,
+    // which is one level up from dist/ (where this compiled file lives).
+    return join(__dirname, '..', '..', 'babel-plugin-awel-source.cjs');
+}
+function hasPackageJsonBabelKey(projectCwd) {
+    const pkgPath = join(projectCwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return 'babel' in pkg;
+    }
+    catch {
+        return false;
+    }
+}
+function findExistingBabelConfig(projectCwd) {
+    for (const file of BABEL_CONFIG_FILES) {
+        if (existsSync(join(projectCwd, file)))
+            return file;
+    }
+    if (hasPackageJsonBabelKey(projectCwd))
+        return 'package.json';
+    return null;
+}
+function readAwelConfig(projectCwd) {
+    const configPath = join(projectCwd, '.awel', 'config.json');
+    if (!existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeAwelConfig(projectCwd, config) {
+    const dir = join(projectCwd, '.awel');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+// ANSI 256-color helpers — darker shades that stay visible on light backgrounds
+const bold = (s) => `\x1b[1m${s}\x1b[22m`;
+const dim = (s) => `\x1b[2m${s}\x1b[22m`;
+const green = (s) => `\x1b[38;5;34m${s}\x1b[39m`;
+const cyan = (s) => `\x1b[38;5;30m${s}\x1b[39m`;
+function promptSelect(title, description, options) {
+    return new Promise((resolve) => {
+        let selected = 0;
+        const { stdin, stdout } = process;
+        const hide = '\x1b[?25l'; // hide cursor
+        const show = '\x1b[?25h'; // show cursor
+        function render() {
+            // Move to start and clear from cursor down
+            let out = `\x1b[${options.length}A\x1b[J`;
+            for (let i = 0; i < options.length; i++) {
+                const pointer = i === selected ? green('❯') : ' ';
+                const label = i === selected ? bold(options[i].label) : dim(options[i].label);
+                out += `  ${pointer} ${label}\n`;
+            }
+            stdout.write(out);
+        }
+        function cleanup() {
+            stdin.setRawMode(false);
+            stdin.removeListener('data', onKey);
+            stdin.pause();
+            stdout.write(show);
+        }
+        // Print header + initial render
+        stdout.write(`\n${bold(green('?'))} ${bold(title)}\n`);
+        stdout.write(`  ${dim(description)}\n\n`);
+        stdout.write(hide);
+        // Print placeholder lines so render() can overwrite them
+        for (let i = 0; i < options.length; i++)
+            stdout.write('\n');
+        render();
+        function onKey(data) {
+            const key = data.toString();
+            // Up arrow or k
+            if (key === '\x1b[A' || key === 'k') {
+                selected = (selected - 1 + options.length) % options.length;
+                render();
+            }
+            // Down arrow or j
+            else if (key === '\x1b[B' || key === 'j') {
+                selected = (selected + 1) % options.length;
+                render();
+            }
+            // Enter
+            else if (key === '\r' || key === '\n') {
+                cleanup();
+                // Overwrite options with the final selection
+                stdout.write(`\x1b[${options.length}A\x1b[J`);
+                stdout.write(`  ${green('❯')} ${bold(options[selected].label)}\n\n`);
+                resolve(options[selected].value);
+            }
+            // Ctrl-C
+            else if (key === '\x03') {
+                cleanup();
+                stdout.write('\n');
+                resolve(false);
+            }
+        }
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onKey);
+    });
+}
+function createBabelConfig(projectCwd) {
+    const pluginPath = getPluginPath();
+    const configContent = `module.exports = {
+  presets: ['next/babel'],
+  plugins: [${JSON.stringify(pluginPath)}],
+};
+`;
+    writeFileSync(join(projectCwd, 'babel.config.js'), configContent, 'utf-8');
+}
+export async function ensureBabelPlugin(projectCwd) {
+    const pluginPath = getPluginPath();
+    const existing = findExistingBabelConfig(projectCwd);
+    if (existing) {
+        // Config exists — check if the awel plugin is already referenced
+        const configPath = existing === 'package.json'
+            ? join(projectCwd, 'package.json')
+            : join(projectCwd, existing);
+        const content = readFileSync(configPath, 'utf-8');
+        if (content.includes('awel-source'))
+            return;
+        console.log(`[Awel] Babel config found (${existing}) but Awel source plugin is not configured.`);
+        console.log(`       Add this to your plugins array:`);
+        console.log(`       require.resolve(${JSON.stringify(pluginPath)})`);
+        console.log(`       Inspector source mapping will use runtime fiber fallback.`);
+        return;
+    }
+    // No babel config exists — check stored preference
+    const config = readAwelConfig(projectCwd);
+    if (config.babelPlugin === true) {
+        createBabelConfig(projectCwd);
+        console.log('[Awel] Created babel.config.js with source-mapping plugin (previously opted in).');
+        return;
+    }
+    if (config.babelPlugin === false) {
+        return;
+    }
+    // Never prompted — ask interactively (skip if not a TTY)
+    if (!process.stdin.isTTY) {
+        return;
+    }
+    const accepted = await promptSelect('Inspector source mapping', 'The Babel plugin gives click-to-source with exact line numbers,\n' +
+        '  but replaces Next.js SWC with Babel (slower builds).\n' +
+        '  Without it, the inspector still works via React fiber detection.', [
+        { label: '⚡ Skip — use runtime fiber detection (no build impact)', value: false },
+        { label: '🌸 Enable — create babel.config.js (best experience, slower builds)', value: true },
+    ]);
+    writeAwelConfig(projectCwd, { ...config, babelPlugin: accepted });
+    if (accepted) {
+        createBabelConfig(projectCwd);
+        console.log(`${green('✔')} Created ${cyan('babel.config.js')} with source-mapping plugin.`);
+    }
+    else {
+        console.log(`${dim('→')} Skipped Babel plugin. Inspector will use runtime fiber fallback.`);
+        console.log(`  ${dim('Run with a fresh .awel/ to be asked again.')}`);
+    }
+}

package/dist/cli/comment-popup.d.ts

@@ -0,0 +1,2 @@
+import { Hono } from 'hono';
+export declare function createCommentPopupRoute(): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/cli/comment-popup.js

@@ -0,0 +1,206 @@
+import { Hono } from 'hono';
+const commentPopupHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #18181b;
+    color: #fafafa;
+    padding: 0 12px 12px;
+    height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+  .header {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 10px 0 10px;
+  }
+  .header-left {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    flex-shrink: 0;
+  }
+  .header-title {
+    font-size: 12px;
+    font-weight: 600;
+    color: #e4e4e7;
+  }
+  .element-info {
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    font-size: 11px;
+    color: #a1a1aa;
+    overflow: hidden;
+  }
+  .element-name {
+    font-weight: 500;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100px;
+  }
+  .element-sep {
+    color: #52525b;
+  }
+  .element-file {
+    color: #71717a;
+    font-family: ui-monospace, SFMono-Regular, monospace;
+    font-size: 10px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 90px;
+  }
+  textarea {
+    flex: 1;
+    width: 100%;
+    background: #09090b;
+    border: 1px solid #27272a;
+    border-radius: 6px;
+    color: #fafafa;
+    font-family: inherit;
+    font-size: 13px;
+    padding: 8px 10px;
+    resize: none;
+    outline: none;
+    transition: border-color 0.15s ease;
+  }
+  textarea:focus {
+    border-color: #a1a1aa;
+  }
+  textarea::placeholder {
+    color: #71717a;
+  }
+  .buttons {
+    display: flex;
+    gap: 6px;
+    margin-top: 8px;
+    justify-content: flex-end;
+  }
+  button {
+    font-family: inherit;
+    font-size: 12px;
+    font-weight: 500;
+    padding: 6px 14px;
+    border-radius: 6px;
+    border: 1px solid #27272a;
+    cursor: pointer;
+    transition: all 0.15s ease;
+  }
+  button:active { transform: scale(0.97); }
+  .btn-close {
+    background: #27272a;
+    color: #a1a1aa;
+  }
+  .btn-close:hover {
+    background: #3f3f46;
+    color: #fafafa;
+  }
+  .btn-submit {
+    background: #fafafa;
+    border-color: #fafafa;
+    color: #18181b;
+  }
+  .btn-submit:hover {
+    background: #e4e4e7;
+  }
+  .btn-submit:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+  .btn-submit kbd {
+    display: inline-block;
+    font-family: inherit;
+    font-size: 10px;
+    font-weight: 600;
+    margin-left: 6px;
+    opacity: 0.5;
+  }
+</style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-left">
+      <span style="font-size:13px;line-height:1">🌸</span>
+      <span class="header-title">Awel</span>
+    </div>
+    <div class="element-info" id="elementInfo"></div>
+  </div>
+  <textarea id="comment" placeholder="Describe what you want to change..." autofocus></textarea>
+  <div class="buttons">
+    <button class="btn-close" id="closeBtn">Cancel</button>
+    <button class="btn-submit" id="submitBtn" disabled>Send<kbd id="shortcutHint"></kbd></button>
+  </div>
+  <script>
+    const params = new URLSearchParams(window.location.search);
+    const elName = params.get('name');
+    const elFile = params.get('file');
+    const infoEl = document.getElementById('elementInfo');
+    const escapeHtml = (value) => value.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    if (elName) {
+      let html = '<span class="element-name">' + escapeHtml(elName) + '</span>';
+      if (elFile) html += '<span class="element-sep">&middot;</span><span class="element-file">' + escapeHtml(elFile) + '</span>';
+      infoEl.innerHTML = html;
+    } else {
+      infoEl.style.display = 'none';
+    }
+
+    const isMac = /Mac|iPhone|iPad/.test(navigator.platform);
+    document.getElementById('shortcutHint').textContent = isMac ? '\\u2318\\u21A9' : 'Ctrl\\u21A9';
+
+    const textarea = document.getElementById('comment');
+    const submitBtn = document.getElementById('submitBtn');
+    const closeBtn = document.getElementById('closeBtn');
+
+    textarea.addEventListener('input', () => {
+      submitBtn.disabled = !textarea.value.trim();
+    });
+
+    function submit() {
+      const text = textarea.value.trim();
+      if (!text) return;
+      window.parent.postMessage({ type: 'AWEL_COMMENT_SUBMIT', comment: text }, '*');
+    }
+
+    function close() {
+      window.parent.postMessage({ type: 'AWEL_COMMENT_CLOSE' }, '*');
+    }
+
+    submitBtn.addEventListener('click', submit);
+    closeBtn.addEventListener('click', close);
+
+    textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        submit();
+      }
+    });
+
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') {
+        close();
+      }
+    });
+
+    // Explicitly focus — autofocus attribute is ignored inside iframes
+    window.addEventListener('focus', () => textarea.focus());
+    textarea.focus();
+  </script>
+</body>
+</html>`;
+export function createCommentPopupRoute() {
+    const app = new Hono();
+    app.get('/_awel/comment-popup', (c) => {
+        return c.html(commentPopupHtml);
+    });
+    return app;
+}

package/dist/cli/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared configuration constants for Awel
+ */
+export declare const AWEL_PORT = 3001;
+export declare const USER_APP_PORT = 3000;
+export declare const DASHBOARD_URL = "http://localhost:3001/_awel/dashboard";
+/**
+ * MIME type mappings for static file serving
+ */
+export declare const MIME_TYPES: Record<string, string>;
+/**
+ * Get MIME type for a file extension
+ */
+export declare function getMimeType(filePath: string): string;

package/dist/cli/config.js

@@ -0,0 +1,29 @@
+/**
+ * Shared configuration constants for Awel
+ */
+export const AWEL_PORT = 3001;
+export const USER_APP_PORT = 3000;
+export const DASHBOARD_URL = `http://localhost:${AWEL_PORT}/_awel/dashboard`;
+/**
+ * MIME type mappings for static file serving
+ */
+export const MIME_TYPES = {
+    'js': 'application/javascript',
+    'css': 'text/css',
+    'svg': 'image/svg+xml',
+    'png': 'image/png',
+    'jpg': 'image/jpeg',
+    'jpeg': 'image/jpeg',
+    'html': 'text/html',
+    'json': 'application/json',
+    'woff': 'font/woff',
+    'woff2': 'font/woff2',
+    'ttf': 'font/ttf',
+};
+/**
+ * Get MIME type for a file extension
+ */
+export function getMimeType(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() || '';
+    return MIME_TYPES[ext] || 'application/octet-stream';
+}

package/dist/cli/devserver.d.ts

@@ -0,0 +1,17 @@
+import type { Socket } from 'net';
+/**
+ * Register a target-side proxy socket.
+ * Called from the http-proxy 'open' event in server.ts.
+ */
+export declare function trackProxySocket(socket: Socket): void;
+/**
+ * Called when an agent stream starts.
+ * Pauses all target-side sockets so HMR data is buffered, not forwarded.
+ */
+export declare function pauseDevServer(_port: number): void;
+/**
+ * Called when an agent stream ends.
+ * Resumes target-side sockets — buffered HMR messages flow through
+ * and the browser picks up all accumulated changes at once.
+ */
+export declare function resumeDevServer(_port: number): void;

package/dist/cli/devserver.js

@@ -0,0 +1,43 @@
+// ─── HMR gate ────────────────────────────────────────────────
+// While the agent is streaming we pause the target-side proxy
+// sockets so HMR messages are buffered in the kernel rather than
+// forwarded to the browser.  The browser-side WebSocket stays
+// connected (no disconnection-triggered reload).  When the stream
+// ends we resume the sockets — buffered messages flow through and
+// the page picks up all changes in a single reload.
+let streaming = false;
+/** Target-side proxy sockets (the connection *to* the dev server). */
+const proxySockets = new Set();
+/**
+ * Register a target-side proxy socket.
+ * Called from the http-proxy 'open' event in server.ts.
+ */
+export function trackProxySocket(socket) {
+    proxySockets.add(socket);
+    socket.once('close', () => proxySockets.delete(socket));
+    // If we're already streaming, pause immediately
+    if (streaming) {
+        socket.pause();
+    }
+}
+/**
+ * Called when an agent stream starts.
+ * Pauses all target-side sockets so HMR data is buffered, not forwarded.
+ */
+export function pauseDevServer(_port) {
+    streaming = true;
+    for (const socket of proxySockets) {
+        socket.pause();
+    }
+}
+/**
+ * Called when an agent stream ends.
+ * Resumes target-side sockets — buffered HMR messages flow through
+ * and the browser picks up all accumulated changes at once.
+ */
+export function resumeDevServer(_port) {
+    streaming = false;
+    for (const socket of proxySockets) {
+        socket.resume();
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/index.js

@@ -0,0 +1,34 @@
+import { program } from 'commander';
+import { startServer } from './server.js';
+import { AWEL_PORT, USER_APP_PORT } from './config.js';
+import { setVerbose } from './verbose.js';
+import { ensureBabelPlugin } from './babel-setup.js';
+import { awel } from './logger.js';
+import { spawnDevServer } from './subprocess.js';
+program
+    .name('awel')
+    .description('AI-powered development overlay for Next.js')
+    .version('0.1.0');
+program
+    .command('dev')
+    .description('Start the development server with Awel overlay')
+    .option('-p, --port <port>', 'Port for target app', String(USER_APP_PORT))
+    .option('-v, --verbose', 'Print all LLM stream events to stderr')
+    .action(async (options) => {
+    const targetPort = parseInt(options.port, 10);
+    if (options.verbose)
+        setVerbose(true);
+    await ensureBabelPlugin(process.cwd());
+    awel.log('🌟 Starting Awel...');
+    awel.log(`   Target app port: ${targetPort}`);
+    awel.log(`   Awel control server: http://localhost:${AWEL_PORT}`);
+    awel.log('');
+    // Start the Awel control server (proxy + dashboard)
+    await startServer({ awelPort: AWEL_PORT, targetPort, projectCwd: process.cwd() });
+    // Start the user's Next.js app via subprocess manager (handles auto-restart)
+    await spawnDevServer({ port: targetPort, cwd: process.cwd() });
+    awel.log('');
+    awel.log(`✨ Awel is ready! Open http://localhost:${AWEL_PORT}`);
+    awel.log('   Look for the floating button in the bottom-right corner.');
+});
+program.parse();

package/dist/cli/inspector.d.ts

@@ -0,0 +1,2 @@
+import { Hono } from 'hono';
+export declare function createInspectorRoute(projectCwd: string): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/cli/inspector.js

@@ -0,0 +1,117 @@
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { EventEmitter } from 'node:events';
+import { readFileSync } from 'fs';
+import { resolve, isAbsolute } from 'path';
+const inspectorBus = new EventEmitter();
+let bufferedSelection = null;
+let sseClientConnected = false;
+/**
+ * Enrich a selection with server-side context:
+ * - Source code snippet around the target line
+ * - Props type definition near the component
+ * - Whether the file has uncommitted changes
+ */
+function enrichSelection(selection, projectCwd) {
+    if (!selection.source || !selection.line)
+        return selection;
+    const filePath = isAbsolute(selection.source)
+        ? selection.source
+        : resolve(projectCwd, selection.source);
+    // Read source snippet
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        const targetLine = selection.line;
+        const start = Math.max(0, targetLine - 10);
+        const end = Math.min(lines.length, targetLine + 10);
+        const snippetLines = [];
+        for (let i = start; i < end; i++) {
+            const lineNum = i + 1;
+            const marker = lineNum === targetLine ? ' > ' : '   ';
+            snippetLines.push(`${marker}${String(lineNum).padStart(4)}  ${lines[i]}`);
+        }
+        selection.sourceSnippet = snippetLines.join('\n');
+        // Look for props type definition near the component
+        const componentName = selection.component;
+        if (componentName) {
+            const escapedName = componentName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const propsPattern = new RegExp(`(?:interface|type)\\s+${escapedName}Props[\\s{<]`);
+            for (let i = 0; i < lines.length; i++) {
+                if (propsPattern.test(lines[i])) {
+                    const defStart = i;
+                    let defEnd = i;
+                    // Grab lines until closing brace or 20 lines max
+                    let braceDepth = 0;
+                    for (let j = i; j < Math.min(lines.length, i + 20); j++) {
+                        for (const ch of lines[j]) {
+                            if (ch === '{')
+                                braceDepth++;
+                            if (ch === '}')
+                                braceDepth--;
+                        }
+                        defEnd = j;
+                        if (braceDepth <= 0 && j > i)
+                            break;
+                    }
+                    selection.propsTypeDefinition = lines.slice(defStart, defEnd + 1).join('\n');
+                    break;
+                }
+            }
+        }
+    }
+    catch {
+        // File not readable, skip enrichment
+    }
+    return selection;
+}
+export function createInspectorRoute(projectCwd) {
+    const inspector = new Hono();
+    // Host script POSTs the selected element here
+    inspector.post('/api/inspector/select', async (c) => {
+        let selection = await c.req.json();
+        selection = enrichSelection(selection, projectCwd);
+        if (sseClientConnected) {
+            inspectorBus.emit('selection', selection);
+        }
+        else {
+            bufferedSelection = selection;
+        }
+        return c.json({ ok: true });
+    });
+    // Dashboard connects here to receive selections in real time
+    inspector.get('/api/inspector/events', (c) => {
+        return streamSSE(c, async (stream) => {
+            sseClientConnected = true;
+            // Flush any buffered selection that arrived before we connected
+            if (bufferedSelection) {
+                await stream.writeSSE({
+                    event: 'selection',
+                    data: JSON.stringify(bufferedSelection),
+                });
+                bufferedSelection = null;
+            }
+            const onSelection = async (sel) => {
+                try {
+                    await stream.writeSSE({
+                        event: 'selection',
+                        data: JSON.stringify(sel),
+                    });
+                }
+                catch {
+                    // Stream closed, ignore
+                }
+            };
+            inspectorBus.on('selection', onSelection);
+            // Keep the stream open until the client disconnects
+            await new Promise((resolve) => {
+                stream.onAbort(() => {
+                    sseClientConnected = false;
+                    inspectorBus.removeListener('selection', onSelection);
+                    resolve();
+                });
+            });
+        });
+    });
+    return inspector;
+}

package/dist/cli/logger.d.ts

@@ -0,0 +1,10 @@
+import type { ResultPromise } from 'execa';
+export declare const awel: {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+/**
+ * Pipe a child process's stdout/stderr line-by-line, prefixing
+ * each line with the magenta [next] tag.
+ */
+export declare function pipeChildOutput(child: ResultPromise): void;