@surenkid/acli-hub 1.0.1 → 1.0.3

package/.env.example

@@ -1,19 +1,21 @@
 # Main server port (backend + built frontend in production)
-PORT=3000
-HOST=0.0.0.0
+ACLI_HUB_PORT=3000
+# Bind address — default 127.0.0.1 (local only). Use 0.0.0.0 for LAN/remote access,
+# and ALWAYS set ACLI_HUB_AUTH_PASSWORD when binding beyond loopback.
+#ACLI_HUB_HOST=0.0.0.0
 
 # Internal ttyd port range (localhost only, proxied through the main port)
-TTYD_PORT_RANGE_START=7681
-TTYD_PORT_RANGE_END=7780
+ACLI_HUB_TTYD_PORT_RANGE_START=7681
+ACLI_HUB_TTYD_PORT_RANGE_END=7780
 
 # Maximum size per uploaded file, in MiB. 0 = unlimited.
-UPLOAD_MAX_MB=500
+ACLI_HUB_UPLOAD_MAX_MB=500
 
 # Login password for the web UI. Leave UNSET to disable authentication
 # (local development). Generate a strong one with: openssl rand -base64 24
 # When set, all pages/API/terminal/WebSocket access requires a 7-day
 # login session (cookie).
-AUTH_PASSWORD=
+ACLI_HUB_AUTH_PASSWORD=
 
 # Config locations (cwd is never read): ~/.config/acli-hub/.env for the installed CLI
 # ($XDG_CONFIG_HOME respected); the repo root .env when running from source.

package/README.md

@@ -56,26 +56,26 @@ brew install ttyd tmux
 ## 🚀 快速开始
 
 ```bash
-# 安装依赖
-npm install
-cd frontend && npm install && cd ..
-
-# 构建前端
-npm run build
-
-# 启动服务
-npm start
+npm install -g @surenkid/acli-hub
+acli-hub
 ```
 
-浏览器打开 `http://localhost:3000` 即可使用。
+浏览器打开 `http://localhost:3000` 即可使用。登录密码等配置放在 `~/.config/acli-hub/.env`（模板见下方配置项）。
+
+> 也可以免安装直接体验：`npx @surenkid/acli-hub`
 
-## 👨‍💻 开发模式
+## 👨‍💻 从源码运行
 
 ```bash
-npm run dev
-```
+git clone https://cnb.cool/surenkid/acli-hub.git
+cd acli-hub
+npm install
+cd frontend && npm install && cd ..
 
