From dcc67477ecdc1166413236d434fbb9485f9d9e27 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 17 Mar 2026 09:54:07 -0400 Subject: [PATCH] fix: align dashboard host warnings with effective bind --- README.md | 11 +- docs/dashboard-auth-cli.md | 2 +- src/commands/config-command-options.ts | 9 +- src/commands/config-command.ts | 50 +++-- src/commands/config-dashboard-host.ts | 51 +++-- src/commands/help-command.ts | 2 +- src/web-server/index.ts | 51 ++++- .../commands/config-command-options.test.ts | 18 +- tests/unit/commands/config-command.test.ts | 185 ++++++++++++++++++ .../commands/config-dashboard-host.test.ts | 34 +++- .../unit/commands/help-command-parity.test.ts | 2 +- .../unit/web-server/start-server-host.test.ts | 8 + ui/README.md | 9 +- 13 files changed, 385 insertions(+), 47 deletions(-) create mode 100644 tests/unit/commands/config-command.test.ts diff --git a/README.md b/README.md index 43e5944e..69391b4f 100644 --- a/README.md +++ b/README.md @@ -50,18 +50,23 @@ bun add -g @kaitranntt/ccs # bun (30x faster) ```bash ccs config -# Opens a local browser URL and prints bind/network details +# Opens a local browser URL ``` -Expose the dashboard to another device on your network: +CCS uses the runtime's system-default bind. If that bind is reachable beyond loopback, +the CLI also prints bind/network details plus an auth reminder. + +Force all-interface binding for remote devices: ```bash ccs config --host 0.0.0.0 -# Terminal prints the LAN URL to open from the other device +# Terminal prints the reachable URLs to open from the other device ``` If you expose the dashboard beyond localhost, protect it first with `ccs config auth setup`. +Use `ccs config --host 127.0.0.1` to force local-only binding. + Dashboard updates hub: `http://localhost:3000/updates` Want to run the dashboard in Docker or pull the prebuilt image? See `docker/README.md`. diff --git a/docs/dashboard-auth-cli.md b/docs/dashboard-auth-cli.md index 7fa33a64..df381442 100644 --- a/docs/dashboard-auth-cli.md +++ b/docs/dashboard-auth-cli.md @@ -6,7 +6,7 @@ CLI commands for managing CCS dashboard authentication. ## Overview -The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful when running the dashboard on a network-accessible machine or when starting it with `ccs config --host 0.0.0.0`. +The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful whenever the dashboard is reachable from another device, including when the runtime's default bind is network-accessible or when you explicitly bind it beyond loopback with `ccs config --host 0.0.0.0`. Authentication is **disabled by default** for backward compatibility. Use the CLI to configure and enable it. diff --git a/src/commands/config-command-options.ts b/src/commands/config-command-options.ts index c4084ef0..100f7076 100644 --- a/src/commands/config-command-options.ts +++ b/src/commands/config-command-options.ts @@ -1,12 +1,10 @@ import { extractOption, hasAnyFlag } from './arg-extractor'; -export const DEFAULT_DASHBOARD_HOST = '0.0.0.0'; - const CONFIG_COMMAND_FLAGS = ['--help', '-h', '--port', '-p', '--host', '-H', '--dev'] as const; export interface ConfigCommandOptions { port?: number; - host: string; + host?: string; hostProvided: boolean; dev: boolean; } @@ -19,7 +17,6 @@ export interface ConfigCommandParseResult { export function parseConfigCommandArgs(args: string[]): ConfigCommandParseResult { const options: ConfigCommandOptions = { - host: DEFAULT_DASHBOARD_HOST, hostProvided: false, dev: false, }; @@ -96,14 +93,14 @@ export function showConfigCommandHelp(): void { console.log(''); console.log('Options:'); console.log(' --port, -p PORT Specify server port (default: auto-detect)'); - console.log(' --host, -H HOST Bind dashboard server host (default: 0.0.0.0)'); + console.log(' --host, -H HOST Bind dashboard server host (default: system default)'); console.log(' --dev Development mode with Vite HMR'); console.log(' --help, -h Show this help message'); console.log(''); console.log('Examples:'); console.log(' ccs config Auto-detect available port'); console.log(' ccs config --port 3000 Use specific port'); - console.log(' ccs config --host 0.0.0.0 Show dashboard on your LAN'); + console.log(' ccs config --host 0.0.0.0 Force all-interface binding for remote devices'); console.log(' ccs config --host 127.0.0.1 Restrict dashboard to this machine'); console.log(' ccs config --dev Development mode with hot reload'); console.log(' ccs config auth setup Configure dashboard login'); diff --git a/src/commands/config-command.ts b/src/commands/config-command.ts index 5a9a2262..87afcdd5 100644 --- a/src/commands/config-command.ts +++ b/src/commands/config-command.ts @@ -14,7 +14,12 @@ import { ensureCliproxyService } from '../cliproxy/service-manager'; import { CLIPROXY_DEFAULT_PORT } from '../cliproxy/config-generator'; import { getDashboardAuthConfig } from '../config/unified-config-loader'; import { initUI, header, ok, info, warn, fail } from '../utils/ui'; -import { isLoopbackHost, resolveDashboardUrls } from './config-dashboard-host'; +import { + isLoopbackHost, + isWildcardHost, + normalizeDashboardHost, + resolveDashboardUrls, +} from './config-dashboard-host'; import { parseConfigCommandArgs, showConfigCommandHelp } from './config-command-options'; /** @@ -90,16 +95,21 @@ export async function handleConfigCommand(args: string[]): Promise { try { // Start server - const { server, wss, cleanup } = await startServer({ + const serverOptions: Parameters[0] = { port, - host: options.host, dev: options.dev, - }); + }; + if (options.hostProvided && options.host) { + serverOptions.host = normalizeDashboardHost(options.host); + } + + const { server, wss, cleanup } = await startServer(serverOptions); // Setup graceful shutdown setupGracefulShutdown(server, wss, cleanup); - const urls = resolveDashboardUrls(options.host, port); + const urls = resolveDashboardUrls(resolveServerBindHost(server) ?? options.host, port); + const shouldWarnAboutExposure = urls.bindHost ? !isLoopbackHost(urls.bindHost) : false; if (options.dev) { console.log(ok(`Dev Server: ${urls.browserUrl}`)); @@ -109,20 +119,27 @@ export async function handleConfigCommand(args: string[]): Promise { console.log(ok(`Dashboard: ${urls.browserUrl}`)); } - if (!isLoopbackHost(urls.bindHost)) { + if (shouldWarnAboutExposure && urls.bindHost) { console.log(info(`Bind host: ${urls.bindHost}`)); - if (urls.networkUrl) { - console.log(info(`Network URL: ${urls.networkUrl}`)); + if (urls.networkUrls?.length === 1) { + console.log(info(`Network URL: ${urls.networkUrls[0]}`)); + } else if (urls.networkUrls && urls.networkUrls.length > 1) { + console.log(info('Network URLs:')); + for (const networkUrl of urls.networkUrls) { + console.log(info(` ${networkUrl}`)); + } } } - if (options.hostProvided && !isLoopbackHost(urls.bindHost)) { + if (shouldWarnAboutExposure && urls.bindHost) { const authConfig = getDashboardAuthConfig(); - console.log(warn('Dashboard may be reachable from other devices on your network.')); + console.log( + warn('Dashboard may be reachable from other devices that can connect to this machine.') + ); if (!authConfig.enabled) { console.log(info('Protect it before sharing: ccs config auth setup')); } - if (!urls.networkUrl) { + if (isWildcardHost(urls.bindHost) && !urls.networkUrls?.length) { console.log(info('Use your machine IP or hostname from the other device.')); } } @@ -143,3 +160,14 @@ export async function handleConfigCommand(args: string[]): Promise { process.exit(1); } } + +function resolveServerBindHost(server: { + address(): string | { address: string } | null; +}): string | undefined { + const address = server.address(); + if (!address || typeof address === 'string') { + return undefined; + } + + return address.address; +} diff --git a/src/commands/config-dashboard-host.ts b/src/commands/config-dashboard-host.ts index 67693730..e4dd8703 100644 --- a/src/commands/config-dashboard-host.ts +++ b/src/commands/config-dashboard-host.ts @@ -12,31 +12,53 @@ interface NetworkInterfaceCandidate { type NetworkInterfacesMap = Record; export interface DashboardUrls { - bindHost: string; + bindHost?: string; browserUrl: string; - networkUrl?: string; + networkUrls?: string[]; } export function isLoopbackHost(host: string): boolean { - return LOOPBACK_HOSTS.has(host.trim().toLowerCase()); + return LOOPBACK_HOSTS.has(normalizeDashboardHost(host)?.toLowerCase() ?? ''); } export function isWildcardHost(host: string): boolean { - return WILDCARD_HOSTS.has(host.trim().toLowerCase()); + return WILDCARD_HOSTS.has(normalizeDashboardHost(host)?.toLowerCase() ?? ''); +} + +export function normalizeDashboardHost(host: string | undefined): string | undefined { + if (!host) { + return undefined; + } + + const trimmedHost = host.trim(); + if (!trimmedHost) { + return undefined; + } + + if (trimmedHost.startsWith('[') && trimmedHost.endsWith(']') && trimmedHost.includes(':')) { + return trimmedHost.slice(1, -1); + } + + return trimmedHost; } export function resolveDashboardUrls( - host: string, + host: string | undefined, port: number, networkInterfaces: NetworkInterfacesMap = os.networkInterfaces() ): DashboardUrls { - const bindHost = host.trim(); + const bindHost = normalizeDashboardHost(host); + if (!bindHost) { + return { + browserUrl: `http://localhost:${port}`, + }; + } if (isWildcardHost(bindHost)) { return { bindHost, browserUrl: `http://localhost:${port}`, - networkUrl: getFirstExternalIpv4Url(port, networkInterfaces), + networkUrls: getExternalIpv4Urls(port, networkInterfaces), }; } @@ -46,10 +68,13 @@ export function resolveDashboardUrls( }; } -function getFirstExternalIpv4Url( +function getExternalIpv4Urls( port: number, networkInterfaces: NetworkInterfacesMap -): string | undefined { +): string[] | undefined { + const urls: string[] = []; + const seen = new Set(); + for (const interfaceName of Object.keys(networkInterfaces)) { const candidates = networkInterfaces[interfaceName]; if (!candidates) { @@ -60,12 +85,16 @@ function getFirstExternalIpv4Url( const family = typeof candidate.family === 'string' ? candidate.family : String(candidate.family); if (family === 'IPv4' && !candidate.internal) { - return `http://${candidate.address}:${port}`; + const url = `http://${candidate.address}:${port}`; + if (!seen.has(url)) { + seen.add(url); + urls.push(url); + } } } } - return undefined; + return urls.length > 0 ? urls : undefined; } function formatHostForUrl(host: string): string { diff --git a/src/commands/help-command.ts b/src/commands/help-command.ts index f0e6ea00..85eb4aba 100644 --- a/src/commands/help-command.ts +++ b/src/commands/help-command.ts @@ -314,7 +314,7 @@ Run ${color('ccs config', 'command')} for web dashboard`.trim(); ['ccs config thinking --mode auto', 'Set thinking mode'], ['ccs config thinking --clear-provider-override codex', 'Clear provider overrides'], ['ccs config --port 3000', 'Use specific port'], - ['ccs config --host 0.0.0.0', 'Expose dashboard to other devices on your LAN'], + ['ccs config --host 0.0.0.0', 'Force all-interface binding for remote devices'], ['ccs persist ', 'Write profile setup to ~/.claude/settings.json'], ['ccs persist --list-backups', 'List available settings.json backups'], ['ccs persist --restore', 'Restore settings.json from latest backup'], diff --git a/src/web-server/index.ts b/src/web-server/index.ts index 0eaa95e7..6ec39e00 100644 --- a/src/web-server/index.ts +++ b/src/web-server/index.ts @@ -113,11 +113,56 @@ export async function startServer(options: ServerOptions): Promise((resolve) => { - server.listen(options.port, options.host, () => { + return new Promise((resolve, reject) => { + const onError = (error: NodeJS.ErrnoException) => { + cleanup(); + reject(new Error(formatListenError(error, options))); + }; + + server.once('error', onError); + + const onListening = () => { + server.off('error', onError); // Usage cache loads on-demand when Analytics page is visited // This keeps server startup instant for users who don't need analytics resolve({ server, wss, cleanup }); - }); + }; + + try { + if (options.host) { + server.listen(options.port, options.host, onListening); + return; + } + + server.listen(options.port, onListening); + } catch (error) { + server.off('error', onError); + cleanup(); + reject(new Error(formatListenError(error as NodeJS.ErrnoException, options))); + } }); } + +function formatListenError(error: NodeJS.ErrnoException, options: ServerOptions): string { + if (error.code === 'EADDRINUSE' && options.host) { + return `Unable to bind ${options.host}:${options.port}; the address may be unavailable or the port may already be in use`; + } + + if (error.code === 'EADDRINUSE') { + return `Port ${options.port} is already in use`; + } + + if (error.code === 'EADDRNOTAVAIL' && options.host) { + return `Cannot bind to ${options.host}:${options.port} on this machine`; + } + + if (error.code === 'EACCES') { + return `Permission denied while binding to port ${options.port}`; + } + + if (options.host) { + return `Cannot bind to ${options.host}:${options.port}: ${error.message}`; + } + + return error.message; +} diff --git a/tests/unit/commands/config-command-options.test.ts b/tests/unit/commands/config-command-options.test.ts index 8d4add79..9c8d94ff 100644 --- a/tests/unit/commands/config-command-options.test.ts +++ b/tests/unit/commands/config-command-options.test.ts @@ -1,17 +1,14 @@ import { describe, expect, it } from 'bun:test'; -import { - DEFAULT_DASHBOARD_HOST, - parseConfigCommandArgs, -} from '../../../src/commands/config-command-options'; +import { parseConfigCommandArgs } from '../../../src/commands/config-command-options'; describe('config command options parser', () => { - it('defaults to wildcard host without explicit override', () => { + it('defaults to system bind behavior without explicit host', () => { const result = parseConfigCommandArgs([]); expect(result.help).toBe(false); expect(result.error).toBeUndefined(); - expect(result.options.host).toBe(DEFAULT_DASHBOARD_HOST); + expect(result.options.host).toBeUndefined(); expect(result.options.hostProvided).toBe(false); }); @@ -29,4 +26,13 @@ describe('config command options parser', () => { expect(result.error).toBe('Invalid host value'); }); + + it('accepts port 65535 and rejects port 65536', () => { + const accepted = parseConfigCommandArgs(['--port', '65535']); + const rejected = parseConfigCommandArgs(['--port', '65536']); + + expect(accepted.error).toBeUndefined(); + expect(accepted.options.port).toBe(65535); + expect(rejected.error).toBe('Invalid port number'); + }); }); diff --git a/tests/unit/commands/config-command.test.ts b/tests/unit/commands/config-command.test.ts new file mode 100644 index 00000000..8b3a4683 --- /dev/null +++ b/tests/unit/commands/config-command.test.ts @@ -0,0 +1,185 @@ +import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'; + +const startServerCalls: Array> = []; +const resolveDashboardUrlsCalls: Array<[string | undefined, number]> = []; +let logLines: string[] = []; +let errorLines: string[] = []; +let dashboardAuthEnabled = false; +let startServerError: Error | null = null; +let mockServerBindHost = '::'; +let originalConsoleLog: typeof console.log; +let originalConsoleError: typeof console.error; +let originalProcessExit: typeof process.exit; + +beforeEach(() => { + startServerCalls.length = 0; + resolveDashboardUrlsCalls.length = 0; + logLines = []; + errorLines = []; + dashboardAuthEnabled = false; + startServerError = null; + mockServerBindHost = '::'; + + originalConsoleLog = console.log; + originalConsoleError = console.error; + originalProcessExit = process.exit; + + console.log = (...args: unknown[]) => { + logLines.push(args.map(String).join(' ')); + }; + console.error = (...args: unknown[]) => { + errorLines.push(args.map(String).join(' ')); + }; + + mock.module('get-port', () => ({ + default: async () => 3000, + })); + + mock.module('open', () => ({ + default: async () => undefined, + })); + + mock.module('../../../src/web-server', () => ({ + startServer: async (options: Record) => { + startServerCalls.push({ ...options }); + if (startServerError) { + throw startServerError; + } + return { + server: { + address: () => ({ address: mockServerBindHost }), + } as never, + wss: {} as never, + cleanup: () => {}, + }; + }, + })); + + mock.module('../../../src/web-server/shutdown', () => ({ + setupGracefulShutdown: () => {}, + })); + + mock.module('../../../src/cliproxy/service-manager', () => ({ + ensureCliproxyService: async () => ({ + started: true, + alreadyRunning: true, + port: 8317, + configRegenerated: false, + }), + })); + + mock.module('../../../src/cliproxy/config-generator', () => ({ + CLIPROXY_DEFAULT_PORT: 8317, + })); + + mock.module('../../../src/config/unified-config-loader', () => ({ + getDashboardAuthConfig: () => ({ + enabled: dashboardAuthEnabled, + }), + })); + + mock.module('../../../src/utils/ui', () => ({ + initUI: async () => {}, + header: (message: string) => message, + ok: (message: string) => message, + info: (message: string) => message, + warn: (message: string) => message, + fail: (message: string) => message, + })); + + mock.module('../../../src/commands/config-dashboard-host', () => ({ + isLoopbackHost: (host: string) => + ['localhost', '127.0.0.1', '::1', '[::1]'].includes(host.trim().toLowerCase()), + isWildcardHost: (host: string) => ['0.0.0.0', '::', '[::]'].includes(host.trim().toLowerCase()), + resolveDashboardUrls: (host: string | undefined, port: number) => { + resolveDashboardUrlsCalls.push([host, port]); + if (!host) { + return { browserUrl: `http://localhost:${port}` }; + } + + if (host === '0.0.0.0' || host === '::') { + return { + bindHost: host, + browserUrl: `http://localhost:${port}`, + networkUrls: [`http://192.168.1.25:${port}`, `http://100.64.0.12:${port}`], + }; + } + + return { + bindHost: host, + browserUrl: `http://${host}:${port}`, + }; + }, + })); +}); + +afterEach(() => { + console.log = originalConsoleLog; + console.error = originalConsoleError; + process.exit = originalProcessExit; + mock.restore(); +}); + +async function loadHandleConfigCommand() { + const mod = await import(`../../../src/commands/config-command?test=${Date.now()}-${Math.random()}`); + return mod.handleConfigCommand; +} + +describe('config command dashboard startup', () => { + it('keeps the default startup path free of an explicit host override', async () => { + const handleConfigCommand = await loadHandleConfigCommand(); + + await handleConfigCommand([]); + + expect(startServerCalls).toHaveLength(1); + expect(startServerCalls[0]).toEqual({ port: 3000, dev: false }); + expect(resolveDashboardUrlsCalls).toEqual([['::', 3000]]); + + const rendered = logLines.join('\n'); + expect(rendered).toContain('Dashboard: http://localhost:3000'); + expect(rendered).toContain('Bind host: ::'); + expect(rendered).toContain('Network URLs:'); + expect(rendered).toContain('Protect it before sharing: ccs config auth setup'); + expect(errorLines).toHaveLength(0); + }); + + it('passes explicit wildcard hosts through and prints exposure guidance', async () => { + const handleConfigCommand = await loadHandleConfigCommand(); + mockServerBindHost = '0.0.0.0'; + + await handleConfigCommand(['--host', '0.0.0.0', '--port', '4100']); + + expect(startServerCalls).toHaveLength(1); + expect(startServerCalls[0]).toEqual({ port: 4100, dev: false, host: '0.0.0.0' }); + expect(resolveDashboardUrlsCalls).toEqual([['0.0.0.0', 4100]]); + + const rendered = logLines.join('\n'); + expect(rendered).toContain('Bind host: 0.0.0.0'); + expect(rendered).toContain('Network URLs:'); + expect(rendered).toContain('http://192.168.1.25:4100'); + expect(rendered).toContain('http://100.64.0.12:4100'); + expect(rendered).toContain( + 'Dashboard may be reachable from other devices that can connect to this machine.' + ); + expect(rendered).toContain('Protect it before sharing: ccs config auth setup'); + expect(errorLines).toHaveLength(0); + }); + + it('fails cleanly when the server cannot bind the requested host', async () => { + const handleConfigCommand = await loadHandleConfigCommand(); + startServerError = new Error( + 'Unable to bind 192.0.2.123:4100; the address may be unavailable or the port may already be in use' + ); + process.exit = ((code?: number) => { + throw new Error(`process.exit(${code ?? 0})`); + }) as typeof process.exit; + + await expect(handleConfigCommand(['--host', '192.0.2.123', '--port', '4100'])).rejects.toThrow( + 'process.exit(1)' + ); + + expect(errorLines.join('\n')).toContain( + 'Failed to start server: Unable to bind 192.0.2.123:4100; the address may be unavailable or the port may already be in use' + ); + }); +}); diff --git a/tests/unit/commands/config-dashboard-host.test.ts b/tests/unit/commands/config-dashboard-host.test.ts index e90c8fd1..a0f85c4e 100644 --- a/tests/unit/commands/config-dashboard-host.test.ts +++ b/tests/unit/commands/config-dashboard-host.test.ts @@ -3,6 +3,7 @@ import { describe, expect, it } from 'bun:test'; import { isLoopbackHost, isWildcardHost, + normalizeDashboardHost, resolveDashboardUrls, } from '../../../src/commands/config-dashboard-host'; @@ -10,11 +11,22 @@ describe('config dashboard host helpers', () => { it('detects loopback and wildcard hosts', () => { expect(isLoopbackHost('localhost')).toBe(true); expect(isLoopbackHost('127.0.0.1')).toBe(true); + expect(isLoopbackHost('::1')).toBe(true); + expect(isLoopbackHost('[::1]')).toBe(true); expect(isWildcardHost('0.0.0.0')).toBe(true); expect(isWildcardHost('::')).toBe(true); + expect(isWildcardHost('[::]')).toBe(true); }); - it('returns localhost browser URL and LAN URL for wildcard host', () => { + it('returns localhost browser URL without network details when host is omitted', () => { + const urls = resolveDashboardUrls(undefined, 3000, {}); + + expect(urls.bindHost).toBeUndefined(); + expect(urls.browserUrl).toBe('http://localhost:3000'); + expect(urls.networkUrls).toBeUndefined(); + }); + + it('returns localhost browser URL and all detected external URLs for wildcard host', () => { const urls = resolveDashboardUrls('0.0.0.0', 3000, { en0: [ { @@ -26,16 +38,32 @@ describe('config dashboard host helpers', () => { cidr: '192.168.1.25/24', }, ], + utun5: [ + { + address: '100.64.0.12', + family: 'IPv4', + internal: false, + }, + ], }); expect(urls.browserUrl).toBe('http://localhost:3000'); - expect(urls.networkUrl).toBe('http://192.168.1.25:3000'); + expect(urls.networkUrls).toEqual(['http://192.168.1.25:3000', 'http://100.64.0.12:3000']); }); it('returns explicit host URL for loopback bindings', () => { const urls = resolveDashboardUrls('127.0.0.1', 3000, {}); + expect(urls.bindHost).toBe('127.0.0.1'); expect(urls.browserUrl).toBe('http://127.0.0.1:3000'); - expect(urls.networkUrl).toBeUndefined(); + expect(urls.networkUrls).toBeUndefined(); + }); + + it('normalizes bracketed IPv6 host literals for binding and URL output', () => { + const urls = resolveDashboardUrls('[::1]', 3000, {}); + + expect(normalizeDashboardHost('[::1]')).toBe('::1'); + expect(urls.bindHost).toBe('::1'); + expect(urls.browserUrl).toBe('http://[::1]:3000'); }); }); diff --git a/tests/unit/commands/help-command-parity.test.ts b/tests/unit/commands/help-command-parity.test.ts index 5130fddc..2b3f6740 100644 --- a/tests/unit/commands/help-command-parity.test.ts +++ b/tests/unit/commands/help-command-parity.test.ts @@ -69,6 +69,6 @@ describe('help command parity', () => { const rendered = stripAnsi(lines.join('\n')); expect(rendered.includes('ccs config --host 0.0.0.0')).toBe(true); - expect(rendered.includes('Expose dashboard to other devices on your LAN')).toBe(true); + expect(rendered.includes('Force all-interface binding for remote devices')).toBe(true); }); }); diff --git a/tests/unit/web-server/start-server-host.test.ts b/tests/unit/web-server/start-server-host.test.ts index fab5ae50..7c1204c6 100644 --- a/tests/unit/web-server/start-server-host.test.ts +++ b/tests/unit/web-server/start-server-host.test.ts @@ -18,6 +18,14 @@ afterEach(async () => { }); describe('startServer host binding', () => { + it('binds with system-default host when no host is provided', async () => { + const instance = await startServer({ port: 0 }); + instances.push(instance); + + const address = instance.server.address() as AddressInfo; + expect(address.port).toBeGreaterThan(0); + }); + it('binds to an explicit loopback host', async () => { const instance = await startServer({ port: 0, host: '127.0.0.1' }); instances.push(instance); diff --git a/ui/README.md b/ui/README.md index c1de82b8..5c395658 100644 --- a/ui/README.md +++ b/ui/README.md @@ -19,13 +19,20 @@ bun run dev ``` This starts the CCS server, opens a local browser URL, and prints bind/network details for the dashboard. +If the runtime bind is reachable beyond loopback, CCS also prints an auth reminder. -For LAN access during development, run: +For remote device access during development, run: ```bash bun run dev -- --host 0.0.0.0 ``` +For local-only development, run: + +```bash +bun run dev -- --host 127.0.0.1 +``` + From `ui/` only (frontend dev server): ```bash