@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/setlist/setlist-web/app/routes/upcoming.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react'
+import { useLoaderData } from 'react-router'
+import type { LoaderFunctionArgs } from 'react-router'
+import { dateFns, type Iso } from 'iso-fns'
+import { getRequestContext } from '~/features/request-context.server'
+import { TaskService } from '~/services.server'
+import { TaskList, TaskExpandedDetail } from '~/components/task-list'
+import type { TaskItem, TaskDetail } from '~/components/task-list'
+
+export async function loader({ context }: LoaderFunctionArgs) {
+  const requestContext = getRequestContext(context)
+  if (!requestContext.user) {
+    throw new Response('Unauthorized', { status: 401 })
+  }
+
+  const profile = requestContext.user
+  const { groups } = await TaskService.ListTasksForUpcoming({}, profile)
+
+  return {
+    groups: groups.map((g) => ({
+      date: g.date,
+      tasks: g.tasks
+    }))
+  }
+}
+
+export default function UpcomingPage() {
+  const { groups } = useLoaderData<typeof loader>()
+  const [selectedTaskId, setSelectedTaskId] = React.useState<number | null>(null)
+  const allTasks = groups.flatMap((g) => g.tasks)
+
+  // Keep the expanded task's group alive so its TaskList doesn't unmount
+  const stickyGroupRef = React.useRef<(typeof groups)[number] | null>(null)
+  if (selectedTaskId != null) {
+    const found = groups.find((g) => g.tasks.some((t) => t.id === selectedTaskId))
+    if (found) stickyGroupRef.current = found
+  } else {
+    stickyGroupRef.current = null
+  }
+  const displayGroups = React.useMemo(() => {
+    if (selectedTaskId == null) return groups
+    if (groups.some((g) => g.tasks.some((t) => t.id === selectedTaskId))) return groups
+    if (!stickyGroupRef.current) return groups
+    const sticky = { ...stickyGroupRef.current, tasks: [] as typeof groups[number]['tasks'] }
+    return [...groups, sticky]
+  }, [groups, selectedTaskId])
+
+  return (
+    <div className="mx-auto max-w-2xl px-8 py-8">
+      <h1 className="mb-6 typography-h1">Upcoming</h1>
+
+      {displayGroups.length === 0 ? (
+        <p className="py-8 text-center text-sm text-neutral-500">No upcoming tasks</p>
+      ) : (
+        <div className="space-y-6">
+          {displayGroups.map((group) => (
+            <div key={group.date}>
+              <h2 className="mb-2 text-sm font-semibold text-neutral-500">{formatDateHeader(group.date as Iso.Date)}</h2>
+              <TaskList
+                tasks={group.tasks as TaskItem[]}
+                positionField="scheduled"
+                showProject
+                selectedTaskId={selectedTaskId}
+                onSelect={(id) => setSelectedTaskId(id === selectedTaskId ? null : id)}
+                renderExpanded={(id) => {
+                  const task = allTasks.find((t) => t.id === id) as TaskDetail | undefined
+                  if (!task) return null
+                  return (
+                    <TaskExpandedDetail key={id} task={task} onClose={() => setSelectedTaskId(null)} />
+                  )
+                }}
+              />
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function formatDateHeader(date: Iso.Date): string {
+  return dateFns.format(date, 'iiii, MMMM d')
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/routes.ts

@@ -0,0 +1,4 @@
+import { type RouteConfig } from '@react-router/dev/routes'
+import { ReactRouterFileRoutes } from '@maestro-js/react-router-file-routes'
+
+export default ReactRouterFileRoutes.getRoutes('routes') satisfies RouteConfig

package/skills/maestro-examples/references/setlist/setlist-web/app/services.server.ts

@@ -0,0 +1 @@
+export * from '@setlist/services'

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/colors.ts

@@ -0,0 +1,47 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add colors --directory app
+
+export const COLORS = [
+  '#f43f5e',
+  '#3b82f6',
+  '#22c55e',
+  '#EAB308',
+  '#8b5cf6',
+  '#191970',
+  '#f97316',
+  '#6b7280',
+  '#ec4899',
+  '#06b6d4',
+  '#84cc16',
+  '#64748b',
+  '#ffff00',
+  '#6366f1',
+  '#ff6347',
+  '#737373',
+  '#14b8a6',
+  '#f59e0b',
+  '#0ea5e9',
+  '#ef4444',
+  '#78716c',
+  '#00ffff',
+  '#d946ef',
+  '#10b981',
+  '#b22222',
+  '#40e0d0',
+  '#71717a',
+  '#a855f7',
+  '#7fff00'
+] as const
+
+export function stringToNumber(str: string) {
+  let h = 0x811c9dc5 // FNV offset basis
+  for (const b of new TextEncoder().encode(str)) {
+    h ^= b
+    h = Math.imul(h, 0x01000193) // 16777619
+  }
+  return h >>> 0 // unsigned 32-bit
+}
+
+export function getColor(seed: number) {
+  return COLORS[seed % COLORS.length]
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/compose-refs.ts

@@ -0,0 +1,35 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add compose-refs --directory app
+
+import React from 'react'
+
+type PossibleRef<T> = React.Ref<T> | undefined
+
+/**
+ * Set a given ref to a given value
+ * This utility takes care of different types of refs: callback refs and RefObject(s)
+ */
+function setRef<T>(ref: PossibleRef<T>, value: T) {
+  if (typeof ref === 'function') {
+    ref(value)
+  } else if (ref !== null && ref !== undefined) {
+    ;(ref as React.MutableRefObject<T>).current = value
+  }
+}
+
+/**
+ * A utility to compose multiple refs together
+ * Accepts callback refs and RefObject(s)
+ */
+export function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  return (node: T) => refs.forEach((ref) => setRef(ref, node))
+}
+
+/**
+ * A custom hook that composes multiple refs
+ * Accepts callback refs and RefObject(s)
+ */
+export function useComposedRefs<T>(...refs: PossibleRef<T>[]) {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useCallback(composeRefs(...refs), refs)
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/tw.ts

@@ -0,0 +1,16 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add tw --directory app
+
+import { twMerge } from 'tailwind-merge'
+import { composeRenderProps } from 'react-aria-components'
+
+export function tw(...inputs: unknown[]) {
+  return twMerge(inputs.flat(Infinity).filter(Boolean).join(' '))
+}
+
+export function composeTailwindRenderProps<T>(
+  className: string | ((renderProps: T) => string) | undefined,
+  tailwind: string
+): string | ((renderProps: T) => string) {
+  return composeRenderProps(className, (prev) => tw(tailwind, prev))
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-dismiss.ts

@@ -0,0 +1,27 @@
+import React from 'react'
+
+/**
+ * Dismisses on Escape key press or click outside the referenced element.
+ */
+export function useDismiss(ref: React.RefObject<HTMLElement | null>, onDismiss: () => void) {
+  React.useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        onDismiss()
+      }
+    }
+
+    function handleClickOutside(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        onDismiss()
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown)
+      document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [ref, onDismiss])
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-fetcher-complete.ts

@@ -0,0 +1,17 @@
+import * as React from 'react'
+import { useStableAccessor } from './use-stable-accessor'
+
+/**
+ * Calls `onComplete` once when a fetcher transitions from a non-idle state back to idle.
+ */
+export function useFetcherComplete(fetcher: { state: string }, onComplete: () => void) {
+  const getOnComplete = useStableAccessor(onComplete)
+  const prevState = React.useRef(fetcher.state)
+  React.useEffect(() => {
+    const wasActive = prevState.current !== 'idle'
+    prevState.current = fetcher.state
+    if (wasActive && fetcher.state === 'idle') {
+      getOnComplete()()
+    }
+  }, [fetcher.state, getOnComplete])
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-prevent-default.ts

@@ -0,0 +1,30 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-prevent-default --directory app
+
+import React from 'react'
+import { useStableAccessor } from './use-stable-accessor'
+
+export function usePreventDefault<E extends React.SyntheticEvent<any>>(
+  eventHandler: React.EventHandler<E> | undefined,
+  preventDefault: boolean
+): React.EventHandler<E> {
+  const getShouldPreventDefault = useStableAccessor(preventDefault)
+  const getEventHandler = useStableAccessor(eventHandler)
+
+  const myEventHandler = React.useCallback(
+    (event: E) => {
+      if (getShouldPreventDefault()) {
+        event.preventDefault()
+        event.stopPropagation()
+        return
+      } else {
+        const eventHandler = getEventHandler()
+        if (eventHandler) {
+          return eventHandler(event)
+        }
+      }
+    },
+    [getEventHandler, getShouldPreventDefault]
+  )
+  return myEventHandler
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-render-props.ts

@@ -0,0 +1,42 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-render-props --directory app
+
+import React from 'react'
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+type DefaultRenderPropKeys<Props> = Extract<'children' | 'className' | 'style', keyof Props>
+
+type MaybeRenderProp<Value, RenderProps> = Value | ((renderProps: RenderProps) => Value)
+
+export type WithRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+> = Prettify<{
+  [K in keyof Props]: K extends Keys ? MaybeRenderProp<Props[K], RenderProps> : Props[K]
+}>
+
+export function useRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+>(props: Props, renderProps: RenderProps, keys: Keys[]) {
+  const withRenderProps = React.useMemo(
+    () =>
+      Object.fromEntries(
+        keys
+          .map((key) => {
+            if (key in props && typeof props[key] === 'function') {
+              return [key, props[key](renderProps)]
+            } else {
+              return []
+            }
+          })
+          .filter((k) => k.length)
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...keys, renderProps, props, ...keys.map((key) => props[key])]
+  )
+  return { ...props, ...withRenderProps }
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-spin-delay.ts

@@ -0,0 +1,27 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-spin-delay --directory app
+
+import React from 'react'
+
+export function useSpinDelay(loading: boolean, { delay = 500, minDuration = 200 } = {}) {
+  const [show, setShow] = React.useState(false)
+  const delayTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+  const minTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  React.useEffect(() => {
+    if (loading) {
+      delayTimer.current = setTimeout(() => setShow(true), delay)
+    } else {
+      clearTimeout(delayTimer.current)
+      if (show) {
+        minTimer.current = setTimeout(() => setShow(false), minDuration)
+      }
+    }
+    return () => {
+      clearTimeout(delayTimer.current)
+      clearTimeout(minTimer.current)
+    }
+  }, [loading, delay, minDuration, show])
+
+  return show
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/utils/use-stable-accessor.ts

@@ -0,0 +1,14 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-stable-accessor --directory app
+
+import React from 'react'
+
+export function useStableAccessor<T>(value: T) {
+  const initialPersisterKey = React.useRef<{ value: T }>({ value })
+  const getValue = React.useCallback(() => {
+    return initialPersisterKey.current.value
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialPersisterKey.current])
+  initialPersisterKey.current.value = value
+  return getValue
+}

package/skills/maestro-examples/references/setlist/setlist-web/environment.d.ts

@@ -0,0 +1,8 @@
+declare module '*.svg' {
+  const href: string
+  export default href
+}
+
+interface ImportMetaEnv {
+  VITE_SENTRY_DSN: string
+}

package/skills/maestro-examples/references/setlist/setlist-web/instrument.server.mjs

@@ -0,0 +1,29 @@
+import * as Sentry from '@sentry/react-router'
+import { Log } from '@maestro-js/log'
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 1.0,
+  sendDefaultPii: true
+})
+
+Log.addTransport(
+  Log.transports.sentry({
+    sentry: Sentry,
+    filter: { level: ['error', 'emergency'] },
+    getCaptureContext(message) {
+      return {
+        tags: { channel: message.channel ?? 'default' },
+        extra: {},
+        level: message.level === 'emergency' ? 'fatal' : message.level
+      }
+    }
+  })
+)
+
+Log.addTransport(
+  Log.transports.sentryBreadcrumbs({
+    sentry: Sentry,
+    filter: { level: ['info', 'warn'] }
+  })
+)

package/skills/maestro-examples/references/setlist/setlist-web/knip.json

@@ -0,0 +1,3 @@
+{
+  "entry": ["./app/routes/**/*.ts?(x)", "./app/entry.server.tsx", "./app/entry.client.tsx"]
+}

package/skills/maestro-examples/references/setlist/setlist-web/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@setlist/setlist-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' maestro config:run --config setlist-web --root $PWD/.. -- react-router dev",
+    "dev-test": "IS_TESTING=true pnpm dev",
+    "build": "react-router build",
+    "start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js",
+    "typecheck": "react-router typegen && tsc --noEmit",
+    "test:e2e": "maestro config:run --config setlist-web --root $PWD/.. -- playwright test",
+    "format": "prettier --write app/ tests/"
+  },
+  "dependencies": {
+    "@internationalized/date": "^3.11.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@maestro-js/form": "^1.0.0-alpha.21",
+    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.21",
+    "@react-aria/interactions": "^3.27.0",
+    "@react-aria/utils": "^3.33.0",
+    "@react-router/node": "^7.9.0",
+    "@sentry/react-router": "^9",
+    "@react-router/serve": "^7.9.0",
+    "@setlist/schemas": "workspace:*",
+    "@setlist/services": "workspace:*",
+    "isbot": "^5",
+    "react": "^19.0.0",
+    "react-aria-components": "^1.15.1",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.9.0",
+    "tailwind-merge": "^3.5.0",
+    "vite-env-only": "^3.0.3",
+    "iso-fns": "^2.0.0-alpha.26",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@react-router/dev": "^7.9.0",
+    "@tailwindcss/vite": "^4.2.0",
+    "@types/node": "^22.19.11",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.7.0",
+    "vite": "^8.0.0",
+    "vite-plugin-icons-spritesheet": "^3.0.1",
+    "vite-tsconfig-paths": "^6.1.1",
+    "@playwright/test": "^1.52.0"
+  }
+}

package/skills/maestro-examples/references/setlist/setlist-web/playwright.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure'
+  },
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /.*\.setup\.ts/
+    },
+    {
+      name: 'chromium',
+      testIgnore: /auth-logout/,
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: '.auth/user.json'
+      },
+      dependencies: ['setup']
+    },
+    {
+      name: 'auth-logout',
+      testMatch: /auth-logout/,
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: '.auth/user.json'
+      },
+      dependencies: ['setup', 'chromium']
+    }
+  ]
+})

package/skills/maestro-examples/references/setlist/setlist-web/react-router.config.ts

@@ -0,0 +1,12 @@
+import type { Config } from '@react-router/dev/config'
+import { sentryOnBuildEnd } from '@sentry/react-router'
+
+export default {
+  ssr: true,
+  future: {
+    v8_middleware: true
+  },
+  async buildEnd({ viteConfig, reactRouterConfig, buildManifest }) {
+    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })
+  }
+} satisfies Config

