diff --git a/README.md b/README.md index ae84faa2..43e5944e 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,18 @@ bun add -g @kaitranntt/ccs # bun (30x faster) ```bash ccs config -# Opens http://localhost:3000 +# Opens a local browser URL and prints bind/network details ``` +Expose the dashboard to another device on your network: + +```bash +ccs config --host 0.0.0.0 +# Terminal prints the LAN URL to open from the other device +``` + +If you expose the dashboard beyond localhost, protect it first with `ccs config auth setup`. + 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 1449e0ec..7fa33a64 100644 --- a/docs/dashboard-auth-cli.md +++ b/docs/dashboard-auth-cli.md @@ -1,12 +1,12 @@ # Dashboard Authentication CLI -Last Updated: 2026-02-26 +Last Updated: 2026-03-17 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. +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`. Authentication is **disabled by default** for backward compatibility. Use the CLI to configure and enable it. diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index 5d47170a..17e2bd27 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -43,6 +43,7 @@ All major modularization work is complete. The codebase evolved from monolithic - **#724**: Codex startup is now free-plan safe. CCS defaults new Codex sessions to a cross-plan model and auto-repairs stale paid-only Codex defaults when the active account is on the free plan. - **#737**: Dashboard model pickers in Cursor, Copilot, and CLIProxy now use a searchable combobox with autofocus and explicit no-results states for large model catalogs. +- **#736**: `ccs config` now supports explicit dashboard bind hosts via `--host`, and surfaces remote-access warnings plus reachable URLs when the effective bind is non-loopback. ### Maintainability Hardening Kickoff diff --git a/src/commands/config-command-options.ts b/src/commands/config-command-options.ts new file mode 100644 index 00000000..c4084ef0 --- /dev/null +++ b/src/commands/config-command-options.ts @@ -0,0 +1,115 @@ +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; + hostProvided: boolean; + dev: boolean; +} + +export interface ConfigCommandParseResult { + help: boolean; + error?: string; + options: ConfigCommandOptions; +} + +export function parseConfigCommandArgs(args: string[]): ConfigCommandParseResult { + const options: ConfigCommandOptions = { + host: DEFAULT_DASHBOARD_HOST, + hostProvided: false, + dev: false, + }; + + if (hasAnyFlag(args, ['--help', '-h'])) { + return { help: true, options }; + } + + const portOption = extractOption(args, ['--port', '-p'], { + knownFlags: CONFIG_COMMAND_FLAGS, + }); + if (portOption.found) { + if (portOption.missingValue || !portOption.value) { + return { help: false, error: 'Invalid port number', options }; + } + + const port = parseInt(portOption.value, 10); + if (Number.isNaN(port) || port <= 0 || port >= 65536) { + return { help: false, error: 'Invalid port number', options }; + } + + options.port = port; + } + + const hostOption = extractOption(portOption.remainingArgs, ['--host', '-H'], { + knownFlags: CONFIG_COMMAND_FLAGS, + }); + if (hostOption.found) { + const host = hostOption.value?.trim(); + if (hostOption.missingValue || !host) { + return { help: false, error: 'Invalid host value', options }; + } + + options.host = host; + options.hostProvided = true; + } + + options.dev = hasAnyFlag(hostOption.remainingArgs, ['--dev']); + + return { help: false, options }; +} + +export function showConfigCommandHelp(): void { + console.log(''); + console.log('Usage: ccs config [command] [options]'); + console.log(''); + console.log('Open web-based configuration dashboard'); + console.log('Includes a dedicated Claude IDE Extension page for VS Code-compatible hosts.'); + console.log(''); + console.log('Commands:'); + console.log(' auth Manage dashboard authentication'); + console.log(' auth setup Configure username and password'); + console.log(' auth show Display current auth status'); + console.log(' auth disable Disable authentication'); + console.log(''); + console.log(' image-analysis Manage image analysis settings'); + console.log(' --enable Enable image analysis via CLIProxy'); + console.log(' --disable Disable image analysis'); + console.log(' --timeout Set analysis timeout (seconds)'); + console.log(' --set-model

Set model for provider'); + console.log(''); + console.log(' Claude IDE Extension'); + console.log(' Dashboard page Generate copy-ready setup for VS Code, Cursor, Windsurf'); + console.log(' Shared settings Shows preferred ~/.claude/settings.json setup'); + console.log(' IDE-local JSON Shows extension-specific environmentVariables snippets'); + console.log(''); + console.log(' thinking Manage thinking/reasoning settings'); + console.log(' --mode Set mode (auto, off, manual)'); + console.log(' --override Set persistent override level'); + console.log(' --clear-override Remove persistent override'); + console.log(' --tier Set tier default level'); + console.log(' --provider-override

Set provider tier override'); + console.log(' --clear-provider-override

