claude-ws 0.3.98 → 0.3.100

package/bin/claude-ws.js

@@ -14,6 +14,18 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
+// ── Subcommand detection ──────────────────────────────────────────────
+// If the first positional arg is a known subcommand, delegate and exit.
+// Otherwise, fall through to the existing foreground startup logic.
+const SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'open'];
+const _firstArg = process.argv[2];
+if (SUBCOMMANDS.includes(_firstArg)) {
+  require(`./lib/commands/${_firstArg}`).run(process.argv.slice(3));
+  // The command handles process.exit — nothing else to do here.
+  return;
+}
+// ── End subcommand detection ──────────────────────────────────────────
+
 const isWindows = process.platform === 'win32';
 
 /**
@@ -59,7 +71,23 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 Claude Workspace - Visual workspace for Claude Code
 
 Usage:
-  claude-ws [options]
+  claude-ws [options]          Start server in foreground (blocks terminal)
+  claude-ws <command> [flags]  Daemon management
+
+Commands:
+  start    Start as background daemon
+           --port, -p <port>   Server port (default: 8556)
+           --host <host>       Bind host (default: localhost)
+           --data-dir <dir>    Data directory
+           --log-dir <dir>     Log directory
+           --no-open           Don't open browser after start
+  stop     Stop the running daemon
+  status   Show daemon PID, URL, and health
+  logs     Tail daemon log files
+           -f, --follow        Follow log output
+           -n, --lines <N>     Number of lines (default: 50)
+           -e, --error         Show error log instead
+  open     Open browser to running instance
 
 Options:
   -v, --version    Show version number
@@ -68,10 +96,15 @@ Options:
 Environment:
   .env: Loaded from current working directory (./.env)
   Database: Stored in ./data/claude-ws.db (or DATA_DIR env)
+  Config:  ~/.claude-ws/config.json (port, host, dataDir, logDir)
 
 Examples:
-  claude-ws              Start server using .env from current directory
-  cd ~/myproject && claude-ws   Use ~/myproject/.env and database
+  claude-ws                     Start server in foreground
+  claude-ws start               Start as daemon
+  claude-ws start --port 3000   Start daemon on port 3000
+  claude-ws status              Check if daemon is running
+  claude-ws logs -f             Follow daemon logs
+  claude-ws stop                Stop the daemon
 
 For more info: https://github.com/Claude-Workspace/claude-ws
   `);

package/bin/lib/cli-parser.js

@@ -0,0 +1,109 @@
+/**
+ * Lightweight CLI argument parser.
+ * Zero dependencies - Node.js built-ins only.
+ *
+ * Supports:
+ *   --port 3000, --port=3000
+ *   --no-open (boolean negation)
+ *   -f (short flags)
+ *   -n 50 (short flags with values)
+ */
+
+/**
+ * @param {string[]} argv - process.argv.slice(N) after subcommand
+ * @param {{ flags: Record<string, { type: 'string'|'boolean', alias?: string, default?: any }> }} schema
+ * @returns {{ flags: Record<string, any>, args: string[] }}
+ */
+function parse(argv, schema) {
+  const flags = {};
+  const args = [];
+  const defs = schema.flags || {};
+
+  // Set defaults
+  for (const [key, def] of Object.entries(defs)) {
+    if (def.default !== undefined) {
+      flags[key] = def.default;
+    } else {
+      flags[key] = def.type === 'boolean' ? false : undefined;
+    }
+  }
+
+  // Build alias map: alias -> canonical name
+  const aliasMap = {};
+  for (const [key, def] of Object.entries(defs)) {
+    if (def.alias) {
+      aliasMap[def.alias] = key;
+    }
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === '--') {
+      args.push(...argv.slice(i + 1));
+      break;
+    }
+
+    // --no-<flag> boolean negation
+    if (arg.startsWith('--no-')) {
+      const name = arg.slice(5);
+      if (defs[name] && defs[name].type === 'boolean') {
+        flags[name] = false;
+        i++;
+        continue;
+      }
+    }
+
+    // --flag=value
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eqIdx = arg.indexOf('=');
+      const name = arg.slice(2, eqIdx);
+      const value = arg.slice(eqIdx + 1);
+      if (defs[name]) {
+        flags[name] = defs[name].type === 'boolean' ? value !== 'false' : value;
+      }
+      i++;
+      continue;
+    }
+
+    // --flag [value]
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2);
+      if (defs[name]) {
+        if (defs[name].type === 'boolean') {
+          flags[name] = true;
+          i++;
+        } else {
+          flags[name] = argv[i + 1];
+          i += 2;
+        }
+        continue;
+      }
+    }
+
+    // -f or -f value (short alias)
+    if (arg.startsWith('-') && !arg.startsWith('--') && arg.length === 2) {
+      const alias = arg.slice(1);
+      const canonical = aliasMap[alias];
+      if (canonical && defs[canonical]) {
+        if (defs[canonical].type === 'boolean') {
+          flags[canonical] = true;
+          i++;
+        } else {
+          flags[canonical] = argv[i + 1];
+          i += 2;
+        }
+        continue;
+      }
+    }
+
+    // Positional argument
+    args.push(arg);
+    i++;
+  }
+
+  return { flags, args };
+}
+
+module.exports = { parse };