package/skills/maestro-examples/references/setlist/setlist-web/tests/areas-create.test.ts

@@ -0,0 +1,37 @@
+import { test, expect } from '@playwright/test'
+import { Db } from '@setlist/services'
+import { TEST_CONSTANTS } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+test.afterAll(async () => {
+  await Db.delete('DELETE FROM areas WHERE userId = ? AND title = ?', [userId, 'Finance'])
+})
+
+test('create an area via inline sidebar input', async ({ page }) => {
+  await page.goto('/inbox')
+  const nav = page.getByRole('navigation')
+
+  // Click the "New area" button in the sidebar
+  await nav.getByRole('button', { name: 'New area' }).click()
+
+  // Type the area title and submit
+  const input = nav.getByPlaceholder('New area...')
+  await expect(input).toBeVisible()
+  await input.fill('Finance')
+  await input.press('Enter')
+
+  // The new area should appear at the end of the sidebar list
+  const areaLink = nav.getByRole('link', { name: 'Finance' })
+  await expect(areaLink).toBeVisible()
+
+  // Navigate to the area detail view
+  await areaLink.click()
+  await page.waitForURL(/\/areas\/\d+/)
+
+  // The detail view should show the area title
+  await expect(page.getByRole('heading', { name: 'Finance' })).toBeVisible()
+
+  // The detail view should show an empty tasks section
+  await expect(page.getByText('No tasks in this area')).toBeVisible()
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/areas-delete.test.ts

@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@setlist/services'
+import { TEST_CONSTANTS } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+const seedData = H.SeedPipe(
+  H.AreaSeed({ id: 9190, userId, title: 'Hobbies', position: 'a0' }),
+  H.ProjectSeed({ id: 9191, userId, areaId: 9190, title: 'Learn Guitar', position: 'a0' })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('delete an area promotes child project to top-level', async ({ page }) => {
+  await page.goto('/inbox')
+  const nav = page.getByRole('navigation')
+
+  // Verify the area and its child project exist in the sidebar
+  const areaLink = nav.getByRole('link', { name: 'Hobbies' })
+  await expect(areaLink).toBeVisible()
+
+  // Right-click the area to open context menu
+  await areaLink.click({ button: 'right' })
+
+  // Click "Delete" in the context menu
+  await page.getByRole('menuitem', { name: 'Delete' }).click()
+
+  // Confirm deletion in the alert dialog
+  const dialog = page.getByRole('alertdialog')
+  await expect(dialog).toBeVisible()
+  await dialog.getByRole('button', { name: 'Delete' }).click()
+
+  // The area should be removed from the sidebar
+  await expect(areaLink).not.toBeVisible()
+
+  // The child project should still be visible as a top-level project
+  const projectLink = nav.getByRole('link', { name: 'Learn Guitar' })
+  await expect(projectLink).toBeVisible()
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/areas-deleted-not-in-sidebar.test.ts

@@ -0,0 +1,44 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@setlist/services'
+import { TEST_CONSTANTS } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+const seedData = H.SeedPipe(H.AreaSeed({ id: 9230, userId, title: 'Archived Hobby', position: 'a0' }))
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('deleted area does not appear in sidebar after reload', async ({ page }) => {
+  await page.goto('/inbox')
+  const nav = page.getByRole('navigation')
+
+  // Verify the area exists in the sidebar
+  const areaLink = nav.getByRole('link', { name: 'Archived Hobby' })
+  await expect(areaLink).toBeVisible()
+
+  // Right-click the area to open context menu
+  await areaLink.click({ button: 'right' })
+
+  // Click "Delete" in the context menu
+  await page.getByRole('menuitem', { name: 'Delete' }).click()
+
+  // Confirm deletion in the alert dialog
+  const dialog = page.getByRole('alertdialog')
+  await expect(dialog).toBeVisible()
+  await dialog.getByRole('button', { name: 'Delete' }).click()
+
+  // The area should be removed from the sidebar immediately
+  await expect(areaLink).not.toBeVisible()
+
+  // Reload the page to verify the deletion persisted
+  await page.reload()
+
+  // The deleted area should still not be visible after reload
+  await expect(nav.getByRole('link', { name: 'Archived Hobby' })).not.toBeVisible()
+})