[t] Remove provider override'); + 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(' --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 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'); + console.log(' ccs config image-analysis Show image settings'); + console.log(' ccs config image-analysis --enable Enable feature'); + console.log(' ccs config thinking Show thinking settings'); + console.log(' ccs config thinking --mode auto Set auto mode'); + console.log(''); +} diff --git a/src/commands/config-command.ts b/src/commands/config-command.ts index 7a7f5f4c..5a9a2262 100644 --- a/src/commands/config-command.ts +++ b/src/commands/config-command.ts @@ -3,7 +3,7 @@ * * Launches web-based configuration dashboard. * Ensures CLIProxy service is running for dashboard features. - * Usage: ccs config [--port PORT] [--dev] + * Usage: ccs config [--port PORT] [--host HOST] [--dev] */ import getPort from 'get-port'; @@ -12,97 +12,10 @@ import { startServer } from '../web-server'; import { setupGracefulShutdown } from '../web-server/shutdown'; 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 { extractOption, hasAnyFlag } from './arg-extractor'; - -interface ConfigOptions { - port?: number; - dev?: boolean; -} - -/** - * Parse command line arguments - */ -function parseArgs(args: string[]): ConfigOptions { - const result: ConfigOptions = {}; - - if (hasAnyFlag(args, ['--help', '-h'])) { - showHelp(); - process.exit(0); - } - - const portOption = extractOption(args, ['--port', '-p']); - if (portOption.found) { - if (portOption.missingValue || !portOption.value) { - console.error(fail('Invalid port number')); - process.exit(1); - } - - const port = parseInt(portOption.value, 10); - if (!isNaN(port) && port > 0 && port < 65536) { - result.port = port; - } else { - console.error(fail('Invalid port number')); - process.exit(1); - } - } - - result.dev = hasAnyFlag(args, ['--dev']); - return result; -} - -/** - * Show help message - */ -function showHelp(): void { - console.log(''); - console.log('Usage: ccs config [command] [options]'); - console.log(''); - console.log('Open web-based configuration dashboard'); - console.log('Includes a dedicated Claude IDE Extension page for VS Code-compatible hosts.'); - console.log(''); - console.log('Commands:'); - console.log(' auth Manage dashboard authentication'); - console.log(' auth setup Configure username and password'); - console.log(' auth show Display current auth status'); - console.log(' auth disable Disable authentication'); - console.log(''); - console.log(' image-analysis Manage image analysis settings'); - console.log(' --enable Enable image analysis via CLIProxy'); - console.log(' --disable Disable image analysis'); - console.log(' --timeout Set analysis timeout (seconds)'); - console.log(' --set-model

Set model for provider'); - console.log(''); - console.log(' Claude IDE Extension'); - console.log(' Dashboard page Generate copy-ready setup for VS Code, Cursor, Windsurf'); - console.log(' Shared settings Shows preferred ~/.claude/settings.json setup'); - console.log(' IDE-local JSON Shows extension-specific environmentVariables snippets'); - console.log(''); - console.log(' thinking Manage thinking/reasoning settings'); - console.log(' --mode Set mode (auto, off, manual)'); - console.log(' --override Set persistent override level'); - console.log(' --clear-override Remove persistent override'); - console.log(' --tier Set tier default level'); - console.log(' --provider-override

Set provider tier override'); - console.log(' --clear-provider-override

