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

package/skills/maestro-examples/references/chorus/chorus-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/chorus/chorus-web/app/utils/use-profile.ts

@@ -0,0 +1,7 @@
+import type { ProfileSchemas } from '@chorus/schemas'
+import { useRouteLoaderData } from 'react-router'
+
+export function useProfile() {
+  const loaderData = useRouteLoaderData('root')
+  return loaderData.profile as ProfileSchemas.Profile | null
+}

package/skills/maestro-examples/references/chorus/chorus-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/chorus/chorus-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/chorus/chorus-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/chorus/chorus-web/app/utils/use-tab-indicator.ts

@@ -0,0 +1,107 @@
+import * as React from 'react'
+
+// --- Shared Tab Styles ---
+
+export const TAB_BASE_CLASSES = 'relative px-4 py-2 text-sm cursor-default transition-colors duration-200'
+export const TAB_INACTIVE_CLASSES = 'text-neutral-500 font-medium'
+export const TAB_DISABLED_CLASSES = 'opacity-50 cursor-not-allowed'
+
+// --- Tab Variant ---
+
+export type TabVariant = 'underline' | 'oval'
+
+// --- Tab Color Map ---
+
+export const tabColorMap = {
+  primary: {
+    text: 'text-primary-500',
+    bg: 'bg-primary-500',
+    outline: 'outline-primary-500'
+  },
+  neutral: {
+    text: 'text-neutral-800',
+    bg: 'bg-neutral-800',
+    outline: 'outline-neutral-800'
+  }
+} as const
+
+export type TabColor = keyof typeof tabColorMap
+
+// --- Variant-Specific Styles ---
+
+export const tabListContainerClasses: Record<TabVariant, string> = {
+  underline: 'relative',
+  oval: 'relative inline-flex bg-neutral-100 rounded-full p-1'
+}
+
+export const tabListInnerClasses: Record<TabVariant, string> = {
+  underline: 'flex space-x-1 border-b border-neutral-200',
+  oval: 'flex space-x-1'
+}
+
+export function getIndicatorClasses(variant: TabVariant, color: TabColor): string {
+  if (variant === 'underline') {
+    return `absolute bottom-0 h-[3px] rounded-full ${tabColorMap[color].bg}`
+  }
+  return `absolute inset-y-1 rounded-full ${tabColorMap[color].bg}`
+}
+
+export const TAB_OVAL_BASE_CLASSES =
+  'relative z-10 px-4 py-1.5 text-sm cursor-default transition-colors duration-200 rounded-full'
+export const TAB_OVAL_SELECTED_CLASSES = 'text-white font-semibold'
+
+// --- Animated Indicator Hook ---
+
+export function useAnimatedIndicator(
+  containerRef: React.RefObject<HTMLDivElement | null>,
+  activeSelector: string,
+  observedAttribute: string
+) {
+  const indicatorRef = React.useRef<HTMLDivElement>(null)
+  const hasAnimated = React.useRef(false)
+
+  const updateIndicator = React.useCallback(() => {
+    const container = containerRef.current
+    const indicator = indicatorRef.current
+    if (!container || !indicator) return
+
+    const activeTab = container.querySelector(activeSelector) as HTMLElement | null
+    if (activeTab) {
+      const containerRect = container.getBoundingClientRect()
+      const tabRect = activeTab.getBoundingClientRect()
+
+      if (!hasAnimated.current) {
+        indicator.style.transition = 'none'
+        hasAnimated.current = true
+      } else {
+        indicator.style.transition = 'left 200ms ease, width 200ms ease'
+      }
+
+      indicator.style.left = `${tabRect.left - containerRect.left}px`
+      indicator.style.width = `${tabRect.width}px`
+      indicator.style.opacity = '1'
+    } else {
+      indicator.style.opacity = '0'
+    }
+  }, [containerRef, activeSelector])
+
+  React.useEffect(() => {
+    updateIndicator()
+
+    const container = containerRef.current
+    if (!container) return
+
+    const observer = new MutationObserver(updateIndicator)
+    observer.observe(container, { attributes: true, subtree: true, attributeFilter: [observedAttribute] })
+
+    const resizeObserver = new ResizeObserver(updateIndicator)
+    resizeObserver.observe(container)
+
+    return () => {
+      observer.disconnect()
+      resizeObserver.disconnect()
+    }
+  }, [containerRef, updateIndicator, observedAttribute])
+
+  return indicatorRef
+}

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

@@ -0,0 +1,15 @@
+import type { Config } from '@maestro-js/config'
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv extends Config.Resolve<typeof import('../config/chorus-web')> {}
+  }
+
+  interface ImportMetaEnv {
+    VITE_SENTRY_DSN: string
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv
+  }
+}

