@pellux/goodvibes-agent 0.1.71 → 0.1.73

package/docs/deployment-and-services.md

@@ -1,52 +0,0 @@
-# Deployment And Services
-
-GoodVibes Agent is a client/operator TUI. It connects to an already-running GoodVibes runtime and does not own runtime or listener deployment.
-
-## Runtime Ownership
-
-Agent must not:
-
-- start an embedded runtime
-- start an embedded HTTP listener
-- install or uninstall OS services
-- start, stop, or restart runtime services
-- enable web, listener, control-plane, or channel surface posture
-
-Those operations belong to GoodVibes TUI or the owning runtime host. Agent reports external runtime readiness but does not configure that host.
-
-## Agent Runtime
-
-The installed package exposes one executable:
-
-```sh
-goodvibes-agent
-```
-
-The executable is backed by TypeScript-authored source with a Bun shebang. Package install smoke must verify:
-
-- `goodvibes-agent --help`
-- `goodvibes-agent --version`
-- `goodvibes-agent status --json`
-- `goodvibes-agent` launches the TUI in a real PTY
-- `goodvibes-agent smoke --json` when that command is available in the baseline being tested
-
-## External Runtime Connection
-
-Agent reads configuration and tokens, then connects to an already-running GoodVibes runtime. The default local control-plane URL is normally:
-
-```text
-http://127.0.0.1:3421
-```
-
-If the runtime is unavailable, unauthenticated, or on an incompatible SDK version, Agent commands should report actionable diagnostics without printing token values.
-
-## Release Rule
-
-Only publish Agent releases that preserve the Agent product policy:
-
-- serial/proactive assistant by default
-- local memory/routines/skills/personas until shared registries are stable
-- Agent knowledge routes only for Agent wiki calls
-- companion chat for normal assistant chat
-- explicit delegation to GoodVibes TUI for build/fix/review work
-- WRFC only when explicitly requested for delegated build/fix/review work

package/src/cli/service-command.ts

@@ -1,26 +0,0 @@
-import type { CliCommandRuntime } from './management.ts';
-import { buildCliServicePosture, formatCliServicePosture } from './service-posture.ts';
-import type { CliCommandOutput } from './types.ts';
-
-export async function handleServiceCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
-  const [sub = 'status'] = runtime.cli.commandArgs;
-  const json = runtime.cli.flags.outputFormat === 'json';
-  if (sub === 'status' || sub === 'check') {
-    const posture = await buildCliServicePosture(runtime, { probe: sub === 'check' });
-    return {
-      output: formatCliServicePosture(posture, json),
-      exitCode: sub === 'check' && posture.issues.length > 0 ? 1 : 0,
-    };
-  }
-  if (sub === 'install' || sub === 'start' || sub === 'restart' || sub === 'stop' || sub === 'uninstall') {
-    const text = 'GoodVibes Agent connects to an existing GoodVibes runtime and does not manage runtime lifecycle. Use GoodVibes TUI or host tooling for service mutations.';
-    return {
-      output: json ? JSON.stringify({ ok: false, kind: 'daemon_lifecycle_external', action: sub, error: text }, null, 2) : text,
-      exitCode: 2,
-    };
-  }
-  return {
-    output: `Usage: ${runtime.cli.binary} service [status|check]`,
-    exitCode: 2,
-  };
-}

package/src/cli/surface-command.ts

