@surenkid/acli-hub 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surenkid/acli-hub",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Web workbench for AI CLIs — run Claude Code, Codex, Kimi and more in your browser (ttyd + tmux)",
   "license": "MIT",
   "bin": {

package/server/index.js

@@ -18,6 +18,14 @@ const authRoute = require('./routes/auth');
 const sessionsRoute = require('./routes/sessions');
 const filesRoute = require('./routes/files');
 const setupWebSocket = require('./ws');
+const { checkDependencies, dependencyReport } = require('./services/deps');
+
+// Fail fast with actionable install hints instead of a half-broken UI.
+const missingDependencies = checkDependencies();
+if (missingDependencies.length) {
+  console.error(dependencyReport(missingDependencies));
+  process.exit(1);
+}
 
 const PORT = parseInt(process.env.ACLI_HUB_PORT || '3000', 10);
 const HOST = process.env.ACLI_HUB_HOST || '127.0.0.1';

package/server/services/deps.js

@@ -0,0 +1,94 @@
+const { spawnSync } = require('child_process');
+
+// Homebrew paths are not always on PATH when the process is launched from a
+// GUI (Dock, Spotlight), so probe with the same augmentation SPAWN_ENV uses.
+const EXTRA_PATH = `/usr/local/bin:/opt/homebrew/bin:${process.env.PATH || ''}`;
+
+// Placeholder doc links — replace with the real FAQ pages when published.
+const DOCS = 'https://acli-hub.uum.cc/faq';
+
+const TOOLS = {
+  tmux: {
+    why: 'to keep terminal sessions alive across browser disconnects',
+    hints: [
+      'macOS:          brew install tmux',
+      'Debian/Ubuntu:  sudo apt install tmux',
+      'Fedora:         sudo dnf install tmux',
+      'Arch:           sudo pacman -S tmux',
+      'Alpine:         sudo apk add tmux',
+    ],
+    docs: `${DOCS}/install-tmux.html`,
+  },
+  ttyd: {
+    why: 'to stream the terminal into your browser',
+    hints: [
+      'macOS:          brew install ttyd',
+      'Debian/Ubuntu:  sudo apt install ttyd',
+      'any Linux:      sudo snap install ttyd --classic',
+      '                (or download a binary from https://github.com/tsl0922/ttyd/releases)',
+    ],
+    docs: `${DOCS}/install-ttyd.html`,
+  },
+};
+
+// A non-zero exit code still proves the binary exists — only a spawn error
+// (ENOENT, EACCES) counts as "not installed".
+function defaultProbe(tool, env) {
+  const args = tool === 'tmux' ? ['-V'] : ['--version'];
+  return { ok: !spawnSync(tool, args, { env, stdio: 'ignore' }).error };
+}
+
+function checkDependencies({ platform = process.platform, env = { ...process.env, PATH: EXTRA_PATH }, probe = defaultProbe } = {}) {
+  const missing = [];
+  for (const tool of Object.keys(TOOLS)) {
+    if (!probe(tool, env).ok) missing.push({ tool });
+  }
+  return missing;
+}
+
+// tmux has no native Windows build (its ncurses dependency is POSIX-only),
+// so any missing dependency on Windows gets one shared WSL walkthrough that
+// also covers the shell: the Ubuntu that wsl --install provides ships bash.
+function windowsReport() {
+  return [
+    '✖ Windows is not supported natively',
+    '',
+    '  ACLI Hub is built on tmux + ttyd + a POSIX shell, and tmux has no',
+    '  native Windows build. Run it inside WSL instead:',
+    '',
+    '    1. wsl --install                          (PowerShell as admin —',
+    '       installs Ubuntu, which already includes bash)',
+    '    2. inside WSL: sudo apt install tmux ttyd',
+    '    3. inside WSL: npm install -g @surenkid/acli-hub && acli-hub',
+    '',
+    '  Note: Git Bash alone is not enough — tmux cannot run outside WSL.',
+    '',
+    `  Full Windows guide: ${DOCS}/install-windows.html`,
+  ].join('\n');
+}
+
+// Claude-Code-style actionable error: what is missing, why it matters, the
+// shortest working command per platform, and where to read more. macOS users
+// only see the brew line; Linux keeps the whole distro family (the distro
+// itself is not probed, so all of apt/dnf/pacman/apk stay listed).
+function relevantHints(hints, platform) {
+  return platform === 'darwin' ? hints.filter(line => line.startsWith('macOS:')) : hints.filter(line => !line.startsWith('macOS:'));
+}
+
+function dependencyReport(missing, platform = process.platform) {
+  if (platform === 'win32') return windowsReport();
+  return missing.map(({ tool }) => {
+    const spec = TOOLS[tool];
+    return [
+      `✖ ${tool} is not installed`,
+      '',
+      `  ACLI Hub needs ${tool} ${spec.why}, but it wasn't found on your PATH.`,
+      '',
+      ...relevantHints(spec.hints, platform).map(line => `    ${line}`),
+      '',
+      `  Full install guide: ${spec.docs}`,
+    ].join('\n');
+  }).join('\n\n');
+}
+
+module.exports = { checkDependencies, dependencyReport };

package/server/services/deps.test.js

@@ -0,0 +1,46 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const { checkDependencies, dependencyReport } = require('./deps');
+
+const found = () => ({ ok: true });
+const notFound = () => ({ ok: false });
+
+test('nothing is reported when both tools probe successfully', () => {
+  assert.deepEqual(checkDependencies({ probe: found }), []);
+});
+
+test('a missing tool lists a complete set of per-platform quick installs', () => {
+  const missing = checkDependencies({ probe: tool => tool === 'ttyd' ? found() : notFound() });
+  assert.deepEqual(missing, [{ tool: 'tmux' }]);
+
+  const report = dependencyReport(missing, 'darwin');
+  assert.match(report, /✖ tmux is not installed/);
+  assert.match(report, /brew install tmux/);
+  assert.match(report, /Full install guide: https:\/\/acli-hub\.uum\.cc\/faq\/install-tmux\.html/);
+  assert.ok(!report.includes('apt'), 'darwin report should not suggest apt');
+});
+
+test('linux reports cover apt/dnf/pacman/apk, snap and the release binaries', () => {
+  const report = dependencyReport(checkDependencies({ probe: notFound }), 'linux');
+  assert.match(report, /✖ tmux is not installed/);
+  assert.match(report, /sudo apt install tmux/);
+  assert.match(report, /sudo dnf install tmux/);
+  assert.match(report, /sudo pacman -S tmux/);
+  assert.match(report, /sudo apk add tmux/);
+  assert.match(report, /✖ ttyd is not installed/);
+  assert.match(report, /sudo apt install ttyd/);
+  assert.match(report, /snap install ttyd --classic/);
+  assert.match(report, /github\.com\/tsl0922\/ttyd\/releases/);
+  assert.match(report, /install-ttyd\.html/);
+});
+
+test('any missing dependency on Windows collapses into one WSL walkthrough', () => {
+  const report = dependencyReport([{ tool: 'tmux' }], 'win32');
+  assert.match(report, /✖ Windows is not supported natively/);
+  assert.match(report, /wsl --install/);
+  assert.match(report, /sudo apt install tmux ttyd/);
+  assert.match(report, /includes bash/);
+  assert.match(report, /Git Bash alone is not enough/);
+  assert.match(report, /install-windows\.html/);
+  assert.ok(!report.includes('brew install'), 'windows report should not suggest brew');
+});