-同时启动后端（端口 3000）和 Vite 开发服务器（端口 5173）。
+npm run dev    # 开发模式：后端 3000 + Vite 5173（热更新）
+# 或构建生产版运行
+npm run build && npm start
+```
 
 ## ⚙️ 配置项
 
@@ -88,14 +88,14 @@ npm run dev
 
 配置项：
 
-| 变量                    | 说明                                       | 默认值    |
-| ----------------------- | ------------------------------------------ | --------- |
-| `PORT`                  | 服务监听端口                               | `3000`    |
-| `HOST`                  | 监听地址                                   | `0.0.0.0` |
-| `AUTH_PASSWORD`         | 登录密码；不设置则关闭认证（仅限本地开发） | _(不设置)_ |
-| `TTYD_PORT_RANGE_START` | ttyd 内部端口范围起始                      | `7681`    |
-| `TTYD_PORT_RANGE_END`   | ttyd 内部端口范围结束                      | `7780`    |
-| `UPLOAD_MAX_MB`         | 单文件上传上限（MiB），0 为不限            | `500`     |
+| 变量                            | 说明                                       | 默认值    |
+| ------------------------------- | ------------------------------------------ | --------- |
+| `ACLI_HUB_PORT`                 | 服务监听端口                               | `3000`    |
+| `ACLI_HUB_HOST`                 | 监听地址；默认仅本机，局域网访问设 `0.0.0.0`（务必同时设密码） | `127.0.0.1` |
+| `ACLI_HUB_AUTH_PASSWORD`        | 登录密码；不设置则关闭认证（仅限本地开发） | _(不设置)_ |
+| `ACLI_HUB_TTYD_PORT_RANGE_START` | ttyd 内部端口范围起始                     | `7681`    |
+| `ACLI_HUB_TTYD_PORT_RANGE_END`   | ttyd 内部端口范围结束                     | `7780`    |
+| `ACLI_HUB_UPLOAD_MAX_MB`        | 单文件上传上限（MiB），0 为不限            | `500`     |
 
 ### 📁 文件面板说明
 
@@ -105,7 +105,7 @@ npm run dev
 
 ### 🔐 公网暴露
 
-设置 `AUTH_PASSWORD` 后，建议将 ACLI Hub 部署在 HTTPS 反向代理（如 Caddy / Nginx / frp）之后，只公开 443 端口。登录会话为 7 天有效的 HttpOnly Cookie，终端 iframe 与 WebSocket 均受同一凭据保护。
+设置 `ACLI_HUB_AUTH_PASSWORD` 后，建议将 ACLI Hub 部署在 HTTPS 反向代理（如 Caddy / Nginx / frp）之后，只公开 443 端口。登录会话为 7 天有效的 HttpOnly Cookie，终端 iframe 与 WebSocket 均受同一凭据保护。
 
 ## 📄 License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surenkid/acli-hub",
-  "version": "1.0.1",
+  "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,11 +18,19 @@ 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');
 
-const PORT = parseInt(process.env.PORT || '3000', 10);
-const HOST = process.env.HOST || '0.0.0.0';
-const TTYD_PORT_START = parseInt(process.env.TTYD_PORT_RANGE_START || '7681', 10);
-const TTYD_PORT_END = parseInt(process.env.TTYD_PORT_RANGE_END || '7780', 10);
+// 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';
+const TTYD_PORT_START = parseInt(process.env.ACLI_HUB_TTYD_PORT_RANGE_START || '7681', 10);
+const TTYD_PORT_END = parseInt(process.env.ACLI_HUB_TTYD_PORT_RANGE_END || '7780', 10);
 
 const app = express();
 const server = http.createServer(app);
@@ -34,7 +42,7 @@ app.use((req, res, next) => {
 });
 
 const sessionManager = new SessionManager(TTYD_PORT_START, TTYD_PORT_END);
-const auth = new AuthService(process.env.AUTH_PASSWORD);
+const auth = new AuthService(process.env.ACLI_HUB_AUTH_PASSWORD);
 
 function requireAuth(req, res, next) {
   if (!auth.isEnabled()) return next();
@@ -130,7 +138,7 @@ server.listen(PORT, HOST, async () => {
   if (auth.isEnabled()) {
     console.log('Auth enabled: login required (sessions last 7 days)');
   } else {
-    console.warn('WARNING: AUTH_PASSWORD is not set — running WITHOUT authentication. Do not expose this to the internet.');
+    console.warn('WARNING: ACLI_HUB_AUTH_PASSWORD is not set — running WITHOUT authentication. Do not expose this to the internet.');
   }
   const restored = await sessionManager.restore();
   if (restored.length > 0) {

package/server/routes/files.js

@@ -69,10 +69,10 @@ function respondError(res, err) {
   res.status(status).json({ error: err.message });
 }
 
-module.exports = function filesRoute({ platform = process.platform, home = os.homedir(), uploadMaxMb = process.env.UPLOAD_MAX_MB ?? '500' } = {}) {
+module.exports = function filesRoute({ platform = process.platform, home = os.homedir(), uploadMaxMb = process.env.ACLI_HUB_UPLOAD_MAX_MB ?? '500' } = {}) {
   const router = express.Router();
   const maximum = Number(uploadMaxMb);
-  if (!Number.isFinite(maximum) || maximum < 0) throw new Error('UPLOAD_MAX_MB must be a non-negative number');
+  if (!Number.isFinite(maximum) || maximum < 0) throw new Error('ACLI_HUB_UPLOAD_MAX_MB must be a non-negative number');
   const uploadLimit = maximum * 1024 * 1024;
   const trash = platform === 'darwin' ? 'mv-trash' : 'rm';
   // Serialize app mutations so concurrent renames/trash moves cannot overwrite

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');
+});