ai-kanban-terminal 0.2.0 → 0.4.0

package/README.md

@@ -20,6 +20,19 @@ Once published to npm:
 npx ai-kanban-terminal
 ```
 
+The server will start and display:
+```
+✓ ai-kanban-terminal is ready!
+
+  Open your browser and navigate to:
+
+  http://localhost:3000
+
+  Press Ctrl+C to stop the server
+```
+
+Then open your browser to `http://localhost:3000` to access the terminal.
+
 Or from GitHub directly:
 
 ```bash
@@ -93,6 +106,57 @@ Once the application starts, you'll see a terminal interface in your browser. Yo
 - **xterm.js**: Terminal emulator in the browser
 - **@xterm/addon-fit**: Automatic terminal resizing
 
+## Troubleshooting
+
+### Nothing happens when running `npx ai-kanban-terminal`
+
+If the command completes but nothing happens:
+
+1. **Check if the server started**: Look for the success message:
+   ```
+   ✓ ai-kanban-terminal is ready!
+   ```
+   
+2. **Manually open your browser**: Navigate to `http://localhost:3000`
+
+3. **Check if port is in use**: If you see "Port 3000 is already in use", try a different port:
+   ```bash
+   PORT=3001 npx ai-kanban-terminal
+   ```
+
+4. **Enable verbose logging**: Check npm installation logs:
+   ```bash
+   npm install -g ai-kanban-terminal --verbose
+   ai-kanban-terminal
+   ```
+
+### Server fails to start
+
+If you see an error about missing `dist` directory:
+
+1. The package may not have been built correctly during publishing
+2. Please report this issue at: https://github.com/kght6123/ai-kanban-terminal/issues
+
+### Terminal not displaying in browser
+
+1. Ensure JavaScript is enabled in your browser
+2. Check browser console for errors (F12 → Console tab)
+3. Verify that `http://localhost:3000` is accessible
+
+### Other issues
+
+For detailed logging when running via npx:
+
+```bash
+# Set DEBUG environment variable for more logs
+DEBUG=* npx ai-kanban-terminal
+
+# Or check Node.js logs
+NODE_DEBUG=* npx ai-kanban-terminal
+```
+
+If issues persist, please open an issue at: https://github.com/kght6123/ai-kanban-terminal/issues
+
 ## Scripts
 
 - `npm run dev` - Start Vite development server on port 5173 (frontend only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-kanban-terminal",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Browser-based terminal with bidirectional shell using Vite, Express, node-pty, xterm.js, and Socket.IO",
   "main": "server.js",
   "type": "commonjs",
@@ -11,7 +11,6 @@
     "dev": "vite",
     "build": "vite build",
     "start": "NODE_ENV=production node server.js",
-    "postinstall": "npm run build",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/server.js

@@ -2,6 +2,7 @@
 
 const express = require('express');
 const path = require('path');
+const fs = require('fs');
 const { createServer } = require('http');
 const { Server } = require('socket.io');
 const pty = require('node-pty');
@@ -24,6 +25,16 @@ const io = new Server(httpServer, {
 
 // Serve static files from dist directory
 const distPath = path.join(__dirname, 'dist');
+
+// Check if dist directory exists
+if (!fs.existsSync(distPath)) {
+  console.error('Error: dist directory not found at:', distPath);
+  console.error('This package may not have been built correctly.');
+  console.error('If you installed via npx, please report this issue at:');
+  console.error('https://github.com/kght6123/ai-kanban-terminal/issues');
+  process.exit(1);
+}
+
 expressApp.use(express.static(distPath));
 
 // Store terminal instances per socket
@@ -37,7 +48,13 @@ io.on('connection', (socket) => {
     
     try {
       // Determine shell based on OS
-      const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
+      let shell;
+      if (os.platform() === 'win32') {
+        shell = process.env.COMSPEC || 'cmd.exe';
+      } else {
+        // Use SHELL environment variable (user's default shell) or fallback to common shells
+        shell = process.env.SHELL || '/bin/sh';
+      }
       
       // Create pseudo-terminal
       // NOTE: Uses HOME directory as working directory for development.
@@ -111,8 +128,17 @@ expressApp.get('*', (req, res) => {
 });
 
 httpServer.listen(port, () => {
-  console.log(`> ai-kanban-terminal ready on http://${hostname}:${port}`);
+  console.log(`\n✓ ai-kanban-terminal is ready!`);
+  console.log(`\n  Open your browser and navigate to:\n`);
+  console.log(`  \x1b[1m\x1b[36mhttp://${hostname}:${port}\x1b[0m\n`);
+  console.log(`  Press Ctrl+C to stop the server\n`);
 }).on('error', (err) => {
-  console.error('Server failed to start:', err);
+  if (err.code === 'EADDRINUSE') {
+    console.error(`\nError: Port ${port} is already in use.`);
+    console.error(`Please try a different port by setting the PORT environment variable:`);
+    console.error(`  PORT=3001 npx ai-kanban-terminal\n`);
+  } else {
+    console.error('Server failed to start:', err);
+  }
   process.exit(1);
 });