agim-cli 1.1.7 → 1.1.9

package/dist/core/tunnel.js

@@ -0,0 +1,151 @@
+// Tunnel — auto-launch cloudflared quick tunnel so operators without a
+// public DNS / reverse proxy can still receive viewer links in IM.
+//
+// Trade-off: quick tunnels are ephemeral. The URL is a random
+// `https://*.trycloudflare.com` reassigned per `cloudflared` process.
+// On agim restart, IM links generated before the restart become dead.
+// Operators who want stable URLs should configure
+// `IMHUB_VIEWER_PUBLIC_BASE_URL` to a reverse proxy (caddy / tailscale /
+// cloudflared named tunnel) instead — when that env is non-empty we
+// skip the auto-tunnel.
+//
+// We deliberately do NOT bundle cloudflared in the npm package (binary is
+// ~30 MB and architecture-specific). Operators install it themselves
+// (`brew install cloudflared` / `apt install cloudflared` / download from
+// https://github.com/cloudflare/cloudflared/releases). agim auto-detects
+// the binary on `start` and emits a friendly install hint if missing.
+import { spawn, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { logger as rootLogger } from './logger.js';
+const log = rootLogger.child({ component: 'tunnel' });
+const URL_RE = /https?:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+let proc = null;
+let currentUrl = null;
+let lastError = null;
+let lastStartAt = null;
+let restartTimer = null;
+/** Common locations where cloudflared may be installed. PATH is searched first. */
+const CANDIDATE_PATHS = [
+    '/usr/local/bin/cloudflared',
+    '/usr/bin/cloudflared',
+    '/opt/homebrew/bin/cloudflared',
+    '/root/.agim/bin/cloudflared',
+    `${process.env.HOME || ''}/.agim/bin/cloudflared`,
+];
+export function findCloudflared() {
+    // PATH first (so users who installed via package manager / homebrew "just work").
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const result = execSync(`${which} cloudflared`, {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+        }).trim();
+        if (result && existsSync(result.split('\n')[0])) {
+            return result.split('\n')[0];
+        }
+    }
+    catch {
+        // fall through
+    }
+    for (const p of CANDIDATE_PATHS) {
+        if (p && existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function getTunnelStatus() {
+    const bin = findCloudflared();
+    return {
+        running: proc !== null && !proc.killed,
+        url: currentUrl,
+        binaryFound: bin !== null,
+        binaryPath: bin,
+        lastError,
+        startedAt: lastStartAt,
+    };
+}
+/**
+ * Start a cloudflared quick tunnel pointing at the given local port. Idempotent
+ * — if a tunnel is already running, returns immediately. The function resolves
+ * as soon as the child is spawned; the URL is captured asynchronously from
+ * stderr and made available via getTunnelStatus().
+ *
+ * Throws if cloudflared isn't installed (so the caller can surface the install
+ * hint to the operator).
+ */
+export function startTunnel(localPort) {
+    if (proc && !proc.killed) {
+        log.debug({ event: 'tunnel.already_running', url: currentUrl }, 'tunnel already running');
+        return;
+    }
+    const bin = findCloudflared();
+    if (!bin) {
+        lastError = 'cloudflared binary not found in PATH; install from https://github.com/cloudflare/cloudflared/releases or via your OS package manager';
+        log.warn({ event: 'tunnel.binary_missing', candidates: CANDIDATE_PATHS }, lastError);
+        return;
+    }
+    const localUrl = `http://127.0.0.1:${localPort}`;
+    log.info({ event: 'tunnel.start', binary: bin, localUrl }, `starting cloudflared quick tunnel → ${localUrl}`);
+    proc = spawn(bin, [
+        'tunnel',
+        '--url', localUrl,
+        '--no-autoupdate',
+        // Quick tunnels: no login, no zone — gives us a random trycloudflare.com URL.
+        // Logging goes to stderr by default; we tap it to extract the URL.
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: false,
+    });
+    lastStartAt = Date.now();
+    lastError = null;
+    currentUrl = null;
+    const captureFromChunk = (chunk) => {
+        const text = chunk.toString('utf8');
+        const m = URL_RE.exec(text);
+        if (m && !currentUrl) {
+            currentUrl = m[0].replace(/\/$/, '');
+            log.info({ event: 'tunnel.url_acquired', url: currentUrl }, `tunnel URL: ${currentUrl}`);
+        }
+        // cloudflared echoes its own status to stderr; surface ERR lines to our log.
+        if (/error|failed|refused/i.test(text)) {
+            log.warn({ event: 'tunnel.stderr', text: text.trim().slice(0, 400) });
+        }
+    };
+    proc.stderr?.on('data', captureFromChunk);
+    proc.stdout?.on('data', captureFromChunk);
+    proc.on('exit', (code, signal) => {
+        log.warn({ event: 'tunnel.exit', code, signal, url: currentUrl }, `cloudflared exited (code=${code}, signal=${signal})`);
+        const wasUrl = currentUrl;
+        proc = null;
+        currentUrl = null;
+        lastError = `cloudflared exited (code=${code}${signal ? `, signal=${signal}` : ''})`;
+        // Auto-restart on non-clean exit so a brief network blip doesn't kill the
+        // tunnel for the rest of the agim process lifetime. 30s cooldown.
+        if (signal !== 'SIGTERM' && signal !== 'SIGINT') {
+            restartTimer = setTimeout(() => {
+                log.info({ event: 'tunnel.auto_restart', previousUrl: wasUrl }, 'auto-restarting tunnel');
+                startTunnel(localPort);
+            }, 30_000);
+        }
+    });
+    proc.on('error', (err) => {
+        lastError = `spawn failed: ${err.message}`;
+        log.error({ event: 'tunnel.spawn_error', err: err.message });
+    });
+}
+export function stopTunnel() {
+    if (restartTimer) {
+        clearTimeout(restartTimer);
+        restartTimer = null;
+    }
+    if (proc && !proc.killed) {
+        log.info({ event: 'tunnel.stop' });
+        proc.kill('SIGTERM');
+        proc = null;
+        currentUrl = null;
+    }
+}
+export function getCurrentTunnelUrl() {
+    return currentUrl;
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/core/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../../src/core/tunnel.ts"],"names":[],"mappings":"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"}

package/dist/core/viewer-config.d.ts

@@ -1,4 +1,5 @@
 import { type ViewerThresholds } from './render-router.js';
+export type ViewerTunnelMode = 'off' | 'quick';
 export interface ViewerConfig {
     /** Master switch. When false, all replies are sent inline regardless of length. */
     enabled: boolean;
@@ -9,10 +10,26 @@ export interface ViewerConfig {
      * IM clients on phones will obviously not be able to open it.
      */
     publicBaseUrl: string;
+    /**
+     * Auto-tunnel mode for operators without a public URL.
+     *   - 'off'   (default): use publicBaseUrl as-is.
+     *   - 'quick': launch cloudflared quick tunnel on startup; URL is
+     *              `https://*.trycloudflare.com` and changes per agim restart.
+     */
+    tunnelMode: ViewerTunnelMode;
     /** Char / line / code-block thresholds for routing to web. */
     thresholds: ViewerThresholds;
 }
 export declare function getViewerConfig(): ViewerConfig;
+/**
+ * Resolve the effective public base URL. Order of preference:
+ *   1. Explicit IMHUB_VIEWER_PUBLIC_BASE_URL (operator-managed reverse proxy)
+ *   2. Auto-tunnel URL if tunnel_mode=quick and cloudflared has acquired a URL
+ *   3. Caller-supplied fallback
+ *
+ * Returns empty string when nothing usable is available.
+ */
+export declare function getEffectivePublicBaseUrl(fallback?: string): string;
 /**
  * Build the URL placed in the IM reply for a saved paste. Returns null if
  * no public base URL is configured AND no fallback was provided. Caller

package/dist/core/viewer-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewer-config.d.ts","sourceRoot":"","sources":["../../src/core/viewer-config.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE9E,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,UAAU,EAAE,gBAAgB,CAAA;CAC7B;AAQD,wBAAgB,eAAe,IAAI,YAAY,CAa9C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKjF"}
+{"version":3,"file":"viewer-config.d.ts","sourceRoot":"","sources":["../../src/core/viewer-config.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAG9E,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,CAAA;AAE9C,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,UAAU,EAAE,gBAAgB,CAAA;IAC5B,8DAA8D;IAC9D,UAAU,EAAE,gBAAgB,CAAA;CAC7B;AAQD,wBAAgB,eAAe,IAAI,YAAY,CAgB9C;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIjF"}

package/dist/core/viewer-config.js

@@ -4,6 +4,7 @@
 // base URL + an enable flag), and the defaults handle everything else. No
 // JSON-config schema dance, no on-disk state — change env, restart, done.
 import { DEFAULT_THRESHOLDS } from './render-router.js';
+import { getCurrentTunnelUrl } from './tunnel.js';
 function parsePositiveInt(raw, fallback) {
     if (!raw)
         return fallback;
@@ -14,9 +15,12 @@ export function getViewerConfig() {
     const enabledRaw = (process.env.IMHUB_VIEWER_ENABLED || '').toLowerCase();
     const enabled = enabledRaw === '1' || enabledRaw === 'true' || enabledRaw === 'yes';
     const publicBaseUrl = (process.env.IMHUB_VIEWER_PUBLIC_BASE_URL || '').replace(/\/$/, '');
+    const tunnelModeRaw = (process.env.IMHUB_VIEWER_TUNNEL_MODE || 'off').toLowerCase();
+    const tunnelMode = tunnelModeRaw === 'quick' ? 'quick' : 'off';
     return {
         enabled,
         publicBaseUrl,
+        tunnelMode,
         thresholds: {
             chars: parsePositiveInt(process.env.IMHUB_VIEWER_CHARS, DEFAULT_THRESHOLDS.chars),
             lines: parsePositiveInt(process.env.IMHUB_VIEWER_LINES, DEFAULT_THRESHOLDS.lines),
@@ -24,14 +28,32 @@ export function getViewerConfig() {
         },
     };
 }
+/**
+ * Resolve the effective public base URL. Order of preference:
+ *   1. Explicit IMHUB_VIEWER_PUBLIC_BASE_URL (operator-managed reverse proxy)
+ *   2. Auto-tunnel URL if tunnel_mode=quick and cloudflared has acquired a URL
+ *   3. Caller-supplied fallback
+ *
+ * Returns empty string when nothing usable is available.
+ */
+export function getEffectivePublicBaseUrl(fallback) {
+    const cfg = getViewerConfig();
+    if (cfg.publicBaseUrl)
+        return cfg.publicBaseUrl;
+    if (cfg.tunnelMode === 'quick') {
+        const tu = getCurrentTunnelUrl();
+        if (tu)
+            return tu;
+    }
+    return (fallback || '').replace(/\/$/, '');
+}
 /**
  * Build the URL placed in the IM reply for a saved paste. Returns null if
  * no public base URL is configured AND no fallback was provided. Caller
  * should treat null as "viewer can't produce a usable link — degrade".
  */
 export function buildPasteUrl(id, fallbackBaseUrl) {
-    const cfg = getViewerConfig();
-    const base = cfg.publicBaseUrl || fallbackBaseUrl || '';
+    const base = getEffectivePublicBaseUrl(fallbackBaseUrl);
     if (!base)
         return null;
     return `${base.replace(/\/$/, '')}/v/${id}`;

package/dist/core/viewer-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"viewer-config.js","sourceRoot":"","sources":["../../src/core/viewer-config.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAE1E,OAAO,EAAE,kBAAkB,EAAyB,MAAM,oBAAoB,CAAA;AAgB9E,SAAS,gBAAgB,CAAC,GAAuB,EAAE,QAAgB;IACjE,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAA;IACzB,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AACnD,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IACzE,MAAM,OAAO,GAAG,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,KAAK,CAAA;IACnF,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACzF,OAAO;QACL,OAAO;QACP,aAAa;QACb,UAAU,EAAE;YACV,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,KAAK,CAAC;YACjF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,KAAK,CAAC;YACjF,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,SAAS,CAAC;SAC/F;KACF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,eAAwB;IAChE,MAAM,GAAG,GAAG,eAAe,EAAE,CAAA;IAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,eAAe,IAAI,EAAE,CAAA;IACvD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAA;AAC7C,CAAC"}
+{"version":3,"file":"viewer-config.js","sourceRoot":"","sources":["../../src/core/viewer-config.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAE1E,OAAO,EAAE,kBAAkB,EAAyB,MAAM,oBAAoB,CAAA;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAyBjD,SAAS,gBAAgB,CAAC,GAAuB,EAAE,QAAgB;IACjE,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAA;IACzB,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AACnD,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IACzE,MAAM,OAAO,GAAG,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,KAAK,CAAA;IACnF,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACzF,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IACnF,MAAM,UAAU,GAAqB,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;IAChF,OAAO;QACL,OAAO;QACP,aAAa;QACb,UAAU;QACV,UAAU,EAAE;YACV,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,KAAK,CAAC;YACjF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,KAAK,CAAC;YACjF,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,SAAS,CAAC;SAC/F;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAiB;IACzD,MAAM,GAAG,GAAG,eAAe,EAAE,CAAA;IAC7B,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,GAAG,CAAC,aAAa,CAAA;IAC/C,IAAI,GAAG,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,mBAAmB,EAAE,CAAA;QAChC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAA;IACnB,CAAC;IACD,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,eAAwB;IAChE,MAAM,IAAI,GAAG,yBAAyB,CAAC,eAAe,CAAC,CAAA;IACvD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAA;AAC7C,CAAC"}

package/dist/web/public/settings.html

@@ -168,6 +168,16 @@
         viewerSaved: 'Saved — change takes effect on the next reply.',
         viewerSaveFailed: 'Failed to save viewer settings',
         viewerMissingUrl: '⚠️ Public URL is empty — Agim will fall back to inline text for long replies (no link can be built).',
+        viewerTunnelMode: 'Auto-tunnel (cloudflared)',
+        viewerTunnelHint: 'For users without a public domain. Agim launches a cloudflared quick tunnel on startup and auto-detects a temporary `*.trycloudflare.com` URL. Requires the `cloudflared` binary to be installed (`brew install cloudflared` / `apt install cloudflared`). URL changes per restart — old paste links die. Leave off when you have a static reverse proxy.',
+        viewerTunnelOff: 'Off (use Public URL above)',
+        viewerTunnelQuick: 'Quick tunnel (temporary URL, no domain needed)',
+        viewerTunnelStatus: 'Tunnel status',
+        viewerTunnelRunning: 'Running',
+        viewerTunnelNotRunning: 'Not running',
+        viewerTunnelBinaryMissing: 'cloudflared not installed',
+        viewerTunnelCurrentUrl: 'Current URL',
+        viewerTunnelRefresh: 'Refresh',
       },
       zh: {
         title: 'Agim — 设置',
@@ -322,6 +332,16 @@
         viewerSaved: '已保存 — 下一条回复生效。',
         viewerSaveFailed: '保存 Viewer 配置失败',
         viewerMissingUrl: '⚠️ 公网域名为空 — 长回复将退回到内联文本（无法构造跳转链接）。',
+        viewerTunnelMode: '自动 tunnel（cloudflared）',
+        viewerTunnelHint: '给没有公网域名的用户。Agim 启动时自动拉起 cloudflared quick tunnel，拿一个临时 `*.trycloudflare.com` URL。需要先装 `cloudflared`（`brew install cloudflared` / `apt install cloudflared`）。**重启后 URL 会变，旧 paste 链接打不开**。有反代域名的话保持关闭即可。',
+        viewerTunnelOff: '关闭（用上面的公网域名）',
+        viewerTunnelQuick: 'Quick tunnel（临时 URL，无需域名）',
+        viewerTunnelStatus: 'Tunnel 状态',
+        viewerTunnelRunning: '运行中',
+        viewerTunnelNotRunning: '未运行',
+        viewerTunnelBinaryMissing: '未安装 cloudflared',
+        viewerTunnelCurrentUrl: '当前 URL',
+        viewerTunnelRefresh: '刷新',
       },
     };
     function t(key) { return T[window.__lang][key] || T.en[key] || key; }
@@ -1419,6 +1439,18 @@
           <input type="text" id="viewerPublicUrl" placeholder="https://agim.example.com" style="max-width:480px" />
           <p class="muted" style="margin-top:4px;font-size:12px">${t('viewerPublicUrlHint')}</p>
 
+          <label style="margin-top:12px;display:block">${t('viewerTunnelMode')}</label>
+          <select id="viewerTunnelMode" style="max-width:480px">
+            <option value="off">${t('viewerTunnelOff')}</option>
+            <option value="quick">${t('viewerTunnelQuick')}</option>
+          </select>
+          <p class="muted" style="margin-top:4px;font-size:12px">${t('viewerTunnelHint')}</p>
+          <div id="viewerTunnelStatusBox" style="margin-top:6px;padding:8px 10px;border:1px solid var(--border, #d0d7de);border-radius:6px;font-size:12px;display:none">
+            <div><strong>${t('viewerTunnelStatus')}:</strong> <span id="viewerTunnelState">—</span></div>
+            <div style="margin-top:4px"><strong>${t('viewerTunnelCurrentUrl')}:</strong> <code id="viewerTunnelCurrentUrl" style="word-break:break-all">—</code></div>
+            <button type="button" class="btn" id="viewerTunnelRefreshBtn" style="margin-top:6px;padding:4px 10px;font-size:12px">${t('viewerTunnelRefresh')}</button>
+          </div>
+
           <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));gap:12px;margin-top:12px;max-width:720px">
             <div>
               <label>${t('viewerChars')}</label>
@@ -1462,6 +1494,32 @@
       `;
     }
 
+    async function refreshViewerTunnelStatus() {
+      const stateEl = document.getElementById('viewerTunnelState');
+      const urlEl = document.getElementById('viewerTunnelCurrentUrl');
+      if (!stateEl || !urlEl) return;
+      stateEl.textContent = '…';
+      urlEl.textContent = '—';
+      try {
+        const data = await authFetch('/api/viewer/tunnel').then(r => r.json());
+        const tun = data && data.tunnel ? data.tunnel : {};
+        if (!tun.binaryFound) {
+          stateEl.textContent = t('viewerTunnelBinaryMissing');
+          stateEl.style.color = '#c0392b';
+        } else if (tun.running) {
+          stateEl.textContent = '✓ ' + t('viewerTunnelRunning');
+          stateEl.style.color = '#16a34a';
+        } else {
+          stateEl.textContent = t('viewerTunnelNotRunning');
+          stateEl.style.color = '';
+        }
+        urlEl.textContent = tun.url || (data && data.effectivePublicUrl) || '—';
+      } catch (err) {
+        stateEl.textContent = 'error';
+        urlEl.textContent = (err && err.message) || String(err);
+      }
+    }
+
     async function loadEnvSection(reveal) {
       try {
         const url = reveal ? '/api/env?reveal=1' : '/api/env';
@@ -1490,6 +1548,16 @@
         set('viewerLines', 'IMHUB_VIEWER_LINES');
         set('viewerCodeLines', 'IMHUB_VIEWER_CODE_LINES');
         set('viewerMaxPastes', 'IMHUB_VIEWER_MAX_PASTES');
+        const vTunnelMode = document.getElementById('viewerTunnelMode');
+        if (vTunnelMode) {
+          vTunnelMode.value = (env['IMHUB_VIEWER_TUNNEL_MODE'] || 'off').toLowerCase() === 'quick' ? 'quick' : 'off';
+        }
+        // Show tunnel status panel only when tunnel mode = quick.
+        const tunnelBox = document.getElementById('viewerTunnelStatusBox');
+        if (tunnelBox) {
+          tunnelBox.style.display = (vTunnelMode && vTunnelMode.value === 'quick') ? 'block' : 'none';
+          if (vTunnelMode && vTunnelMode.value === 'quick') void refreshViewerTunnelStatus();
+        }
         const viewerStatus = document.getElementById('viewerStatus');
         if (viewerStatus) {
           if (!env['IMHUB_VIEWER_PUBLIC_BASE_URL']) {
@@ -1801,6 +1869,13 @@
       });
       document.getElementById('revealBaidu')?.addEventListener('click', () => loadEnvSection(true));
 
+      // Tunnel mode dropdown — show/hide status panel on change.
+      document.getElementById('viewerTunnelMode')?.addEventListener('change', (e) => {
+        const box = document.getElementById('viewerTunnelStatusBox');
+        if (box) box.style.display = e.target.value === 'quick' ? 'block' : 'none';
+      });
+      document.getElementById('viewerTunnelRefreshBtn')?.addEventListener('click', () => refreshViewerTunnelStatus());
+
       // Viewer card — save toggle + URL + thresholds in one round-trip.
       document.getElementById('saveViewer')?.addEventListener('click', async () => {
         const enabled = document.getElementById('viewerEnabled')?.checked ? '1' : '0';
@@ -1809,6 +1884,7 @@
         const lines = (document.getElementById('viewerLines')?.value || '').trim();
         const codeLines = (document.getElementById('viewerCodeLines')?.value || '').trim();
         const maxPastes = (document.getElementById('viewerMaxPastes')?.value || '').trim();
+        const tunnelMode = document.getElementById('viewerTunnelMode')?.value || 'off';
         const status = document.getElementById('viewerStatus');
         try {
           await authFetch('/api/env', {
@@ -1822,6 +1898,7 @@
                 IMHUB_VIEWER_LINES: lines || null,
                 IMHUB_VIEWER_CODE_LINES: codeLines || null,
                 IMHUB_VIEWER_MAX_PASTES: maxPastes || null,
+                IMHUB_VIEWER_TUNNEL_MODE: tunnelMode || 'off',
               },
             }),
           });

package/dist/web/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/web/server.ts"],"names":[],"mappings":"AAsDA,wBAAgB,iBAAiB,IAAI,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAOrE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA+rB/C"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/web/server.ts"],"names":[],"mappings":"AAsDA,wBAAgB,iBAAiB,IAAI,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAOrE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAksB/C"}

package/dist/web/server.js

@@ -412,6 +412,9 @@ export async function startWebServer(options) {
         if (url.pathname === '/api/viewer' && req.method === 'GET') {
             return handleViewerList(req, res, url);
         }
+        if (url.pathname === '/api/viewer/tunnel' && req.method === 'GET') {
+            return handleViewerTunnelStatus(req, res);
+        }
         const viewerIdMatch = url.pathname.match(/^\/api\/viewer\/([0-9a-f-]{8,})$/i);
         if (viewerIdMatch && req.method === 'GET') {
             return handleViewerGet(req, res, viewerIdMatch[1]);
@@ -1640,6 +1643,7 @@ const ENV_EDITABLE_KEYS = [
     'IMHUB_VIEWER_LINES',
     'IMHUB_VIEWER_CODE_LINES',
     'IMHUB_VIEWER_MAX_PASTES',
+    'IMHUB_VIEWER_TUNNEL_MODE',
 ];
 const SECRET_KEYS = new Set(['IMHUB_SMTP_PASS', 'IMHUB_BAIDU_MAP_AK']);
 function maskSecret(v) {
@@ -2786,6 +2790,19 @@ async function handleViewerDelete(_req, res, id) {
     }
     sendJson(res, 200, { ok: true });
 }
+async function handleViewerTunnelStatus(_req, res) {
+    const { getTunnelStatus } = await import('../core/tunnel.js');
+    const { getViewerConfig, getEffectivePublicBaseUrl } = await import('../core/viewer-config.js');
+    const cfg = getViewerConfig();
+    const tunnel = getTunnelStatus();
+    sendJson(res, 200, {
+        enabled: cfg.enabled,
+        tunnelMode: cfg.tunnelMode,
+        staticPublicUrl: cfg.publicBaseUrl,
+        effectivePublicUrl: getEffectivePublicBaseUrl(),
+        tunnel,
+    });
+}
 // ============================================
 // WebSocket chat handlers
 // ============================================