@bytespell/shella 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# Shella
+
+Self-hosted AI coding agents. Access from your phone.
+
+Run multiple AI agents in parallel, persist sessions across devices, and manage everything from a touch-friendly mobile interface.
+
+## Install
+
+### npx (Developers)
+
+```bash
+npx @bytespell/shella
+```
+
+Opens at `http://localhost:3067`. Access from your phone using the LAN IP shown.
+
+### Docker (Homelab)
+
+```yaml
+# docker-compose.yml
+services:
+  shella:
+    image: ghcr.io/bytespell/shella
+    ports:
+      - '3067:3067'
+    volumes:
+      - /path/to/projects:/project
+      - shella-data:/root/.config/shella
+    restart: unless-stopped
+
+volumes:
+  shella-data:
+```
+
+```bash
+docker compose up -d
+# Access at http://<server-ip>:3067
+```
+
+## Features
+
+- **Parallel agents** - Run multiple agents on different tasks simultaneously
+- **Session persistence** - Sessions survive restarts, pick up from any device
+- **Cross-device sync** - Same windows, same state, real-time sync
+- **Mobile-first** - Touch-optimized for iOS Safari
+
+## CLI Options
+
+```bash
+shella                           # Start with defaults
+shella --port 3000               # Custom web port
+shella --opencode-port 5000      # Custom OpenCode port
+shella --no-open                 # Don't open browser
+shella --help                    # Show help
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev servers (Vite + Express + OpenCode)
+npm run start:dev
+
+# Build for production
+npm run build
+
+# Test production build locally
+node bin/cli.js --no-open
+```
+
+## Requirements
+
+- Node.js 20.19+ or 22.12+
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { createOpencodeServer } from '@opencode-ai/sdk';
+import { networkInterfaces } from 'os';
+import { spawn } from 'child_process';
+import { createConnection } from 'net';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = '0.1.0';
+/**
+ * Check if a port is available
+ */
+async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host: '127.0.0.1' });
+        socket.setTimeout(1000);
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(false); // Port is in use
+        });
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(true); // Port is available
+        });
+        socket.on('error', () => {
+            resolve(true); // Port is available (connection refused)
+        });
+    });
+}
+/**
+ * Get the LAN IP address for mobile access
+ */
+function getLanIp() {
+    const interfaces = networkInterfaces();
+    for (const [name, addrs] of Object.entries(interfaces)) {
+        // Skip loopback, docker, veth, bridge interfaces
+        if (/^(lo|docker|veth|br-|virbr)/.test(name))
+            continue;
+        for (const addr of addrs || []) {
+            if (addr.family === 'IPv4' && !addr.internal) {
+                return addr.address;
+            }
+        }
+    }
+    return 'localhost';
+}
+/**
+ * Print a nice boxed message with the access URL
+ */
+function printAccessBox(lanIp, port) {
+    const url = `http://${lanIp}:${port}`;
+    const urlLine = `    ${url}`;
+    const width = Math.max(44, urlLine.length + 4);
+    const border = '-'.repeat(width);
+    const pad = (s) => s + ' '.repeat(width - s.length);
+    console.log(`
++${border}+
+|${pad('')}|
+|${pad('  Access from any device:')}|
+|${pad('')}|
+|${pad(urlLine)}|
+|${pad('')}|
++${border}+
+`);
+}
+let opencodeServer = null;
+let expressProcess = null;
+async function startCommand(options) {
+    const port = parseInt(options.port);
+    const opencodePort = parseInt(options.opencodePort);
+    console.log(`Shella v${VERSION}\n`);
+    // Check if ports are available
+    const webPortAvailable = await isPortAvailable(port);
+    const ocPortAvailable = await isPortAvailable(opencodePort);
+    if (!webPortAvailable) {
+        console.error(`Error: Port ${port} is already in use.`);
+        console.error(`\nTry one of these:`);
+        console.error(`  - Stop the process using port ${port}`);
+        console.error(`  - Use a different port: shella --port 3070`);
+        process.exit(1);
+    }
+    if (!ocPortAvailable) {
+        console.error(`Error: Port ${opencodePort} is already in use (OpenCode port).`);
+        console.error(`\nThis usually means OpenCode is already running.`);
+        console.error(`\nTry one of these:`);
+        console.error(`  - Kill the existing OpenCode: pkill -f "opencode serve"`);
+        console.error(`  - Use a different port: shella --opencode-port 4097`);
+        process.exit(1);
+    }
+    // Start OpenCode server using the bundled binary
+    console.log('Starting OpenCode...');
+    try {
+        opencodeServer = await createOpencodeServer({
+            port: opencodePort,
+            timeout: 30000,
+        });
+        console.log(`  OpenCode ready (port ${opencodePort})`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`\nFailed to start OpenCode: ${message}`);
+        if (message.includes('port')) {
+            console.error(`\nThe port ${opencodePort} may be in use. Try:`);
+            console.error(`  shella --opencode-port 4097`);
+        }
+        process.exit(1);
+    }
+    // Start Express server in production mode
+    console.log('Starting Shella server...');
+    const serverPath = path.join(__dirname, '..', 'dist', 'server', 'index.js');
+    expressProcess = spawn('node', [serverPath], {
+        env: {
+            ...process.env,
+            NODE_ENV: 'production',
+            PORT: String(port),
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // Wait for server to be ready
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new Error('Server startup timeout (10s). Check logs for errors.'));
+        }, 10000);
+        expressProcess.stdout?.on('data', (data) => {
+            const output = data.toString();
+            if (output.includes('Running on')) {
+                clearTimeout(timeout);
+                resolve();
+            }
+            // Forward output but strip the prefix since we add our own
+            process.stdout.write(output.replace(/\[shella-server\] /g, '  '));
+        });
+        expressProcess.stderr?.on('data', (data) => {
+            process.stderr.write(data);
+        });
+        expressProcess.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`Failed to spawn server: ${err.message}`));
+        });
+        expressProcess.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                clearTimeout(timeout);
+                reject(new Error(`Server exited with code ${code}`));
+            }
+        });
+    });
+    console.log(`  Shella ready (port ${port})`);
+    // Print access box
+    const lanIp = getLanIp();
+    printAccessBox(lanIp, port);
+    console.log('Press Ctrl+C to stop\n');
+    // Open browser if requested
+    if (options.open) {
+        const url = `http://localhost:${port}`;
+        const openCommand = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        spawn(openCommand, [url], { stdio: 'ignore', detached: true }).unref();
+    }
+}
+/**
+ * Graceful shutdown handler
+ */
+function shutdown() {
+    console.log('\nShutting down...');
+    if (expressProcess) {
+        expressProcess.kill('SIGTERM');
+        expressProcess = null;
+    }
+    if (opencodeServer) {
+        opencodeServer.close();
+        opencodeServer = null;
+    }
+    console.log('Goodbye!');
+    process.exit(0);
+}
+// Handle shutdown signals
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+// CLI definition
+program
+    .name('shella')
+    .description('Self-hosted AI coding agents. Access from your phone.')
+    .version(VERSION);
+program
+    .command('start', { isDefault: true })
+    .description('Start Shella')
+    .option('-p, --port <port>', 'Web server port', '3067')
+    .option('--opencode-port <port>', 'OpenCode server port', '4096')
+    .option('--no-open', "Don't open browser automatically")
+    .action(startCommand);
+program.parse();

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+declare const CONFIG_DIR: string;
+export { CONFIG_DIR };

