@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/cli/serve.js

@@ -0,0 +1,432 @@
+/**
+ * nimbus serve -- Headless HTTP API Server
+ *
+ * Exposes the Nimbus agent loop as a REST + SSE API designed for
+ * consumption by the Web UI, IDE extensions, and third-party integrations.
+ *
+ * Endpoints:
+ *   POST /api/chat          -- Send a message, receive SSE streaming response
+ *   POST /api/run           -- Non-interactive single prompt (JSON response)
+ *   GET  /api/sessions      -- List all sessions
+ *   GET  /api/session/:id   -- Session details + conversation messages
+ *   POST /api/session/:id   -- Continue an existing session (SSE streaming)
+ *   GET  /api/health        -- Health check
+ *   GET  /api/openapi.json  -- OpenAPI 3.1 specification
+ *
+ * Usage:
+ *   nimbus serve                        # localhost:4200
+ *   nimbus serve --port 8080            # custom port
+ *   nimbus serve --host 0.0.0.0        # bind to all interfaces
+ *   nimbus serve --auth admin:secret   # enable HTTP Basic Auth
+ *
+ * @module cli/serve
+ */
+import { Elysia } from 'elysia';
+import { cors } from '@elysiajs/cors';
+import { initApp } from '../app';
+import { runAgentLoop } from '../agent/loop';
+import { defaultToolRegistry } from '../tools/schemas/types';
+import { standardTools } from '../tools/schemas/standard';
+import { devopsTools } from '../tools/schemas/devops';
+import { SessionManager } from '../sessions/manager';
+import { saveConversation, getConversation } from '../state/conversations';
+import { shareSession, getSharedSession, listShares } from '../sharing/sync';
+import { ContextManager } from '../agent/context-manager';
+import { getOpenAPISpec } from './openapi-spec';
+import { createAuthMiddleware } from './serve-auth';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Ensure the default tool registry is populated.
+ * Idempotent -- skips tools that are already registered.
+ */
+function ensureToolsRegistered() {
+    if (defaultToolRegistry.size > 0) {
+        return;
+    }
+    for (const tool of [...standardTools, ...devopsTools]) {
+        try {
+            defaultToolRegistry.register(tool);
+        }
+        catch {
+            // Already registered -- skip.
+        }
+    }
+}
+/**
+ * Validate and narrow a mode string to the AgentMode union.
+ */
+function parseMode(mode) {
+    if (mode === 'plan' || mode === 'build' || mode === 'deploy') {
+        return mode;
+    }
+    return 'build';
+}
+/**
+ * Create an SSE-formatted ReadableStream that runs the agent loop and
+ * emits events for text, tool calls, completion, and errors.
+ *
+ * SSE event types:
+ *   session    -- { id, mode }
+ *   text       -- { content }
+ *   tool_start -- { id, name, input? }
+ *   tool_end   -- { id, name, output?, isError }
+ *   done       -- { turns, usage, cost }
+ *   error      -- { message }
+ */
+function createAgentSSEStream(userMessage, history, sessionId, mode, model, router, contextManager, sessionManager) {
+    return new ReadableStream({
+        async start(controller) {
+            const encoder = new TextEncoder();
+            const send = (event, data) => {
+                const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+                controller.enqueue(encoder.encode(payload));
+            };
+            try {
+                send('session', { id: sessionId, mode });
+                const result = await runAgentLoop(userMessage, history, {
+                    router,
+                    toolRegistry: defaultToolRegistry,
+                    mode,
+                    model,
+                    sessionId,
+                    onText: (text) => {
+                        send('text', { content: text });
+                    },
+                    onToolCallStart: (toolCall) => {
+                        send('tool_start', {
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.input,
+                        });
+                    },
+                    onToolCallEnd: (toolCall, toolResult) => {
+                        send('tool_end', {
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            output: typeof toolResult.output === 'string'
+                                ? toolResult.output.slice(0, 5000)
+                                : toolResult.output,
+                            isError: toolResult.isError,
+                        });
+                    },
+                });
+                // Persist conversation
+                saveConversation(sessionId, userMessage.slice(0, 100), result.messages, model);
+                // Update session stats
+                sessionManager.updateSession(sessionId, {
+                    tokenCount: result.usage.totalTokens,
+                    costUSD: result.totalCost,
+                });
+                send('done', {
+                    turns: result.turns,
+                    usage: result.usage,
+                    cost: result.totalCost,
+                });
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                send('error', { message: msg });
+            }
+            finally {
+                controller.close();
+            }
+        },
+    });
+}
+/**
+ * Wrap a ReadableStream as an SSE Response with proper headers.
+ */
+function sseResponse(stream) {
+    return new Response(stream, {
+        headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Main Command
+// ---------------------------------------------------------------------------
+/**
+ * Start the Nimbus headless API server.
+ *
+ * Initializes the app context (DB + LLM router), registers tools, sets up
+ * all API routes via Elysia, and starts listening.
+ */
+export async function serveCommand(options) {
+    const port = options.port ?? 4200;
+    const host = options.host ?? 'localhost';
+    // M1: stop a running background server
+    if (options.stop) {
+        const { join } = await import('node:path');
+        const { homedir } = await import('node:os');
+        const { readFileSync, unlinkSync, existsSync } = await import('node:fs');
+        const pidFile = join(homedir(), '.nimbus', 'serve.pid');
+        if (!existsSync(pidFile)) {
+            console.log('No background nimbus serve process found.');
+            return;
+        }
+        const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+        try {
+            process.kill(pid, 'SIGTERM');
+            unlinkSync(pidFile);
+            console.log(`Stopped nimbus serve (PID: ${pid})`);
+        }
+        catch (e) {
+            console.error(`Failed to stop process ${pid}: ${e.message}`);
+            unlinkSync(pidFile);
+        }
+        return;
+    }
+    // M1: daemonize — spawn detached child and exit
+    if (options.background) {
+        const { spawn } = await import('node:child_process');
+        const { join } = await import('node:path');
+        const { homedir } = await import('node:os');
+        const { writeFileSync, mkdirSync } = await import('node:fs');
+        const nimbusDir = join(homedir(), '.nimbus');
+        mkdirSync(nimbusDir, { recursive: true });
+        const childArgs = [process.argv[1], 'serve', '--port', String(port)];
+        if (options.host)
+            childArgs.push('--host', options.host);
+        if (options.auth)
+            childArgs.push('--auth', options.auth);
+        const child = spawn(process.execPath, childArgs, {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        child.unref();
+        writeFileSync(join(nimbusDir, 'serve.pid'), String(child.pid), 'utf-8');
+        console.log(`nimbus serve started in background (PID: ${child.pid})`);
+        console.log(`Stop with: nimbus serve stop`);
+        return;
+    }
+    // G19: Security guard — non-localhost binding requires explicit auth
+    const isLocalhost = !host || host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (!isLocalhost && !options.auth) {
+        throw new Error(`Cannot bind nimbus serve to ${host} without authentication.\n` +
+            'Use --auth user:pass to enable HTTP Basic Auth, or bind to localhost only.');
+    }
+    // G19: Auto-generate token for localhost when no auth provided
+    let autoToken;
+    if (isLocalhost && !options.auth) {
+        const { randomBytes } = await import('node:crypto');
+        autoToken = randomBytes(16).toString('hex');
+        process.stderr.write(`\nNimbus API token: ${autoToken}\n`);
+        process.stderr.write('Pass as: Authorization: Bearer <token>\n\n');
+    }
+    // ------------------------------------------------------------------
+    // Initialize core systems
+    // ------------------------------------------------------------------
+    const { router } = await initApp();
+    const sessionManager = SessionManager.getInstance();
+    const contextManager = new ContextManager();
+    ensureToolsRegistered();
+    // ------------------------------------------------------------------
+    // Build Elysia app
+    // ------------------------------------------------------------------
+    const app = new Elysia().use(cors({
+        origin: true,
+        methods: ['GET', 'POST', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Authorization'],
+    }));
+    // HTTP Basic Auth (explicit or auto-generated token)
+    if (options.auth) {
+        const colonIdx = options.auth.indexOf(':');
+        if (colonIdx > 0) {
+            const user = options.auth.slice(0, colonIdx);
+            const pass = options.auth.slice(colonIdx + 1);
+            app.onBeforeHandle(createAuthMiddleware({ username: user, password: pass }));
+        }
+    }
+    else if (autoToken) {
+        // G19: Bearer token auth for localhost when no explicit auth provided
+        const capturedToken = autoToken;
+        app.onBeforeHandle((ctx) => {
+            const authHeader = ctx.request.headers.get('Authorization') ?? '';
+            if (authHeader !== `Bearer ${capturedToken}`) {
+                ctx.set.status = 401;
+                return { error: 'Unauthorized. Pass Authorization: Bearer <token>' };
+            }
+        });
+    }
+    // ------------------------------------------------------------------
+    // GET /api/health
+    // ------------------------------------------------------------------
+    app.get('/api/health', () => ({
+        status: 'ok',
+        version: '0.2.0',
+        uptime: process.uptime(),
+        db: true,
+        llm: true,
+    }));
+    // ------------------------------------------------------------------
+    // GET /api/openapi.json
+    // ------------------------------------------------------------------
+    app.get('/api/openapi.json', () => getOpenAPISpec());
+    // ------------------------------------------------------------------
+    // GET /api/sessions
+    // ------------------------------------------------------------------
+    app.get('/api/sessions', () => ({
+        sessions: sessionManager.list(),
+    }));
+    // ------------------------------------------------------------------
+    // GET /api/session/:id
+    // ------------------------------------------------------------------
+    app.get('/api/session/:id', ({ params }) => {
+        const session = sessionManager.get(params.id);
+        if (!session) {
+            return new Response(JSON.stringify({ error: 'Session not found' }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        const conversation = getConversation(params.id);
+        return {
+            session,
+            messages: conversation?.messages ?? [],
+        };
+    });
+    // ------------------------------------------------------------------
+    // POST /api/chat -- SSE streaming chat
+    // ------------------------------------------------------------------
+    app.post('/api/chat', async (ctx) => {
+        const body = ctx.body;
+        const mode = parseMode(body.mode);
+        // Get or create session
+        let sessionId = body.sessionId;
+        let session = sessionId ? sessionManager.get(sessionId) : null;
+        if (!session) {
+            session = sessionManager.create({
+                name: `API Session ${new Date().toISOString().slice(0, 16)}`,
+                mode,
+                model: body.model,
+            });
+            sessionId = session.id;
+        }
+        // Load existing conversation history
+        const existing = getConversation(sessionId);
+        const history = existing?.messages ?? [];
+        const stream = createAgentSSEStream(body.message, history, sessionId, mode, body.model, router, contextManager, sessionManager);
+        return sseResponse(stream);
+    });
+    // ------------------------------------------------------------------
+    // POST /api/run -- Non-interactive single prompt
+    // ------------------------------------------------------------------
+    app.post('/api/run', async (ctx) => {
+        const body = ctx.body;
+        const mode = parseMode(body.mode);
+        const session = sessionManager.create({
+            name: `Run: ${body.prompt.slice(0, 50)}`,
+            mode,
+            model: body.model,
+        });
+        try {
+            const result = await runAgentLoop(body.prompt, [], {
+                router,
+                toolRegistry: defaultToolRegistry,
+                mode,
+                model: body.model,
+            });
+            // Persist conversation and mark session complete
+            saveConversation(session.id, body.prompt.slice(0, 100), result.messages, body.model);
+            sessionManager.complete(session.id);
+            // Extract final assistant message
+            const lastAssistant = [...result.messages].reverse().find(m => m.role === 'assistant');
+            return {
+                sessionId: session.id,
+                response: lastAssistant?.content ?? '',
+                turns: result.turns,
+                usage: result.usage,
+                cost: result.totalCost,
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            sessionManager.complete(session.id);
+            return new Response(JSON.stringify({ error: msg }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+    });
+    // ------------------------------------------------------------------
+    // POST /api/session/:id -- Continue existing session (SSE)
+    // ------------------------------------------------------------------
+    app.post('/api/session/:id', async (ctx) => {
+        const params = ctx.params;
+        const body = ctx.body;
+        const session = sessionManager.get(params.id);
+        if (!session) {
+            return new Response(JSON.stringify({ error: 'Session not found' }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        const existing = getConversation(params.id);
+        const history = existing?.messages ?? [];
+        const mode = parseMode(session.mode);
+        const stream = createAgentSSEStream(body.message, history, params.id, mode, body.model ?? session.model, router, contextManager, sessionManager);
+        return sseResponse(stream);
+    });
+    // ------------------------------------------------------------------
+    // POST /api/share -- Share a session
+    // ------------------------------------------------------------------
+    app.post('/api/share', ctx => {
+        const body = ctx.body;
+        const shared = shareSession(body.sessionId, {
+            isLive: body.isLive,
+            ttlDays: body.ttlDays,
+        });
+        if (!shared) {
+            return new Response(JSON.stringify({ error: 'Session not found' }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        return {
+            shareId: shared.id,
+            url: `http://${host}:${port}/nimbus/share/${shared.id}`,
+            expiresAt: shared.expiresAt,
+            isLive: shared.isLive,
+        };
+    });
+    // ------------------------------------------------------------------
+    // GET /api/share/:id -- Get shared session
+    // ------------------------------------------------------------------
+    app.get('/api/share/:id', ({ params }) => {
+        const shared = getSharedSession(params.id);
+        if (!shared) {
+            return new Response(JSON.stringify({ error: 'Shared session not found or expired' }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        return shared;
+    });
+    // ------------------------------------------------------------------
+    // GET /api/shares -- List all shares
+    // ------------------------------------------------------------------
+    app.get('/api/shares', () => ({
+        shares: listShares(),
+    }));
+    // ------------------------------------------------------------------
+    // Start listening
+    // ------------------------------------------------------------------
+    app.listen({ port, hostname: host });
+    console.log(`
+  Nimbus API Server
+  ─────────────────────────────
+  Local:   http://${host}:${port}
+  Health:  http://${host}:${port}/api/health
+  OpenAPI: http://${host}:${port}/api/openapi.json
+  ${options.auth ? '  Auth:    HTTP Basic Auth enabled' : '  Auth:    None (use --auth user:pass to enable)'}
+
+  Press Ctrl+C to stop.
+  `);
+}

package/dist/src/cli/web.js

@@ -0,0 +1,50 @@
+/**
+ * nimbus web -- Start the API server and open the Web UI
+ *
+ * Convenience command that:
+ *   1. Starts `nimbus serve` on the configured port
+ *   2. Opens the astron-landing Web UI in the default browser
+ *
+ * Usage:
+ *   nimbus web                     # serve on 4200, open http://localhost:6001/nimbus
+ *   nimbus web --port 8080         # custom serve port
+ *   nimbus web --ui-url https://app.example.com/nimbus   # custom Web UI URL
+ */
+import { spawn } from 'node:child_process';
+import { serveCommand } from './serve';
+/**
+ * Open a URL in the default browser (cross-platform).
+ */
+async function openBrowser(url) {
+    const { platform } = process;
+    const cmd = platform === 'darwin'
+        ? ['open', url]
+        : platform === 'win32'
+            ? ['cmd', '/c', 'start', url]
+            : ['xdg-open', url];
+    const proc = spawn(cmd[0], cmd.slice(1), { stdio: 'ignore', detached: true });
+    proc.unref();
+}
+/**
+ * Run the web command: start serve and open browser.
+ */
+export async function webCommand(options) {
+    const port = options.port ?? 4200;
+    const uiUrl = options.uiUrl ?? 'http://localhost:6001/nimbus';
+    console.log(`Starting Nimbus API server on port ${port}...`);
+    console.log(`Opening Web UI at ${uiUrl}\n`);
+    // Open browser after a short delay to let the server start (skipped with --no-open)
+    if (!options.noOpen) {
+        setTimeout(() => {
+            openBrowser(uiUrl).catch(() => {
+                console.log(`Could not open browser. Please visit: ${uiUrl}`);
+            });
+        }, 1500);
+    }
+    // Start the server (this blocks)
+    await serveCommand({
+        port,
+        host: options.host,
+        auth: options.auth,
+    });
+}