Skip to content

onboarding support#12

Merged
newbe36524 merged 1 commit intomainfrom
flow
Feb 9, 2026
Merged

onboarding support#12
newbe36524 merged 1 commit intomainfrom
flow

Conversation

@newbe36524
Copy link
Contributor

@newbe36524 newbe36524 commented Feb 9, 2026

Summary by CodeRabbit

Release Notes

  • New Features

    • Added first-time user onboarding wizard with guided setup flow for new installations
    • Improved empty-state messaging with clear "Start Setup Wizard" button
    • Integrated build status notifications to external services
    • Enhanced port discovery and management for web service startup
  • Improvements

    • Unified update source configuration supporting environment variable overrides
    • Enhanced version download progress tracking and reporting
    • Improved dependency installation feedback with live progress updates
    • Added comprehensive development documentation
  • Documentation

    • Added development setup guide with configuration options
    • Updated README with update source configuration details

@coderabbitai
Copy link

coderabbitai bot commented Feb 9, 2026

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR introduces a comprehensive first-time user onboarding wizard for Hagicode Desktop, along with supporting infrastructure including CI/CD Feishu notifications, unified update source configuration, enhanced version management UI, Redux state management layers, IPC communication handlers, and extensive English/Chinese internationalization.

Changes

Cohort / File(s) Summary
CI/CD and Build Notifications
.github/workflows/build.yml, openspec/changes/archive/2026-02-09-feishu-build-release-notification/*, openspec/changes/archive/2026-02-09-feishu-notification-composite-action/*
Added three new steps to Build Summary job: determine workflow status, compile successful platforms, and send Feishu webhook notifications. Includes detailed proposal specs, implementation tasks, and alternative composite action approach. Changes expose build results via job outputs for downstream notification steps.
Documentation and Configuration
README.md, README.zh-CN.md, docs/development.md, openspec/project.md, src/main/config.ts
Extended README files with UPDATE_SOURCE_OVERRIDE environment variable documentation; added comprehensive development guide covering update sources, environment setup, and debugging; updated project manifest; changed default server port from 3000 to 36546.
Update Source Configuration
src/main/package-source-config-manager.ts, src/main/package-sources/http-index-source.ts, src/main/version-manager.ts, openspec/changes/archive/2026-02-10-unified-update-source-config/*
Unified default package source to HTTP index for development and production; added UPDATE_SOURCE_OVERRIDE environment variable support with validation; enhanced version comparison to support semantic versioning with pre-release tags; extended VersionManager.installVersion with optional progress callback; includes proposal, specs, and implementation tasks.
Main Process Onboarding and Managers
src/main/main.ts, src/main/onboarding-manager.ts, src/main/web-service-manager.ts
Added OnboardingManager class coordinating download, dependency installation, and service startup with progress callbacks and state persistence via electron-store; registered 11 new IPC handlers for onboarding lifecycle; enhanced WebServiceManager with OS-specific port checking and auto-increment retry logic; emits version:activeVersionChanged events to renderer on version changes.
Preload and IPC Bridge
src/preload/index.ts
Exposed 11 onboarding control methods and 3 progress event listeners to renderer via electronAPI, plus openHagicodeInApp, onOnboardingSwitchToWeb, and onOnboardingOpenHagicode handlers for cross-process communication.
Onboarding Types and Definitions
src/types/onboarding.ts, openspec/changes/archive/2026-02-09-first-time-user-onboarding-wizard/*, openspec/changes/archive/2026-02-09-improve-empty-state-button-clarity/*, openspec/changes/archive/2026-02-09-onboarding-wizard-version-download-fix/*
Defined OnboardingStep, DownloadProgress, DependencyItem, ServiceLaunchProgress, OnboardingState, and StoredOnboardingState interfaces; includes comprehensive onboarding proposal with UI mocks, detailed specs, implementation tasks, and related fixes for download progress propagation and empty-state button clarity.
Redux State Management
src/renderer/store/index.ts, src/renderer/store/slices/onboardingSlice.ts, src/renderer/store/thunks/onboardingThunks.ts
Added onboardingReducer to root store; created onboardingSlice with 10 action creators and 10 selectors covering state mutations, thunk handlers for all onboarding steps, and computed selectors for navigation logic; defined 8 async thunks (checkTrigger, skip, download, checkDeps, installDeps, startService, complete, reset) and 2 sync actions for step navigation.
Onboarding UI Components
src/renderer/components/onboarding/*, src/renderer/components/SystemManagementView.tsx, src/renderer/components/VersionManagementPage.tsx, src/renderer/App.tsx
Created OnboardingWizard main orchestrator; 4 step-specific components (WelcomeIntro, PackageDownload, DependencyInstaller, ServiceLauncher); 3 helper components (OnboardingProgress, OnboardingActions, SkipConfirmDialog); integrated onboarding into App.tsx with event listeners; added handleStartWizard to SystemManagementView and handleStartOnboarding to VersionManagementPage with toast notifications.
Internationalization
src/renderer/i18n/index.ts, src/renderer/i18n/locales/zh-CN/*, src/renderer/i18n/locales/en-US/*
Added onboarding.json translation files (zh-CN and en-US) with 117 keys covering all wizard steps, progress states, and guidance; extended common.json and pages.json with system.noVersionInstalled and versionManagement.noVersionsInstalled blocks; wired onboarding namespace into i18next resources.
OpenSpec and Planning
openspec/changes/archive/2026-02-09-first-time-user-onboarding-wizard/, openspec/changes/archive/2026-02-09-improve-empty-state-button-clarity/, remaining openspec task and proposal files
Comprehensive specifications and implementation guides for onboarding wizard (proposal, specs, tasks), empty-state button improvements (proposal, i18n specs, tasks), and related onboarding fixes; documents user flows, acceptance criteria, and phased implementation plans without executable code changes.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant UI as Renderer UI
    participant Store as Redux Store
    participant Thunk as Async Thunk
    participant IPC as IPC Bridge
    participant Main as Main Process
    participant VM as VersionManager
    participant DM as DependencyManager
    participant WSM as WebServiceManager

    User->>UI: Enter Onboarding
    UI->>Store: dispatch(checkOnboardingTrigger())
    Store->>Thunk: execute thunk
    Thunk->>IPC: electronAPI.checkTriggerCondition()
    IPC->>Main: onboarding:check-trigger
    Main->>Main: OnboardingManager.checkTriggerCondition()
    Main-->>IPC: { shouldShow: true }
    IPC-->>Thunk: result
    Thunk-->>Store: fulfilled payload

    User->>UI: Click Next → Download
    UI->>Store: dispatch(downloadPackage())
    Store->>Thunk: execute thunk
    Thunk->>IPC: electronAPI.downloadPackage()
    IPC->>Main: onboarding:download-package
    Main->>VM: VersionManager.installVersion(versionId, onProgress)
    VM->>VM: downloadPackage(onProgress callback)
    VM-->>Main: progress events
    Main->>IPC: emit onboarding:download-progress
    IPC-->>UI: progress callback
    UI->>Store: dispatch(setDownloadProgress(progress))
    Store-->>UI: update UI

    VM-->>Main: download complete
    Main-->>Thunk: { success: true, version }
    Thunk-->>Store: fulfilled with version
    Store-->>UI: update downloadProgress state

    User->>UI: Click Next → Dependencies
    UI->>Store: dispatch(installDependencies(version))
    Store->>Thunk: execute thunk
    Thunk->>IPC: electronAPI.installDependencies(version)
    IPC->>Main: onboarding:install-dependencies
    Main->>DM: DependencyManager.installDependencies()
    DM-->>Main: progress events
    Main->>IPC: emit onboarding:dependency-progress
    IPC-->>UI: progress callback
    UI->>Store: dispatch(setDependenciesStatus(status))

    User->>UI: Click Next → Launch Service
    UI->>Store: dispatch(startService(version))
    Store->>Thunk: execute thunk
    Thunk->>IPC: electronAPI.startService(version)
    IPC->>Main: onboarding:start-service
    Main->>WSM: WebServiceManager.start()
    WSM->>WSM: checkPortAvailable() + auto-increment
    WSM-->>Main: service running
    Main->>IPC: emit onboarding:service-progress
    IPC-->>UI: progress callback
    UI->>Store: dispatch(setServiceProgress(running))

    User->>UI: Complete Onboarding
    UI->>Store: dispatch(completeOnboarding(version))
    Store->>Thunk: execute thunk
    Thunk->>IPC: electronAPI.completeOnboarding(version)
    IPC->>Main: onboarding:complete
    Main->>Main: OnboardingManager.completeOnboarding()
    Main->>Main: emit onboarding:open-hagicode event
    Main-->>IPC: event to renderer
    IPC-->>UI: openHagicode callback
    UI->>UI: Navigate away, show Hagicode
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

  • add basic framework #1: Modifies the same .github/workflows/build.yml file; this PR builds upon the Build Summary job structure introduced by that PR to add consolidated status reporting and Feishu notifications.
  • Fixes electron app packaging and startup issues #5: Both PRs extend main process IPC surface and window/app interaction APIs (onboarding handlers, openHagicodeInApp), so they interact in the exposed electron API layer.

Poem

🐰 A Wizard's Welcome

Hop along the onboarding path so bright,
Download, install, with progress in sight,
Redux state flows from main to the view,
Dependencies checked—now Hagicode's true!
From wizard's first step to service that soars, 🚀

✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch flow

Comment @coderabbitai help to get the list of available commands and usage tips.

@newbe36524 newbe36524 merged commit 6028f3c into main Feb 9, 2026
1 of 2 checks passed
@newbe36524 newbe36524 deleted the flow branch February 9, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant