create-appraisejs 0.3.0 → 0.3.1-alpha.1

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace-state.ts

@@ -0,0 +1,231 @@
+import { inferGroupSuggestion, normalizeRoute, suggestLocatorName } from '@/lib/locator-picker/suggestions'
+
+import type {
+  GroupResolutionMode,
+  LocatorPickerSession,
+  LocatorSourceType,
+  LocatorWorkspaceEnvironment,
+  LocatorWorkspaceInitialValues,
+  LocatorWorkspaceLocatorGroup,
+  LocatorWorkspaceModule,
+  LocatorWorkspaceState,
+} from './create-locator-workspace-types'
+import { locatorSourceTypes, locatorWorkspaceResolutionModes } from './create-locator-workspace-types'
+
+export function statusTone(status: LocatorPickerSession['status']) {
+  switch (status) {
+    case 'picked':
+      return 'default'
+    case 'saving':
+      return 'secondary'
+    case 'closed':
+      return 'outline'
+    case 'error':
+      return 'destructive'
+    case 'ready':
+      return 'secondary'
+    case 'starting':
+    default:
+      return 'secondary'
+  }
+}
+
+export function formatStatus(status: LocatorPickerSession['status']) {
+  return status === 'picked' ? 'Picked' : `${status.charAt(0).toUpperCase()}${status.slice(1)}`
+}
+
+export function createInitialWorkspaceState(
+  environments: LocatorWorkspaceEnvironment[],
+  initialValues?: LocatorWorkspaceInitialValues,
+): LocatorWorkspaceState {
+  const {
+    locatorName = '',
+    selector = '',
+    resolutionMode = 'existing',
+    existingLocatorGroupId = '',
+    newLocatorGroupName = '',
+    route = '/',
+    moduleId = '',
+  } = initialValues ?? {}
+  const initialRoute = normalizeRoute(route)
+
+  return {
+    sourceType: environments.length > 0 ? 'environment' : 'url',
+    environmentId: environments[0]?.id ?? '',
+    url: '',
+    locatorName,
+    selector,
+    resolutionMode,
+    existingLocatorGroupId,
+    newLocatorGroupName,
+    route: initialRoute,
+    moduleId,
+    lastAutoLocatorName: locatorName,
+    lastAutoSelector: selector,
+    lastAutoExistingGroupId: existingLocatorGroupId,
+    lastAutoGroupName: newLocatorGroupName,
+    lastAutoRoute: initialRoute,
+    lastAutoModuleId: moduleId,
+  }
+}
+
+export function getPickerPayloadSignature(session: LocatorPickerSession | null) {
+  const pickedLocator = session?.pickedLocator
+  if (!session || !pickedLocator) {
+    return ''
+  }
+
+  return `${session.updatedAt}:${pickedLocator.currentUrl}:${pickedLocator.selector}`
+}
+
+export function applyPickedLocatorToWorkspaceState(
+  currentState: LocatorWorkspaceState,
+  session: LocatorPickerSession,
+  locatorGroups: LocatorWorkspaceLocatorGroup[],
+  modules: LocatorWorkspaceModule[],
+): LocatorWorkspaceState {
+  const pickedLocator = session.pickedLocator
+  if (!pickedLocator) {
+    return currentState
+  }
+
+  const nextState = { ...currentState }
+
+  applyPickedSelector(nextState, currentState, pickedLocator.selector)
+  applySuggestedLocatorName(nextState, currentState, suggestLocatorName(pickedLocator))
+
+  const suggestion = inferGroupSuggestion(pickedLocator.pathname, pickedLocator.pageTitle, locatorGroups, modules)
+  applySuggestedRoute(nextState, currentState, suggestion.route)
+
+  if (suggestion.mode === 'existing') {
+    applyExistingGroupSuggestion(nextState, currentState, suggestion.existingLocatorGroupId)
+  } else {
+    applyNewGroupSuggestion(nextState, currentState, suggestion.suggestedGroupName, suggestion.suggestedModuleId)
+  }
+
+  return nextState
+}
+
+function canReplaceAutoValue(currentValue: string, lastAutoValue: string) {
+  return currentValue === '' || currentValue === lastAutoValue
+}
+
+function canReplaceRoute(currentState: LocatorWorkspaceState) {
+  return currentState.route === '/' || canReplaceAutoValue(currentState.route, currentState.lastAutoRoute)
+}
+
+function canSwitchToCreateMode(currentState: LocatorWorkspaceState) {
+  return (
+    currentState.resolutionMode === 'create' ||
+    canReplaceAutoValue(currentState.existingLocatorGroupId, currentState.lastAutoExistingGroupId)
+  )
+}
+
+function applyPickedSelector(
+  nextState: LocatorWorkspaceState,
+  currentState: LocatorWorkspaceState,
+  pickedSelector: string,
+) {
+  if (!canReplaceAutoValue(currentState.selector, currentState.lastAutoSelector)) {
+    return
+  }
+
+  nextState.selector = pickedSelector
+  nextState.lastAutoSelector = pickedSelector
+}
+
+function applySuggestedLocatorName(
+  nextState: LocatorWorkspaceState,
+  currentState: LocatorWorkspaceState,
+  suggestedName: string,
+) {
+  if (!suggestedName || !canReplaceAutoValue(currentState.locatorName, currentState.lastAutoLocatorName)) {
+    return
+  }
+
+  nextState.locatorName = suggestedName
+  nextState.lastAutoLocatorName = suggestedName
+}
+
+function applySuggestedRoute(
+  nextState: LocatorWorkspaceState,
+  currentState: LocatorWorkspaceState,
+  suggestedRoute: string,
+) {
+  if (!canReplaceRoute(currentState)) {
+    return
+  }
+
+  nextState.route = suggestedRoute
+  nextState.lastAutoRoute = suggestedRoute
+}
+
+function applyExistingGroupSuggestion(
+  nextState: LocatorWorkspaceState,
+  currentState: LocatorWorkspaceState,
+  suggestedLocatorGroupId: string | undefined,
+) {
+  nextState.resolutionMode = currentState.resolutionMode === 'create' ? 'existing' : currentState.resolutionMode
+
+  if (!canReplaceAutoValue(currentState.existingLocatorGroupId, currentState.lastAutoExistingGroupId)) {
+    return
+  }
+
+  const nextExistingGroupId = suggestedLocatorGroupId ?? ''
+  nextState.existingLocatorGroupId = nextExistingGroupId
+  nextState.lastAutoExistingGroupId = nextExistingGroupId
+}
+
+function applyNewGroupSuggestion(
+  nextState: LocatorWorkspaceState,
+  currentState: LocatorWorkspaceState,
+  suggestedGroupName: string,
+  suggestedModuleId: string | undefined,
+) {
+  if (canSwitchToCreateMode(currentState)) {
+    nextState.resolutionMode = 'create'
+  }
+
+  if (canReplaceAutoValue(currentState.newLocatorGroupName, currentState.lastAutoGroupName)) {
+    nextState.newLocatorGroupName = suggestedGroupName
+    nextState.lastAutoGroupName = suggestedGroupName
+  }
+
+  if (canReplaceAutoValue(currentState.moduleId, currentState.lastAutoModuleId)) {
+    const nextModuleId = suggestedModuleId ?? ''
+    nextState.moduleId = nextModuleId
+    nextState.lastAutoModuleId = nextModuleId
+  }
+}
+
+export function createWorkspaceAutoFillSnapshot(state: LocatorWorkspaceState) {
+  return {
+    lastAutoLocatorName: state.locatorName,
+    lastAutoSelector: state.selector,
+    lastAutoExistingGroupId: state.existingLocatorGroupId,
+    lastAutoGroupName: state.newLocatorGroupName,
+    lastAutoRoute: state.route,
+    lastAutoModuleId: state.moduleId,
+  }
+}
+
+export function canSaveLocator(state: LocatorWorkspaceState) {
+  return (
+    state.locatorName.trim() !== '' &&
+    state.selector.trim() !== '' &&
+    ((state.resolutionMode === 'existing' && state.existingLocatorGroupId !== '') ||
+      (state.resolutionMode === 'create' && state.newLocatorGroupName.trim() !== '' && state.moduleId !== ''))
+  )
+}
+
+export function canLaunchPicker(state: LocatorWorkspaceState) {
+  return state.sourceType === 'environment' ? state.environmentId !== '' : state.url.trim() !== ''
+}
+
+export function getLocatorSourceType(value: string): LocatorSourceType {
+  return locatorSourceTypes.find(sourceType => sourceType === value) ?? 'environment'
+}
+
+export function getLocatorWorkspaceResolutionMode(value: string): GroupResolutionMode {
+  return locatorWorkspaceResolutionModes.find(resolutionMode => resolutionMode === value) ?? 'existing'
+}

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace-types.ts

