@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/editor/ai/opencode-client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenCode AI client — wraps the OpenCode REST API for AI coding agent integration.
+ * Connects to an OpenCode server (`opencode serve`) that handles LLM calls and file editing.
+ */
+import type { AiChatOptions, AiChatResult, AiStatusResult } from './types.js';
+/**
+ * Stream an AI chat message via OpenCode's REST API.
+ * Creates a session, sends message, and parses the response.
+ */
+export declare function streamAiChat(projectDir: string, options: AiChatOptions): AiChatResult;
+/**
+ * Check if OpenCode server is reachable.
+ */
+export declare function checkAiStatus(): Promise<AiStatusResult>;

package/dist/editor/ai/opencode-client.js

@@ -0,0 +1,99 @@
+/**
+ * OpenCode AI client — wraps the OpenCode REST API for AI coding agent integration.
+ * Connects to an OpenCode server (`opencode serve`) that handles LLM calls and file editing.
+ */
+import { buildPrompt } from './types.js';
+const OPENCODE_URL = process.env.OPENCODE_URL || 'http://localhost:4096';
+const OPENCODE_PASSWORD = process.env.OPENCODE_SERVER_PASSWORD || '';
+function buildHeaders() {
+    const headers = { 'Content-Type': 'application/json' };
+    if (OPENCODE_PASSWORD) {
+        headers['Authorization'] = `Bearer ${OPENCODE_PASSWORD}`;
+    }
+    return headers;
+}
+/**
+ * Stream an AI chat message via OpenCode's REST API.
+ * Creates a session, sends message, and parses the response.
+ */
+export function streamAiChat(projectDir, options) {
+    const tokenCallbacks = [];
+    const doneCallbacks = [];
+    const errorCallbacks = [];
+    const controller = new AbortController();
+    let sessionId = options.sessionId || '';
+    const enrichedPrompt = buildPrompt(options);
+    const run = async () => {
+        try {
+            // Create a new session if we don't have one
+            if (!sessionId) {
+                const createRes = await fetch(`${OPENCODE_URL}/session`, {
+                    method: 'POST',
+                    headers: buildHeaders(),
+                    body: JSON.stringify({ path: projectDir }),
+                    signal: controller.signal,
+                });
+                if (!createRes.ok) {
+                    throw new Error(`Failed to create OpenCode session: ${createRes.status}`);
+                }
+                const sessionData = await createRes.json();
+                sessionId = sessionData.id || sessionData.sessionId || '';
+            }
+            // Send message — OpenCode returns JSON with parts array
+            const msgRes = await fetch(`${OPENCODE_URL}/session/${sessionId}/message`, {
+                method: 'POST',
+                headers: buildHeaders(),
+                body: JSON.stringify({ parts: [{ type: 'text', text: enrichedPrompt }] }),
+                signal: controller.signal,
+            });
+            if (!msgRes.ok) {
+                const errText = await msgRes.text().catch(() => '');
+                throw new Error(`OpenCode message failed: ${msgRes.status} ${errText}`);
+            }
+            // OpenCode returns JSON response with parts array
+            const data = await msgRes.json();
+            let fullText = '';
+            // Extract text from response parts
+            const parts = data.parts || [];
+            for (const part of parts) {
+                if (part.type === 'text' && part.text) {
+                    fullText += part.text;
+                    for (const cb of tokenCallbacks)
+                        cb(part.text);
+                }
+            }
+            for (const cb of doneCallbacks)
+                cb(fullText);
+        }
+        catch (err) {
+            if (err?.name === 'AbortError')
+                return;
+            for (const cb of errorCallbacks)
+                cb(err instanceof Error ? err : new Error(String(err)));
+        }
+    };
+    // Start the async flow
+    run();
+    return {
+        get sessionId() { return sessionId; },
+        onToken: (cb) => { tokenCallbacks.push(cb); },
+        onDone: (cb) => { doneCallbacks.push(cb); },
+        onError: (cb) => { errorCallbacks.push(cb); },
+        abort: () => controller.abort(),
+    };
+}
+/**
+ * Check if OpenCode server is reachable.
+ */
+export async function checkAiStatus() {
+    try {
+        const res = await fetch(`${OPENCODE_URL}/global/health`, {
+            headers: buildHeaders(),
+            signal: AbortSignal.timeout(3000),
+        });
+        return { configured: res.ok, backend: 'opencode' };
+    }
+    catch {
+        return { configured: false, backend: 'opencode' };
+    }
+}