package/dist/server/index.js

@@ -0,0 +1,94 @@
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { corsMiddleware } from './middleware/cors.js';
+import windowsRoutes from './routes/windows.js';
+import modelStateRoutes from './routes/model-state.js';
+import logsRoutes from './routes/logs.js';
+import proxyRoutes from './routes/proxy.js';
+import { getDatabase } from './services/database.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Runtime mode detection
+const isProd = process.env.NODE_ENV === 'production';
+// Port: 3067 in prod, 3068 in dev (Vite uses 3067 in dev)
+const PORT = process.env.PORT || (isProd ? 3067 : 3068);
+// Config directory: ~/.config/shella/
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'shella');
+// Log file: ~/.config/shella/shella.log in prod, ./dev.log in dev
+const LOG_FILE = isProd
+    ? path.join(CONFIG_DIR, 'shella.log')
+    : path.resolve(process.cwd(), 'dev.log');
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        console.log(`[shella-server] Created config directory: ${CONFIG_DIR}`);
+    }
+}
+const app = express();
+// CORS - allow all origins for mobile debugging
+app.use(corsMiddleware);
+// JSON body parsing
+app.use(express.json());
+// Health check
+app.get('/health', (_req, res) => res.json({ status: 'ok' }));
+// Mount API routes
+app.use('/__shella', windowsRoutes);
+app.use('/__model-state', modelStateRoutes);
+app.use('/__logs', logsRoutes);
+app.use('/api', proxyRoutes);
+// Production: serve static files from dist/web/
+if (isProd) {
+    const webDir = path.join(__dirname, '..', 'web');
+    if (fs.existsSync(webDir)) {
+        console.log(`[shella-server] Serving static files from ${webDir}`);
+        app.use(express.static(webDir));
+        // SPA fallback: serve index.html for non-API routes
+        // Express 5 requires named wildcards, use {*path} syntax
+        app.get('{*path}', (req, res, next) => {
+            // Skip API routes
+            if (req.path.startsWith('/api') ||
+                req.path.startsWith('/__shella') ||
+                req.path.startsWith('/__model-state') ||
+                req.path.startsWith('/__logs') ||
+                req.path.startsWith('/health')) {
+                return next();
+            }
+            res.sendFile(path.join(webDir, 'index.html'));
+        });
+    }
+    else {
+        console.warn(`[shella-server] Warning: ${webDir} not found. Static serving disabled.`);
+    }
+}
+/**
+ * Start the server
+ */
+async function start() {
+    // Ensure config directory exists in prod
+    if (isProd) {
+        ensureConfigDir();
+    }
+    // Initialize database before starting server
+    await getDatabase();
+    // Clear/create log file on server start
+    const logDir = path.dirname(LOG_FILE);
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    fs.writeFileSync(LOG_FILE, `--- Shella server started ${new Date().toISOString()} ---\n`);
+    app.listen(PORT, () => {
+        console.log(`[shella-server] Running on http://localhost:${PORT}`);
+        console.log(`[shella-server] Mode: ${isProd ? 'production' : 'development'}`);
+        console.log(`[shella-server] Logging to ${LOG_FILE}`);
+    });
+}
+start().catch((err) => {
+    console.error('[shella-server] Failed to start:', err);
+    process.exit(1);
+});
+export { CONFIG_DIR };