@@ -1,247 +0,0 @@
-import type { ConfigKey } from '../config/index.ts';
-import {
-  GOODVIBES_NTFY_AGENT_TOPIC,
-  GOODVIBES_NTFY_CHAT_TOPIC,
-  GOODVIBES_NTFY_REMOTE_TOPIC,
-  resolveGoodVibesNtfyTopics,
-} from '@pellux/goodvibes-sdk/platform/integrations';
-import { getMissingSurfaceFeatureFlags } from '../runtime/surface-feature-flags.ts';
-import { resolveRuntimeEndpointBinding } from './endpoints.ts';
-import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
-import type { CliCommandRuntime } from './management.ts';
-import {
-  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']],
-  ['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-agent surfaces ${sub} <web|listener|control-plane|surfaceId>`, exitCode: 2 };
-    const text = [
-      'GoodVibes Agent does not mutate runtime, listener, web, or channel surface posture.',
-      'Configure those surfaces from GoodVibes TUI or the external GoodVibes runtime host, then use `goodvibes-agent surfaces check` for read-only diagnostics.',
-    ].join(' ');
-    return {
-      output: formatJsonOrText(runtime.cli)({
-        ok: false,
-        kind: 'daemon_lifecycle_external',
-        action: `surfaces.${sub}`,
-        target,
-        error: text,
-      }, text),
-      exitCode: 2,
-    };
-  }
-  if (sub !== 'list' && sub !== 'status' && sub !== 'check' && sub !== 'show') {
-    return { output: 'Usage: goodvibes-agent surfaces [list|check|show <surfaceId>]', exitCode: 2 };
-  }
-  const controlPlane = resolveRuntimeEndpointBinding(config, 'controlPlane');
-  const web = resolveRuntimeEndpointBinding(config, 'web');
-  const httpListener = resolveRuntimeEndpointBinding(config, 'httpListener');
-  const includeProbe = sub === 'check';
-  const targetExternalSurface = target && SURFACE_CONFIGS.some(([id]) => id === target);
-  const shouldProbeControlPlane = includeProbe && !target;
-  const shouldProbeWeb = includeProbe && !target;
-  const shouldProbeListener = includeProbe && (!target || targetExternalSurface);
-  const [controlPlaneReachable, webReachable, listenerReachable] = includeProbe
-    ? await Promise.all([
-      shouldProbeControlPlane ? probeTcp(controlPlane.host, controlPlane.port) : Promise.resolve(undefined),
-      shouldProbeWeb ? probeTcp(web.host, web.port) : Promise.resolve(undefined),
-      shouldProbeListener ? probeTcp(httpListener.host, httpListener.port) : Promise.resolve(undefined),
-    ])
-    : [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)));
-    const missingFeatureFlags = enabled === true ? getMissingSurfaceFeatureFlags(config, id) : [];
-    return {
-      id,
-      label,
-      enabled,
-      ready: !enabled || (missing.length === 0 && missingFeatureFlags.length === 0),
-      missing,
-      missingFeatureFlags,
-    };
-  });
-  const filteredSurfaces = target ? externalSurfaces.filter((surface) => surface.id === target) : externalSurfaces;
-  if (target && filteredSurfaces.length === 0) return { output: `Unknown surface: ${target}`, exitCode: 1 };
-  const ntfyTopics = resolveGoodVibesNtfyTopics({
-    chatTopic: String(config.get('surfaces.ntfy.chatTopic' as ConfigKey) || GOODVIBES_NTFY_CHAT_TOPIC),
-    agentTopic: String(config.get('surfaces.ntfy.agentTopic' as ConfigKey) || GOODVIBES_NTFY_AGENT_TOPIC),
-    remoteTopic: String(config.get('surfaces.ntfy.remoteTopic' as ConfigKey) || GOODVIBES_NTFY_REMOTE_TOPIC),
-  });
-  const readinessIssues: string[] = [];
-  if (shouldProbeControlPlane && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
-    readinessIssues.push(`Control plane is enabled but not reachable on ${controlPlane.host}:${controlPlane.port}.`);
-  }
-  if (shouldProbeWeb && config.get('web.enabled') === true && !webReachable) {
-    readinessIssues.push(`Web surface is enabled but not reachable on ${web.host}:${web.port}.`);
-  }
-  if (shouldProbeListener && 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(', ')}.`);
-    }
-    if (surface.missingFeatureFlags.length > 0) {
-      readinessIssues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.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 Agent 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(',')}` : ''}${surface.enabled && surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
-    ...(filteredSurfaces.some((surface) => surface.id === 'ntfy') ? [
-      '',
-      'ntfy inbound topics:',
-      `  chat: ${ntfyTopics.chatTopic}`,
-      `  agent: ${ntfyTopics.agentTopic}`,
-      `  runtime-only remote: ${ntfyTopics.remoteTopic}`,
-      `  default delivery topic: ${String(config.get('surfaces.ntfy.topic') || '(none)')}`,
-    ] : []),
-    ...(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 missingFeatureFlags: 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)));
-    const missingFeatureFlags = surfaceEnabled === true ? getMissingSurfaceFeatureFlags(runtime.configManager, id) : [];
-    return {
-      id,
-      label,
-      enabled: surfaceEnabled,
-      ready: surfaceEnabled !== true || (missing.length === 0 && missingFeatureFlags.length === 0),
-      missing,
-      missingFeatureFlags,
-    };
-  }).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 on the external runtime config, but Agent service ownership is disabled.');
-  if (enabled === true && service.autostart !== true) issues.push('HTTP listener is enabled on the external runtime config, but autostart is off.');
-  if (enabled === true && service.restartOnFailure !== true) issues.push('HTTP listener is enabled on the external runtime config, but 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(', ')}.`);
-    if (surface.missingFeatureFlags.length > 0) issues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.join(', ')}.`);
-  }
-  return { enabled, ...binding, posture, reachable, service, auth, surfaces, issues };
-}
-
-export function formatListenerTestResult(runtime: CliCommandRuntime, value: ListenerTestResult): string {
-  return formatJsonOrText(runtime.cli)(value, [
-    'GoodVibes Agent 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(',')}` : ''}${surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
-    value.issues.length === 0 ? '  readiness: ready' : '  readiness: needs attention',
-    ...value.issues.map((issue) => `    - ${issue}`),
-  ].join('\n'));
-}