package/dist/editor/ai/snapshot-store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-memory file snapshot store for AI turn rollback.
+ * Saves file contents before each AI turn so they can be restored.
+ */
+export interface Snapshot {
+    turnId: string;
+    files: Map<string, string>;
+    timestamp: number;
+}
+/**
+ * Save a snapshot of file contents before an AI turn.
+ */
+export declare function save(turnId: string, files: Map<string, string>): void;
+/**
+ * Restore file contents from a saved snapshot.
+ * Returns the files map if found, null otherwise.
+ */
+export declare function restore(turnId: string): Map<string, string> | null;
+/**
+ * List available snapshot turn IDs (newest first).
+ */
+export declare function listTurns(): string[];

package/dist/editor/ai/snapshot-store.js

@@ -0,0 +1,35 @@
+/**
+ * In-memory file snapshot store for AI turn rollback.
+ * Saves file contents before each AI turn so they can be restored.
+ */
+const MAX_SNAPSHOTS = 10;
+const snapshots = [];
+/**
+ * Save a snapshot of file contents before an AI turn.
+ */
+export function save(turnId, files) {
+    snapshots.push({ turnId, files, timestamp: Date.now() });
+    // Keep only the last N snapshots
+    while (snapshots.length > MAX_SNAPSHOTS) {
+        snapshots.shift();
+    }
+}
+/**
+ * Restore file contents from a saved snapshot.
+ * Returns the files map if found, null otherwise.
+ */
+export function restore(turnId) {
+    const idx = snapshots.findIndex(s => s.turnId === turnId);
+    if (idx === -1)
+        return null;
+    const snapshot = snapshots[idx];
+    // Remove this and all newer snapshots (they're invalidated by rollback)
+    snapshots.splice(idx);
+    return snapshot.files;
+}
+/**
+ * List available snapshot turn IDs (newest first).
+ */
+export function listTurns() {
+    return snapshots.map(s => s.turnId).reverse();
+}

package/dist/editor/ai/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared types and constants for AI backend clients.
+ */
+export interface AiChatOptions {
+    mode: 'element' | 'project';
+    prompt: string;
+    context: {
+        sourceFile?: string;
+        sourceLine?: number;
+        elementTag?: string;
+        elementAttributes?: Record<string, string>;
+        sourceContent?: string;
+    };
+    sessionId?: string;
+    /** 'fast' uses Sonnet for quick edits, 'default' uses the standard model */
+    model?: 'fast' | 'default';
+}
+export interface AiChatResult {
+    sessionId: string;
+    onToken: (cb: (text: string) => void) => void;
+    onDone: (cb: (fullText: string) => void) => void;
+    onError: (cb: (err: Error) => void) => void;
+    abort: () => void;
+}
+export interface AiStatusResult {
+    configured: boolean;
+    backend: 'claude-code' | 'opencode';
+}
+export declare const SYSTEM_PROMPT = "You are an AI coding assistant working inside a LumenJS project.\n\nLumenJS is a full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes.\n\nKey conventions:\n- Pages live in `pages/` directory \u2014 file path maps to URL route\n- Components are Lit web components (LitElement) auto-registered by file path\n- Layouts: `_layout.ts` in any directory for nested layouts (use <slot>)\n- API routes: `api/` directory with named exports (GET, POST, PUT, DELETE)\n- Server loaders: `export async function loader()` for server-side data fetching\n- Styles: use Tailwind CSS classes or Lit's `static styles` with css template tag\n- Config: `lumenjs.config.ts` at project root\n\nAuto-registration:\n- Pages and layouts are auto-registered by file path \u2014 do NOT add @customElement decorators.\n  `pages/about.ts` \u2192 `<page-about>`, `pages/blog/_layout.ts` \u2192 `<layout-blog>`\n\nServer loaders:\n- `export async function loader({ params, query, url, headers, locale })` at file top level.\n- Return a data object \u2192 available as `this.loaderData` on the page element.\n\nSubscribe (SSE):\n- `export async function subscribe({ params, headers, locale, push })` for real-time data.\n- Call `push(data)` to send events \u2192 available as `this.liveData` on the page element.\n\nMiddleware:\n- `_middleware.ts` in any directory applies to that route subtree.\n\nDynamic routes:\n- `[slug]` for dynamic params, `[...rest]` for catch-all.\n\nProperties:\n- Use `@property()` for public reactive props, `@state()` for internal state (from `lit/decorators.js`).\n\nExample \u2014 adding a new page (`pages/contact.ts`):\n```\nimport { LitElement, html, css } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nexport default class extends LitElement {\n  static styles = css\\`/* styles here */\\`;\n  render() { return html\\`<h1>Contact</h1>\\`; }\n}\n```\n\nIMPORTANT \u2014 Styling rules:\n- When asked to change a style (color, font, spacing, etc.), find and UPDATE the EXISTING CSS rule in `static styles = css\\`...\\``. Do NOT add a new class or duplicate rule.\n- Never add inline `style=\"...\"` attributes on HTML template elements. Always modify the CSS rule in `static styles`.\n- Example: to change the h1 color, find the `h1 { ... }` rule in `static styles` and update its `color` property. Do not create a new class.\n- If no CSS rule exists for the element, add one to the existing `static styles` block \u2014 do not add a separate `<style>` tag.\n\nIMPORTANT \u2014 i18n / translation rules (when the project uses i18n):\n- Text content in templates uses `t('key')` from `@lumenjs/i18n` \u2014 NEVER replace a `t()` call with hardcoded text.\n- To change displayed text, edit the translation value in `locales/<locale>.json` \u2014 do NOT modify the template.\n- Example: to change the subtitle, update `\"home.subtitle\"` in `locales/en.json` (and other locale files like `locales/fr.json`).\n- To add new text, add a key to ALL locale JSON files and use `t('new.key')` in the template.\n- The dev server watches locale files and updates the page automatically via HMR.\n\nYou have full access to the filesystem and can run shell commands.\nWhen a task requires a new npm package, install it with `npm install <package>`.\nAfter npm install, the dev server will automatically restart to load the new dependency.\nVite's HMR will pick up file changes automatically \u2014 no manual restart needed.\n\nIMPORTANT \u2014 Be fast and direct:\n- Make changes immediately \u2014 do not explain what you will do before doing it.\n- Read the file, make the edit, done. Minimize tool calls.\n- For simple CSS/text changes, edit directly without reading first if you have the source context.\n- Keep responses under 2 sentences. The user sees the diff, not your explanation.\n";
+export declare function buildPrompt(options: AiChatOptions): string;

