@pellux/goodvibes-tui 0.19.25 → 0.19.26

package/src/cli/status.ts

@@ -1,6 +1,9 @@
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 import type { OnboardingCompletionMarkersState } from '../runtime/onboarding/index.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
+import { isNetworkFacing } from './network-posture.ts';
+import type { GoodVibesCliOutputFormat } from './types.ts';
+import type { CliServicePosture } from './service-posture.ts';
 
 export interface CliStatusOptions {
   readonly configManager: Pick<ConfigManager, 'get'>;
@@ -8,7 +11,9 @@ export interface CliStatusOptions {
   readonly homeDirectory: string;
   readonly onboardingMarkers?: OnboardingCompletionMarkersState;
   readonly auth?: CliAuthStatus;
+  readonly service?: CliServicePosture;
   readonly doctor?: boolean;
+  readonly outputFormat?: GoodVibesCliOutputFormat;
 }
 
 export interface CliAuthStatus {
@@ -20,38 +25,285 @@ export interface CliAuthStatus {
   readonly operatorTokenPresent: boolean;
 }
 
+export interface CliDoctorFinding {
+  readonly id: string;
+  readonly area: 'auth' | 'network' | 'onboarding' | 'security' | 'service' | 'secrets';
+  readonly severity: 'warning' | 'risk';
+  readonly summary: string;
+  readonly cause: string;
+  readonly impact: string;
+  readonly action: string;
+}
+
+export interface CliStatusSnapshot {
+  readonly title: 'GoodVibes status' | 'GoodVibes doctor';
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  readonly provider: {
+    readonly provider: string;
+    readonly model: string;
+    readonly reasoning: string;
+  };
+  readonly auth: {
+    readonly permissionMode: unknown;
+    readonly permissionLabel: string;
+    readonly secretPolicy: unknown;
+    readonly secretPolicyLabel: string;
+    readonly localUsers: CliAuthStatus | null;
+  };
+  readonly service: {
+    readonly enabled: unknown;
+    readonly autostart: unknown;
+    readonly restartOnFailure: unknown;
+    readonly lifecycle?: CliServicePosture;
+  };
+  readonly surfaces: {
+    readonly controlPlane: ReturnType<typeof resolveRuntimeEndpointBinding> & { readonly enabled: unknown };
+    readonly httpListener: ReturnType<typeof resolveRuntimeEndpointBinding> & { readonly enabled: unknown };
+    readonly web: ReturnType<typeof resolveRuntimeEndpointBinding> & { readonly enabled: unknown };
+  };
+  readonly onboarding: {
+    readonly completed: boolean;
+    readonly scope: string;
+    readonly updatedAt: number | null;
+  };
+  readonly findings: readonly CliDoctorFinding[];
+}
+
 function yesNo(value: unknown): string {
   return value === true ? 'yes' : 'no';
 }
 
+function permissionModeLabel(mode: unknown): string {
+  if (mode === 'prompt') return 'Ask before powerful actions';
+  if (mode === 'allow-all') return 'Allow everything';
+  if (mode === 'custom') return 'Custom rules';
+  return String(mode ?? 'unknown');
+}
+
+function secretPolicyLabel(policy: unknown): string {
+  if (policy === 'preferred_secure') return 'Use secure storage when available';
+  if (policy === 'require_secure') return 'Require secure storage';
+  if (policy === 'plaintext_allowed') return 'Allow plaintext storage';
+  return String(policy ?? 'unknown');
+}
+
 function bindLine(label: string, enabled: unknown, binding: { readonly hostMode: string; readonly host: string; readonly port: number }): string {
   return `  ${label}: ${yesNo(enabled)} (${binding.hostMode} ${binding.host}:${binding.port})`;
 }
 
-export function renderCliStatus(options: CliStatusOptions): string {
+export function buildCliDoctorFindings(options: CliStatusOptions): readonly CliDoctorFinding[] {
   const config = options.configManager;
-  const serviceEnabled = config.get('service.enabled');
-  const serviceAutostart = config.get('service.autostart');
-  const restartOnFailure = config.get('service.restartOnFailure');
-  const daemonEnabled = config.get('danger.daemon');
-  const listenerEnabled = config.get('danger.httpListener');
-  const webEnabled = config.get('web.enabled');
-  const controlPlaneEnabled = config.get('controlPlane.enabled');
+  const serviceEnabled = config.get('service.enabled') === true;
+  const serviceAutostart = config.get('service.autostart') === true;
+  const restartOnFailure = config.get('service.restartOnFailure') === true;
+  const daemonEnabled = config.get('danger.daemon') === true;
+  const listenerEnabled = config.get('danger.httpListener') === true;
+  const webEnabled = config.get('web.enabled') === true;
+  const controlPlaneEnabled = config.get('controlPlane.enabled') === true;
   const controlPlaneBinding = resolveRuntimeEndpointBinding(config, 'controlPlane');
   const httpListenerBinding = resolveRuntimeEndpointBinding(config, 'httpListener');
   const webBinding = resolveRuntimeEndpointBinding(config, 'web');
+  const permissionMode = config.get('permissions.mode');
+  const secretPolicy = config.get('storage.secretPolicy');
   const marker = options.onboardingMarkers?.effective;
-  const warnings: string[] = [];
+  const serverBackedEnabled = daemonEnabled || controlPlaneEnabled || listenerEnabled || webEnabled;
+  const networkFacingSurfaces = [
+    ['control plane', controlPlaneEnabled, controlPlaneBinding],
+    ['HTTP listener', listenerEnabled, httpListenerBinding],
+    ['web surface', webEnabled, webBinding],
+  ].filter(([, enabled, binding]) => isNetworkFacing(enabled, binding as typeof controlPlaneBinding));
+
+  const findings: CliDoctorFinding[] = [];
+
+  if (serverBackedEnabled && !serviceEnabled) {
+    findings.push({
+      id: 'service-disabled-for-server-surfaces',
+      area: 'service',
+      severity: 'warning',
+      summary: 'Server-backed surfaces are enabled but service mode is off.',
+      cause: 'One or more daemon, control-plane, listener, or web settings are enabled while service.enabled is false.',
+      impact: 'The configured surfaces may not start automatically or survive restarts.',
+      action: 'Enable service mode or disable the server-backed surfaces you do not want.',
+    });
+  }
+
+  if (serviceEnabled && !serviceAutostart) {
+    findings.push({
+      id: 'service-autostart-disabled',
+      area: 'service',
+      severity: 'warning',
+      summary: 'Service mode is enabled but autostart is off.',
+      cause: 'service.enabled is true and service.autostart is false.',
+      impact: 'GoodVibes may not start after login or reboot even though service mode is selected.',
+      action: 'Enable service.autostart if the daemon/listener/web surfaces should stay available.',
+    });
+  }
+
+  if (serviceEnabled && !restartOnFailure) {
+    findings.push({
+      id: 'service-restart-disabled',
+      area: 'service',
+      severity: 'warning',
+      summary: 'Service restart-on-failure is off.',
+      cause: 'service.enabled is true and service.restartOnFailure is false.',
+      impact: 'A crashed daemon or listener may stay down until manually restarted.',
+      action: 'Enable service.restartOnFailure for durable daemon/listener operation.',
+    });
+  }
+
+  if (options.service) {
+    for (const issue of options.service.issues) {
+      if (findings.some((finding) => finding.summary === issue)) continue;
+      findings.push({
+        id: `service-lifecycle-${findings.length}`,
+        area: 'service',
+        severity: 'warning',
+        summary: issue,
+        cause: 'The service lifecycle inspection found a mismatch between configured service/surface state and observed host state.',
+        impact: 'Daemon, control-plane, listener, or web availability may not match the configuration.',
+        action: 'Run goodvibes service check and apply the suggested service install/start/configuration fix.',
+      });
+    }
+  }
+
+  if (!marker?.payload) {
+    findings.push({
+      id: 'onboarding-incomplete',
+      area: 'onboarding',
+      severity: 'warning',
+      summary: 'Onboarding has not been completed for this user/project.',
+      cause: 'No effective onboarding completion marker was found.',
+      impact: 'Important service, network, provider, auth, or permission choices may still be implicit defaults.',
+      action: 'Run /onboarding in the TUI or goodvibes onboarding status to review setup state.',
+    });
+  }
 
-  if ((daemonEnabled || controlPlaneEnabled || listenerEnabled || webEnabled) && !serviceEnabled) {
-    warnings.push('server-backed surfaces are enabled but service.enabled is off');
+  if (networkFacingSurfaces.length > 0 && options.auth?.userStorePresent !== true) {
+    findings.push({
+      id: 'network-surface-without-local-users',
+      area: 'auth',
+      severity: 'risk',
+      summary: 'Network-facing surfaces are enabled before local users are configured.',
+      cause: `${networkFacingSurfaces.map(([name]) => name).join(', ')} are LAN/custom-bound, but no local auth user store was found.`,
+      impact: 'Remote access paths may be unusable or unsafe until local admin auth is configured.',
+      action: 'Create/verify a local admin user before exposing GoodVibes on the network.',
+    });
   }
-  if (serviceEnabled && !serviceAutostart) warnings.push('service.enabled is on but service.autostart is off');
-  if (serviceEnabled && !restartOnFailure) warnings.push('service.enabled is on but service.restartOnFailure is off');
-  if (!marker?.payload) warnings.push('onboarding has not been completed for this user/project');
+
+  if (networkFacingSurfaces.length > 0 && options.auth?.bootstrapCredentialPresent === true) {
+    findings.push({
+      id: 'network-surface-with-bootstrap-credential',
+      area: 'auth',
+      severity: 'risk',
+      summary: 'A bootstrap credential is still present while network-facing surfaces are enabled.',
+      cause: `${networkFacingSurfaces.map(([name]) => name).join(', ')} are LAN/custom-bound and auth-bootstrap.txt exists.`,
+      impact: 'Bootstrap credentials should be treated as temporary setup material, not long-lived network access credentials.',
+      action: 'Replace bootstrap auth with a named admin user and retire the bootstrap credential.',
+    });
+  }
+
+  if (permissionMode === 'allow-all') {
+    findings.push({
+      id: 'allow-all-permissions',
+      area: 'security',
+      severity: 'risk',
+      summary: 'Allow everything permission mode is active.',
+      cause: 'permissions.mode is allow-all.',
+      impact: 'Powerful write, edit, network, and execution tools can run without a Human-in-the-Loop (HITL) approval prompt.',
+      action: 'Use Ask before powerful actions or Custom rules unless this is an intentionally trusted environment.',
+    });
+  }
+
+  if (secretPolicy === 'plaintext_allowed') {
+    findings.push({
+      id: 'plaintext-secrets-allowed',
+      area: 'secrets',
+      severity: 'risk',
+      summary: 'Plaintext secret storage is allowed.',
+      cause: 'storage.secretPolicy is plaintext_allowed.',
+      impact: 'Provider keys and surface tokens may be stored without secure backend protection.',
+      action: 'Use Require secure storage or Use secure storage when available for normal operation.',
+    });
+  }
+
+  if (listenerEnabled && isNetworkFacing(listenerEnabled, httpListenerBinding)) {
+    findings.push({
+      id: 'network-http-listener-enabled',
+      area: 'network',
+      severity: 'warning',
+      summary: 'The HTTP listener is reachable beyond loopback.',
+      cause: `HTTP listener is enabled on ${httpListenerBinding.host}:${httpListenerBinding.port} with ${httpListenerBinding.hostMode} binding.`,
+      impact: 'External tools and devices may be able to reach incoming event endpoints.',
+      action: 'Keep listener secrets/signature checks configured for every enabled webhook surface.',
+    });
+  }
+
+  return findings;
+}
+
+export function buildCliStatusSnapshot(options: CliStatusOptions): CliStatusSnapshot {
+  const config = options.configManager;
+  const controlPlaneBinding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+  const httpListenerBinding = resolveRuntimeEndpointBinding(config, 'httpListener');
+  const webBinding = resolveRuntimeEndpointBinding(config, 'web');
+  const marker = options.onboardingMarkers?.effective;
+  const findings = buildCliDoctorFindings(options);
+  return {
+    title: options.doctor ? 'GoodVibes doctor' : 'GoodVibes status',
+    workingDirectory: options.workingDirectory,
+    homeDirectory: options.homeDirectory,
+    provider: {
+      provider: String(config.get('provider.provider')),
+      model: String(config.get('provider.model')),
+      reasoning: String(config.get('provider.reasoningEffort')),
+    },
+    auth: {
+      permissionMode: config.get('permissions.mode'),
+      permissionLabel: permissionModeLabel(config.get('permissions.mode')),
+      secretPolicy: config.get('storage.secretPolicy'),
+      secretPolicyLabel: secretPolicyLabel(config.get('storage.secretPolicy')),
+      localUsers: options.auth ?? null,
+    },
+    service: {
+      enabled: config.get('service.enabled'),
+      autostart: config.get('service.autostart'),
+      restartOnFailure: config.get('service.restartOnFailure'),
+      ...(options.service ? { lifecycle: options.service } : {}),
+    },
+    surfaces: {
+      controlPlane: { enabled: config.get('controlPlane.enabled'), ...controlPlaneBinding },
+      httpListener: { enabled: config.get('danger.httpListener'), ...httpListenerBinding },
+      web: { enabled: config.get('web.enabled'), ...webBinding },
+    },
+    onboarding: {
+      completed: Boolean(marker?.payload),
+      scope: marker?.scope ?? 'none',
+      updatedAt: marker?.payload?.updatedAt ?? null,
+    },
+    findings,
+  };
+}
+
+export function renderCliStatus(options: CliStatusOptions): string {
+  const config = options.configManager;
+  const snapshot = buildCliStatusSnapshot(options);
+  const serviceEnabled = snapshot.service.enabled;
+  const serviceAutostart = snapshot.service.autostart;
+  const restartOnFailure = snapshot.service.restartOnFailure;
+  const controlPlaneEnabled = snapshot.surfaces.controlPlane.enabled;
+  const listenerEnabled = snapshot.surfaces.httpListener.enabled;
+  const webEnabled = snapshot.surfaces.web.enabled;
+  const controlPlaneBinding = snapshot.surfaces.controlPlane;
+  const httpListenerBinding = snapshot.surfaces.httpListener;
+  const webBinding = snapshot.surfaces.web;
+  const marker = options.onboardingMarkers?.effective;
+  const findings = snapshot.findings;
+
+  if (options.outputFormat === 'json') return JSON.stringify(snapshot, null, 2);
 
   const lines = [
-    options.doctor ? 'GoodVibes doctor' : 'GoodVibes status',
+    snapshot.title,
     `  workingDir: ${options.workingDirectory}`,
     `  homeDir: ${options.homeDirectory}`,
     '',
@@ -61,8 +313,8 @@ export function renderCliStatus(options: CliStatusOptions): string {
     `  reasoning: ${String(config.get('provider.reasoningEffort'))}`,
     '',
     'Auth:',
-    `  permissions: ${String(config.get('permissions.mode'))}`,
-    `  secretPolicy: ${String(config.get('storage.secretPolicy'))}`,
+    `  permissions: ${permissionModeLabel(config.get('permissions.mode'))} (${String(config.get('permissions.mode'))})`,
+    `  secretPolicy: ${secretPolicyLabel(config.get('storage.secretPolicy'))} (${String(config.get('storage.secretPolicy'))})`,
     options.auth
       ? `  localUsers: ${options.auth.userStorePresent ? 'present' : 'missing'} (${options.auth.userStorePath})`
       : '  localUsers: unknown',
@@ -77,6 +329,14 @@ export function renderCliStatus(options: CliStatusOptions): string {
     `  enabled: ${yesNo(serviceEnabled)}`,
     `  autostart: ${yesNo(serviceAutostart)}`,
     `  restartOnFailure: ${yesNo(restartOnFailure)}`,
+    ...(options.service ? [
+      `  platform: ${options.service.managed.platform}`,
+      `  installed: ${yesNo(options.service.managed.installed)}`,
+      `  running: ${yesNo(options.service.managed.running)}`,
+      `  pid: ${options.service.managed.pid ?? 'n/a'}`,
+      `  definition: ${options.service.managed.path}`,
+      `  log: ${options.service.log.path ?? 'n/a'} (${options.service.log.exists ? 'present' : 'missing'})`,
+    ] : []),
     '',
     'Surfaces:',
     bindLine('controlPlane', controlPlaneEnabled, controlPlaneBinding),
@@ -91,8 +351,18 @@ export function renderCliStatus(options: CliStatusOptions): string {
 
   if (options.doctor) {
     lines.push('', 'Warnings:');
-    if (warnings.length === 0) lines.push('  none');
-    else lines.push(...warnings.map((warning) => `  - ${warning}`));
+    if (findings.length === 0) {
+      lines.push('  none');
+    } else {
+      for (const finding of findings) {
+        lines.push(
+          `  - [${finding.severity}:${finding.area}:${finding.id}] ${finding.summary}`,
+          `    cause: ${finding.cause}`,
+          `    impact: ${finding.impact}`,
+          `    action: ${finding.action}`,
+        );
+      }
+    }
   }
 
   return lines.join('\n');

package/src/cli/surface-command.ts

@@ -0,0 +1,248 @@
+import type { ConfigKey } from '../config/index.ts';
+import { resolveRuntimeEndpointBinding } from './endpoints.ts';
+import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
+import type { CliCommandRuntime } from './management.ts';
+import {
+  applyTargetEndpointFlagsOrDefault,
+  enableEndpointLanDefault,
+  enableServicePosture,
+  formatJsonOrText,
+  isPresentConfigValue,
+  probeTcp,
+  readAuthPaths,
+  yesNo,
+} from './management.ts';
+
+export const SURFACE_CONFIGS = [
+  ['slack', 'Slack', ['surfaces.slack.signingSecret', 'surfaces.slack.botToken']],
+  ['discord', 'Discord', ['surfaces.discord.publicKey', 'surfaces.discord.botToken', 'surfaces.discord.applicationId']],
+  ['telegram', 'Telegram', ['surfaces.telegram.botToken']],
+  ['webhook', 'Webhook', ['surfaces.webhook.secret']],
+  ['ntfy', 'ntfy', ['surfaces.ntfy.baseUrl', 'surfaces.ntfy.topic']],
+  ['googleChat', 'Google Chat', ['surfaces.googleChat.webhookUrl']],
+  ['signal', 'Signal', ['surfaces.signal.bridgeUrl', 'surfaces.signal.account']],
+  ['whatsapp', 'WhatsApp', ['surfaces.whatsapp.accessToken', 'surfaces.whatsapp.phoneNumberId']],
+  ['imessage', 'iMessage', ['surfaces.imessage.bridgeUrl', 'surfaces.imessage.account']],
+  ['msteams', 'Microsoft Teams', ['surfaces.msteams.appId', 'surfaces.msteams.appPassword']],
+  ['bluebubbles', 'BlueBubbles', ['surfaces.bluebubbles.serverUrl', 'surfaces.bluebubbles.password']],
+  ['mattermost', 'Mattermost', ['surfaces.mattermost.baseUrl', 'surfaces.mattermost.botToken']],
+  ['matrix', 'Matrix', ['surfaces.matrix.homeserverUrl', 'surfaces.matrix.accessToken', 'surfaces.matrix.userId']],
+] as const;
+
+export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise<{ readonly output: string; readonly exitCode: number }> {
+  const config = runtime.configManager;
+  const [sub = 'list', ...rest] = runtime.cli.commandArgs;
+  const target = rest[0];
+  if (sub === 'enable' || sub === 'disable') {
+    if (!target) return { output: `Usage: goodvibes surfaces ${sub} <web|listener|control-plane|surfaceId>`, exitCode: 2 };
+    const enabled = sub === 'enable';
+    if (target === 'web') {
+      runtime.configManager.setDynamic('web.enabled', enabled);
+      if (enabled) {
+        runtime.configManager.setDynamic('danger.daemon', true);
+        runtime.configManager.setDynamic('controlPlane.enabled', true);
+        const webError = applyTargetEndpointFlagsOrDefault(runtime, 'web');
+        if (webError) return { output: webError, exitCode: 2 };
+        const webBinding = resolveRuntimeEndpointBinding(runtime.configManager, 'web');
+        if (runtime.cli.flags.hostname !== undefined && webBinding.hostMode === 'local') {
+          runtime.configManager.setDynamic('controlPlane.hostMode', 'local');
+          runtime.configManager.setDynamic('controlPlane.host', '127.0.0.1');
+          runtime.configManager.setDynamic('controlPlane.allowRemote', false);
+        } else {
+          enableEndpointLanDefault(runtime.configManager, 'controlPlane');
+        }
+      }
+    }
+    else if (target === 'listener' || target === 'http-listener') {
+      runtime.configManager.setDynamic('danger.httpListener', enabled);
+      if (enabled) {
+        const listenerError = applyTargetEndpointFlagsOrDefault(runtime, 'httpListener');
+        if (listenerError) return { output: listenerError, exitCode: 2 };
+      }
+    }
+    else if (target === 'control-plane' || target === 'controlPlane') {
+      runtime.configManager.setDynamic('controlPlane.enabled', enabled);
+      runtime.configManager.setDynamic('danger.daemon', enabled);
+      if (enabled) {
+        const controlPlaneError = applyTargetEndpointFlagsOrDefault(runtime, 'controlPlane');
+        if (controlPlaneError) return { output: controlPlaneError, exitCode: 2 };
+      }
+    }
+    else if (SURFACE_CONFIGS.some(([id]) => id === target)) {
+      runtime.configManager.setDynamic(`surfaces.${target}.enabled` as ConfigKey, enabled);
+      if (enabled) {
+        runtime.configManager.setDynamic('danger.httpListener', true);
+        enableEndpointLanDefault(runtime.configManager, 'httpListener');
+      }
+    }
+    else return { output: `Unknown surface: ${target}`, exitCode: 1 };
+    if (enabled) {
+      enableServicePosture(runtime.configManager);
+    }
+    return { output: `Surface ${enabled ? 'enabled' : 'disabled'}: ${target}`, exitCode: 0 };
+  }
+  if (sub !== 'list' && sub !== 'status' && sub !== 'check' && sub !== 'show') {
+    return { output: 'Usage: goodvibes surfaces [list|check|show <surfaceId>|enable <surfaceId>|disable <surfaceId>]', exitCode: 2 };
+  }
+  const controlPlane = resolveRuntimeEndpointBinding(config, 'controlPlane');
+  const web = resolveRuntimeEndpointBinding(config, 'web');
+  const httpListener = resolveRuntimeEndpointBinding(config, 'httpListener');
+  const includeProbe = sub === 'check';
+  const [controlPlaneReachable, webReachable, listenerReachable] = includeProbe
+    ? await Promise.all([
+      probeTcp(controlPlane.host, controlPlane.port),
+      probeTcp(web.host, web.port),
+      probeTcp(httpListener.host, httpListener.port),
+    ])
+    : [undefined, undefined, undefined];
+  const externalSurfaces = SURFACE_CONFIGS.map(([id, label, requiredKeys]) => {
+    const enabled = config.get(`surfaces.${id}.enabled` as ConfigKey);
+    const missing = requiredKeys.filter((key) => !isPresentConfigValue(config.get(key as ConfigKey)));
+    return {
+      id,
+      label,
+      enabled,
+      ready: !enabled || missing.length === 0,
+      missing,
+    };
+  });
+  const filteredSurfaces = target ? externalSurfaces.filter((surface) => surface.id === target) : externalSurfaces;
+  if (target && filteredSurfaces.length === 0) return { output: `Unknown surface: ${target}`, exitCode: 1 };
+  const readinessIssues: string[] = [];
+  if (includeProbe && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
+    readinessIssues.push(`Control plane is enabled but not reachable on ${controlPlane.host}:${controlPlane.port}.`);
+  }
+  if (includeProbe && config.get('web.enabled') === true && !webReachable) {
+    readinessIssues.push(`Web surface is enabled but not reachable on ${web.host}:${web.port}.`);
+  }
+  if (includeProbe && config.get('danger.httpListener') === true && !listenerReachable) {
+    readinessIssues.push(`HTTP listener is enabled but not reachable on ${httpListener.host}:${httpListener.port}.`);
+  }
+  for (const surface of filteredSurfaces) {
+    if (surface.enabled !== true) continue;
+    if (config.get('danger.httpListener') !== true) {
+      readinessIssues.push(`${surface.label} is enabled but the HTTP listener is disabled.`);
+    }
+    if (surface.missing.length > 0) {
+      readinessIssues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
+    }
+  }
+  const value = {
+    controlPlane: {
+      enabled: config.get('controlPlane.enabled'),
+      hostMode: controlPlane.hostMode,
+      configuredHost: controlPlane.configuredHost,
+      host: controlPlane.host,
+      port: controlPlane.port,
+      reachable: controlPlaneReachable,
+    },
+    web: {
+      enabled: config.get('web.enabled'),
+      hostMode: web.hostMode,
+      configuredHost: web.configuredHost,
+      host: web.host,
+      port: web.port,
+      reachable: webReachable,
+    },
+    httpListener: {
+      enabled: config.get('danger.httpListener'),
+      hostMode: httpListener.hostMode,
+      configuredHost: httpListener.configuredHost,
+      host: httpListener.host,
+      port: httpListener.port,
+      reachable: listenerReachable,
+    },
+    surfaces: filteredSurfaces,
+    readinessIssues,
+  };
+  const output = formatJsonOrText(runtime.cli)(value, [
+    'GoodVibes surfaces',
+    `  control-plane: ${yesNo(value.controlPlane.enabled)} (${value.controlPlane.hostMode} ${value.controlPlane.host}:${value.controlPlane.port})${includeProbe ? ` reachable=${yesNo(value.controlPlane.reachable)}` : ''}`,
+    `  web: ${yesNo(value.web.enabled)} (${value.web.hostMode} ${value.web.host}:${value.web.port})${includeProbe ? ` reachable=${yesNo(value.web.reachable)}` : ''}`,
+    `  http-listener: ${yesNo(value.httpListener.enabled)} (${value.httpListener.hostMode} ${value.httpListener.host}:${value.httpListener.port})${includeProbe ? ` reachable=${yesNo(value.httpListener.reachable)}` : ''}`,
+    '',
+    'External surfaces:',
+    ...value.surfaces.map((surface) => `  ${surface.label.padEnd(16)} enabled=${yesNo(surface.enabled)} ready=${yesNo(surface.ready)}${surface.enabled && surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}`),
+    ...(includeProbe ? [
+      readinessIssues.length === 0 ? 'Readiness: ready' : 'Readiness: needs attention',
+      ...readinessIssues.map((issue) => `  - ${issue}`),
+    ] : []),
+  ].join('\n'));
+  return { output, exitCode: includeProbe && readinessIssues.length > 0 ? 1 : 0 };
+}
+
+export interface ListenerTestResult {
+  readonly enabled: unknown;
+  readonly hostMode: string;
+  readonly configuredHost: string;
+  readonly host: string;
+  readonly port: number;
+  readonly posture: ReturnType<typeof classifyBindPosture>;
+  readonly reachable: boolean;
+  readonly service: {
+    readonly enabled: unknown;
+    readonly autostart: unknown;
+    readonly restartOnFailure: unknown;
+  };
+  readonly auth: ReturnType<typeof readAuthPaths>;
+  readonly surfaces: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly enabled: unknown;
+    readonly ready: boolean;
+    readonly missing: readonly string[];
+  }[];
+  readonly issues: readonly string[];
+}
+
+export async function buildListenerTestResult(runtime: CliCommandRuntime): Promise<ListenerTestResult> {
+  const enabled = runtime.configManager.get('danger.httpListener');
+  const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'httpListener');
+  const posture = classifyBindPosture(binding);
+  const reachable = enabled === true ? await probeTcp(binding.host, binding.port) : false;
+  const auth = readAuthPaths(runtime);
+  const service = {
+    enabled: runtime.configManager.get('service.enabled'),
+    autostart: runtime.configManager.get('service.autostart'),
+    restartOnFailure: runtime.configManager.get('service.restartOnFailure'),
+  };
+  const surfaces = SURFACE_CONFIGS.map(([id, label, requiredKeys]) => {
+    const surfaceEnabled = runtime.configManager.get(`surfaces.${id}.enabled` as ConfigKey);
+    const missing = requiredKeys.filter((key) => !isPresentConfigValue(runtime.configManager.get(key as ConfigKey)));
+    return {
+      id,
+      label,
+      enabled: surfaceEnabled,
+      ready: surfaceEnabled !== true || missing.length === 0,
+      missing,
+    };
+  }).filter((surface) => surface.enabled === true);
+  const issues: string[] = [];
+  if (enabled !== true) issues.push('HTTP listener is disabled.');
+  if (enabled === true && service.enabled !== true) issues.push('HTTP listener is enabled but service mode is off.');
+  if (enabled === true && service.autostart !== true) issues.push('HTTP listener is enabled but service autostart is off.');
+  if (enabled === true && service.restartOnFailure !== true) issues.push('HTTP listener is enabled but service restart-on-failure is off.');
+  if (isNetworkFacing(enabled, binding) && !auth.userStorePresent) issues.push('Network-facing listener has no local auth user store.');
+  if (isNetworkFacing(enabled, binding) && auth.bootstrapCredentialPresent) issues.push('Network-facing listener still has a bootstrap credential file.');
+  for (const surface of surfaces) {
+    if (surface.missing.length > 0) issues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
+  }
+  return { enabled, ...binding, posture, reachable, service, auth, surfaces, issues };
+}
+
+export function formatListenerTestResult(runtime: CliCommandRuntime, value: ListenerTestResult): string {
+  return formatJsonOrText(runtime.cli)(value, [
+    'GoodVibes listener test',
+    `  enabled: ${yesNo(value.enabled)}`,
+    `  endpoint: ${value.hostMode} ${value.host}:${value.port}`,
+    `  bind posture: ${value.posture.label}`,
+    `  reachable: ${yesNo(value.reachable)}`,
+    `  service: enabled=${yesNo(value.service.enabled)} autostart=${yesNo(value.service.autostart)} restartOnFailure=${yesNo(value.service.restartOnFailure)}`,
+    `  local auth users: ${value.auth.userStorePresent ? 'present' : 'missing'}`,
+    `  bootstrap credential: ${value.auth.bootstrapCredentialPresent ? 'present' : 'missing'}`,
+    value.surfaces.length === 0 ? '  enabled webhook surfaces: none' : '  enabled webhook surfaces:',
+    ...value.surfaces.map((surface) => `    ${surface.label}: ready=${yesNo(surface.ready)}${surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}`),
+    value.issues.length === 0 ? '  readiness: ready' : '  readiness: needs attention',
+    ...value.issues.map((issue) => `    - ${issue}`),
+  ].join('\n'));
+}

package/src/cli/types.ts

@@ -3,6 +3,7 @@ export type GoodVibesCliCommand =
   | 'run'
   | 'serve'
   | 'web'
+  | 'service'
   | 'status'
   | 'doctor'
   | 'onboarding'
@@ -27,6 +28,11 @@ export type GoodVibesCliCommand =
 
 export type GoodVibesCliOutputFormat = 'text' | 'json' | 'stream-json';
 
+export interface CliCommandOutput {
+  readonly output: string;
+  readonly exitCode: number;
+}
+
 export interface GoodVibesCliFlags {
   readonly provider: string | undefined;
   readonly model: string | undefined;

package/src/cli-flags.ts

@@ -8,6 +8,7 @@ export {
   applyRuntimeFeatureFlagOverrides,
   handleGoodVibesCliCommand,
   parseGoodVibesCli,
+  renderGoodVibesCommandHelp,
   renderGoodVibesHelp,
   renderGoodVibesVersion,
 } from './cli/index.ts';

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.19.25';
+let _version = '0.19.26';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;