[t] Remove provider override'); - console.log(''); - console.log('Options:'); - console.log(' --port, -p PORT Specify server port (default: auto-detect)'); - 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 --dev Development mode with hot reload'); - console.log(' ccs config auth setup Configure dashboard login'); - console.log(' ccs config Open dashboard, then choose Claude IDE Extension'); - console.log(' ccs config image-analysis Show image settings'); - console.log(' ccs config image-analysis --enable Enable feature'); - console.log(' ccs config thinking Show thinking settings'); - console.log(' ccs config thinking --mode auto Set auto mode'); - console.log(''); -} +import { isLoopbackHost, resolveDashboardUrls } from './config-dashboard-host'; +import { parseConfigCommandArgs, showConfigCommandHelp } from './config-command-options'; /** * Handle config command @@ -131,8 +44,18 @@ export async function handleConfigCommand(args: string[]): Promise { await initUI(); - const options = parseArgs(args); - const verbose = options.dev || false; + const parsed = parseConfigCommandArgs(args); + if (parsed.help) { + showConfigCommandHelp(); + process.exit(0); + } + if (parsed.error) { + console.error(fail(parsed.error)); + process.exit(1); + } + + const options = parsed.options; + const verbose = options.dev; console.log(header('CCS Config Dashboard')); console.log(''); @@ -167,28 +90,50 @@ export async function handleConfigCommand(args: string[]): Promise { try { // Start server - const { server, wss, cleanup } = await startServer({ port, dev: options.dev }); + const { server, wss, cleanup } = await startServer({ + port, + host: options.host, + dev: options.dev, + }); // Setup graceful shutdown setupGracefulShutdown(server, wss, cleanup); - const url = `http://localhost:${port}`; + const urls = resolveDashboardUrls(options.host, port); if (options.dev) { - console.log(ok(`Dev Server: ${url}`)); + console.log(ok(`Dev Server: ${urls.browserUrl}`)); console.log(''); console.log(info('HMR enabled - UI changes will hot-reload')); } else { - console.log(ok(`Dashboard: ${url}`)); + console.log(ok(`Dashboard: ${urls.browserUrl}`)); + } + + if (!isLoopbackHost(urls.bindHost)) { + console.log(info(`Bind host: ${urls.bindHost}`)); + if (urls.networkUrl) { + console.log(info(`Network URL: ${urls.networkUrl}`)); + } + } + + if (options.hostProvided && !isLoopbackHost(urls.bindHost)) { + const authConfig = getDashboardAuthConfig(); + console.log(warn('Dashboard may be reachable from other devices on your network.')); + if (!authConfig.enabled) { + console.log(info('Protect it before sharing: ccs config auth setup')); + } + if (!urls.networkUrl) { + console.log(info('Use your machine IP or hostname from the other device.')); + } } console.log(''); // Open browser try { - await open(url, { wait: false }); + await open(urls.browserUrl, { wait: false }); console.log(info('Browser opened automatically')); } catch { - console.log(info(`Open manually: ${url}`)); + console.log(info(`Open manually: ${urls.browserUrl}`)); } console.log(''); diff --git a/src/commands/config-dashboard-host.ts b/src/commands/config-dashboard-host.ts new file mode 100644 index 00000000..67693730 --- /dev/null +++ b/src/commands/config-dashboard-host.ts @@ -0,0 +1,77 @@ +import * as os from 'os'; + +const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']); +const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]']); + +interface NetworkInterfaceCandidate { + address: string; + family: string | number; + internal: boolean; +} + +type NetworkInterfacesMap = Record; + +export interface DashboardUrls { + bindHost: string; + browserUrl: string; + networkUrl?: string; +} + +export function isLoopbackHost(host: string): boolean { + return LOOPBACK_HOSTS.has(host.trim().toLowerCase()); +} + +export function isWildcardHost(host: string): boolean { + return WILDCARD_HOSTS.has(host.trim().toLowerCase()); +} + +export function resolveDashboardUrls( + host: string, + port: number, + networkInterfaces: NetworkInterfacesMap = os.networkInterfaces() +): DashboardUrls { + const bindHost = host.trim(); + + if (isWildcardHost(bindHost)) { + return { + bindHost, + browserUrl: `http://localhost:${port}`, + networkUrl: getFirstExternalIpv4Url(port, networkInterfaces), + }; + } + + return { + bindHost, + browserUrl: `http://${formatHostForUrl(bindHost)}:${port}`, + }; +} + +function getFirstExternalIpv4Url( + port: number, + networkInterfaces: NetworkInterfacesMap +): string | undefined { + for (const interfaceName of Object.keys(networkInterfaces)) { + const candidates = networkInterfaces[interfaceName]; + if (!candidates) { + continue; + } + + for (const candidate of candidates) { + const family = + typeof candidate.family === 'string' ? candidate.family : String(candidate.family); + if (family === 'IPv4' && !candidate.internal) { + return `http://${candidate.address}:${port}`; + } + } + } + + return undefined; +} + +function formatHostForUrl(host: string): string { + if (host.includes(':') && !host.startsWith('[') && !host.endsWith(']')) { + return `[${host}]`; + } + + return host; +} diff --git a/src/commands/help-command.ts b/src/commands/help-command.ts index 6eb794c0..f0e6ea00 100644 --- a/src/commands/help-command.ts +++ b/src/commands/help-command.ts @@ -314,6 +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 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 61dd2941..0eaa95e7 100644 --- a/src/web-server/index.ts +++ b/src/web-server/index.ts @@ -17,6 +17,7 @@ import { shutdownUsageAggregator } from './usage/aggregator'; export interface ServerOptions { port: number; + host?: string; staticDir?: string; dev?: boolean; } @@ -113,7 +114,7 @@ export async function startServer(options: ServerOptions): Promise((resolve) => { - server.listen(options.port, () => { + server.listen(options.port, options.host, () => { // 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 }); diff --git a/tests/unit/commands/config-command-options.test.ts b/tests/unit/commands/config-command-options.test.ts new file mode 100644 index 00000000..8d4add79 --- /dev/null +++ b/tests/unit/commands/config-command-options.test.ts @@ -0,0 +1,32 @@ +import { describe, expect, it } from 'bun:test'; + +import { + DEFAULT_DASHBOARD_HOST, + parseConfigCommandArgs, +} from '../../../src/commands/config-command-options'; + +describe('config command options parser', () => { + it('defaults to wildcard host without explicit override', () => { + const result = parseConfigCommandArgs([]); + + expect(result.help).toBe(false); + expect(result.error).toBeUndefined(); + expect(result.options.host).toBe(DEFAULT_DASHBOARD_HOST); + expect(result.options.hostProvided).toBe(false); + }); + + it('parses explicit host and port overrides', () => { + const result = parseConfigCommandArgs(['--host', '0.0.0.0', '--port', '4100']); + + expect(result.error).toBeUndefined(); + expect(result.options.host).toBe('0.0.0.0'); + expect(result.options.hostProvided).toBe(true); + expect(result.options.port).toBe(4100); + }); + + it('rejects missing host values', () => { + const result = parseConfigCommandArgs(['--host']); + + expect(result.error).toBe('Invalid host value'); + }); +}); diff --git a/tests/unit/commands/config-dashboard-host.test.ts b/tests/unit/commands/config-dashboard-host.test.ts new file mode 100644 index 00000000..e90c8fd1 --- /dev/null +++ b/tests/unit/commands/config-dashboard-host.test.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from 'bun:test'; + +import { + isLoopbackHost, + isWildcardHost, + resolveDashboardUrls, +} from '../../../src/commands/config-dashboard-host'; + +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(isWildcardHost('0.0.0.0')).toBe(true); + expect(isWildcardHost('::')).toBe(true); + }); + + it('returns localhost browser URL and LAN URL for wildcard host', () => { + const urls = resolveDashboardUrls('0.0.0.0', 3000, { + en0: [ + { + address: '192.168.1.25', + netmask: '255.255.255.0', + family: 'IPv4', + mac: '00:00:00:00:00:00', + internal: false, + cidr: '192.168.1.25/24', + }, + ], + }); + + expect(urls.browserUrl).toBe('http://localhost:3000'); + expect(urls.networkUrl).toBe('http://192.168.1.25:3000'); + }); + + it('returns explicit host URL for loopback bindings', () => { + const urls = resolveDashboardUrls('127.0.0.1', 3000, {}); + + expect(urls.browserUrl).toBe('http://127.0.0.1:3000'); + expect(urls.networkUrl).toBeUndefined(); + }); +}); diff --git a/tests/unit/commands/help-command-parity.test.ts b/tests/unit/commands/help-command-parity.test.ts index 27cd4de6..5130fddc 100644 --- a/tests/unit/commands/help-command-parity.test.ts +++ b/tests/unit/commands/help-command-parity.test.ts @@ -58,4 +58,17 @@ describe('help command parity', () => { true ); }); + + test('root help documents dashboard host binding example', async () => { + const lines: string[] = []; + console.log = (...args: unknown[]) => { + lines.push(args.map((arg) => String(arg)).join(' ')); + }; + + await handleHelpCommand(); + + 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); + }); }); diff --git a/tests/unit/web-server/start-server-host.test.ts b/tests/unit/web-server/start-server-host.test.ts new file mode 100644 index 00000000..fab5ae50 --- /dev/null +++ b/tests/unit/web-server/start-server-host.test.ts @@ -0,0 +1,36 @@ +import { afterEach, describe, expect, it } from 'bun:test'; +import type { AddressInfo } from 'net'; + +import { startServer } from '../../../src/web-server'; + +const instances: Array>> = []; + +afterEach(async () => { + while (instances.length > 0) { + const instance = instances.pop(); + if (!instance) { + continue; + } + + instance.cleanup(); + await new Promise((resolve) => instance.server.close(() => resolve())); + } +}); + +describe('startServer host binding', () => { + it('binds to an explicit loopback host', async () => { + const instance = await startServer({ port: 0, host: '127.0.0.1' }); + instances.push(instance); + + const address = instance.server.address() as AddressInfo; + expect(address.address).toBe('127.0.0.1'); + }); + + it('binds to wildcard host when requested', async () => { + const instance = await startServer({ port: 0, host: '0.0.0.0' }); + instances.push(instance); + + const address = instance.server.address() as AddressInfo; + expect(['0.0.0.0', '::']).toContain(address.address); + }); +}); diff --git a/ui/README.md b/ui/README.md index cc1d3800..c1de82b8 100644 --- a/ui/README.md +++ b/ui/README.md @@ -18,7 +18,13 @@ From project root: bun run dev ``` -This starts the CCS server and serves the dashboard at `http://localhost:3000`. +This starts the CCS server, opens a local browser URL, and prints bind/network details for the dashboard. + +For LAN access during development, run: + +```bash +bun run dev -- --host 0.0.0.0 +``` From `ui/` only (frontend dev server):