@bytespell/shella 0.1.3 → 0.1.5

package/README.md

@@ -1,4 +1,4 @@
-# Shella
+# shella
 
 Self-hosted AI coding agents. Access from your phone.
 
@@ -56,6 +56,54 @@ docker compose up -d
 # Access at http://<server-ip>:3067
 ```
 
+## GitHub Authentication
+
+AI agents may need to push code changes to GitHub. Shella uses the GitHub CLI (`gh`) for authentication.
+
+### Docker Setup
+
+```bash
+# 1. Start shella
+docker compose up -d
+
+# 2. Authenticate with GitHub (one-time setup)
+docker exec -it shella gh auth login
+
+# 3. Follow the device flow prompts
+#    - Choose "GitHub.com"
+#    - Choose "HTTPS"
+#    - Authenticate via browser
+```
+
+Your authentication is stored in `/projects/.shella/gh/` and persists across container restarts and rebuilds.
+
+### npx Usage
+
+If running via `npx @bytespell/shella`, you need `gh` installed on your system:
+
+```bash
+# Install gh CLI (macOS)
+brew install gh
+
+# Install gh CLI (Linux)
+# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+
+# Authenticate
+gh auth login
+
+# Run shella
+npx @bytespell/shella
+```
+
+### Verify Authentication
+
+```bash
+# Check auth status
+docker exec shella gh auth status
+
+# Should show: "Logged in to github.com as <username>"
+```
+
 ## Features
 
 - **Parallel agents** - Run multiple agents on different tasks simultaneously

package/bin/cli.js

@@ -1,14 +1,29 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import { createOpencodeServer } from '@opencode-ai/sdk';
-import { networkInterfaces } from 'os';
+import { networkInterfaces, homedir } from 'os';
 import { spawn } from 'child_process';
 import { createConnection } from 'net';
-import { existsSync, readdirSync } from 'fs';
+import { existsSync, readdirSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import * as p from '@clack/prompts';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const VERSION = '0.1.3';
+const VERSION = '0.1.4';
+// Brand color (indigo) for terminal output
+const BRAND = '\x1b[38;2;99;102;241m'; // rgb(99, 102, 241) - matches --primary
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const brand = (text) => `${BRAND}${text}${RESET}`;
+const dim = (text) => `${DIM}${text}${RESET}`;
+/**
+ * Load OpenCode config with plugin and model definitions.
+ */
+function getOpencodeConfig() {
+    const configPath = path.join(__dirname, '..', 'dist', 'config', 'openai-codex-models.json');
+    const raw = readFileSync(configPath, 'utf-8');
+    return JSON.parse(raw);
+}
 /**
  * Check if running inside Docker container
  */
@@ -35,6 +50,17 @@ async function isPortAvailable(port) {
         });
     });
 }
+/**
+ * Find the next available port starting from a given port
+ */
+async function findAvailablePort(start, maxAttempts = 100) {
+    for (let port = start; port < start + maxAttempts; port++) {
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    return null;
+}
 /**
  * Get the LAN IP address for mobile access
  */
@@ -52,31 +78,6 @@ function getLanIp() {
     }
     return 'localhost';
 }
-/**
- * Print a nice boxed message with the access URL
- */
-function printAccessBox(lanIp, port, projectName) {
-    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('');
-    console.log(`+${border}+`);
-    console.log(`|${pad('')}|`);
-    if (projectName) {
-        console.log(`|${pad(`  Shella v${VERSION} - ${projectName}`)}|`);
-    }
-    else {
-        console.log(`|${pad(`  Shella v${VERSION}`)}|`);
-    }
-    console.log(`|${pad('')}|`);
-    console.log(`|${pad('  Access from any device:')}|`);
-    console.log(`|${pad(urlLine)}|`);
-    console.log(`|${pad('')}|`);
-    console.log(`+${border}+`);
-    console.log('');
-}
 /**
  * Register projects with OpenCode by creating a session in each directory.
  * This triggers OpenCode to discover and register the project.
@@ -88,14 +89,14 @@ async function registerProjects(opencodePort, projectsDir) {
         // Resolve to absolute path
         const absDir = path.resolve(projectsDir);
         if (!existsSync(absDir)) {
-            console.error(`Error: Projects directory not found: ${absDir}`);
+            p.log.error(`projects directory not found: ${absDir}`);
             process.exit(1);
         }
         // Register each subdirectory (OpenCode will determine if it's a git repo)
         const entries = readdirSync(absDir, { withFileTypes: true });
         const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
         if (dirs.length === 0) {
-            console.error(`Error: No subdirectories found in ${absDir}`);
+            p.log.error(`no subdirectories found in ${absDir}`);
             process.exit(1);
         }
         for (const entry of dirs) {
@@ -143,29 +144,37 @@ async function startCommand(options) {
     const port = parseInt(options.port);
     const opencodePort = parseInt(options.opencodePort);
     const cwd = process.cwd();
-    // Docker requires --projects-dir
-    if (isDocker() && !options.projectsDir) {
-        console.error('Error: --projects-dir is required when running in Docker.\n');
-        console.error('Example:');
-        console.error('  docker run -v ~/code:/project shella --projects-dir /project\n');
-        console.error('Or in docker-compose.yml:');
-        console.error('  command: ["--projects-dir", "/project"]');
+    const verbose = options.verbose;
+    // Determine mode based on --projects-dir presence
+    const mode = options.projectsDir ? 'server' : 'cwd';
+    // Docker requires --projects-dir (server mode)
+    if (isDocker() && mode === 'cwd') {
+        p.log.error('--projects-dir is required when running in Docker');
+        p.log.message('example: docker run -v ~/code:/project shella --projects-dir /project');
+        p.log.message('or in docker-compose.yml: command: ["--projects-dir", "/project"]');
         process.exit(1);
     }
-    // Determine the projects directory to pass to the server
+    // Determine the directory to pass to the server
     const projectsDir = options.projectsDir ? path.resolve(options.projectsDir) : cwd;
     // 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: shella --port 3070`);
