feat(onboarding): run the tour against the project named in the URL

frontend/common/hooks/__tests__/useLastEnv.test.ts

@@ -0,0 +1,16 @@
+import { parseLastEnv } from 'common/hooks/useLastEnv'
+
+describe('parseLastEnv', () => {
+  it('reads what usePageTracking wrote', () => {
+    const raw = JSON.stringify({ environmentId: 'abc', orgId: 1, projectId: 2 })
+    expect(parseLastEnv(raw)).toEqual({
+      environmentId: 'abc',
+      orgId: 1,
+      projectId: 2,
+    })
+  })
+
+  it.each([null, '', 'not json', '{'])('survives %p', (raw) => {
+    expect(parseLastEnv(raw)).toBeNull()
+  })
+})

frontend/common/hooks/useLastEnv.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react'
+
+// `lastEnv` is written by usePageTracking as you browse, and read by App and Nav
+// to restore where you were. environmentId is the api_key, since routes use it.
+export type LastEnv = {
+  orgId?: number | string
+  projectId?: number | string
+  environmentId?: string
+}
+
+export const parseLastEnv = (raw: string | null): LastEnv | null => {
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+export const useLastEnv = (): LastEnv | null => {
+  const [lastEnv, setLastEnv] = useState<LastEnv | null>(null)
+
+  useEffect(() => {
+    if (typeof AsyncStorage === 'undefined') return
+    Promise.resolve(AsyncStorage.getItem('lastEnv')).then((raw) =>
+      setLastEnv(parseLastEnv(raw)),
+    )
+  }, [])
+
+  return lastEnv
+}

frontend/web/components/navigation/navbars/TopNavbar.tsx

@@ -8,13 +8,22 @@ import Headway from 'components/Headway'
 import { Project } from 'common/types/responses'
 import AccountDropdown from 'components/navigation/AccountDropdown'
 import ThemeToggle from 'components/ThemeToggle'
+import { useLastEnv } from 'common/hooks/useLastEnv'
 
 type TopNavType = {
   activeProject: Project | undefined
   projectId?: number
 }
 
 const TopNavbar: FC<TopNavType> = ({ activeProject, projectId }) => {
+  // Name the project the tour should run against: the one you're in, else the
+  // one you were last in. Without it the page falls back to the org's first.
+  const lastEnv = useLastEnv()
+  const onboardingProjectId = projectId ?? lastEnv?.projectId
+  const gettingStartedTo = onboardingProjectId
+    ? `/getting-started?project=${onboardingProjectId}`
+    : '/getting-started'
+
   return (
     <React.Fragment>
       <nav className='mt-2 mb-1 space flex-row hidden-xs-down'>
@@ -33,7 +42,7 @@ const TopNavbar: FC<TopNavType> = ({ activeProject, projectId }) => {
           )}
           <NavLink
             activeClassName='active'
-            to={'/getting-started'}
+            to={gettingStartedTo}
             className='d-flex gap-1 d-none d-md-flex text-end lh-1 align-items-center'
           >
             <span>

frontend/web/components/pages/onboarding/OnboardingFlow/OnboardingFlow.tsx

@@ -17,6 +17,7 @@ import { useOnboardingConnection } from 'components/pages/onboarding/hooks/useOn
 import { useUpdateOrganisationMutation } from 'common/services/useOrganisation'
 import { useUpdateProjectMutation } from 'common/services/useProject'
 import API from 'project/api'
+import OnboardingAlreadySetUp from 'components/pages/onboarding/onboarding-already-set-up'
 import Constants from 'common/constants'
 import './OnboardingFlow.scss'
 
@@ -30,6 +31,7 @@ const OnboardingFlow: FC = () => {
     environment,
     environmentKey,
     featureName: bootstrappedFeatureName,
+    hasDemoFlag,
     organisationId,
     organisationName,
     projectId,
@@ -197,6 +199,17 @@ const OnboardingFlow: FC = () => {
     )
   }
 
+  // The project already had flags, so nothing was seeded to tour with.
+  if (!hasDemoFlag) {
+    return (
+      <OnboardingAlreadySetUp
+        projectName={projectDisplayName}
+        featuresHref={`/project/${projectId}/environment/${environmentKey}/features`}
+        onSkip={skipToApp}
+      />
+    )
+  }
+
   return (
     <div className='onboarding-flow mx-auto d-flex flex-column gap-4'>
       <div className='d-flex justify-content-end'>

frontend/web/components/pages/onboarding/hooks/__tests__/demoFlag.test.ts

@@ -0,0 +1,45 @@
+import { ProjectFlag, Tag } from 'common/types/responses'
+import {
+  DEMO_FLAG_NAME,
+  findDemoFlag,
+  shouldSeedDemoFlag,
+} from 'components/pages/onboarding/hooks/demoFlag'
+
+const flag = (name: string, tags: number[] = []): ProjectFlag =>
+  ({ id: name.length, name, tags } as ProjectFlag)
+
+const onboardingTag = { id: 7, label: 'Onboarding' } as Tag
+
+describe('shouldSeedDemoFlag', () => {
+  it('seeds into an empty project', () => {
+    expect(shouldSeedDemoFlag([])).toBe(true)
+  })
+
+  it('seeds nothing once the project has flags of its own', () => {
+    // The customer's list. A flag they did not ask for would appear in every
+    // environment, production included.
+    expect(shouldSeedDemoFlag([flag('checkout_v2')])).toBe(false)
+  })
+})
+
+describe('findDemoFlag', () => {
+  it('finds a previous run by its tag, whatever it was renamed to', () => {
+    const renamed = flag('my_own_name', [onboardingTag.id])
+    expect(findDemoFlag([flag('checkout_v2'), renamed], onboardingTag)).toBe(
+      renamed,
+    )
+  })
+
+  it('falls back to the name when the tag is missing', () => {
+    const demo = flag(DEMO_FLAG_NAME)
+    expect(findDemoFlag([flag('checkout_v2'), demo], undefined)).toBe(demo)
+  })
+
+  it('finds nothing in a project that never ran the tour', () => {
+    expect(findDemoFlag([flag('checkout_v2')], onboardingTag)).toBeUndefined()
+  })
+
+  it('finds nothing in an empty project', () => {
+    expect(findDemoFlag([], onboardingTag)).toBeUndefined()
+  })
+})

frontend/web/components/pages/onboarding/hooks/__tests__/onboardingProject.test.ts

@@ -0,0 +1,30 @@
+import { ProjectSummary } from 'common/types/responses'
+import { selectOnboardingProject } from 'components/pages/onboarding/hooks/onboardingProject'
+
+const project = (id: number): ProjectSummary =>
+  ({ id, name: `project ${id}` } as ProjectSummary)
+
+const projects = [project(10), project(20), project(30)]
+
+describe('selectOnboardingProject', () => {
+  it('runs against the project named in the URL', () => {
+    expect(selectOnboardingProject(projects, 20)).toBe(projects[1])
+  })
+
+  it('matches the id as a string, which is how it arrives', () => {
+    expect(selectOnboardingProject(projects, '30')).toBe(projects[2])
+  })
+
+  it('ignores a project outside this organisation', () => {
+    // A link carried over from another org, or an edited URL.
+    expect(selectOnboardingProject(projects, 999)).toBe(projects[0])
+  })
+
+  it.each([null, undefined, ''])('falls back to the first with %p', (id) => {
+    expect(selectOnboardingProject(projects, id)).toBe(projects[0])
+  })
+
+  it('returns nothing for an empty org, so the caller creates one', () => {
+    expect(selectOnboardingProject([], 20)).toBeUndefined()
+  })
+})

frontend/web/components/pages/onboarding/hooks/bootstrapOnboarding.ts

@@ -16,27 +16,29 @@ import {
   ProjectSummary,
   Tag,
 } from 'common/types/responses'
+import { selectOnboardingProject } from './onboardingProject'
+import {
+  DEMO_FLAG_NAME,
+  ONBOARDING_TAG,
+  findDemoFlag,
+  shouldSeedDemoFlag,
+} from './demoFlag'
 import { SmartDefaults } from './useSmartDefaults'
 import { createOrganisationViaAccountStore } from './createOrganisationViaAccountStore'
 import API from 'project/api'
 import Constants from 'common/constants'
 
 type Store = ReturnType<typeof getStore>
 
-const FLAG_NAME = 'show_demo_button'
 const DEFAULT_ORG_NAME = 'My organisation'
 const DEFAULT_PROJECT_NAME = 'My first project'
 const DEV_ENVIRONMENT_NAME = 'Development'
 const PROD_ENVIRONMENT_NAME = 'Production'
-const ONBOARDING_TAG = {
-  color: '#3cb371',
-  description: 'Created during onboarding',
-  label: 'Onboarding',
-}
-
 type ExistingOrg = { id: number; name: string }
 
 export type BootstrapInput = {
+  // From `?project=` on the entry URL. Ignored when it isn't in this org.
+  requestedProjectId?: string | null
   defaults: SmartDefaults
   existingOrg?: ExistingOrg
 }
@@ -47,6 +49,9 @@ export type OnboardingBootstrap = {
   project: ProjectSummary
   environment: Environment
   featureName: string
+  // False when the project already had flags, so we seeded nothing and the tour
+  // has no flag of its own to teach with.
+  hasDemoFlag: boolean
 }
 
 async function ensureOrganisation(
@@ -73,11 +78,12 @@ async function ensureProject(
   store: Store,
   organisationId: number,
   defaults: SmartDefaults,
+  requestedProjectId?: string | null,
 ): Promise<ProjectSummary> {
   const projects = await store
     .dispatch(projectService.endpoints.getProjects.initiate({ organisationId }))
     .unwrap()
-  const existing = projects?.[0]
+  const existing = selectOnboardingProject(projects ?? [], requestedProjectId)
   if (existing) {
     return existing
   }
@@ -154,30 +160,28 @@ async function ensureFlag(
       }),
     )
     .unwrap()
+  const results = flags?.results ?? []
   const onboardingTag = await findOnboardingTag(store, project.id)
-  const existing =
-    (onboardingTag &&
-      flags?.results?.find((f) => f.tags?.includes(onboardingTag.id))) ||
-    flags?.results?.find((f) => f.name === FLAG_NAME)
+  const existing = findDemoFlag(results, onboardingTag)
   if (existing) {
     return existing
   }
-  const isFirstFeature = !flags?.results?.length
+  if (!shouldSeedDemoFlag(results)) {
+    return undefined
+  }
   const created = await store
     .dispatch(
       projectFlagService.endpoints.createProjectFlag.initiate({
         body: {
-          name: FLAG_NAME,
+          name: DEMO_FLAG_NAME,
           project: project.id,
           type: 'STANDARD',
         } as Req['createProjectFlag']['body'],
         project_id: project.id,
       }),
     )
     .unwrap()
-  if (isFirstFeature) {
-    API.trackEvent(Constants.events.CREATE_FIRST_FEATURE)
-  }
+  API.trackEvent(Constants.events.CREATE_FIRST_FEATURE)
   return created
 }
 
@@ -218,7 +222,12 @@ export async function bootstrapOnboarding(
   input: BootstrapInput,
 ): Promise<OnboardingBootstrap> {
   const organisation = await ensureOrganisation(store, input)
-  const project = await ensureProject(store, organisation.id, input.defaults)
+  const project = await ensureProject(
+    store,
+    organisation.id,
+    input.defaults,
+    input.requestedProjectId,
+  )
   const environment = await ensureEnvironments(store, project)
   const flag = await ensureFlag(store, project)
   if (flag) {
@@ -227,7 +236,8 @@ export async function bootstrapOnboarding(
   AppActions.refreshOrganisation()
   return {
     environment,
-    featureName: flag?.name ?? FLAG_NAME,
+    featureName: flag?.name ?? DEMO_FLAG_NAME,
+    hasDemoFlag: !!flag,
     organisationId: organisation.id,
     organisationName: organisation.name,
     project,

frontend/web/components/pages/onboarding/hooks/demoFlag.ts

@@ -0,0 +1,25 @@
+import { ProjectFlag, Tag } from 'common/types/responses'
+
+export const DEMO_FLAG_NAME = 'show_demo_button'
+
+export const ONBOARDING_TAG = {
+  color: '#3cb371',
+  description: 'Created during onboarding',
+  label: 'Onboarding',
+}
+
+// The demo flag from a previous run: tagged first, since the user is free to
+// rename it, and a rename is a delete and recreate so the name alone is not
+// reliable.
+export const findDemoFlag = (
+  flags: ProjectFlag[],
+  onboardingTag?: Tag,
+): ProjectFlag | undefined =>
+  (onboardingTag && flags.find((f) => f.tags?.includes(onboardingTag.id))) ||
+  flags.find((f) => f.name === DEMO_FLAG_NAME)
+
+// Only seed into an empty project. An established project's flag list belongs to
+// the customer, and a flag they did not ask for turns up in every environment,
+// production included, because features are project-level.
+export const shouldSeedDemoFlag = (flags: ProjectFlag[]): boolean =>
+  !flags.length

frontend/web/components/pages/onboarding/hooks/onboardingProject.ts

@@ -0,0 +1,14 @@
+import { ProjectSummary } from 'common/types/responses'
+
+// /getting-started is an entry point rather than a project-scoped page, so the
+// project it should run against arrives as `?project=`. The URL is authoritative:
+// an id that isn't in this organisation's list is ignored rather than trusted.
+export const selectOnboardingProject = (
+  projects: ProjectSummary[],
+  requestedProjectId?: string | number | null,
+): ProjectSummary | undefined => {
+  const requested =
+    !!requestedProjectId &&
+    projects.find((p) => `${p.id}` === `${requestedProjectId}`)
+  return requested || projects[0]
+}