package/skills/maestro-examples/references/chorus/chorus-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/chorus/chorus-web/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@chorus/chorus-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' maestro config:run --config chorus-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 chorus-web --root $PWD/.. -- playwright test"
+  },
+  "dependencies": {
+    "@bundled-es-modules/pdfjs-dist": "3.6.172-alpha.1",
+    "@internationalized/date": "^3.11.0",
+    "@maestro-js/form": "^1.0.0-alpha.21",
+    "@maestro-js/permissions": "^1.0.0-alpha.21",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.21",
+    "@react-aria/interactions": "^3.27.0",
+    "@react-aria/utils": "^3.33.0",
+    "@react-router/node": "^7.9.0",
+    "@react-router/serve": "^7.9.0",
+    "@chorus/schemas": "workspace:*",
+    "@chorus/services": "workspace:*",
+    "isbot": "^5",
+    "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
+    "match-sorter": "^8.2.0",
+    "react": "^19.0.0",
+    "react-aria-components": "^1.15.1",
+    "react-dom": "^19.0.0",
+    "react-pdf-hook": "^1.0.4",
+    "react-router": "^7.9.0",
+    "tailwind-merge": "^3.5.0",
+    "vaul": "^1.1.2",
+    "zod": "^4.0.0",
+    "@sentry/react-router": "^9"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.21",
+    "@playwright/test": "^1.58.2",
+    "@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-env-only": "^3.0.2",
+    "vite-plugin-icons-spritesheet": "^3.0.1",
+    "vite-tsconfig-paths": "^6.1.1"
+  }
+}