+        p.log.error(`port ${port} is already in use`);
+        p.log.message('try: shella --port 3070');
         process.exit(1);
     }
+    // Check OpenCode port - use fallback if in use (likely another OpenCode instance)
+    let actualOpencodePort = opencodePort;
+    const ocPortAvailable = await isPortAvailable(opencodePort);
     if (!ocPortAvailable) {
-        console.error(`Error: Port ${opencodePort} is already in use (OpenCode).`);
-        console.error(`\nTry: pkill -f "opencode serve" or shella --opencode-port 4097`);
-        process.exit(1);
+        const fallbackPort = await findAvailablePort(opencodePort + 1);
+        if (!fallbackPort) {
+            p.log.error(`port ${opencodePort} is in use and no fallback ports available`);
+            process.exit(1);
+        }
+        actualOpencodePort = fallbackPort;
+        p.log.warn(`port ${opencodePort} is in use (possibly another OpenCode instance)`);
+        p.log.message(`using port ${actualOpencodePort} instead`);
     }
     // Ensure opencode binary from node_modules/.bin is in PATH
     // Required for: npm install -g @bytespell/shella
@@ -174,76 +183,152 @@ async function startCommand(options) {
     const binPath = path.join(__dirname, '..', 'node_modules', '.bin');
     const pathSep = process.platform === 'win32' ? ';' : ':';
     process.env.PATH = process.env.PATH ? `${binPath}${pathSep}${process.env.PATH}` : binPath;
-    // Show minimal startup message
-    console.log('Starting Shella...');
+    // In verbose mode, use simple status messages instead of clack UI
+    // This prevents spinner interference with log streaming
+    const s = verbose ? null : p.spinner();
+    const log = (msg) => {
+        if (verbose) {
+            console.log(msg);
+        }
+    };
+    if (!verbose) {
+        p.intro(`${brand('shella')} ${dim(`v${VERSION}`)}`);
+    }
+    else {
+        log(`${brand('shella')} ${dim(`v${VERSION}`)}`);
+    }
     // Start OpenCode server using the bundled binary
+    if (s)
+        s.start('Starting OpenCode...');
+    else
+        log('starting opencode...');
+    // Set XDG env vars to isolate OpenCode data to shella directories
+    // This prevents shella from polluting user's existing OpenCode installation
+    const home = homedir();
+    process.env.XDG_DATA_HOME = path.join(home, '.local', 'share', 'shella');
+    process.env.XDG_CACHE_HOME = path.join(home, '.cache', 'shella');
+    process.env.XDG_CONFIG_HOME = path.join(home, '.config', 'shella');
+    process.env.XDG_STATE_HOME = path.join(home, '.local', 'state', 'shella');
     try {
+        const config = getOpencodeConfig();
         opencodeServer = await createOpencodeServer({
-            port: opencodePort,
+            port: actualOpencodePort,
             timeout: 30000,
+            config,
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`Failed to start OpenCode: ${message}`);
+        if (s)
+            s.stop('Failed to start OpenCode', 1);
+        p.log.error(message);
         process.exit(1);
     }
     // Register projects with OpenCode
-    const { names } = await registerProjects(opencodePort, options.projectsDir);
+    if (s)
+        s.message('Registering directories...');
+    else
+        log('registering directories...');
+    const { names } = await registerProjects(actualOpencodePort, options.projectsDir);
     const projectName = names.length === 1 ? names[0] : names.length > 1 ? `${names.length} projects` : undefined;
-    // Start Express server in production mode, passing projectsDir
+    // Start Express server in production mode, passing mode and directory
+    if (s)
+        s.message('Starting server...');
+    else
+        log('starting server...');
     const serverPath = path.join(__dirname, '..', 'dist', 'server', 'index.js');
-    expressProcess = spawn('node', [serverPath, '--projects-dir', projectsDir], {
+    if (verbose) {
+        console.log(`[shella] mode: ${mode}, directory: ${projectsDir}`);
+    }
+    // Pass mode and directory to server
+    const serverArgs = mode === 'server'
+        ? ['--mode', 'server', '--projects-dir', projectsDir]
+        : ['--mode', 'cwd', '--directory', projectsDir];
+    expressProcess = spawn('node', [serverPath, ...serverArgs], {
         env: {
             ...process.env,
             NODE_ENV: 'production',
             PORT: String(port),
+            OPENCODE_URL: `http://localhost:${actualOpencodePort}`,
         },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
+    // Track if server is ready (for verbose mode log streaming)
+    let serverReady = false;
     // Wait for server to be ready
-    await new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            reject(new Error('Server startup timeout'));
-        }, 10000);
-        expressProcess.stdout?.on('data', (data) => {
-            const output = data.toString();
-            if (output.includes('Running on')) {
-                clearTimeout(timeout);
-                resolve();
-            }
-            // Suppress all server output
-        });
-        expressProcess.stderr?.on('data', () => {
-            // Suppress stderr too
-        });
-        expressProcess.on('error', (err) => {
-            clearTimeout(timeout);
-            reject(new Error(`Failed to spawn server: ${err.message}`));
-        });
-        expressProcess.on('exit', (code) => {
-            if (code !== 0 && code !== null) {
+    try {
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('Server startup timeout'));
+            }, 10000);
+            expressProcess.stdout?.on('data', (data) => {
+                const output = data.toString();
+                if (output.includes('Running on')) {
+                    clearTimeout(timeout);
+                    serverReady = true;
+                    resolve();
+                }
+                // In verbose mode, stream logs after server is ready
+                if (verbose && serverReady) {
+                    process.stdout.write(output);
+                }
+            });
+            expressProcess.stderr?.on('data', (data) => {
+                // In verbose mode, stream stderr after server is ready
+                if (verbose && serverReady) {
+                    process.stderr.write(data);
+                }
+            });
+            expressProcess.on('error', (err) => {
                 clearTimeout(timeout);
-                reject(new Error(`Server exited with code ${code}`));
-            }
+                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}`));
+                }
+            });
         });
-    });
-    // Print access box
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (s)
+            s.stop('Failed', 1);
+        p.log.error(message);
+        process.exit(1);
+    }
+    // Stop spinner and show success
+    if (s) {
+        s.stop('Ready');
+    }
+    // Show access URL
     const lanIp = getLanIp();
-    printAccessBox(lanIp, port, projectName);
-    console.log('Press Ctrl+C to stop');
+    const url = `http://${lanIp}:${port}`;
+    const title = projectName ? `${projectName}` : 'access from any device';
+    if (verbose) {
+        log(`\n${brand(url)}`);
+        log(dim(title));
+        log(`\n${dim('press ctrl+c to stop')}\n`);
+    }
+    else {
+        p.log.success(`${brand(url)}`);
+        p.log.message(dim(title));
+        p.outro(dim('press ctrl+c to stop'));
+    }
     // Open browser if requested
     if (options.open) {
-        const url = `http://localhost:${port}`;
+        const localUrl = `http://localhost:${port}`;
         const openCommand = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        spawn(openCommand, [url], { stdio: 'ignore', detached: true }).unref();
+        spawn(openCommand, [localUrl], { stdio: 'ignore', detached: true }).unref();
     }
 }
 /**
  * Graceful shutdown handler
  */
 function shutdown() {
-    console.log('\nStopping...');
+    console.log(''); // newline after ^C
+    console.log(dim('stopping...'));
     if (expressProcess) {
         expressProcess.kill('SIGTERM');
         expressProcess = null;
@@ -252,22 +337,34 @@ function shutdown() {
         opencodeServer.close();
         opencodeServer = null;
     }
+    console.log(`${brand('shella')} ${dim('stopped')}`);
     process.exit(0);
 }
 // Handle shutdown signals
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 // CLI definition
+// Default verbose to true in Docker for easier debugging
+const defaultVerbose = isDocker();
 program
     .name('shella')
-    .description('Self-hosted AI coding agents. Access from your phone.')
-    .version(VERSION);
-program
-    .command('start', { isDefault: true })
-    .description('Start Shella')
+    .description(`${brand('shella')} - Self-hosted AI coding agents. Access from your phone.
+
+Modes:
+  ${brand('shella')}                    Run in current directory (cwd mode)
+  ${brand('shella')} --projects-dir .   Register all subdirectories as projects (server mode)`)
+    .version(VERSION)
     .option('-p, --port <port>', 'Web server port', '3067')
     .option('--opencode-port <port>', 'OpenCode server port', '4096')
     .option('--projects-dir <path>', 'Directory containing projects (each subdirectory becomes a project)')
     .option('--no-open', "Don't open browser automatically")
-    .action(startCommand);
+    .option('-v, --verbose', 'Show detailed logs during startup', defaultVerbose)
+    .option('--quiet', 'Suppress logs (opposite of --verbose)')
+    .action((options) => {
+    // --quiet overrides --verbose
+    if (options.quiet) {
+        options.verbose = false;
+    }
+    return startCommand(options);
+});
 program.parse();

package/dev/cli.tsx

@@ -0,0 +1,38 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * shella dev CLI - Ink-based development server orchestrator
+ *
+ * Usage:
+ *   npx devi              Start interactive TUI (default)
+ *   npx devi [command]    Run command and exit
+ *
+ * Commands:
+ *   status, start, stop, logs, errors, clear
+ *   docker:up, docker:down, docker:status, etc.
+ */
+
+export {}; // Make this a module for top-level await
+
+import fs from 'fs';
+
+// Check if running inside a container - this tool won't work there
+if (fs.existsSync('/.dockerenv') || fs.existsSync('/run/.containerenv')) {
+  console.error('\x1b[31m✗ Error: Running inside a container\x1b[0m');
+  console.error(
+    '\x1b[33m  The dev tool manages host-based servers and cannot be used from containers.\x1b[0m',
+  );
+  console.error('\x1b[33m  Please run this command from your host machine instead.\x1b[0m');
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  // Interactive mode - launch Ink TUI
+  const { runInteractive } = await import('./interactive.js');
+  await runInteractive();
+} else {
+  // Non-interactive - run command and exit
+  const { runCommand } = await import('./core.js');
+  await runCommand(args);
+}