package/dist/editor/ai/types.js

@@ -0,0 +1,136 @@
+/**
+ * Shared types and constants for AI backend clients.
+ */
+export const SYSTEM_PROMPT = `You are an AI coding assistant working inside a LumenJS project.
+
+LumenJS is a full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes.
+
+Key conventions:
+- Pages live in \`pages/\` directory — file path maps to URL route
+- Components are Lit web components (LitElement) auto-registered by file path
+- Layouts: \`_layout.ts\` in any directory for nested layouts (use <slot>)
+- API routes: \`api/\` directory with named exports (GET, POST, PUT, DELETE)
+- Server loaders: \`export async function loader()\` for server-side data fetching
+- Styles: use Tailwind CSS classes or Lit's \`static styles\` with css template tag
+- Config: \`lumenjs.config.ts\` at project root
+
+Auto-registration:
+- Pages and layouts are auto-registered by file path — do NOT add @customElement decorators.
+  \`pages/about.ts\` → \`<page-about>\`, \`pages/blog/_layout.ts\` → \`<layout-blog>\`
+
+Server loaders:
+- \`export async function loader({ params, query, url, headers, locale })\` at file top level.
+- Return a data object → available as \`this.loaderData\` on the page element.
+
+Subscribe (SSE):
+- \`export async function subscribe({ params, headers, locale, push })\` for real-time data.
+- Call \`push(data)\` to send events → available as \`this.liveData\` on the page element.
+
+Middleware:
+- \`_middleware.ts\` in any directory applies to that route subtree.
+
+Dynamic routes:
+- \`[slug]\` for dynamic params, \`[...rest]\` for catch-all.
+
+Properties:
+- Use \`@property()\` for public reactive props, \`@state()\` for internal state (from \`lit/decorators.js\`).
+
+Example — adding a new page (\`pages/contact.ts\`):
+\`\`\`
+import { LitElement, html, css } from 'lit';
+import { property } from 'lit/decorators.js';
+
+export default class extends LitElement {
+  static styles = css\\\`/* styles here */\\\`;
+  render() { return html\\\`<h1>Contact</h1>\\\`; }
+}
+\`\`\`
+
+IMPORTANT — Styling rules:
+- When asked to change a style (color, font, spacing, etc.), find and UPDATE the EXISTING CSS rule in \`static styles = css\\\`...\\\`\`. Do NOT add a new class or duplicate rule.
+- Never add inline \`style="..."\` attributes on HTML template elements. Always modify the CSS rule in \`static styles\`.
+- Example: to change the h1 color, find the \`h1 { ... }\` rule in \`static styles\` and update its \`color\` property. Do not create a new class.
+- If no CSS rule exists for the element, add one to the existing \`static styles\` block — do not add a separate \`<style>\` tag.
+
+IMPORTANT — i18n / translation rules (when the project uses i18n):
+- Text content in templates uses \`t('key')\` from \`@lumenjs/i18n\` — NEVER replace a \`t()\` call with hardcoded text.
+- To change displayed text, edit the translation value in \`locales/<locale>.json\` — do NOT modify the template.
+- Example: to change the subtitle, update \`"home.subtitle"\` in \`locales/en.json\` (and other locale files like \`locales/fr.json\`).
+- To add new text, add a key to ALL locale JSON files and use \`t('new.key')\` in the template.
+- The dev server watches locale files and updates the page automatically via HMR.
+
+You have full access to the filesystem and can run shell commands.
+When a task requires a new npm package, install it with \`npm install <package>\`.
+After npm install, the dev server will automatically restart to load the new dependency.
+Vite's HMR will pick up file changes automatically — no manual restart needed.
+
+IMPORTANT — Be fast and direct:
+- Make changes immediately — do not explain what you will do before doing it.
+- Read the file, make the edit, done. Minimize tool calls.
+- For simple CSS/text changes, edit directly without reading first if you have the source context.
+- Keep responses under 2 sentences. The user sees the diff, not your explanation.
+`;
+export function buildPrompt(options) {
+    const { mode, prompt, context } = options;
+    let result = prompt;
+    if (mode === 'element' && context.elementTag) {
+        let enriched = `I'm looking at \`<${context.elementTag}>\``;
+        if (context.sourceFile) {
+            enriched += ` in \`${context.sourceFile}`;
+            if (context.sourceLine)
+                enriched += `:${context.sourceLine}`;
+            enriched += '`';
+        }
+        if (context.elementAttributes && Object.keys(context.elementAttributes).length > 0) {
+            const attrs = Object.entries(context.elementAttributes)
+                .map(([k, v]) => `${k}="${v}"`)
+                .join(' ');
+            enriched += ` with attributes: ${attrs}`;
+        }
+        enriched += `. ${prompt}`;
+        result = enriched;
+    }
+    // Append i18n context — only include keys actually used in the current source file
+    if (context?.i18n?.translations) {
+        const i18n = context.i18n;
+        const locales = Object.keys(i18n.translations);
+        result += `\n\nThis project uses i18n (locales: ${locales.join(', ')}).`;
+        // Extract t('key') calls from source to only send relevant translations
+        const sourceContent = context.sourceContent || '';
+        const usedKeys = new Set();
+        const tCallRegex = /t\(['"]([^'"]+)['"]\)/g;
+        let tMatch;
+        while ((tMatch = tCallRegex.exec(sourceContent)) !== null) {
+            usedKeys.add(tMatch[1]);
+        }
+        if (usedKeys.size > 0) {
+            result += ` Relevant translation keys from this file:\n`;
+            for (const [locale, trans] of Object.entries(i18n.translations)) {
+                const filtered = {};
+                for (const key of usedKeys) {
+                    const value = getNestedValue(trans, key);
+                    if (value !== undefined)
+                        filtered[key] = value;
+                }
+                if (Object.keys(filtered).length > 0) {
+                    result += `locales/${locale}.json (relevant keys): ${JSON.stringify(filtered, null, 2)}\n`;
+                }
+            }
+        }
+        else {
+            result += ` Edit locale JSON files in locales/ to change text — do not hardcode text in templates.\n`;
+        }
+    }
+    return result;
+}
+/** Resolve a dot-separated key like 'home.subtitle' from a nested object */
+function getNestedValue(obj, key) {
+    const parts = key.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}

package/dist/editor/ai-chat-panel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AI Chat Bubble — floating chat popover that appears next to the selected element.
+ * Streams responses from OpenCode AI coding agent via the editor API.
+ */
+export declare function createAiChatPanel(): HTMLDivElement;
+export declare function showAiChatForElement(el: HTMLElement): void;
+export declare function showAiChatForElements(els: HTMLElement[]): void;
+/** Update target reference after HMR and reanchor the panel to the new element */
+export declare function updateAiChatTarget(el: HTMLElement): void;
+export declare function hideAiChatPanel(): void;
+export declare function isAiChatPanelOpen(): boolean;
+/** Reposition on scroll/resize if open (skips if element was disconnected by HMR) */
+export declare function updateAiChatPosition(): void;