package/skills/maestro-examples/references/chorus/chorus-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:3001',
+    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/chorus/chorus-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/chorus/chorus-web/tests/auth-landing.test.ts

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test'
+
+test.use({ storageState: { cookies: [], origins: [] } })
+
+test('landing page shows log in link', async ({ page }) => {
+  await page.goto('/')
+  await expect(page.getByRole('link', { name: 'Log in' })).toBeVisible()
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/auth-login.test.ts

@@ -0,0 +1,40 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@chorus/services'
+import { TEST_CONSTANTS } from './constants'
+
+test.use({ storageState: { cookies: [], origins: [] } })
+
+const seedData = H.SeedPipe(
+  H.ProfileSeed({
+    profileId: 1100,
+    email: 'login-test@example.com',
+    passwordHash: TEST_CONSTANTS.passwordHash
+  })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('can log in with existing credentials', async ({ page }) => {
+  await page.goto('/login')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Email').fill('login-test@example.com')
+  await page.getByLabel('Password', { exact: true }).fill(TEST_CONSTANTS.password)
+  await page.getByRole('button', { name: 'Log in' }).click()
+  await page.waitForURL('/')
+  await expect(page.getByRole('navigation').getByRole('link', { name: 'Log in' })).not.toBeVisible()
+})
+
+test('login with wrong password shows error', async ({ page }) => {
+  await page.goto('/login')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Email').fill('nobody@example.com')
+  await page.getByLabel('Password', { exact: true }).fill('wrongpassword')
+  await page.getByRole('button', { name: 'Log in' }).click()
+  await expect(page.getByText('Incorrect email or password')).toBeVisible()
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/auth-logout.test.ts

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test'
+
+test('logout destroys session and redirects to home', async ({ page }) => {
+  await page.goto('/logout')
+  await page.getByRole('button', { name: 'Log out' }).click()
+  await page.waitForURL('/')
+  await expect(page.getByRole('link', { name: 'Log in' })).toBeVisible()
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/auth-signup.test.ts

@@ -0,0 +1,15 @@
+import { test, expect } from '@playwright/test'
+
+test.use({ storageState: { cookies: [], origins: [] } })
+
+test('can sign up a new account', async ({ page }) => {
+  const email = `signup-${Date.now()}@example.com`
+  await page.goto('/signup')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Email').fill(email)
+  await page.getByLabel('Password', { exact: true }).fill('password123')
+  await page.getByLabel('Confirm password').fill('password123')
+  await page.getByRole('button', { name: 'Sign up' }).click()
+  await page.waitForURL('/')
+  await expect(page.getByRole('navigation').getByRole('link', { name: 'Log in' })).not.toBeVisible()
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/auth.setup.ts

@@ -0,0 +1,42 @@
+import { test as setup, expect } from '@playwright/test'
+import { H } from '@chorus/services'
+import { TEST_CONSTANTS } from './constants'
+
+const authFile = '.auth/user.json'
+
+const seedData = H.SeedPipe(
+  H.ProfileSeed({
+    profileId: TEST_CONSTANTS.profileId,
+    email: TEST_CONSTANTS.email,
+    username: TEST_CONSTANTS.username,
+    passwordHash: TEST_CONSTANTS.passwordHash
+  })
+)
+
+setup.beforeAll(async () => {
+  await seedData.setup()
+})
+
+setup('authenticate', async ({ page }) => {
+  // Warm up Vite dev server — visiting pages triggers dependency discovery
+  // and optimization. After Vite finishes optimizing, it reloads. We visit
+  // pages, wait for stability, then proceed with the actual login.
+  for (let i = 0; i < 3; i++) {
+    try {
+      await page.goto('/', { timeout: 10000 })
+      await page.waitForLoadState('networkidle')
+      break
+    } catch {
+      await page.waitForTimeout(3000)
+    }
+  }
+
+  await page.goto('/login')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Email').fill(TEST_CONSTANTS.email)
+  await page.getByLabel('Password', { exact: true }).fill(TEST_CONSTANTS.password)
+  await page.getByRole('button', { name: 'Log in' }).click()
+  await page.waitForURL('/')
+
+  await page.context().storageState({ path: authFile })
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/channel-browse.test.ts

@@ -0,0 +1,43 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@chorus/services'
+
+const seedData = H.SeedPipe(
+  H.ProfileSeed({ profileId: 2000 }),
+  H.ChannelSeed({
+    id: 2000,
+    ownerProfileId: 2000,
+    name: 'Browse Channel',
+    slug: 'browse-channel',
+    description: 'A channel for browsing tests'
+  })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('channel list page loads and shows channels', async ({ page }) => {
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: 'Channels' })).toBeVisible()
+  await expect(page.getByText('Browse Channel')).toBeVisible()
+})
+
+test('clicking a channel navigates to channel detail', async ({ page }) => {
+  await page.goto('/')
+  await page.getByText('Browse Channel').click()
+  await expect(page).toHaveURL(/\/c\/browse-channel/)
+  await expect(page.getByText('A channel for browsing tests')).toBeVisible()
+})
+
+test.describe('unauthenticated', () => {
+  test.use({ storageState: { cookies: [], origins: [] } })
+
+  test('unauthenticated user can browse channels', async ({ page }) => {
+    await page.goto('/')
+    await expect(page.getByText('Browse Channel')).toBeVisible()
+  })
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/channel-create.test.ts

@@ -0,0 +1,34 @@
+import { test, expect } from '@playwright/test'
+import { Db } from '@chorus/services'
+import { TEST_CONSTANTS } from './constants'
+
+test.afterAll(async () => {
+  await Db.delete('DELETE FROM channels WHERE ownerProfileId = ? AND name = ?', [TEST_CONSTANTS.profileId, 'My New Channel'])
+})
+
+test('authenticated user can create a channel', async ({ page }) => {
+  await page.goto('/c/new')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Channel Name').fill('My New Channel')
+  await page.getByLabel('Description').fill('Channel description here')
+  await page.getByRole('button', { name: 'Create Channel' }).click()
+  await expect(page).toHaveURL(/\/c\/my-new-channel/)
+  await expect(page.getByText('My New Channel')).toBeVisible()
+  await expect(page.getByText('Channel description here')).toBeVisible()
+})
+
+test('create channel form shows validation errors for empty fields', async ({ page }) => {
+  await page.goto('/c/new')
+  await page.waitForLoadState('networkidle')
+  await page.getByRole('button', { name: 'Create Channel' }).click()
+  await expect(page.getByText(/required/i).first()).toBeVisible()
+})
+
+test.describe('unauthenticated', () => {
+  test.use({ storageState: { cookies: [], origins: [] } })
+
+  test('unauthenticated user is redirected from create channel page', async ({ page }) => {
+    await page.goto('/c/new')
+    await expect(page).toHaveURL(/\/login/)
+  })
+})

package/skills/maestro-examples/references/chorus/chorus-web/tests/channel-edit.test.ts

@@ -0,0 +1,33 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@chorus/services'
+import { TEST_CONSTANTS } from './constants'
+
+const seedData = H.SeedPipe(
+  H.ChannelSeed({
+    id: 2200,
+    ownerProfileId: TEST_CONSTANTS.profileId,
+    name: 'Editable Channel',
+    slug: 'editable-channel',
+    description: 'Original description'
+  })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('channel owner can edit channel name and description', async ({ page }) => {
+  await page.goto('/c/editable-channel/edit')
+  await page.waitForLoadState('networkidle')
+  await page.getByLabel('Channel Name').clear()
+  await page.getByLabel('Channel Name').fill('Updated Channel')
+  await page.getByLabel('Description').clear()
+  await page.getByLabel('Description').fill('Updated description')
+  await page.getByRole('button', { name: 'Save Changes' }).click()
+  await expect(page.getByText('Updated Channel')).toBeVisible()
+  await expect(page.getByText('Updated description')).toBeVisible()
+})