@pellux/goodvibes-tui 0.19.27 → 0.19.29

package/src/input/onboarding/onboarding-wizard-steps.ts

@@ -1,8 +1,14 @@
 import { NETWORK_MODE_OPTIONS, REASONING_OPTIONS, HITL_MODE_OPTIONS, GUIDANCE_MODE_OPTIONS, PERMISSION_MODE_OPTIONS, SECRET_POLICY_OPTIONS } from './onboarding-wizard-constants.ts';
-import { EXTERNAL_SURFACE_SPECS } from './onboarding-wizard-external-surfaces.ts';
+import {
+  EXTERNAL_SURFACE_SPECS,
+  getExternalSurfaceAutoStartDefaultValue,
+  getExternalSurfaceAutoStartFieldId,
+  isExternalSurfaceSelectedByDefault,
+  type ExternalSurfaceSpec,
+} from './onboarding-wizard-external-surfaces.ts';
 import { countSelected, modelSelectionLabel, normalizeText } from './onboarding-wizard-helpers.ts';
 import type { OnboardingWizardController } from './onboarding-wizard.ts';
-import type { OnboardingWizardAcknowledgementFieldDefinition, OnboardingWizardChecklistFieldDefinition, OnboardingWizardFieldDefinition, OnboardingWizardModelPickerFieldDefinition, OnboardingWizardRadioFieldDefinition, OnboardingWizardStepDefinition } from './onboarding-wizard-types.ts';
+import type { OnboardingWizardAcknowledgementFieldDefinition, OnboardingWizardChecklistFieldDefinition, OnboardingWizardExternalSurfaceStepId, OnboardingWizardFieldDefinition, OnboardingWizardModelPickerFieldDefinition, OnboardingWizardRadioFieldDefinition, OnboardingWizardRadioOption, OnboardingWizardStepDefinition } from './onboarding-wizard-types.ts';
 
 export function buildOnboardingWizardSteps(controller: OnboardingWizardController): readonly OnboardingWizardStepDefinition[] {
   if (controller.hydrationPending || controller.hydrationError !== null) return [buildLoadingStep(controller)];
@@ -24,6 +30,9 @@ export function buildOnboardingWizardSteps(controller: OnboardingWizardControlle
 
   if (wantsExternalServices) {
     steps.push(buildExternalServicesStep(controller));
+    for (const surface of getSelectedExternalSurfaceSpecs(controller)) {
+      steps.push(buildExternalSurfaceStep(controller, surface));
+    }
   }
 
   steps.push(buildProviderAccessStep(controller));
@@ -83,7 +92,7 @@ export function buildCapabilitiesStep(controller: OnboardingWizardController): O
         id: 'capabilities.select-all',
         action: 'select-all-capabilities',
         label: 'Select all server-backed capabilities',
-        hint: 'Enable browser access, other-device LAN access, webhooks/events, and external integrations. Local TUI Only is turned off.',
+        hint: 'Enable browser access, LAN reachability, webhooks/events, and external app surfaces. Local TUI Only is turned off.',
         defaultValue: 'Action',
       },
       {
@@ -98,9 +107,9 @@ export function buildCapabilitiesStep(controller: OnboardingWizardController): O
 
     return {
       id: 'capabilities',
-      title: 'What should GoodVibes be able to do?',
+      title: 'Choose GoodVibes capabilities',
       shortLabel: 'Capabilities',
-      description: 'Choose the features this install should enable. Local TUI Only is selected when no server-backed capabilities are enabled.',
+      description: 'Choose what GoodVibes should be able to do. Local TUI Only avoids servers; any other choice enables service mode and autostart.',
       summaryTitle: 'Selected capabilities',
       summaryLines: [
         `${selectedCount}/${capabilities.length} option(s) selected`,
@@ -263,68 +272,169 @@ export function buildDefaultModelStep(controller: OnboardingWizardController): O
   }
 
 export function buildExternalServicesStep(controller: OnboardingWizardController): OnboardingWizardStepDefinition {
-    const enabledCount = EXTERNAL_SURFACE_SPECS
-      .filter((surface) => controller.getBooleanFieldValue(surface.enabledFieldId, surface.defaultEnabled(controller.runtimeSnapshot)))
+    const selectedCount = EXTERNAL_SURFACE_SPECS
+      .filter((surface) => controller.getBooleanFieldValue(
+        surface.enabledFieldId,
+        isExternalSurfaceSelectedByDefault(surface, controller.runtimeSnapshot),
+      ))
       .length;
     const fields: OnboardingWizardFieldDefinition[] = [];
 
     for (const surface of EXTERNAL_SURFACE_SPECS) {
-      const enabled = controller.getBooleanFieldValue(surface.enabledFieldId, surface.defaultEnabled(controller.runtimeSnapshot));
       fields.push({
         kind: 'checklist',
         id: surface.enabledFieldId,
         label: surface.label,
-        hint: surface.hint,
-        defaultValue: surface.defaultEnabled(controller.runtimeSnapshot),
+        hint: `${surface.hint} Selecting this opens a dedicated setup screen; auto-start is chosen on that screen.`,
+        defaultValue: isExternalSurfaceSelectedByDefault(surface, controller.runtimeSnapshot),
       });
+    }
 
-      if (!enabled) continue;
-      for (const setupField of surface.fields) {
-        if (setupField.kind === 'radio') {
-          fields.push({
-            kind: 'radio',
-            id: setupField.id,
-            label: setupField.label,
-            hint: setupField.hint,
-            options: setupField.options ?? [],
-            defaultValue: setupField.defaultValue(controller.runtimeSnapshot),
-          });
-          continue;
+    fields.push(
+      {
+        kind: 'action',
+        id: 'external-services.select-all',
+        action: 'select-all-external-surfaces',
+        label: 'Select all external surfaces',
+        hint: 'Show setup screens for every supported external surface. Auto-start stays controlled per surface.',
+        defaultValue: 'Action',
+      },
+      {
+        kind: 'action',
+        id: 'external-services.clear',
+        action: 'clear-external-surfaces',
+        label: 'Clear all external surfaces',
+        hint: 'Hide all external surface setup screens. The HTTP listener can still be enabled separately by webhook/event capabilities.',
+        defaultValue: 'Action',
+      },
+      {
+        kind: 'radio',
+        id: 'external-services.secret-policy',
+        label: 'Secret storage policy',
+        hint: 'Choose how selected surface secrets should be stored. Secret values are never shown in the wizard.',
+        options: SECRET_POLICY_OPTIONS,
+        defaultValue: controller.runtimeSnapshot?.runtimeDefaults.secretStoragePolicy ?? 'preferred_secure',
+      },
+    );
+
+    return {
+      id: 'external-services',
+      title: 'Choose external surfaces',
+      shortLabel: 'Services',
+      description: 'Select the apps and integration surfaces GoodVibes should prepare. Each selected surface gets its own setup screen and its own auto-start choice.',
+      summaryTitle: 'External surfaces',
+      summaryLines: [
+        `${selectedCount} external surface(s) selected for setup`,
+        `Secret policy: ${controller.getStringFieldValue('external-services.secret-policy', controller.runtimeSnapshot?.runtimeDefaults.secretStoragePolicy ?? 'preferred_secure')}`,
+        selectedCount > 0 ? 'Selected surfaces appear as separate setup screens.' : 'No external surfaces selected.',
+      ],
+      fields,
+    };
+  }
+
+function getSelectedExternalSurfaceSpecs(controller: OnboardingWizardController): readonly ExternalSurfaceSpec[] {
+    return EXTERNAL_SURFACE_SPECS.filter((surface) => (
+      controller.getBooleanFieldValue(
+        surface.enabledFieldId,
+        isExternalSurfaceSelectedByDefault(surface, controller.runtimeSnapshot),
+      )
+    ));
+  }
+
+const SURFACE_AUTO_START_OPTIONS: readonly OnboardingWizardRadioOption[] = [
+  {
+    id: 'yes',
+    label: 'Yes',
+    hint: 'Start this surface automatically when the GoodVibes service starts.',
+  },
+  {
+    id: 'no',
+    label: 'No',
+    hint: 'Save these settings but leave the surface idle until it is enabled from Settings > Surfaces.',
+  },
+];
+
+function buildExternalSurfaceStep(
+  controller: OnboardingWizardController,
+  surface: ExternalSurfaceSpec,
+): OnboardingWizardStepDefinition {
+    let setupCount = 0;
+    let setupCompleteCount = 0;
+    const autoStartFieldId = getExternalSurfaceAutoStartFieldId(surface);
+    const autoStartDefault = getExternalSurfaceAutoStartDefaultValue(surface, controller.runtimeSnapshot);
+    const autoStartValue = controller.getStringFieldValue(autoStartFieldId, autoStartDefault);
+    const setupFields = surface.fields.map((setupField): OnboardingWizardFieldDefinition => {
+      const suggested = controller.isRequiredExternalSetupField(setupField.id);
+      if (suggested) {
+        setupCount += 1;
+        if (normalizeText(setupField.defaultValue(controller.runtimeSnapshot)).length > 0
+          || normalizeText(controller.getStringFieldValue(setupField.id, '')).length > 0) {
+          setupCompleteCount += 1;
         }
+      }
 
-        fields.push({
-          kind: setupField.kind,
+      const hint = suggested
+        ? `${setupField.hint} Recommended because ${surface.label} is selected, but it will not block saving.`
+        : setupField.hint;
+
+      if (setupField.kind === 'radio') {
+        return {
+          kind: 'radio',
           id: setupField.id,
           label: setupField.label,
-          hint: setupField.hint,
-          placeholder: setupField.placeholder,
+          hint,
+          options: setupField.options ?? [],
           defaultValue: setupField.defaultValue(controller.runtimeSnapshot),
-          required: controller.isRequiredExternalSetupField(setupField.id),
-        });
+        };
       }
-    }
 
-    fields.push({
-      kind: 'radio',
-      id: 'external-services.secret-policy',
-      label: 'Secret storage policy',
-      hint: 'Choose how external integration secrets should be stored.',
-      options: SECRET_POLICY_OPTIONS,
-      defaultValue: controller.runtimeSnapshot?.runtimeDefaults.secretStoragePolicy ?? 'preferred_secure',
+      return {
+        kind: setupField.kind,
+        id: setupField.id,
+        label: setupField.label,
+        hint,
+        placeholder: setupField.placeholder,
+        defaultValue: setupField.defaultValue(controller.runtimeSnapshot),
+      };
     });
+    const ntfyTopicSummary = surface.id === 'ntfy'
+      ? [
+          `Chat topic: ${controller.getStringFieldValue('external-services.ntfy.chat-topic', 'goodvibes-chat')}`,
+          `Agent topic: ${controller.getStringFieldValue('external-services.ntfy.agent-topic', 'goodvibes-agent')}`,
+          `Daemon-only remote topic: ${controller.getStringFieldValue('external-services.ntfy.remote-topic', 'goodvibes-ntfy')}`,
+        ]
+      : [];
+    const title = `${surface.label.replace(/ surface$/i, '')} setup`;
+    const setupSummary = setupCount === 0
+      ? 'Suggested setup: none'
+      : `Suggested setup entered: ${setupCompleteCount}/${setupCount}`;
 
     return {
-      id: 'external-services',
-      title: 'External apps and services',
-      shortLabel: 'Services',
-      description: 'Select each external surface this install should prepare and enter its setup values directly in the wizard. Sensitive fields remain masked.',
-      summaryTitle: 'External service summary',
+      id: `external-surface:${surface.id}` as OnboardingWizardExternalSurfaceStepId,
+      title,
+      shortLabel: surface.label.replace(/ surface$/i, ''),
+      description: `Configure ${surface.label}. Settings are saved either way; auto-start controls whether this surface starts with the background service.`,
+      summaryTitle: `${surface.label} setup`,
       summaryLines: [
-        `${enabledCount} external surface(s) selected`,
+        `Auto-start: ${autoStartValue === 'yes' ? 'yes' : 'no'}`,
+        ...ntfyTopicSummary,
+        setupSummary,
         `Secret policy: ${controller.getStringFieldValue('external-services.secret-policy', controller.runtimeSnapshot?.runtimeDefaults.secretStoragePolicy ?? 'preferred_secure')}`,
-        'Secrets remain masked and policy-controlled.',
+        autoStartValue === 'yes'
+          ? 'The surface will be enabled after apply.'
+          : 'Start it later from Settings > Surfaces by turning Enabled on.',
+      ],
+      fields: [
+        {
+          kind: 'radio',
+          id: autoStartFieldId,
+          label: 'Auto-start this surface',
+          hint: `Yes turns on ${surface.enabledConfigKey}. No saves setup values but keeps the surface off until Settings > Surfaces enables it.`,
+          options: SURFACE_AUTO_START_OPTIONS,
+          defaultValue: autoStartDefault,
+        },
+        ...setupFields,
       ],
-      fields,
     };
   }
 
@@ -510,34 +620,36 @@ export function buildAccountsStep(controller: OnboardingWizardController): Onboa
     const needsAuthBootstrap = controller.requiresAuthBootstrap();
     const needsExistingAuthAcknowledgement = controller.hasServerCapabilitiesSelected()
       && !needsAuthBootstrap
-      && controller.hasAdminAuthUser();
+      && controller.hasLocalAuthUser();
     const fields: OnboardingWizardFieldDefinition[] = [];
+    const defaultAdminUsername = controller.getDefaultAdminUsername();
 
-    if (needsAuthBootstrap) {
-      const defaultAdminUsername = controller.getDefaultAdminUsername();
-      fields.push(
-        {
-          kind: 'text',
-          id: 'accounts.admin-username',
-          label: 'Local auth admin username',
-          hint: 'Required before any background service, browser surface, or listener is exposed.',
-          placeholder: defaultAdminUsername,
-          defaultValue: defaultAdminUsername,
-          required: true,
-        },
-        {
-          kind: 'masked',
-          id: 'accounts.admin-password',
-          label: 'Local auth admin password',
-          hint: controller.hasBootstrapCredentialPresent()
-            ? 'Creates a new local admin, removes the bootstrap credential file, and retires the bootstrap admin before LAN/server settings are applied.'
-            : 'Creates the first local admin user and an initial session before LAN/server settings are applied.',
-          placeholder: 'password required',
-          defaultValue: '',
-          required: true,
-        },
-      );
-    }
+    fields.push(
+      {
+        kind: 'text',
+        id: 'accounts.admin-username',
+        label: 'Local auth admin username',
+        hint: needsAuthBootstrap
+          ? 'Required before any background service, browser surface, or listener is exposed.'
+          : 'Optional. Enter an existing admin username to rotate its password, or a new username to create another admin.',
+        placeholder: defaultAdminUsername,
+        defaultValue: defaultAdminUsername,
+        required: needsAuthBootstrap,
+      },
+      {
+        kind: 'masked',
+        id: 'accounts.admin-password',
+        label: 'Local auth admin password',
+        hint: needsAuthBootstrap
+          ? controller.hasBootstrapCredentialPresent()
+            ? 'Creates or updates the named local admin, removes the bootstrap credential file, and retires the bootstrap admin when it is a different user.'
+            : 'Creates the first local admin user and an initial session before LAN/server settings are applied.'
+          : 'Optional. Leave blank to keep existing local auth unchanged; enter a password to create or rotate the named admin user.',
+        placeholder: needsAuthBootstrap ? 'password required' : 'leave blank to keep unchanged',
+        defaultValue: '',
+        required: needsAuthBootstrap,
+      },
+    );
 
     fields.push(
       {
@@ -563,13 +675,17 @@ export function buildAccountsStep(controller: OnboardingWizardController): Onboa
       {
         kind: 'status',
         id: 'accounts.bootstrap',
-        label: 'Bootstrap credential hint',
+        label: 'Local auth readiness',
         hint: needsAuthBootstrap
           ? 'The wizard will create local auth before applying network-accessible settings.'
-          : 'Masked auth state stays visible without leaking sensitive values.',
+          : controller.hasAdminAuthUser()
+            ? 'An existing local auth admin user was detected and will be kept.'
+            : controller.hasLocalAuthUser()
+              ? 'Existing local auth users were detected and will be kept.'
+              : 'No server-backed capability is selected, so local auth is not required.',
         defaultValue: needsAuthBootstrap
           ? controller.hasBootstrapCredentialPresent() ? 'Bootstrap replacement required' : 'Local admin required'
-          : auth?.bootstrapCredentialPresent ? 'Configured' : 'Not detected',
+          : controller.hasAdminAuthUser() ? 'Admin detected' : controller.hasLocalAuthUser() ? 'Local auth detected' : 'Not required',
       },
       {
         kind: 'status',
@@ -586,7 +702,7 @@ export function buildAccountsStep(controller: OnboardingWizardController): Onboa
       shortLabel: 'Accounts',
       description: needsAuthBootstrap
         ? 'Create wizard-owned local auth before any LAN, browser, service, or listener settings are applied.'
-        : 'Require explicit acknowledgement for existing subscription or local-auth state when reopening the wizard in edit mode.',
+        : 'Review existing subscription and local auth state. Existing local auth is kept unless you change it elsewhere.',
       summaryTitle: 'Stored account state',
       summaryLines: [
         `Subscriptions: ${controller.runtimeSnapshot?.subscriptions.active.length ?? 0} active / ${controller.runtimeSnapshot?.subscriptions.pending.length ?? 0} pending`,
@@ -595,46 +711,63 @@ export function buildAccountsStep(controller: OnboardingWizardController): Onboa
           ? controller.hasBootstrapCredentialPresent()
             ? 'Bootstrap credentials will be replaced before network settings are applied'
             : 'Local admin will be created before network settings are applied'
-          : auth?.bootstrapCredentialPresent ? 'Bootstrap credential file present' : 'No bootstrap credential file detected',
+          : controller.hasLocalAuthUser() ? 'Existing local auth will be kept' : 'Local auth is not required for this setup',
       ],
       fields,
     };
   }
 
 export function buildReviewStep(controller: OnboardingWizardController): OnboardingWizardStepDefinition {
+    const feedback = controller.applyFeedback;
+    const feedbackFields: OnboardingWizardFieldDefinition[] = feedback
+      ? [
+          {
+            kind: 'status',
+            id: 'review.feedback',
+            label: feedback.title,
+            hint: feedback.summary,
+            defaultValue: feedback.severity === 'error' ? 'Needs attention' : feedback.severity === 'warning' ? 'Warning' : 'Info',
+          },
+          ...feedback.messages.slice(0, 8).map((message, index): OnboardingWizardFieldDefinition => ({
+            kind: 'status',
+            id: `review.feedback.${index}`,
+            label: message,
+            hint: message,
+            defaultValue: feedback.severity === 'error' ? 'Error' : feedback.severity === 'warning' ? 'Warning' : 'Info',
+          })),
+        ]
+      : [];
+    const unsavedLabel = controller.dirtyStepCount === 1
+      ? '1 screen has unapplied changes'
+      : `${controller.dirtyStepCount} screens have unapplied changes`;
+
     return {
       id: 'review',
-      title: 'Review and completion',
+      title: 'Review and apply',
       shortLabel: 'Review',
       description: 'Review the selected settings and apply them directly from the wizard.',
       summaryTitle: 'Review posture',
       summaryLines: [
-        `${controller.dirtyStepCount} dirty step(s)`,
-        `${controller.buildApplyRequest().operations.length} operation(s) ready to apply`,
-        `Pending picker: ${controller.pendingModelPickerTarget ?? 'none'}`,
-        controller.isEditingTextField() ? `Editing: ${controller.editingFieldId}` : 'Ready for apply/verify',
+        unsavedLabel,
+        `${controller.buildApplyRequest().operations.length} settings change(s) ready to apply`,
+        feedback ? `Last apply: ${feedback.title}` : 'No apply errors reported',
+        controller.isEditingTextField() ? `Editing: ${controller.editingFieldId}` : 'Ready to apply',
       ],
       fields: [
+        ...feedbackFields,
         {
-          kind: 'checklist',
-          id: 'review.project-marker',
-          label: 'Write project completion marker',
-          hint: 'Project scope keeps the workspace-specific completion state close to the repo.',
-          defaultValue: true,
-        },
-        {
-          kind: 'checklist',
-          id: 'review.user-marker',
-          label: 'Write user completion marker',
-          hint: 'User scope keeps the shell-level completion marker available outside this workspace.',
-          defaultValue: controller.defaultReviewUserMarker(),
+          kind: 'status',
+          id: 'review.global-marker',
+          label: 'Global onboarding check',
+          hint: 'Opening this wizard marks onboarding as shown for this user account, so new projects do not reopen it automatically.',
+          defaultValue: 'Already marked as shown',
         },
         {
           kind: 'action',
           id: 'review.apply',
           action: 'apply',
           label: 'Apply settings and verify',
-          hint: 'Persist the wizard settings, write completion markers, and verify the resulting runtime state.',
+          hint: 'Persist the wizard settings and verify the resulting runtime state. The global onboarding check was already recorded when the wizard opened.',
           defaultValue: 'Ready',
         },
       ],

package/src/input/onboarding/onboarding-wizard-types.ts

@@ -16,12 +16,15 @@ import type { ConfigKey } from '../../config/index.ts';
 
 export type OnboardingWizardMode = OnboardingMode;
 
+export type OnboardingWizardExternalSurfaceStepId = `external-surface:${string}`;
+
 export type OnboardingWizardStepId =
   | 'loading'
   | 'capabilities'
   | 'network'
   | 'access'
   | 'external-services'
+  | OnboardingWizardExternalSurfaceStepId
   | 'provider-access'
   | 'default-model'
   | 'experience'
@@ -41,9 +44,20 @@ export type OnboardingWizardAction =
   | 'apply'
   | 'select-all-capabilities'
   | 'clear-capabilities'
+  | 'select-all-external-surfaces'
+  | 'clear-external-surfaces'
   | 'start-openai-subscription'
   | 'finish-openai-subscription';
 
+export type OnboardingWizardApplyFeedbackSeverity = 'info' | 'warning' | 'error';
+
+export interface OnboardingWizardApplyFeedback {
+  readonly severity: OnboardingWizardApplyFeedbackSeverity;
+  readonly title: string;
+  readonly summary: string;
+  readonly messages: readonly string[];
+}
+
 export interface OnboardingWizardRadioOption {
   readonly id: string;
   readonly label: string;
@@ -159,6 +173,7 @@ export interface OnboardingWizardSnapshot {
   readonly editBuffer: string;
   readonly hydrationPending: boolean;
   readonly hydrationError: string | null;
+  readonly applyFeedback: OnboardingWizardApplyFeedback | null;
   readonly hydration: OnboardingWizardRuntimeHydration;
 }