@@ -0,0 +1,68 @@
+import type { ActionResponseData } from '@/types/form/actionHandler'
+import type { GroupResolutionMode as PickerGroupResolutionMode, LocatorPickerSession } from '@/types/locator-picker'
+import type { Environment, Locator, LocatorGroup, Module } from '@prisma/client'
+
+export type { ActionResponseData, Environment, Locator, LocatorGroup, LocatorPickerSession, Module }
+
+export type LocatorSourceType = 'environment' | 'url'
+export type LocatorWorkspaceMode = 'create' | 'modify'
+export type GroupResolutionMode = PickerGroupResolutionMode
+export type LocatorWorkspaceDisplayMode = 'page' | 'inline'
+
+export type LocatorWorkspaceEnvironment = Pick<Environment, 'id' | 'name'>
+export type LocatorWorkspaceLocatorGroup = Pick<LocatorGroup, 'id' | 'name' | 'route' | 'moduleId'>
+export type LocatorWorkspaceModule = Pick<Module, 'id' | 'name' | 'parentId'>
+
+export type InlineLocatorSaveResult = {
+  locatorId: string
+  locatorName: string
+  locatorGroupId: string
+  locatorGroupName: string
+  selector: string
+  route: string
+  moduleId: string
+}
+
+export const locatorSourceTypes = ['environment', 'url'] as const
+export const locatorWorkspaceResolutionModes = ['existing', 'create'] as const
+
+export type LocatorWorkspaceInitialValues = {
+  locatorName?: string
+  selector?: string
+  resolutionMode?: GroupResolutionMode
+  existingLocatorGroupId?: string
+  newLocatorGroupName?: string
+  route?: string
+  moduleId?: string
+}
+
+export type CreateLocatorWorkspaceProps = {
+  environments: LocatorWorkspaceEnvironment[]
+  locatorGroups: LocatorWorkspaceLocatorGroup[]
+  modules: LocatorWorkspaceModule[]
+  mode?: LocatorWorkspaceMode
+  displayMode?: LocatorWorkspaceDisplayMode
+  locatorId?: string
+  initialValues?: LocatorWorkspaceInitialValues
+  onSaveSuccess?: (result: InlineLocatorSaveResult) => void | Promise<void>
+  onClose?: () => void
+}
+
+export type LocatorWorkspaceState = {
+  sourceType: LocatorSourceType
+  environmentId: string
+  url: string
+  locatorName: string
+  selector: string
+  resolutionMode: GroupResolutionMode
+  existingLocatorGroupId: string
+  newLocatorGroupName: string
+  route: string
+  moduleId: string
+  lastAutoLocatorName: string
+  lastAutoSelector: string
+  lastAutoExistingGroupId: string
+  lastAutoGroupName: string
+  lastAutoRoute: string
+  lastAutoModuleId: string
+}

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace.test.tsx