package/dist/server/middleware/cors.d.ts

@@ -0,0 +1,6 @@
+import cors from 'cors';
+export declare const corsMiddleware: (req: cors.CorsRequest, res: {
+    statusCode?: number | undefined;
+    setHeader(key: string, value: string): any;
+    end(): any;
+}, next: (err?: any) => any) => void;

package/dist/server/middleware/cors.js

@@ -0,0 +1,8 @@
+import cors from 'cors';
+// Allow all origins for mobile debugging over LAN
+export const corsMiddleware = cors({
+    origin: true,
+    credentials: true,
+    methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'X-Client-Id', 'Accept'],
+});

package/dist/server/routes/logs.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/dist/server/routes/logs.js

@@ -0,0 +1,29 @@
+import { Router } from 'express';
+import fs from 'fs';
+import path from 'path';
+const LOG_FILE = path.resolve(process.cwd(), 'dev.log');
+const router = Router();
+// POST /__logs - receive browser console logs
+router.post('/', (req, res) => {
+    try {
+        const { level, args } = req.body;
+        const prefix = level === 'error' ? '🔴' : level === 'warn' ? '🟡' : '🌐';
+        const timestamp = new Date().toISOString().slice(11, 23); // HH:MM:SS.mmm
+        const message = args
+            .map((a) => (typeof a === 'object' ? JSON.stringify(a) : String(a)))
+            .join(' ');
+        const line = `${timestamp} ${prefix} ${message}`;
+        // Log to terminal
+        console.log(line);
+        // Append to file
+        fs.appendFileSync(LOG_FILE, line + '\n');
+        res.sendStatus(200);
+    }
+    catch {
+        const fallback = `${new Date().toISOString().slice(11, 23)} 🌐 [parse error] ${JSON.stringify(req.body)}`;
+        console.log(fallback);
+        fs.appendFileSync(LOG_FILE, fallback + '\n');
+        res.sendStatus(200);
+    }
+});
+export default router;