package/bin/lib/commands/logs.js

@@ -0,0 +1,73 @@
+/**
+ * `claude-ws logs` — Tail daemon log files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { parse } = require('../cli-parser');
+const config = require('../config');
+
+const FLAG_SCHEMA = {
+  flags: {
+    follow: { type: 'boolean', alias: 'f', default: false },
+    lines: { type: 'string', alias: 'n', default: '50' },
+    error: { type: 'boolean', alias: 'e', default: false },
+  },
+};
+
+function run(argv) {
+  const { flags } = parse(argv, FLAG_SCHEMA);
+  const conf = config.resolve({});
+
+  const logFile = flags.error
+    ? path.join(conf.logDir, 'claude-ws-error.log')
+    : path.join(conf.logDir, 'claude-ws.log');
+
+  if (!fs.existsSync(logFile)) {
+    console.log(`[claude-ws] No log file found at ${logFile}`);
+    console.log('[claude-ws] Has the daemon been started? Try: claude-ws start');
+    process.exit(1);
+  }
+
+  const tailArgs = [];
+  tailArgs.push('-n', flags.lines);
+  if (flags.follow) {
+    tailArgs.push('-f');
+  }
+  tailArgs.push(logFile);
+
+  console.log(`[claude-ws] ${flags.error ? 'Error log' : 'Log'}: ${logFile}`);
+  console.log('---');
+
+  const tail = spawn('tail', tailArgs, { stdio: 'inherit' });
+
+  tail.on('error', (err) => {
+    // tail not available (Windows) — fall back to reading file
+    if (err.code === 'ENOENT') {
+      const content = fs.readFileSync(logFile, 'utf-8');
+      const lines = content.split('\n');
+      const n = parseInt(flags.lines, 10) || 50;
+      const tail = lines.slice(-n);
+      console.log(tail.join('\n'));
+
+      if (flags.follow) {
+        console.log('[claude-ws] -f (follow) is not supported on this platform.');
+      }
+    } else {
+      console.error(`[claude-ws] Error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  tail.on('close', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Forward Ctrl+C to tail
+  process.on('SIGINT', () => {
+    tail.kill('SIGINT');
+  });
+}
+
+module.exports = { run };

package/bin/lib/commands/open.js

@@ -0,0 +1,49 @@
+/**
+ * `claude-ws open` — Open browser to the running instance.
+ */
+
+const { exec } = require('child_process');
+const config = require('../config');
+const daemon = require('../daemon');
+
+/**
+ * Open a URL in the default browser (cross-platform).
+ * @param {string} url
+ */
+function openUrl(url) {
+  const platform = process.platform;
+  let cmd;
+  if (platform === 'darwin') {
+    cmd = `open "${url}"`;
+  } else if (platform === 'win32') {
+    cmd = `start "" "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+
+  exec(cmd, (err) => {
+    if (err) {
+      console.log(`[claude-ws] Could not open browser. Visit: ${url}`);
+    }
+  });
+}
+
+async function run(_argv) {
+  const { running, pid } = daemon.checkRunning();
+
+  if (!running) {
+    console.log('[claude-ws] No running daemon found.');
+    console.log('[claude-ws] Start one first: claude-ws start');
+    process.exit(1);
+  }
+
+  const conf = config.resolve({});
+  const url = `http://${conf.host}:${conf.port}`;
+
+  console.log(`[claude-ws] Opening ${url} (PID ${pid})`);
+  openUrl(url);
+
+  process.exit(0);
+}
+
+module.exports = { run, openUrl };

package/bin/lib/commands/start.js

@@ -0,0 +1,73 @@
+/**
+ * `claude-ws start` — Start claude-ws as a background daemon.
+ */
+
+const { parse } = require('../cli-parser');
+const config = require('../config');
+const daemon = require('../daemon');
+const health = require('../health');
+
+const FLAG_SCHEMA = {
+  flags: {
+    port: { type: 'string', alias: 'p' },
+    host: { type: 'string' },
+    'data-dir': { type: 'string' },
+    'log-dir': { type: 'string' },
+    'no-open': { type: 'boolean' },
+  },
+};
+
+async function run(argv) {
+  const { flags } = parse(argv, FLAG_SCHEMA);
+  const conf = config.resolve(flags);
+
+  // Check if already running
+  const { running, pid } = daemon.checkRunning();
+  if (running) {
+    console.log(`[claude-ws] Already running (PID ${pid})`);
+    console.log(`[claude-ws] URL: http://${conf.host}:${conf.port}`);
+    console.log('[claude-ws] Use "claude-ws stop" to stop it first.');
+    process.exit(1);
+  }
+
+  console.log('[claude-ws] Starting daemon...');
+  console.log(`[claude-ws] Port: ${conf.port}`);
+  console.log(`[claude-ws] Host: ${conf.host}`);
+  console.log(`[claude-ws] Data: ${conf.dataDir}`);
+  console.log(`[claude-ws] Logs: ${conf.logDir}`);
+
+  const childPid = daemon.daemonize({
+    port: conf.port,
+    host: conf.host,
+    dataDir: conf.dataDir,
+    logDir: conf.logDir,
+    noOpen: flags['no-open'],
+  });
+
+  console.log(`[claude-ws] Daemon started (PID ${childPid})`);
+  console.log('[claude-ws] Waiting for server to become ready...');
+
+  const ready = await health.waitUntilReady(conf.host, conf.port, 60000, 2000);
+
+  if (ready) {
+    console.log(`[claude-ws] Server is ready at http://${conf.host}:${conf.port}`);
+
+    // Open browser unless --no-open
+    if (!flags['no-open']) {
+      try {
+        const openCmd = require('../commands/open');
+        openCmd.openUrl(`http://${conf.host}:${conf.port}`);
+      } catch {
+        // Non-critical — don't fail the start
+      }
+    }
+  } else {
+    console.log('[claude-ws] Server did not respond within 60s.');
+    console.log('[claude-ws] Check logs: claude-ws logs');
+    console.log('[claude-ws] The daemon may still be starting up (building, installing deps, etc.).');
+  }
+
+  process.exit(0);
+}
+
+module.exports = { run };

package/bin/lib/commands/status.js

@@ -0,0 +1,35 @@
+/**
+ * `claude-ws status` — Show daemon status, PID, URL, and health.
+ */
+
+const config = require('../config');
+const daemon = require('../daemon');
+const health = require('../health');
+
+async function run(_argv) {
+  const { running, pid } = daemon.checkRunning();
+
+  if (!running) {
+    console.log('[claude-ws] Status: NOT RUNNING');
+    process.exit(0);
+  }
+
+  const conf = config.resolve({});
+  const result = await health.check(conf.host, conf.port);
+
+  console.log('[claude-ws] Status: RUNNING');
+  console.log(`[claude-ws] PID: ${pid}`);
+  console.log(`[claude-ws] URL: http://${conf.host}:${conf.port}`);
+
+  if (result.ok) {
+    console.log(`[claude-ws] Health: OK (HTTP ${result.statusCode})`);
+  } else {
+    console.log(`[claude-ws] Health: UNREACHABLE (${result.error})`);
+    console.log('[claude-ws] The server process is running but not responding to HTTP.');
+    console.log('[claude-ws] It may still be starting up. Check: claude-ws logs');
+  }
+
+  process.exit(0);
+}
+
+module.exports = { run };

package/bin/lib/commands/stop.js

@@ -0,0 +1,50 @@
+/**
+ * `claude-ws stop` — Stop the running daemon.
+ */
+
+const daemon = require('../daemon');
+
+async function run(_argv) {
+  const { running, pid } = daemon.checkRunning();
+
+  if (!running) {
+    console.log('[claude-ws] No running daemon found.');
+    process.exit(0);
+  }
+
+  console.log(`[claude-ws] Stopping daemon (PID ${pid})...`);
+
+  // Send SIGTERM
+  const sent = daemon.sendSignal(pid, 'SIGTERM');
+  if (!sent) {
+    console.log('[claude-ws] Failed to send SIGTERM — process may have already exited.');
+    daemon.removePid();
+    process.exit(0);
+  }
+
+  // Poll for exit (up to 10s)
+  const exited = await daemon.waitForExit(pid, 10000);
+
+  if (exited) {
+    daemon.removePid();
+    console.log('[claude-ws] Daemon stopped.');
+    process.exit(0);
+  }
+
+  // Force kill
+  console.log('[claude-ws] Daemon did not exit gracefully, sending SIGKILL...');
+  daemon.sendSignal(pid, 'SIGKILL');
+
+  const killed = await daemon.waitForExit(pid, 5000);
+  daemon.removePid();
+
+  if (killed) {
+    console.log('[claude-ws] Daemon killed.');
+  } else {
+    console.log(`[claude-ws] Warning: Process ${pid} may still be running.`);
+  }
+
+  process.exit(0);
+}
+
+module.exports = { run };

package/bin/lib/config.js

@@ -0,0 +1,93 @@
+/**
+ * Configuration loader for claude-ws daemon mode.
+ *
+ * Priority: CLI flags > env vars > config file > defaults.
+ * Config file: ~/.claude-ws/config.json
+ * PID file:    ~/.claude-ws/claude-ws.pid
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CLAUDE_WS_DIR = path.join(os.homedir(), '.claude-ws');
+const CONFIG_PATH = path.join(CLAUDE_WS_DIR, 'config.json');
+const PID_PATH = path.join(CLAUDE_WS_DIR, 'claude-ws.pid');
+
+const DEFAULTS = {
+  port: 8556,
+  host: 'localhost',
+  dataDir: path.join(CLAUDE_WS_DIR, 'data'),
+  logDir: path.join(CLAUDE_WS_DIR, 'logs'),
+};
+
+/**
+ * Ensure ~/.claude-ws/ directory exists.
+ */
+function ensureDir() {
+  if (!fs.existsSync(CLAUDE_WS_DIR)) {
+    fs.mkdirSync(CLAUDE_WS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load config file if it exists.
+ * @returns {object}
+ */
+function loadConfigFile() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return {};
+  }
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error(`[claude-ws] Warning: Failed to parse ${CONFIG_PATH}: ${err.message}`);
+    return {};
+  }
+}
+
+/**
+ * Resolve the final configuration by merging defaults, config file, env vars,
+ * and CLI flags (passed as an object).
+ *
+ * @param {object} [cliFlags={}] - Parsed CLI flags (e.g. { port: '3000', host: '0.0.0.0' })
+ * @returns {{ port: number, host: string, dataDir: string, logDir: string }}
+ */
+function resolve(cliFlags = {}) {
+  ensureDir();
+
+  const file = loadConfigFile();
+
+  const port = parseInt(
+    cliFlags.port || process.env.PORT || file.port || DEFAULTS.port,
+    10,
+  );
+
+  const host =
+    cliFlags.host || process.env.HOST || file.host || DEFAULTS.host;
+
+  const dataDir =
+    cliFlags['data-dir'] || process.env.DATA_DIR || file.dataDir || DEFAULTS.dataDir;
+
+  const logDir =
+    cliFlags['log-dir'] || process.env.LOG_DIR || file.logDir || DEFAULTS.logDir;
+
+  // Ensure log and data dirs exist
+  for (const dir of [dataDir, logDir]) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  return { port, host, dataDir, logDir };
+}
+
+module.exports = {
+  CLAUDE_WS_DIR,
+  CONFIG_PATH,
+  PID_PATH,
+  DEFAULTS,
+  ensureDir,
+  resolve,
+};