@@ -2,7 +2,7 @@
 
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import CreateLocatorWorkspace from './create-locator-workspace'
 
@@ -32,6 +32,14 @@ vi.mock('@/actions/locator-picker/locator-picker-actions', () => ({
 }))
 
 describe('CreateLocatorWorkspace', () => {
+  beforeEach(() => {
+    push.mockClear()
+    refresh.mockClear()
+    toast.mockClear()
+    startLocatorPickerSessionAction.mockReset()
+    savePickedLocatorAction.mockReset()
+  })
+
   it('launches chromium from an environment', async () => {
     const user = userEvent.setup()
 
@@ -81,6 +89,15 @@ describe('CreateLocatorWorkspace', () => {
     savePickedLocatorAction.mockResolvedValue({
       status: 200,
       message: 'Locator saved successfully',
+      data: {
+        locatorId: 'locator-1',
+        locatorName: 'Login button',
+        locatorGroupId: 'group-1',
+        locatorGroupName: 'Login',
+        selector: 'button[data-testid="login"]',
+        route: '/account/login',
+        moduleId: 'module-1',
+      },
     })
 
     render(
@@ -122,4 +139,59 @@ describe('CreateLocatorWorkspace', () => {
     expect(push).toHaveBeenCalledWith('/locators')
     expect(refresh).toHaveBeenCalled()
   })
+
+  it('calls onSaveSuccess and closes in inline mode without navigating', async () => {
+    const user = userEvent.setup()
+    const onSaveSuccess = vi.fn()
+    const onClose = vi.fn()
+
+    savePickedLocatorAction.mockResolvedValue({
+      status: 200,
+      message: 'Locator saved successfully',
+      data: {
+        locatorId: 'locator-1',
+        locatorName: 'Login button',
+        locatorGroupId: 'group-1',
+        locatorGroupName: 'Login',
+        selector: 'button[data-testid="login"]',
+        route: '/login',
+        moduleId: 'module-1',
+      },
+    })
+
+    render(
+      <CreateLocatorWorkspace
+        displayMode="inline"
+        environments={[{ id: 'env-1', name: 'Staging' }]}
+        locatorGroups={[{ id: 'group-1', name: 'Login', route: '/login', moduleId: 'module-1' }]}
+        modules={[{ id: 'module-1', name: 'Account', parentId: null }]}
+        initialValues={{
+          locatorName: 'Login button',
+          selector: 'button[data-testid="login"]',
+          resolutionMode: 'existing',
+          existingLocatorGroupId: 'group-1',
+        }}
+        onSaveSuccess={onSaveSuccess}
+        onClose={onClose}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: 'Save Locator' }))
+
+    await waitFor(() => {
+      expect(onSaveSuccess).toHaveBeenCalledWith({
+        locatorId: 'locator-1',
+        locatorName: 'Login button',
+        locatorGroupId: 'group-1',
+        locatorGroupName: 'Login',
+        selector: 'button[data-testid="login"]',
+        route: '/login',
+        moduleId: 'module-1',
+      })
+    })
+
+    expect(onClose).toHaveBeenCalled()
+    expect(push).not.toHaveBeenCalled()
+    expect(refresh).not.toHaveBeenCalled()
+  })
 })

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace.tsx

@@ -26,8 +26,11 @@ export default function CreateLocatorWorkspace({
   locatorGroups,
   modules,
   mode = 'create',
+  displayMode = 'page',
   locatorId,
   initialValues,
+  onSaveSuccess,
+  onClose,
 }: CreateLocatorWorkspaceProps) {
   const {
     isModifyMode,
@@ -54,8 +57,11 @@ export default function CreateLocatorWorkspace({
     locatorGroups,
     modules,
     mode,
+    displayMode,
     locatorId,
     initialValues,
+    onSaveSuccess,
+    onClose,
   })
 
   return (
@@ -76,14 +82,14 @@ export default function CreateLocatorWorkspace({
               onValueChange={value => setSourceType(getLocatorSourceType(value))}
               className="grid gap-3"
             >
-              <label className="flex items-center gap-3 rounded-lg border p-3">
+              <label htmlFor="source-environment" className="flex items-center gap-3 rounded-lg border p-3">
                 <RadioGroupItem value="environment" id="source-environment" disabled={environments.length === 0} />
                 <div>
                   <div className="font-medium">Saved environment</div>
                   <div className="text-sm text-muted-foreground">Launch from an existing base URL.</div>
                 </div>
               </label>
-              <label className="flex items-center gap-3 rounded-lg border p-3">
+              <label htmlFor="source-url" className="flex items-center gap-3 rounded-lg border p-3">
                 <RadioGroupItem value="url" id="source-url" />
                 <div>
                   <div className="font-medium">Direct URL</div>
@@ -120,13 +126,8 @@ export default function CreateLocatorWorkspace({
               </div>
             )}
 
-            <Button
-              type="button"
-              onClick={handleStart}
-              disabled={isStarting || !canLaunch}
-              className="w-full"
-            >
-              {isStarting ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Target className="mr-2 h-4 w-4" />}
+            <Button type="button" onClick={handleStart} disabled={isStarting || !canLaunch} className="w-full">
+              {isStarting ? <Loader2 className="mr-2 size-4 animate-spin" /> : <Target className="mr-2 size-4" />}
               Launch Chromium
             </Button>
 
@@ -157,7 +158,9 @@ export default function CreateLocatorWorkspace({
 
                   <div className="space-y-2 text-sm">
                     <div className="font-medium">Current page</div>
-                    <div className="break-all text-muted-foreground">{session.currentUrl || session.launchSource.url}</div>
+                    <div className="break-all text-muted-foreground">
+                      {session.currentUrl || session.launchSource.url}
+                    </div>
                     <div className="text-muted-foreground">{session.pageTitle || 'Waiting for page metadata'}</div>
                   </div>
 
@@ -183,9 +186,9 @@ export default function CreateLocatorWorkspace({
           </CardHeader>
           <CardContent className="space-y-5">
             {session?.pickedLocator ? (
-              <div className="rounded-lg border bg-muted/30 p-4">
+              <div className="bg-muted/30 rounded-lg border p-4">
                 <div className="mb-2 flex items-center gap-2 text-sm font-medium">
-                  <ExternalLink className="h-4 w-4" />
+                  <ExternalLink className="size-4" />
                   Picked from page
                 </div>
                 <div className="space-y-2 text-sm text-muted-foreground">
@@ -219,20 +222,20 @@ export default function CreateLocatorWorkspace({
               </div>
 
               <div className="space-y-2">
-                <Label>Group Resolution</Label>
+                <div className="text-sm font-medium">Group Resolution</div>
                 <RadioGroup
                   value={state.resolutionMode}
                   onValueChange={value => setResolutionMode(getLocatorWorkspaceResolutionMode(value))}
                   className="grid gap-3"
                 >
-                  <label className="flex items-center gap-3 rounded-lg border p-3">
+                  <label htmlFor="group-existing" className="flex items-center gap-3 rounded-lg border p-3">
                     <RadioGroupItem value="existing" id="group-existing" />
                     <div>
                       <div className="font-medium">Use existing group</div>
                       <div className="text-sm text-muted-foreground">Attach the locator to a saved route group.</div>
                     </div>
                   </label>
-                  <label className="flex items-center gap-3 rounded-lg border p-3">
+                  <label htmlFor="group-create" className="flex items-center gap-3 rounded-lg border p-3">
                     <RadioGroupItem value="create" id="group-create" />
                     <div>
                       <div className="font-medium">Create new group</div>
@@ -312,7 +315,7 @@ export default function CreateLocatorWorkspace({
 
             <div className="flex justify-end">
               <Button type="button" onClick={handleSave} disabled={!canSave || isSaving}>
-                {isSaving ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Save className="mr-2 h-4 w-4" />}
+                {isSaving ? <Loader2 className="mr-2 size-4 animate-spin" /> : <Save className="mr-2 size-4" />}
                 {isModifyMode ? 'Update Locator' : 'Save Locator'}
               </Button>
             </div>

package/templates/starter/src/app/(base)/locators/create/page.tsx

@@ -34,20 +34,16 @@ const CreateLocatorPage = async () => {
       <div className="mb-8">
         <PageHeader>
           <span className="flex items-center">
-            <Crosshair className="mr-2 h-8 w-8" />
+            <Crosshair className="mr-2 size-8" />
             Create Locator
           </span>
         </PageHeader>
         <HeaderSubtitle>
-          Launch Chromium, use the built-in picker overlay to capture one live selector, then finalize the locator
-          name and group details here.
+          Launch Chromium, use the built-in picker overlay to capture one live selector, then finalize the locator name
+          and group details here.
         </HeaderSubtitle>
       </div>
-      <CreateLocatorWorkspace
-        environments={environmentRows}
-        locatorGroups={locatorGroupRows}
-        modules={moduleRows}
-      />
+      <CreateLocatorWorkspace environments={environmentRows} locatorGroups={locatorGroupRows} modules={moduleRows} />
     </>
   )
 }

package/templates/starter/src/app/(base)/locators/create/use-locator-workspace.ts

@@ -17,6 +17,7 @@ import {
   canSaveLocator,
   createInitialWorkspaceState,
   createWorkspaceAutoFillSnapshot,
+  getInlineLocatorSaveResult,
   getLocatorPickerSession,
   getPickerPayloadSignature,
   type CreateLocatorWorkspaceProps,
@@ -29,12 +30,16 @@ export function useLocatorWorkspace({
   locatorGroups,
   modules,
   mode = 'create',
+  displayMode = 'page',
   locatorId,
   initialValues,
+  onSaveSuccess,
+  onClose,
 }: CreateLocatorWorkspaceProps) {
   const router = useRouter()
   const payloadSignatureRef = useRef('')
   const isModifyMode = mode === 'modify'
+  const isInlineMode = displayMode === 'inline'
 
   const [state, setState] = useState(() => createInitialWorkspaceState(environments, initialValues))
   const [session, setSession] = useState<LocatorPickerSession | null>(null)
@@ -70,7 +75,11 @@ export function useLocatorWorkspace({
 
   useEffect(() => {
     const nextPayloadSignature = getPickerPayloadSignature(session)
-    if (!session?.pickedLocator || nextPayloadSignature === '' || nextPayloadSignature === payloadSignatureRef.current) {
+    if (
+      !session?.pickedLocator ||
+      nextPayloadSignature === '' ||
+      nextPayloadSignature === payloadSignatureRef.current
+    ) {
       return
     }
 
@@ -113,7 +122,8 @@ export function useLocatorWorkspace({
 
     toast({
       title: 'Chromium launched',
-      description: 'Use the in-browser Appraise picker panel to start picking, click one element, then confirm Use selector.',
+      description:
+        'Use the in-browser Appraise picker panel to start picking, click one element, then confirm Use selector.',
     })
   }
 
@@ -139,8 +149,15 @@ export function useLocatorWorkspace({
         title: isModifyMode ? 'Locator updated' : 'Locator saved',
         description: response.message,
       })
-      router.push('/locators')
-      router.refresh()
+      const saveResult = getInlineLocatorSaveResult(response.data)
+
+      if (isInlineMode && saveResult) {
+        await onSaveSuccess?.(saveResult)
+        onClose?.()
+      } else {
+        router.push('/locators')
+        router.refresh()
+      }
       return
     }
 
@@ -161,6 +178,7 @@ export function useLocatorWorkspace({
 
   return {
     isModifyMode,
+    isInlineMode,
     session,
     state,
     isStarting,

package/templates/starter/src/app/(base)/locators/locator-file-sync.test.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { syncLocatorsFromFilesAction } from '@/actions/locator/locator-actions'
+
+import { runLocatorFileSync } from './locator-file-sync'
+import { showLocatorSyncFailureToast, showLocatorSyncToast } from './locator-sync-toast'
+
+vi.mock('@/actions/locator/locator-actions', () => ({
+  syncLocatorsFromFilesAction: vi.fn(),
+}))
+
+vi.mock('./locator-sync-toast', () => ({
+  showLocatorSyncToast: vi.fn(),
+  showLocatorSyncFailureToast: vi.fn(),
+}))
+
+const syncLocatorsFromFilesActionMock = vi.mocked(syncLocatorsFromFilesAction)
+const showLocatorSyncToastMock = vi.mocked(showLocatorSyncToast)
+const showLocatorSyncFailureToastMock = vi.mocked(showLocatorSyncFailureToast)
+
+describe('runLocatorFileSync', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('shows success toast when sync succeeds', async () => {
+    const refresh = vi.fn()
+    const payload = { locatorsCreated: 1, locatorsMergedToFile: 2, conflicts: 0, errors: [] }
+
+    syncLocatorsFromFilesActionMock.mockResolvedValue({ status: 200, data: payload, error: null })
+
+    await runLocatorFileSync(refresh)
+
+    expect(showLocatorSyncToastMock).toHaveBeenCalledWith(payload, refresh)
+    expect(showLocatorSyncFailureToastMock).not.toHaveBeenCalled()
+  })
+
+  it('shows failure toast when sync returns an error response', async () => {
+    syncLocatorsFromFilesActionMock.mockResolvedValue({ status: 500, data: null, error: 'sync failed' })
+
+    await runLocatorFileSync(vi.fn())
+
+    expect(showLocatorSyncFailureToastMock).toHaveBeenCalledWith('sync failed')
+  })
+})

package/templates/starter/src/app/(base)/locators/locator-file-sync.ts

@@ -0,0 +1,18 @@
+import { syncLocatorsFromFilesAction } from '@/actions/locator/locator-actions'
+
+import { showLocatorSyncFailureToast, showLocatorSyncToast, type LocatorSyncPayload } from './locator-sync-toast'
+
+export async function runLocatorFileSync(refresh: () => void) {
+  try {
+    const result = await syncLocatorsFromFilesAction()
+
+    if (result.status === 200 && result.data) {
+      showLocatorSyncToast(result.data as LocatorSyncPayload, refresh)
+      return
+    }
+
+    showLocatorSyncFailureToast(result.error || 'An error occurred during sync')
+  } catch (error) {
+    showLocatorSyncFailureToast(`An error occurred: ${error}`)
+  }
+}