@pi-chamber/web 0.1.8

package/README.md

@@ -0,0 +1,43 @@
+# @pi-chamber/web
+
+PiChamber's web server and browser UI for the Pi coding-agent runtime.
+
+## Run
+
+```bash
+pichamber serve --port 3000
+```
+
+The server starts the local Pi session daemon, serves the browser UI, and exposes authenticated Pi routes under `/api/pi/*`.
+
+```bash
+pichamber serve --port 8080
+pichamber serve --lan --ui-password <password>
+pichamber connect-url --port 3000 --qr
+pichamber stop
+```
+
+Use `--api-only` for a host intended to be paired from a PiChamber desktop or mobile client. LAN-bound servers require a UI password unless the explicit unsafe-development override is set.
+
+## Runtime contract
+
+- Pi session state and actions are served only through `/api/pi/*`.
+- PiChamber-owned UI settings, custom themes, and update metadata use `/api/pi/ui-settings`, `/api/pi/themes`, and `/api/pi/update-check`; removed `/api/config/*` and `/api/pichamber/*` aliases are not required.
+- Browser and paired clients authenticate with UI sessions or scoped client credentials.
+- `connect-url` creates a one-time pairing link; credentials are not written to URLs or logs.
+- The server owns the Pi daemon lifecycle and stops its locally managed daemon during shutdown.
+
+## Development
+
+```bash
+bun run --cwd packages/web build
+bun run --cwd packages/web type-check
+bun run --cwd packages/web test
+```
+
+Build flags:
+
+- `VITE_REACT_COMPILER=1` re-enables the `babel-plugin-react-compiler` pass for
+  release builds. It is opt-in because the pass costs ~25s of the ~52s
+  production build; the default build ships without compiler memoization.
+- `VITE_ENABLE_REACT_SCAN=1` injects the react-scan dev script into the page.