package/dist/server/routes/model-state.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/dist/server/routes/model-state.js

@@ -0,0 +1,81 @@
+import { Router } from 'express';
+import path from 'path';
+import fs from 'fs';
+import { STATE_DIR } from '../services/database.js';
+const MODEL_STATE_FILE = path.join(STATE_DIR, 'model.json');
+function ensureStateDir() {
+    if (!fs.existsSync(STATE_DIR)) {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+    }
+}
+function readModelState() {
+    try {
+        if (!fs.existsSync(MODEL_STATE_FILE)) {
+            return { recent: [], favorite: [] };
+        }
+        const data = fs.readFileSync(MODEL_STATE_FILE, 'utf-8');
+        const parsed = JSON.parse(data);
+        return {
+            recent: Array.isArray(parsed.recent) ? parsed.recent : [],
+            favorite: Array.isArray(parsed.favorite) ? parsed.favorite : [],
+            variant: typeof parsed.variant === 'object' && parsed.variant !== null ? parsed.variant : {},
+        };
+    }
+    catch (err) {
+        console.error('[model-state] Failed to read model state:', err);
+        return { recent: [], favorite: [] };
+    }
+}
+function writeModelState(state) {
+    try {
+        ensureStateDir();
+        fs.writeFileSync(MODEL_STATE_FILE, JSON.stringify(state, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.error('[model-state] Failed to write model state:', err);
+        throw err;
+    }
+}
+function toggleFavorite(model) {
+    const state = readModelState();
+    const exists = state.favorite.some((f) => f.providerID === model.providerID && f.modelID === model.modelID);
+    if (exists) {
+        // Remove from favorites
+        state.favorite = state.favorite.filter((f) => f.providerID !== model.providerID || f.modelID !== model.modelID);
+    }
+    else {
+        // Add to favorites
+        state.favorite = [model, ...state.favorite];
+    }
+    writeModelState(state);
+    return state;
+}
+const router = Router();
+// GET /__model-state - read model state
+router.get('/', (_req, res) => {
+    try {
+        const state = readModelState();
+        res.json({ recent: state.recent, favorite: state.favorite });
+    }
+    catch (err) {
+        console.error('[model-state] Failed to get model state:', err);
+        res.status(500).json({ error: 'Failed to read model state' });
+    }
+});
+// POST /__model-state/favorite - toggle favorite
+router.post('/favorite', (req, res) => {
+    try {
+        const model = req.body;
+        if (!model.providerID || !model.modelID) {
+            res.status(400).json({ error: 'providerID and modelID required' });
+            return;
+        }
+        const state = toggleFavorite(model);
+        res.json({ recent: state.recent, favorite: state.favorite });
+    }
+    catch (err) {
+        console.error('[model-state] Failed to toggle favorite:', err);
+        res.status(500).json({ error: 'Failed to update model state' });
+    }
+});
+export default router;

package/dist/server/routes/proxy.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/dist/server/routes/proxy.js

@@ -0,0 +1,122 @@
+import { Router } from 'express';
+const OPENCODE_URL = process.env.OPENCODE_URL || 'http://localhost:4096';
+const router = Router();
+// Routes that should return 202 immediately without waiting for OpenCode response.
+// These are "fire-and-forget" - the browser doesn't need the response body,
+// and waiting would cause the UI to hang while OpenCode processes the request.
+const FIRE_AND_FORGET_PATTERNS = [
+    { method: 'POST', pattern: /^\/session\/[^/]+\/shell$/ },
+    { method: 'POST', pattern: /^\/session\/[^/]+\/command$/ },
+    { method: 'POST', pattern: /^\/session\/[^/]+\/abort$/ },
+    { method: 'POST', pattern: /^\/session\/[^/]+\/revert$/ },
+    { method: 'POST', pattern: /^\/session\/[^/]+\/unrevert$/ },
+    { method: 'POST', pattern: /^\/session\/[^/]+\/summarize$/ },
+    // Permission endpoints (old and new SDK versions)
+    { method: 'POST', pattern: /^\/session\/[^/]+\/permissions\/[^/]+$/ },
+    { method: 'POST', pattern: /^\/permission\/[^/]+\/reply$/ },
+];
+const isFireAndForget = (method, path) => {
+    // Strip query string for matching
+    const pathWithoutQuery = path.split('?')[0];
+    return FIRE_AND_FORGET_PATTERNS.some((route) => route.method === method && route.pattern.test(pathWithoutQuery));
+};
+const buildTargetUrl = (req) => {
+    const url = new URL(req.url, OPENCODE_URL);
+    return url;
+};
+const buildHeaders = (req, includeBody) => {
+    const headers = {};
+    if (typeof req.headers['accept'] === 'string') {
+        headers['accept'] = req.headers['accept'];
+    }
+    if (includeBody) {
+        headers['content-type'] = 'application/json';
+    }
+    return headers;
+};
+const hasBody = (method) => {
+    return ['POST', 'PUT', 'PATCH'].includes(method);
+};
+// Fire-and-forget: send request to OpenCode but return 202 immediately
+const fireAndForget = (req, label) => {
+    const url = buildTargetUrl(req);
+    const headers = buildHeaders(req, hasBody(req.method));
+    fetch(url, {
+        method: req.method,
+        headers,
+        body: hasBody(req.method) ? JSON.stringify(req.body ?? {}) : undefined,
+    }).catch((error) => {
+        console.error(`[proxy] ${label} fire-and-forget error:`, error);
+    });
+};
+// Stream proxy: forward request and stream response back
+const streamProxy = async (req, res) => {
+    const url = buildTargetUrl(req);
+    const headers = buildHeaders(req, hasBody(req.method));
+    try {
+        const response = await fetch(url, {
+            method: req.method,
+            headers,
+            body: hasBody(req.method) ? JSON.stringify(req.body ?? {}) : undefined,
+        });
+        // Forward status
+        res.status(response.status);
+        // Forward headers (except content-length which may be wrong after buffering)
+        response.headers.forEach((value, key) => {
+            if (key.toLowerCase() !== 'content-length') {
+                res.setHeader(key, value);
+            }
+        });
+        // Handle 204 No Content
+        if (response.status === 204 || !response.body) {
+            res.end();
+            return;
+        }
+        // Check if this is SSE
+        const contentType = response.headers.get('content-type') ?? '';
+        const isSSE = contentType.includes('text/event-stream');
+        if (isSSE) {
+            // SSE: stream chunks as they arrive
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            const reader = response.body.getReader();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    res.write(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            res.end();
+        }
+        else {
+            // Non-SSE: buffer and send
+            const buffer = Buffer.from(await response.arrayBuffer());
+            res.send(buffer);
+        }
+    }
+    catch (error) {
+        console.error(`[proxy] ${req.method} ${req.url} error:`, error);
+        res.status(502).json({ error: 'Failed to proxy request to OpenCode' });
+    }
+};
+// Log all proxied requests
+router.use((req, _res, next) => {
+    console.log(`[proxy] ${req.method} ${req.url}`);
+    next();
+});
+// Main proxy handler
+router.use('/', async (req, res) => {
+    if (isFireAndForget(req.method, req.url)) {
+        const label = req.url.split('?')[0];
+        fireAndForget(req, label);
+        res.status(202).end();
+        return;
+    }
+    await streamProxy(req, res);
+});
+export default router;

package/dist/server/routes/windows.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;