Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(desktop-app): add an onboarding preview switch for local runs

Andy Paviaab31f1e7a792
diff --git a/Makefile b/Makefile
index 47f48360e..e3dd39281 100644
--- a/Makefile
+++ b/Makefile
@@ -783,8 +783,12 @@ local-web: ## Run Control UI locally against minikube control-api port-forward
wait_for_port control-api 8090 "$$api_pid" http://127.0.0.1:8090/health; \
CONTROL_API_INTERNAL_URL=http://localhost:8090 npm --prefix control-ui run dev
+.PHONY: local-app-onboarding
+local-app-onboarding: ## Run Desktop App showing the first-run onboarding flow (isolated; real environments untouched)
+ @$(MAKE) --no-print-directory EVENFIRE_ONBOARDING_PREVIEW=true local-app
+
.PHONY: local-app
-local-app: ## Run Desktop App locally against minikube API port-forwards
+local-app: ## Run Desktop App locally against minikube API port-forwards (EVENFIRE_ONBOARDING_PREVIEW=true previews onboarding)
@set -euo pipefail; \
cleanup() { \
local pids; \
@@ -854,7 +858,7 @@ local-app: ## Run Desktop App locally against minikube API port-forwards
wait_for_port control-api 8090 "$$control_api_pid" http://127.0.0.1:8090/health; \
wait_for_port external-rest-api 8091 "$$external_api_pid" http://127.0.0.1:8091/health; \
wait_for_port rpc-proxy 8094 "$$rpc_proxy_pid" http://127.0.0.1:8094/health; \
- env -u ELECTRON_RUN_AS_NODE EXTERNAL_REST_API_BASE_URL=http://127.0.0.1:8091 RPC_PROXY_BASE_URL=http://127.0.0.1:8094 CONTROL_API_BASE_URL=http://127.0.0.1:8090 npm --prefix desktop-app run dev
+ env -u ELECTRON_RUN_AS_NODE EXTERNAL_REST_API_BASE_URL=http://127.0.0.1:8091 RPC_PROXY_BASE_URL=http://127.0.0.1:8094 CONTROL_API_BASE_URL=http://127.0.0.1:8090 EVENFIRE_ONBOARDING_PREVIEW="$(EVENFIRE_ONBOARDING_PREVIEW)" npm --prefix desktop-app run dev
.PHONY: local-ui
local-ui: ## Run Control UI, Profile UI, and Desktop App locally against minikube port-forwards
diff --git a/desktop-app/src/__tests__/appService.onboarding.test.ts b/desktop-app/src/__tests__/appService.onboarding.test.ts
index 85e9c72c8..726e405cb 100644
--- a/desktop-app/src/__tests__/appService.onboarding.test.ts
+++ b/desktop-app/src/__tests__/appService.onboarding.test.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-const openExternal = vi.fn(async () => undefined)
+const openExternal = vi.fn(async (_url: string) => undefined)
// config.ts touches the Electron `app` at module load; provide a minimal mock
// with a NON-packaged, ready app so the env-var runtime-config path is active.
diff --git a/desktop-app/src/__tests__/config.onboardingPreview.test.ts b/desktop-app/src/__tests__/config.onboardingPreview.test.ts
new file mode 100644
index 000000000..99afa949f
--- /dev/null
+++ b/desktop-app/src/__tests__/config.onboardingPreview.test.ts
@@ -0,0 +1,134 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('electron', () => ({
+ app: {
+ getPath: vi.fn(() => '/tmp/evenfire-test-userdata'),
+ isPackaged: false,
+ isReady: vi.fn(() => true),
+ setName: vi.fn(),
+ setPath: vi.fn(),
+ getName: vi.fn(() => 'Evenfire'),
+ },
+}))
+
+const LOCALHOST_EXTERNAL = 'http://127.0.0.1:8091'
+const LOCALHOST_RPC = 'http://127.0.0.1:8094'
+
+async function loadState() {
+ vi.resetModules()
+ const config = await import('../config.js')
+ // getDesktopRuntimeConfigState hydrates first, so this is the value the
+ // renderer actually receives — not the pre-hydrate one.
+ return config.getDesktopRuntimeConfigState()
+}
+
+describe('EVENFIRE_ONBOARDING_PREVIEW', () => {
+ const saved = {
+ external: process.env.EXTERNAL_REST_API_BASE_URL,
+ rpc: process.env.RPC_PROXY_BASE_URL,
+ preview: process.env.EVENFIRE_ONBOARDING_PREVIEW,
+ explicit: process.env.CLERUM_DESKTOP_CONFIG_PATH,
+ }
+
+ beforeEach(() => {
+ delete process.env.EVENFIRE_ONBOARDING_PREVIEW
+ delete process.env.CLERUM_DESKTOP_CONFIG_PATH
+ })
+
+ afterEach(() => {
+ for (const [key, value] of [
+ ['EXTERNAL_REST_API_BASE_URL', saved.external],
+ ['RPC_PROXY_BASE_URL', saved.rpc],
+ ['EVENFIRE_ONBOARDING_PREVIEW', saved.preview],
+ ['CLERUM_DESKTOP_CONFIG_PATH', saved.explicit],
+ ] as const) {
+ if (value === undefined) delete process.env[key]
+ else process.env[key] = value
+ }
+ vi.resetModules()
+ })
+
+ it('defaults to off: an env-configured app stays configured', async () => {
+ process.env.EXTERNAL_REST_API_BASE_URL = LOCALHOST_EXTERNAL
+ process.env.RPC_PROXY_BASE_URL = LOCALHOST_RPC
+
+ expect((await loadState()).configured).toBe(true)
+ })
+
+ it('ignores any value other than "true"', async () => {
+ process.env.EXTERNAL_REST_API_BASE_URL = LOCALHOST_EXTERNAL
+ process.env.RPC_PROXY_BASE_URL = LOCALHOST_RPC
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = 'false'
+
+ expect((await loadState()).configured).toBe(true)
+
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = '1'
+ expect((await loadState()).configured).toBe(true)
+ })
+
+ it('starts cold when enabled, even with the make local-app runtime vars set', async () => {
+ process.env.EXTERNAL_REST_API_BASE_URL = LOCALHOST_EXTERNAL
+ process.env.RPC_PROXY_BASE_URL = LOCALHOST_RPC
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = 'true'
+
+ // configured === false is what routes the renderer to onboarding.
+ expect((await loadState()).configured).toBe(false)
+ })
+
+ it('reads and writes a separate directory, never the real runtime config', async () => {
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = 'true'
+ const previewPath = (await loadState()).storagePath
+
+ delete process.env.EVENFIRE_ONBOARDING_PREVIEW
+ const realPath = (await loadState()).storagePath
+
+ expect(previewPath).not.toBe(realPath)
+ expect(previewPath).toContain('runtime-configs-onboarding-preview')
+ expect(realPath).toMatch(/runtime-configs$/)
+ })
+
+ it('survives hydration under a real `make local-app` launch', async () => {
+ // Regression: hydrateDesktopRuntimeConfig re-pinned the Localhost option
+ // whenever the app was launched with --evenfire-desktop-dev-package AND
+ // localhost endpoints — exactly what `make local-app` does. That flipped
+ // `configured` back to true after boot, so the app opened on sign-in while
+ // the boot log still claimed onboarding.
+ process.argv.push('--evenfire-desktop-dev-package')
+ try {
+ process.env.EXTERNAL_REST_API_BASE_URL = LOCALHOST_EXTERNAL
+ process.env.RPC_PROXY_BASE_URL = LOCALHOST_RPC
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = 'true'
+
+ const state = await loadState()
+
+ expect(state.configured).toBe(false)
+ expect(state.activeOptionId).not.toBe('__localhost__')
+ } finally {
+ process.argv = process.argv.filter(a => a !== '--evenfire-desktop-dev-package')
+ }
+ })
+
+ it('still pins Localhost for a dev-package launch when preview is off', async () => {
+ process.argv.push('--evenfire-desktop-dev-package')
+ try {
+ process.env.EXTERNAL_REST_API_BASE_URL = LOCALHOST_EXTERNAL
+ process.env.RPC_PROXY_BASE_URL = LOCALHOST_RPC
+
+ const state = await loadState()
+
+ expect(state.configured).toBe(true)
+ } finally {
+ process.argv = process.argv.filter(a => a !== '--evenfire-desktop-dev-package')
+ }
+ })
+
+ it('does not let an explicit config path hand the preview an environment', async () => {
+ process.env.EVENFIRE_ONBOARDING_PREVIEW = 'true'
+ process.env.CLERUM_DESKTOP_CONFIG_PATH = '/tmp/evenfire-explicit/runtime-config.json'
+
+ const state = await loadState()
+
+ expect(state.configured).toBe(false)
+ expect(state.storagePath).toContain('runtime-configs-onboarding-preview')
+ })
+})
diff --git a/desktop-app/src/config.ts b/desktop-app/src/config.ts
index 37a40b95e..53a4b05d6 100644
--- a/desktop-app/src/config.ts
+++ b/desktop-app/src/config.ts
@@ -56,6 +56,25 @@ const LOCALHOST_RPC_PROXY_BASE_URL = 'http://127.0.0.1:8094'
const DEFAULT_DEPLOYMENT_DOCS_URL =
'https://github.com/evenfire-ai/evenfire#deploying-to-a-remote-cluster'
const RUNTIME_CONFIG_DIR_NAME = 'runtime-configs'
+/**
+ * Dev switch for previewing the first-run onboarding flow (spec §5.1) on a
+ * machine that already has environments configured. Defaults to false; only
+ * the exact string "true" enables it.
+ *
+ * Onboarding is by definition the zero-environment state, so a developer whose
+ * app is already configured — including anyone launched by `make local-app`,
+ * which exports EXTERNAL_REST_API_BASE_URL and RPC_PROXY_BASE_URL — can never
+ * reach it. Rather than fake the view, this makes the app genuinely start cold:
+ * it reads and writes runtime config in a SEPARATE directory and ignores the
+ * env-var runtime config. The wizard is real, saving an environment works, and
+ * the developer's actual environments are neither read nor modified — unset the
+ * variable and they are all still there.
+ */
+const ONBOARDING_PREVIEW = process.env.EVENFIRE_ONBOARDING_PREVIEW?.trim().toLowerCase() === 'true'
+const ONBOARDING_PREVIEW_DIR_NAME = 'runtime-configs-onboarding-preview'
+const activeRuntimeConfigDirName = ONBOARDING_PREVIEW
+ ? ONBOARDING_PREVIEW_DIR_NAME
+ : RUNTIME_CONFIG_DIR_NAME
const RUNTIME_CONFIG_INDEX_FILE = 'index.json'
const PACKAGED_ENV_FILE = '.env.prod'
const MAX_PROFILE_FILE_ATTEMPTS = 1000
@@ -143,6 +162,9 @@ loadPackagedEnv()
function explicitRuntimeConfigPath(): string {
if (app?.isPackaged) return ''
+ // The onboarding preview owns its own directory; an explicit config file
+ // would hand it a configured environment and defeat the point.
+ if (ONBOARDING_PREVIEW) return ''
return process.env.CLERUM_DESKTOP_CONFIG_PATH?.trim() || ''
}
@@ -198,11 +220,11 @@ function runtimeConfigDirectoryPath(): string {
if (explicit) return path.dirname(explicit)
if (app?.isReady()) {
- return path.join(app.getPath('userData'), RUNTIME_CONFIG_DIR_NAME)
+ return path.join(app.getPath('userData'), activeRuntimeConfigDirName)
}
// Keep a deterministic fallback before Electron is ready.
- return path.join(defaultUserDataDirectoryPath(), RUNTIME_CONFIG_DIR_NAME)
+ return path.join(defaultUserDataDirectoryPath(), activeRuntimeConfigDirName)
}
function runtimeConfigIndexPath(): string {
@@ -516,6 +538,9 @@ const desktopDevPackageRuntimeConfigEnabled =
runtimeEndpointsMatch(envRuntimeConfig, localhostRuntimeConfig)
const canUseEnvRuntimeConfig = !app?.isPackaged || desktopDevPackageRuntimeConfigEnabled
const envRuntimeConfigured = Boolean(
+ // `make local-app` exports both of these, which would mark the app
+ // configured and skip the wizard the preview exists to show.
+ !ONBOARDING_PREVIEW &&
canUseEnvRuntimeConfig &&
process.env.EXTERNAL_REST_API_BASE_URL?.trim() &&
process.env.RPC_PROXY_BASE_URL?.trim()
@@ -550,6 +575,33 @@ let desktopRuntimeConfigured = Boolean(
activeStoredProfile || envRuntimeConfigured || activeRuntimeOptionId === LOCALHOST_OPTION_ID
)
+/**
+ * Diagnostic for "why did the app open on this screen?".
+ *
+ * `configured` decides sign-in vs. the first-run onboarding wizard, and it is
+ * resolved twice: once at module load, then again by
+ * `hydrateDesktopRuntimeConfig` once Electron is ready. Only the second value
+ * reaches the renderer, so this is logged from there — logging the module-load
+ * value instead reports a screen the user never sees. No URLs, tokens or paths
+ * beyond the config directory name; nothing secret.
+ */
+function logRuntimeConfigResolution(): void {
+ if (process.env.VITEST) return
+ console.log(
+ '[evenfire] runtime config:',
+ JSON.stringify({
+ configured: desktopRuntimeConfigured,
+ screen: desktopRuntimeConfigured ? 'sign-in' : 'onboarding',
+ onboardingPreview: ONBOARDING_PREVIEW,
+ onboardingPreviewRaw: process.env.EVENFIRE_ONBOARDING_PREVIEW ?? '(unset)',
+ activeOptionId: activeRuntimeOptionId,
+ configDir: activeRuntimeConfigDirName,
+ isPackaged: Boolean(app?.isPackaged),
+ devPackageLaunch: desktopDevPackageRuntimeConfigEnabled,
+ })
+ )
+}
+
const initialRuntimeConfig =
activeRuntimeOptionId === LOCALHOST_OPTION_ID
? localhostRuntimeConfig
@@ -602,14 +654,24 @@ export function hydrateDesktopRuntimeConfig(): void {
if (runtimeConfigHydrated) return
if (!app?.isReady()) return
runtimeConfigHydrated = true
+ resolveHydratedRuntimeConfig()
+ logRuntimeConfigResolution()
+}
+function resolveHydratedRuntimeConfig(): void {
const loaded = loadStoredProfilesSync()
storedProfiles = loaded.profiles
const preserveLocalhostRuntime =
- preferLocalhostRuntimeByDefault ||
- (desktopDevPackageRuntimeConfigEnabled &&
- envMatchesLocalhostOption &&
- isLocalhostRuntimeConfig(currentRuntimeConfig()))
+ // The onboarding preview must not be pulled back onto the Localhost
+ // option here. `make local-app` satisfies every condition below — it
+ // passes --evenfire-desktop-dev-package and points the env endpoints at
+ // 127.0.0.1 — which would re-mark the app configured after boot and land
+ // the developer on sign-in, the exact screen the preview exists to bypass.
+ !ONBOARDING_PREVIEW &&
+ (preferLocalhostRuntimeByDefault ||
+ (desktopDevPackageRuntimeConfigEnabled &&
+ envMatchesLocalhostOption &&
+ isLocalhostRuntimeConfig(currentRuntimeConfig())))
activeRuntimeOptionId = preserveLocalhostRuntime ? LOCALHOST_OPTION_ID : loaded.activeProfileId
const selectedProfile = resolveActiveProfile(storedProfiles, activeRuntimeOptionId)