package/bin/cli-entry.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+function normalizeCliEntryPath(filePath, realpath = fs.realpathSync) {
+  if (typeof filePath !== 'string' || filePath.trim().length === 0) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  try {
+    return realpath(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+function isModuleCliExecution(
+  entryPath = process.argv[1],
+  moduleUrl,
+  realpath = fs.realpathSync,
+  expectedBinName,
+) {
+  if (typeof entryPath !== 'string' || entryPath.trim().length === 0) {
+    return false;
+  }
+  if (typeof moduleUrl !== 'string' || moduleUrl.trim().length === 0) {
+    return false;
+  }
+
+  try {
+    const normalizedEntryPath = normalizeCliEntryPath(entryPath, realpath);
+    const normalizedModulePath = normalizeCliEntryPath(fileURLToPath(moduleUrl), realpath);
+    if (!normalizedEntryPath || !normalizedModulePath) {
+      return false;
+    }
+    if (pathToFileURL(normalizedEntryPath).href === pathToFileURL(normalizedModulePath).href) {
+      return true;
+    }
+
+    if (typeof expectedBinName === 'string' && expectedBinName.trim().length > 0) {
+      const parsedEntryName = path.parse(normalizedEntryPath).name.toLowerCase();
+      return parsedEntryName === expectedBinName.trim().toLowerCase();
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  normalizeCliEntryPath,
+  isModuleCliExecution,
+};

package/bin/cli-output.js

@@ -0,0 +1,140 @@
+/**
+ * CLI output formatting adapter.
+ *
+ * Wraps @clack/prompts for structured, beautiful terminal output.
+ * Custom formatters (icons, redaction) live here to isolate the
+ * formatting dependency from the rest of the CLI.
+ */
+
+import {
+  intro,
+  outro,
+  log,
+  box,
+  confirm,
+  select,
+  text,
+  password,
+  spinner,
+  progress,
+  cancel,
+  isCancel,
+} from '@clack/prompts';
+
+// ── Provider icons ──────────────────────────────────────────────
+
+const TUNNEL_PROVIDER_ICON = {
+  cloudflare: '☁',
+};
+
+function formatProviderWithIcon(provider) {
+  if (typeof provider !== 'string' || provider.trim().length === 0) {
+    return 'unknown';
+  }
+  const normalized = provider.trim().toLowerCase();
+  const icon = TUNNEL_PROVIDER_ICON[normalized];
+  return icon ? `${icon} ${normalized}` : normalized;
+}
+
+// ── Status-aware log dispatch ───────────────────────────────────
+
+/**
+ * Print a status-tagged message using clack log primitives.
+ *
+ * @param {'success'|'warning'|'error'|'info'|'neutral'} status
+ * @param {string} message  Primary line
+ * @param {string} [detail] Optional dim secondary line appended after newline
+ */
+function logStatus(status, message, detail) {
+  const full = detail ? `${message}\n${detail}` : message;
+  switch (status) {
+    case 'success':
+      log.success(full);
+      break;
+    case 'warning':
+      log.warn(full);
+      break;
+    case 'error':
+      log.error(full);
+      break;
+    case 'info':
+    case 'neutral':
+    default:
+      log.info(full);
+      break;
+  }
+}
+
+// ── TTY detection ───────────────────────────────────────────────
+
+/**
+ * Whether both stdout and stdin are interactive TTYs.
+ * Prompts must be disabled when stdin is piped (e.g. --token-stdin).
+ */
+const isTTY = Boolean(process.stdout?.isTTY) && Boolean(process.stdin?.isTTY);
+
+function isJsonMode(options) {
+  return Boolean(options?.json);
+}
+
+function isQuietMode(options) {
+  return Boolean(options?.quiet);
+}
+
+function shouldRenderHumanOutput(options) {
+  return !isJsonMode(options) && !isQuietMode(options);
+}
+
+function canPrompt(options) {
+  return shouldRenderHumanOutput(options) && isTTY;
+}
+
+function createSpinner(options) {
+  return canPrompt(options) ? spinner() : null;
+}
+
+async function createProgress(options, config) {
+  return canPrompt(options) ? progress(config) : null;
+}
+
+function printJson(payload) {
+  const base = payload && typeof payload === 'object' && !Array.isArray(payload)
+    ? { ...payload }
+    : { data: payload };
+
+  const messages = Array.isArray(base.messages) ? base.messages : undefined;
+  const hasWarning = Boolean(messages?.some((entry) => entry?.level === 'warning'));
+  const hasError = Boolean(messages?.some((entry) => entry?.level === 'error'));
+  const normalizedStatus = base.status === 'ok' || base.status === 'warning' || base.status === 'error'
+    ? base.status
+    : (hasError ? 'error' : (hasWarning ? 'warning' : 'ok'));
+
+  const output = {
+    status: normalizedStatus,
+    ...base,
+  };
+
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+export {
+  intro,
+  outro,
+  log,
+  box,
+  confirm,
+  select,
+  text,
+  password,
+  cancel,
+  isCancel,
+  isJsonMode,
+  isQuietMode,
+  shouldRenderHumanOutput,
+  canPrompt,
+  createSpinner,
+  createProgress,
+  printJson,
+  formatProviderWithIcon,
+  logStatus,
+};

package/bin/cli-output.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+async function withInteractiveTty(fn) {
+  const stdoutDescriptor = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+  const stdinDescriptor = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+
+  Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: true });
+  Object.defineProperty(process.stdin, 'isTTY', { configurable: true, value: true });
+
+  try {
+    return await fn();
+  } finally {
+    if (stdoutDescriptor) {
+      Object.defineProperty(process.stdout, 'isTTY', stdoutDescriptor);
+    } else {
+      delete process.stdout.isTTY;
+    }
+
+    if (stdinDescriptor) {
+      Object.defineProperty(process.stdin, 'isTTY', stdinDescriptor);
+    } else {
+      delete process.stdin.isTTY;
+    }
+  }
+}
+
+describe('cli output', () => {
+  it('creates interactive clack spinner and progress helpers', async () => {
+    await withInteractiveTty(async () => {
+      const output = await import('./cli-output.js?interactive-test');
+
+      expect(output.createSpinner({})).toBeTruthy();
+      await expect(output.createProgress({}, { max: 2 })).resolves.toBeTruthy();
+    });
+  });
+});

package/bin/cli.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { isModuleCliExecution } from './cli-entry.js';
+import { EXIT_CODE, TunnelCliError } from './lib/cli-errors.js';
+import {
+  resolveServeHost,
+  hasUiPasswordConfigured,
+  generateUiPassword,
+  resolveServeUiPassword,
+  assertAuthenticatedNetworkExposure,
+} from './lib/cli-network.js';
+import {
+  maskToken,
+  resolveToken,
+  redactProfileForOutput,
+  redactProfilesForOutput,
+  warnIfUnsafeFilePermissions,
+  ensureTunnelProfilesMigrated as ensureTunnelProfilesMigratedBase,
+} from './lib/cli-tunnel-profiles.js';
+import {
+  parseArgs,
+  showHelp,
+  showStartupHelp,
+  showConnectUrlHelp,
+  showTunnelHelp,
+  generateCompletionScript,
+  findClosestMatch,
+} from './lib/cli-args.js';
+import { readDesktopLocalPortFromSettings } from './lib/cli-paths.js';
+import { startupCommand } from './lib/commands-startup.js';
+import { logsCommand } from './lib/commands-logs.js';
+import { statusCommand } from './lib/commands-status.js';
+import { createUpdateCommand } from './lib/commands-update.js';
+import { createConnectUrlCommand } from './lib/commands-connect-url.js';
+import { createLifecycleCommands } from './lib/commands-lifecycle.js';
+import { createServeCommand } from './lib/commands-serve.js';
+import { createTunnelCommand, isValidTunnelDoctorResponse, shouldDisplayTunnelQr } from './lib/commands-tunnel.js';
+import {
+  resolveDoctorPortStatuses,
+  discoverRunningInstances,
+  discoverPiChamberInstanceOnPort,
+  discoverLifecycleInstances,
+  discoverUnconfirmedRegistryInstanceOnPort,
+  resolveTunnelProviders,
+} from './lib/cli-lifecycle.js';
+import {
+  fetchTunnelProvidersFromPort,
+  fetchSystemInfoFromPort,
+} from './lib/cli-http.js';
+import {
+  getPidFilePath,
+  getInstanceFilePath,
+  isProcessRunning,
+  isOpenchamberCmdline,
+  isOpenchamberProcessRunning,
+  isPiChamberCmdline,
+  getOpenchamberProcessState,
+} from './lib/cli-process.js';
+import {
+  intro as clackIntro, outro as clackOutro, cancel as clackCancel,
+  isJsonMode,
+  isQuietMode,
+  printJson,
+  logStatus,
+} from './cli-output.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PACKAGE_JSON = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+let onCancelCleanup = null;
+let activeCommandOptions = null;
+let foregroundServerActive = false;
+let foregroundShutdown = null;
+
+function setCancelCleanup(handler) {
+  onCancelCleanup = typeof handler === 'function' ? handler : null;
+}
+
+function shouldWarnForTunnelProfileFile() {
+  if (!activeCommandOptions) return false;
+  return !isJsonMode(activeCommandOptions) && !isQuietMode(activeCommandOptions);
+}
+
+function ensureTunnelProfilesMigrated() {
+  return ensureTunnelProfilesMigratedBase({ shouldWarn: shouldWarnForTunnelProfileFile() });
+}
+
+const HAS_PLAIN_FLAG = process.argv.includes('--plain');
+const STYLE_ENABLED = process.stdout.isTTY && process.env.NO_COLOR !== '1' && !HAS_PLAIN_FLAG;
+const ANSI = {
+  bold: '\x1b[1m',
+  unbold: '\x1b[22m',
+};
+
+function boldText(text) {
+  if (!STYLE_ENABLED) return text;
+  return `${ANSI.bold}${text}${ANSI.unbold}`;
+}
+
+function importFromFilePath(filePath) {
+  return import(pathToFileURL(filePath).href);
+}
+
+function getBunBinary() {
+  if (typeof process.env.BUN_BINARY === 'string' && process.env.BUN_BINARY.trim().length > 0) {
+    return process.env.BUN_BINARY.trim();
+  }
+  if (typeof process.env.BUN_INSTALL === 'string' && process.env.BUN_INSTALL.trim().length > 0) {
+    return path.join(process.env.BUN_INSTALL.trim(), 'bin', 'bun');
+  }
+  return 'bun';
+}
+
+const BUN_BIN = getBunBinary();
+
+function isBunRuntime() {
+  return typeof globalThis.Bun !== 'undefined';
+}
+
+function isBunInstalled() {
+  try {
+    const result = spawnSync(BUN_BIN, ['--version'], {
+      stdio: 'ignore',
+      env: process.env,
+      windowsHide: true,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function getPreferredServerRuntime() {
+  return isBunInstalled() ? 'bun' : 'node';
+}
+
+const commands = {
+  serve: null,
+
+  'connect-url': null,
+
+  stop: null,
+
+  restart: null,
+
+  status: statusCommand,
+
+  logs: logsCommand,
+
+  startup: startupCommand,
+
+  update: null,
+};
+
+commands.serve = createServeCommand({
+  serverPath: path.join(__dirname, '..', 'server', 'index.js'),
+  bunBin: BUN_BIN,
+  getPreferredServerRuntime,
+  setForegroundServerActive(value) { foregroundServerActive = value; },
+  setForegroundShutdown(handler) { foregroundShutdown = handler; },
+});
+
+{
+  const lifecycleCommands = createLifecycleCommands({ serveCommand: commands.serve.bind(commands) });
+  commands.stop = lifecycleCommands.stop;
+  commands.restart = lifecycleCommands.restart;
+}
+
+commands.tunnel = createTunnelCommand({
+  serveCommand: commands.serve.bind(commands),
+  stopCommand: commands.stop.bind(commands),
+  setCancelCleanup,
+  boldText,
+  ensureTunnelProfilesMigrated,
+});
+
+commands['connect-url'] = createConnectUrlCommand({
+  serveCommand: commands.serve.bind(commands),
+});
+
+commands.update = createUpdateCommand({
+  importFromFilePath,
+  packageManagerPath: path.join(__dirname, '..', 'server', 'lib', 'package-manager.js'),
+  serveCommand: commands.serve.bind(commands),
+});
+
+async function main() {
+  const parsed = parseArgs();
+  const { command, subcommand, tunnelAction, startupAction, options, removedFlagErrors, helpRequested, versionRequested } = parsed;
+  activeCommandOptions = options;
+
+  if (versionRequested) {
+    if (isJsonMode(options)) {
+      printJson({ version: PACKAGE_JSON.version });
+    } else {
+      console.log(PACKAGE_JSON.version);
+    }
+    return;
+  }
+
+  if (removedFlagErrors.length > 0) {
+    if (isJsonMode(options)) {
+      printJson({
+        status: 'error',
+        error: {
+          message: removedFlagErrors[0],
+          details: removedFlagErrors,
+        },
+      });
+    } else {
+      for (const error of removedFlagErrors) {
+        console.error(`Error: ${error}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  if (helpRequested) {
+    if (command === 'tunnel') {
+      showTunnelHelp();
+    } else if (command === 'startup') {
+      showStartupHelp();
+    } else if (command === 'connect-url') {
+      showConnectUrlHelp();
+    } else {
+      showHelp();
+    }
+    return;
+  }
+
+  if (command === 'tunnel') {
+    await commands.tunnel(options, subcommand, tunnelAction);
+    return;
+  }
+
+  if (command === 'startup') {
+    await commands.startup(options, startupAction);
+    return;
+  }
+
+  if (!commands[command]) {
+    const knownCommands = ['serve', 'stop', 'restart', 'status', 'tunnel', 'startup', 'logs', 'update'];
+    const suggestion = findClosestMatch(command, knownCommands);
+    const hint = suggestion ? ` Did you mean '${suggestion}'?` : '';
+    if (isJsonMode(options)) {
+      printJson({
+        status: 'error',
+        error: {
+          message: `Unknown command '${command}'.${hint}`,
+        },
+        messages: [{ level: 'info', code: 'USAGE_HELP', message: 'Use --help to see available commands' }],
+      });
+    } else {
+      console.error(`Error: Unknown command '${command}'.${hint}`);
+      console.error('Use --help to see available commands');
+    }
+    process.exit(EXIT_CODE.USAGE_ERROR);
+  }
+
+  await commands[command](options);
+}
+
+const isCliExecution = isModuleCliExecution(process.argv[1], import.meta.url, fs.realpathSync, 'pichamber');
+
+if (isCliExecution) {
+  let isHandlingSigint = false;
+  process.on('SIGINT', () => {
+    if (isHandlingSigint) {
+      return;
+    }
+    if (foregroundServerActive) {
+      if (typeof foregroundShutdown === 'function') {
+        void foregroundShutdown('SIGINT');
+      }
+      return;
+    }
+    isHandlingSigint = true;
+    (async () => {
+      clackCancel('Operation cancelled.');
+      if (onCancelCleanup) {
+        try {
+          await onCancelCleanup();
+        } catch {
+        } finally {
+          setCancelCleanup(null);
+        }
+      }
+      process.exit(130);
+    })();
+  });
+
+  process.on('unhandledRejection', (reason, promise) => {
+    if (isJsonMode(activeCommandOptions)) {
+      printJson({
+        status: 'error',
+        error: {
+          message: `Unhandled rejection: ${String(reason)}`,
+        },
+      });
+    } else {
+      console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    }
+    process.exit(1);
+  });
+
+  process.on('uncaughtException', (error) => {
+    if (isJsonMode(activeCommandOptions)) {
+      printJson({
+        status: 'error',
+        error: {
+          message: `Uncaught exception: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      });
+    } else {
+      console.error('Uncaught Exception:', error);
+    }
+    process.exit(1);
+  });
+
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (isJsonMode(activeCommandOptions)) {
+      printJson({
+        status: 'error',
+        error: {
+          message,
+        },
+      });
+    } else if (process.stdout?.isTTY && !HAS_PLAIN_FLAG) {
+      clackIntro(boldText('Error'));
+      logStatus('error', message);
+      clackOutro('failed');
+    } else {
+      console.error(`Error: ${message}`);
+    }
+    const exitCode = error instanceof TunnelCliError ? error.exitCode : EXIT_CODE.GENERAL_ERROR;
+    process.exit(exitCode);
+  });
+}
+
+export {
+  main,
+  commands,
+  parseArgs,
+  assertAuthenticatedNetworkExposure,
+  resolveServeHost,
+  hasUiPasswordConfigured,
+  generateUiPassword,
+  resolveServeUiPassword,
+  shouldDisplayTunnelQr,
+  isValidTunnelDoctorResponse,
+  readDesktopLocalPortFromSettings,
+  getPidFilePath,
+  getInstanceFilePath,
+  isProcessRunning,
+  isOpenchamberProcessRunning,
+  isOpenchamberCmdline,
+  isPiChamberCmdline,
+  getOpenchamberProcessState,
+  resolveTunnelProviders,
+  fetchTunnelProvidersFromPort,
+  fetchSystemInfoFromPort,
+  discoverRunningInstances,
+  discoverPiChamberInstanceOnPort,
+  discoverLifecycleInstances,
+  discoverUnconfirmedRegistryInstanceOnPort,
+  ensureTunnelProfilesMigrated,
+  resolveToken,
+  redactProfileForOutput,
+  redactProfilesForOutput,
+  maskToken,
+  findClosestMatch,
+  generateCompletionScript,
+  TunnelCliError,
+  EXIT_CODE,
+  warnIfUnsafeFilePermissions,
+};