feat/onboarding (#337)

* feat(onboarding): add cookie helper, types and mock data

* feat(onboarding): add stepper, contextual preview and shell

* feat(onboarding): add sso-gate step

* feat(onboarding): add account-info step with real signup

* feat(onboarding): add security step

* feat(onboarding): add preferences step

* fix(onboarding): validate avatar upload size/type and handle FileReader errors

* feat(onboarding): add org-create step

* feat(onboarding): add invite-members step

* feat(onboarding): add notifier step reusing real provider list

* feat(onboarding): add storage step reusing real provider list

* feat(onboarding): add defaults step

* feat(onboarding): add agent-create step

* feat(onboarding): add agent-waiting step with simulated ping

* feat(onboarding): add project-create step

* feat(onboarding): add db-settings step with per-db repeat

* feat(onboarding): add finish step with confetti

* feat(onboarding): wire full step graph

* feat(onboarding): add /welcome route

* feat(onboarding): gate landing, auth and dashboard routes behind onboarding cookie

* fix(onboarding): call next() in finish step so onFlowComplete fires and cookie is written

* docs: add onboarding channel config + style refactor spec

* docs: add conditional step skip when no agents to spec

* docs(onboarding): add implementation plan for channel config flow and style refactor

* feat(onboarding): extend OnboardingChannel with name and config fields

* feat(onboarding): add two-phase config flow and org-combobox style to notifier step

* fix(onboarding): prevent duplicate notifier providers and guard Continue button

* feat(onboarding): add two-phase config flow and org-combobox style to storage step

* style(onboarding): restyle sso-gate provider buttons to org-combobox card style

* style(onboarding): restyle security method choice to org-combobox card style

* style(onboarding): restyle theme toggles in preferences step to org-combobox card style

* style(onboarding): restyle DB toggle buttons in project-create step to org-combobox card style

* feat(onboarding): skip agent-waiting/project-create/db-settings when no agents created

* feat(onboarding): update type system — meta, firstName/lastName, org.id, databases

* feat(onboarding): add settings.onboarding column + markOnboardingDoneAction

* feat(onboarding): add resolveOnboardingState server function

* fix(onboarding): remove unused imports from onboarding-state.ts

* style(onboarding): add branding to shell, fix progress bar full width

* feat(onboarding): replace preview panel with stepper checklist

* feat(onboarding): add step-login replacing sso-gate

* fix(onboarding): step-login — conform to global mutation pattern, handle SSO errors

* feat(onboarding): step-account-info — firstName/lastName, conditional password, findOrCreate

* feat(onboarding): avatar API route (next/og) + AvatarPicker in preferences step

* feat(onboarding): step-security reads passkeyEnabled from flowData.meta

* feat(onboarding): step-org-create calls real createOrganizationAction

* fix(onboarding): step-org-create — simplify error handling, throw on empty name

* feat(onboarding): notifier + storage steps call real actions + findOrCreate on back

* feat(onboarding): step-agent-create calls real createAgentAction + findOrCreate

* feat(onboarding): step-agent-waiting polls real agent lastContact via useQuery

* feat(onboarding): add step-agent-key with edgeKey generation via server action

* feat(onboarding): step-project-create uses real action + real DBs from flowData

* feat(onboarding): wire steps — add login + agent-key, remove sso-gate

* feat(onboarding): page.tsx uses resolveOnboardingState — server-driven resume

* chore(onboarding): delete mock/cookie/preview/sso-gate files — replaced by real implementation

* feat(onboarding): add emailPasswordEnabled to meta, remove logoDataUrl from org

* feat(onboarding): DB-driven resume — query notifiers/storages, check agent lastContact

* feat(onboarding): agent-waiting step is now skippable

* feat(onboarding): login — auto-advance if session, callbackURL on SSO, hide email/pw when disabled, empty state

* fix(onboarding): step-login — add next to useEffect deps, default emailPasswordEnabled to false

* fix(onboarding): verify session after passkey registration, fallback to signIn.passkey()

* feat(onboarding): theme applied dynamically via setTheme, avatar saved to user.image

* feat(onboarding): remove org logo upload — orgs have no logo

* feat(onboarding): show Next button in shell when navigating backwards

* docs: add onboarding refactor design spec

* docs: add onboarding refactor implementation plan

* refactor(onboarding): extract useCreateAgent and useDeleteAgent hooks

* refactor(onboarding): extract useCreateOrg and useCreateProject hooks

* fix(onboarding): trim project name, standardize error narrowing in org/project hooks

* fix(onboarding): use narrowed createData.value in use-create-org

* refactor(onboarding): extract useUpdateAccount hook

* refactor(onboarding): extract useAddNotifier and useRemoveNotifier hooks

* refactor(onboarding): extract useAddStorage and useRemoveStorage hooks

* refactor(onboarding): extract useAgentStatus and useGenerateEdgeKey hooks

* refactor(onboarding): extract useMarkOnboardingDone hook, remove .gitkeep files

* docs: add onboarding theme persistence & progress bar fix spec

* docs: add onboarding theme & progress bar implementation plan

* fix(onboarding): persist theme to db on selection in StepPreferences

* fix(onboarding): recalculate progress bar from full STEP_ORDER position

* fix(theme): sync user theme from DB on all routes, not only dashboard

* fix(theme): use current theme as fallback in preferences, prevent session override of localStorage

* fix(onboarding): correct resume steps and skip agent-waiting flash when agent is connected

* fix(onboarding): properly resolve onboarding state, remove redirect trap in step-defaults, block waiting flash

* fix(onboarding): resume at db-settings instead of finish if no database exists for the project

* fix(onboarding): redirect to agent-create if project exists but no agent is found

* fix(onboarding): allow going from agent-create to project-create if a project already exists

* fix(onboarding): skip intermediate agent steps when going back from project-create to agent-create

* fix(onboarding): skip default step when going back from agent-create if no notifiers and storages exist

* feat(onboarding): allow user to choose between passkey and password during registration if both are enabled

* feat(onboarding): replace tabs with single form and multiple buttons for auth choice

* style(onboarding): improve empty auth state UI with lucide icon and better layout

* fix(onboarding): completely hide back button on the first step instead of disabling it

* fix(onboarding): skip default step if no notifiers and storages exist when advancing from storage step

* fix(onboarding): correctly show select placeholder when default value does not exist in the list

* refactor(onboarding): remove duplicate generate-edge-key action and use core utility directly

* feat(onboarding): compute edgeKey directly on the server side to avoid lazy loading

* fix(onboarding): skip db-settings step if no database is found on the agent

* fix(onboarding): do not skip db settings if agent is connected but no databases found

* refactor(onboarding): skip db settings entirely if no database is selected in project create

* feat(onboarding): auto-save database selections on project create instantly

* style(onboarding): replace button opacity flash with specific spinner animation on db select

* feat(onboarding): extend OnboardingDbSettings with retention, schedule, and policy fields

* feat(onboarding): add applyOnboardingDbSettingsAction server action

* feat(onboarding): add BackupScheduleSelector component

* feat(onboarding): rewrite step-db-settings with three-level phase navigation and full policy persistence

* fix(onboarding): wire applyMutation.mutateAsync everywhere and stabilize list keys

* docs(sdd): append hotfix summary for applyMutation and list keys

* fix(onboarding): address final review findings - atomicity, scheduling guard, apply-all recovery, client validation

* add: onboarding

* fix(migration): merge

* fix(migration): apply for onboarding

* fix(settings): make avatar selector, dicebear picker and tab bar responsive

* chore: checkpoint before features reorganization

* Task 2: Add migration script for features directory reorganization

* refactor(agents): reorganize into actions/components/schemas/hooks

* refactor(auth): reorganize into actions/components/schemas

* refactor(channel): reorganize into components/schemas, nest notifications+storages under components

* refactor(database): reorganize into actions/components/schemas

* refactor(layout): move all components to components/

* refactor(logs): reorganize into components/types

* refactor(migration): reorganize into actions/components

* refactor(notifications): reorganize into components/types/utils

* refactor(organizations): reorganize into actions/components/schemas/hooks/utils

* refactor(profile): reorganize into actions/components/schemas

* refactor(projects): reorganize into actions/components/schemas

* refactor(settings): reorganize into actions/components/schemas/hooks

* refactor(statistics): reorganize into components/utils

* refactor(storages): reorganize into types/utils

* refactor(theme): move all components to components/

* refactor(updates): reorganize into components/hooks

* refactor(upload): move action to actions/

* refactor(users): reorganize into actions/components/schemas

* fix: update broken imports after features reorganization (double-quote relative imports, channel subdir absolute paths)

* fix: .gitignore

* fix: onboarding

* fix: removed dead files

* feat: backfill onboarding flag for instances with existing data

* fix: persist onboarding=true on boot when SKIP_ONBOARDING is set

* feat: remove avatarMode/dicebearStyle from DB schema and types

* feat: simplify resolveAvatarUrl — custom image first, gravatar fallback

* feat: allow avatar upload regardless of mode

* feat: remove avatarMode from layout and profile prop chains

* feat: remove avatar mode admin tab and supporting files

* feat: remove avatar mode selector from onboarding defaults step

* fix: remove preferences onboarding step and fix routing

* fix: remove stale preferences entry from onboarding checklist

* feat: add avatar reset button and explanatory tooltip on profile page

* fix: move avatar tooltip to top-right badge overlay on avatar

* fix: use small destructive button for avatar removal

* fix

* Update step-defaults.tsx

* fix: default dev password for keycloak refer to env

* fix

* fix(migration): refactoring

* fix: api agent helpers.ts

* Update .env.example

---------

Co-authored-by: Théo LAGACHE <theo.lagache@soluce-technologies.com>
Co-authored-by: charles-gauthereau <charles.gauthereau@soluce-technologies.com>
This commit is contained in:
Théo LAGACHE
2026-06-27 17:08:38 +02:00
committed by GitHub
co-authored by Théo LAGACHE charles-gauthereau
parent 40d3228db6
commit 40247efddd
451 changed files with 15904 additions and 5054 deletions
@@ -0,0 +1,55 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { addNotificationChannelAction } from "@/features/channel/components/notifications/channel.action";
import type { OnboardingChannel } from "@/features/onboarding/types";
type NotifierInput = {
provider: string;
name: string;
config: Record<string, unknown>;
label: string;
};
export const useAddNotifier = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async ({ provider, name, config, label }: NotifierInput) => {
const orgId = (state?.context.flowData.org as any)?.id as
| string
| undefined;
const result = await addNotificationChannelAction({
organizationId: orgId,
data: {
provider: provider as any,
name,
config: config as any,
enabled: true,
},
});
const inner = result?.data;
if (!inner?.success || !inner.value)
throw new Error("Failed to save channel");
const channel: OnboardingChannel = {
id: inner.value.id,
provider,
label,
name,
config,
};
const notifiers = [
...((state?.context.flowData.notifiers ?? []) as OnboardingChannel[]),
channel,
];
await updateContext({
flowData: { ...state?.context.flowData, notifiers },
});
return channel;
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,56 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { addStorageChannelAction } from "@/features/channel/components/storages/channel.action";
import type { OnboardingChannel } from "@/features/onboarding/types";
type StorageInput = {
provider: string;
name: string;
config: Record<string, unknown>;
label: string;
};
export const useAddStorage = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async ({ provider, name, config, label }: StorageInput) => {
const orgId = (state?.context.flowData.org as any)?.id as
| string
| undefined;
const result = await addStorageChannelAction({
organizationId: orgId,
data: {
provider: provider as any,
name,
config: config as any,
enabled: true,
},
});
const inner = result?.data;
if (!inner?.success || !inner.value)
throw new Error("Failed to save storage");
const channel: OnboardingChannel = {
id: inner.value.id,
provider,
label,
name,
config,
organizationId: orgId ?? null,
};
const storages = [
...((state?.context.flowData.storages ?? []) as OnboardingChannel[]),
channel,
];
await updateContext({
flowData: { ...state?.context.flowData, storages },
});
return channel;
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,23 @@
"use client";
import { useQuery } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { getAgentStatusAction } from "@/features/onboarding/actions/get-agent-status.action";
import type { OnboardingAgent } from "@/features/onboarding/types";
export const useAgentStatus = () => {
const { state } = useOnboarding();
const agents = (state?.context.flowData.agents ?? []) as OnboardingAgent[];
const firstAgentId = agents[0]?.id;
return useQuery({
queryKey: ["onboarding-agent-status", firstAgentId],
queryFn: async () => {
if (!firstAgentId) return { connected: false };
const result = await getAgentStatusAction({ agentId: firstAgentId });
return result?.data ?? { connected: false };
},
refetchInterval: 3_000,
enabled: !!firstAgentId,
});
};
@@ -0,0 +1,12 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { toast } from "sonner";
import { applyOnboardingDbSettingsAction } from "@/features/onboarding/actions/apply-db-settings.action";
export const useApplyDbSettings = () =>
useMutation({
mutationFn: (args: Parameters<typeof applyOnboardingDbSettingsAction>[0]) =>
applyOnboardingDbSettingsAction(args),
onError: () => toast.error("Failed to save settings."),
});
@@ -0,0 +1,46 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { createAgentAction } from "@/features/agents/actions/agents.action";
import type { OnboardingAgent, OnboardingDefaultsData } from "@/features/onboarding/types";
import { generateEdgeKey } from "@/utils/edge_key";
import { getServerUrl } from "@/utils/get-server-url";
export const useCreateAgent = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async (name: string) => {
const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
if (!orgId) throw new Error("Missing org ID — cannot create agent");
const defaults = (state?.context.flowData.defaults ?? {}) as OnboardingDefaultsData;
const result = await createAgentAction({
organizationId: orgId,
data: { name, description: "" },
});
if (!result?.data?.data) {
throw new Error(result?.serverError ?? `Failed to create agent "${name}"`);
}
const edgeKey = await generateEdgeKey(getServerUrl(), result.data.data.id);
const newAgent: OnboardingAgent = {
id: result.data.data.id,
name: result.data.data.name,
edgeKey,
notifierId: defaults.notifierId,
storageId: defaults.storageId,
};
const agents = [
...((state?.context.flowData.agents ?? []) as OnboardingAgent[]),
newAgent,
];
await updateContext({ flowData: { ...state?.context.flowData, agents } });
return newAgent;
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,63 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import {
createOrganizationAction,
updateOrganizationAction,
} from "@/features/organizations/actions/organization.action";
import { slugify } from "@/utils/slugify";
export const useCreateOrg = () => {
const { state, updateContext, next } = useOnboarding();
return useMutation({
mutationFn: async (name: string) => {
const trimmed = name.trim();
if (!trimmed) throw new Error("Organisation name is required");
const existingOrg = state?.context.flowData.org as
| { id: string; name: string }
| undefined;
if (existingOrg) {
const result = await updateOrganizationAction({
organizationId: existingOrg.id,
data: { name: trimmed, slug: slugify(trimmed), users: [] },
});
const updateData = result?.data;
if (!updateData?.success) {
throw new Error(
updateData?.actionError?.message ?? "Failed to update organisation",
);
}
await updateContext({
flowData: {
...state?.context.flowData,
org: { id: existingOrg.id, name: trimmed },
},
});
} else {
const result = await createOrganizationAction({ name: trimmed });
const createData = result?.data;
if (!createData?.success) {
throw new Error(
createData?.actionError?.message ?? "Failed to create organisation",
);
}
const org = createData.value;
if (!org) throw new Error("Failed to create organisation");
await updateContext({
flowData: {
...state?.context.flowData,
org: { id: org.id, name: org.name },
},
});
}
await next();
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,62 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import {
createProjectAction,
updateProjectAction,
} from "@/features/projects/actions/projects.action";
import type { OnboardingProjectData } from "@/features/onboarding/types";
type ProjectInput = { name: string; databaseIds: string[] };
export const useCreateProject = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async ({ name, databaseIds }: ProjectInput) => {
const trimmed = name.trim();
if (!trimmed) throw new Error("Project name is required");
const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
if (!orgId) throw new Error("No organisation ID found");
const existingProject = state?.context.flowData.project as OnboardingProjectData | undefined;
if (existingProject?.id) {
const result = await updateProjectAction({
data: { name: trimmed, databases: databaseIds },
organizationId: orgId,
projectId: existingProject.id,
});
const updateData = result?.data;
if (!updateData?.success) {
throw new Error(updateData?.actionError?.message ?? "Failed to update project");
}
await updateContext({
flowData: {
...state?.context.flowData,
project: { id: existingProject.id, name: trimmed, databaseIds },
},
});
} else {
const result = await createProjectAction({
data: { name: trimmed, databases: databaseIds },
organizationId: orgId,
});
const createData = result?.data;
if (!createData?.success) {
throw new Error(createData?.actionError?.message ?? "Failed to create project");
}
const project = createData.value;
if (!project) throw new Error("Failed to create project");
await updateContext({
flowData: {
...state?.context.flowData,
project: { id: project.id, name: project.name, databaseIds },
},
});
}
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,25 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { deleteAgentAction } from "@/features/agents/actions/agent-delete.action";
import type { OnboardingAgent } from "@/features/onboarding/types";
export const useDeleteAgent = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async (agentId: string) => {
const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
const result = await deleteAgentAction({ agentId, organizationId: orgId });
if (result?.data?.success === false) throw new Error("Failed to delete agent");
const agents = (
(state?.context.flowData.agents ?? []) as OnboardingAgent[]
).filter((a) => a.id !== agentId);
await updateContext({ flowData: { ...state?.context.flowData, agents } });
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,14 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { markOnboardingDoneAction } from "@/features/onboarding/actions/onboarding-mark-done.action";
export const useMarkOnboardingDone = () => {
return useMutation({
mutationFn: async () => {
const result = await markOnboardingDoneAction({});
if (!result?.data) throw new Error("Failed to mark onboarding done");
return result.data;
},
});
};
@@ -0,0 +1,32 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { removeNotificationChannelAction } from "@/features/channel/components/notifications/channel.action";
import type { OnboardingChannel } from "@/features/onboarding/types";
export const useRemoveNotifier = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async (id: string) => {
const orgId = (state?.context.flowData.org as any)?.id as
| string
| undefined;
const result = await removeNotificationChannelAction({
organizationId: orgId,
notificationChannelId: id,
});
if (result?.data?.success === false)
throw new Error("Failed to remove channel");
const notifiers = (
(state?.context.flowData.notifiers ?? []) as OnboardingChannel[]
).filter((c) => c.id !== id);
await updateContext({
flowData: { ...state?.context.flowData, notifiers },
});
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,32 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { removeStorageChannelAction } from "@/features/channel/components/storages/channel.action";
import type { OnboardingChannel } from "@/features/onboarding/types";
export const useRemoveStorage = () => {
const { state, updateContext } = useOnboarding();
return useMutation({
mutationFn: async (id: string) => {
const orgId = (state?.context.flowData.org as any)?.id as
| string
| undefined;
const result = await removeStorageChannelAction({
organizationId: orgId,
id,
});
if (result?.data?.success === false)
throw new Error("Failed to remove storage");
const storages = (
(state?.context.flowData.storages ?? []) as OnboardingChannel[]
).filter((c) => c.id !== id);
await updateContext({
flowData: { ...state?.context.flowData, storages },
});
},
onError: (err: Error) => toast.error(err.message),
});
};
@@ -0,0 +1,115 @@
"use client";
import { useMutation } from "@tanstack/react-query";
import { useOnboarding } from "@onboardjs/react";
import { toast } from "sonner";
import { z } from "zod";
import { authClient, signUp, passkey, signIn } from "@/lib/auth/auth-client";
import { updateAccountAction } from "@/features/onboarding/actions/update-account.action";
import { generatePasskeyContextAction } from "@/features/onboarding/actions/generate-passkey-context.action";
import { WithPasswordSchema } from "@/features/onboarding/schemas/account.schema";
type AccountInput = z.infer<typeof WithPasswordSchema> & {
method?: "passkey" | "password";
};
export const useUpdateAccount = (refetchSession: () => Promise<any>) => {
const { state, updateContext, next } = useOnboarding();
return useMutation({
mutationFn: async (values: AccountInput) => {
const existingAccount = state?.context.flowData.account;
const isUpdateMode = !!existingAccount;
const selectedMethod = values.method ?? "password";
if (isUpdateMode) {
const result = await updateAccountAction({
firstName: values.firstName,
lastName: values.lastName,
});
if (!result?.data) throw new Error("Failed to update account");
await updateContext({
flowData: {
...state?.context.flowData,
account: {
firstName: values.firstName,
lastName: values.lastName,
email: values.email,
},
},
});
await next();
return;
}
if (selectedMethod === "passkey") {
const name = `${values.firstName} ${values.lastName}`;
const ctxResult = await generatePasskeyContextAction({
name,
email: values.email,
});
const context = ctxResult?.data;
if (!context) throw new Error("Failed to generate passkey context");
const result = await passkey.addPasskey({
name: values.email,
context,
});
if (result?.error) {
throw new Error(
result.error.message ?? "Passkey registration failed",
);
}
await refetchSession();
const { data: freshSession } = await authClient.getSession();
if (!freshSession?.user) {
const signInResult = await (signIn as any).passkey();
if (signInResult?.error) {
throw new Error(
"Registration succeeded but sign-in failed. Please reload and sign in.",
);
}
}
await updateContext({
flowData: {
...state?.context.flowData,
account: {
firstName: values.firstName,
lastName: values.lastName,
email: values.email,
},
security: { method: "passkey" },
},
});
await next();
return;
}
await signUp.email(
{
name: `${values.firstName} ${values.lastName}`,
email: values.email,
password: values.password ?? "",
} as any,
{
onSuccess: async () => {
await updateContext({
flowData: {
...state?.context.flowData,
account: {
firstName: values.firstName,
lastName: values.lastName,
email: values.email,
},
},
});
await next();
},
onError: (error) => {
toast.error(error.error.message);
},
},
);
},
onError: (err: Error) => toast.error(err.message),
});
};