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

package/skills/maestro-examples/references/cadence/cadence-web/app/components/toast.tsx

@@ -0,0 +1,182 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add toast --directory app
+
+import * as React from 'react'
+import { flushSync } from 'react-dom'
+import {
+  Text,
+  UNSTABLE_Toast as AriaToast,
+  UNSTABLE_ToastContent as ToastContent,
+  UNSTABLE_ToastQueue as ToastQueue,
+  UNSTABLE_ToastRegion as AriaToastRegion
+} from 'react-aria-components'
+import { tw } from '../utils/tw'
+import { Icon } from './icon'
+import { HeadlessButton } from './helpers/headless-button'
+
+export interface Toast {
+  title: string
+  description?: string
+  variant?: 'info' | 'positive' | 'warning' | 'negative' | 'notice'
+}
+
+const queue = new ToastQueue<Toast>({
+  wrapUpdate(fn) {
+    if ('startViewTransition' in document) {
+      document.startViewTransition(() => {
+        flushSync(fn)
+      })
+    } else {
+      fn()
+    }
+  }
+})
+
+export function showToast(
+  toast: Toast,
+  options?: {
+    /** Handler that is called when the toast is closed, either by the user or after a timeout. */
+    onClose?: () => void
+    /** A timeout to automatically close the toast after, in milliseconds. */
+    timeout?: number | null
+  }
+) {
+  return queue.add(toast, {
+    ...options,
+    timeout: typeof options?.timeout === 'undefined' ? 5_000 : (options?.timeout ?? undefined)
+  })
+}
+
+export function ToastRegion({ toast }: { toast?: Toast | null }) {
+  return (
+    <>
+      <style>
+        {`
+::view-transition-new(.toast):only-child {
+  animation: maestro-toast-slide-in 400ms;
+}
+
+::view-transition-old(.toast):only-child {
+  animation: maestro-toast-slide-out 400ms;
+  animation-fill-mode: forwards;
+}
+
+@keyframes maestro-toast-slide-out {
+  to {
+    translate: 0 100%;
+    opacity: 0;
+    visibility: hidden;
+  }
+}
+
+@keyframes maestro-toast-slide-in {
+  from {
+    translate: 0 100%;
+    opacity: 0;
+  }
+}
+      `}
+      </style>
+      <AriaToastRegion
+        className="fixed right-4 bottom-4 sm:right-6 sm:bottom-6 z-[6000] flex flex-col gap-2 pointer-events-none outline-none"
+        queue={queue}
+      >
+        {({ toast }) => <ToastItem toast={toast} />}
+      </AriaToastRegion>
+      {toast ? <DeclaredToast toast={toast} /> : null}
+    </>
+  )
+}
+
+ToastRegion.displayName = 'ToastRegion'
+
+// --- Internal Components ---
+
+function ToastItem({ toast }: { toast: { content: Toast; key: string } }) {
+  const variant = toast.content.variant || 'info'
+  const hasDescription = !!toast.content.description
+
+  return (
+    <AriaToast
+      toast={toast}
+      style={{ viewTransitionName: toast.key } as React.CSSProperties}
+      className={tw(
+        'pointer-events-auto',
+        'flex gap-3 rounded-lg px-4 py-3 shadow-lg',
+        'min-w-[300px] max-w-md',
+        '[view-transition-class:toast]',
+        hasDescription ? 'items-start' : 'items-center',
+        variantClasses[variant]
+      )}
+    >
+      <Icon name={variantIconNames[variant]} className={tw('h-5 w-5 shrink-0', hasDescription && 'mt-0.5')} />
+      <ToastContent className="flex flex-1 flex-col min-w-0">
+        <Text slot="title" className="font-semibold text-sm">
+          {toast.content.title}
+        </Text>
+        {toast.content.description && (
+          <Text slot="description" className="mt-1 text-sm">
+            {toast.content.description}
+          </Text>
+        )}
+      </ToastContent>
+      <HeadlessButton
+        onClick={() => queue.close(toast.key)}
+        className={tw(
+          'flex-shrink-0 rounded p-1 transition-colors',
+          'hover:bg-black/5 focus:outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2',
+          variantCloseOutlineClasses[variant]
+        )}
+      >
+        <Icon name="x-mark" className="h-5 w-5" />
+      </HeadlessButton>
+    </AriaToast>
+  )
+}
+
+function DeclaredToast({
+  toast,
+  options
+}: {
+  toast: Toast
+  options?: {
+    onClose?: () => void
+    timeout?: number | null
+  }
+}) {
+  const shown = React.useRef(false)
+  React.useEffect(() => {
+    if (shown.current) return
+    shown.current = true
+    setTimeout(() => {
+      showToast(toast, options)
+    }, 0)
+  }, [toast, options])
+  return null
+}
+
+// --- Variant Maps ---
+
+const variantClasses = {
+  info: 'bg-info-50 text-info-800 ring-1 ring-info-200',
+  positive: 'bg-positive-50 text-positive-800 ring-1 ring-positive-200',
+  warning: 'bg-notice-50 text-notice-800 ring-1 ring-notice-200',
+  negative: 'bg-negative-50 text-negative-800 ring-1 ring-negative-200',
+  notice: 'bg-neutral-50 text-neutral-700 ring-1 ring-neutral-200'
+}
+
+const variantIconNames = {
+  info: 'information-circle',
+  positive: 'check',
+  warning: 'exclamation-triangle',
+  negative: 'x-mark',
+  notice: 'information-circle'
+} as const
+
+const variantCloseOutlineClasses = {
+  info: 'focus-visible:outline-info-500',
+  positive: 'focus-visible:outline-positive-600',
+  warning: 'focus-visible:outline-notice-600',
+  negative: 'focus-visible:outline-negative-600',
+  notice: 'focus-visible:outline-neutral-400'
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/top-nav.tsx

@@ -0,0 +1,175 @@
+import * as React from 'react'
+import { NavLink, useLocation } from 'react-router'
+import { Form } from '~/components/form'
+import { Icon } from '~/components/icon'
+import type { IconName } from '~/icons/types'
+
+interface TopNavProps {
+  orgName: string
+  userName: string
+  userRole: string
+  csrfToken: string
+}
+
+const navItems: { to: string; label: string; icon: IconName }[] = [
+  { to: '/contacts', label: 'Contacts', icon: 'users' },
+  { to: '/activity', label: 'Activity', icon: 'clock' },
+  { to: '/archive', label: 'Archive', icon: 'archive-box' },
+  { to: '/users', label: 'Users', icon: 'users' },
+  { to: '/settings', label: 'Settings', icon: 'cog-6-tooth' }
+]
+
+export function TopNav({ orgName, userName, userRole, csrfToken }: TopNavProps) {
+  const [mobileOpen, setMobileOpen] = React.useState(false)
+  const [userMenuOpen, setUserMenuOpen] = React.useState(false)
+  const userMenuRef = React.useRef<HTMLDivElement>(null)
+  const location = useLocation()
+
+  React.useEffect(() => {
+    setMobileOpen(false)
+  }, [location.pathname])
+
+  React.useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (userMenuRef.current && !userMenuRef.current.contains(e.target as Node)) {
+        setUserMenuOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [])
+
+  return (
+    <header className="sticky top-0 z-40 border-b border-neutral-200 bg-white">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <div className="flex h-14 items-center justify-between">
+          {/* Logo / Org name */}
+          <div className="flex items-center gap-8">
+            <NavLink to="/contacts" className="flex items-center gap-2">
+              <div className="flex h-7 w-7 items-center justify-center rounded-md bg-primary-600 text-white">
+                <span className="text-xs font-bold">{orgName.charAt(0).toUpperCase()}</span>
+              </div>
+              <span className="text-sm font-semibold text-neutral-900 hidden sm:block">{orgName}</span>
+            </NavLink>
+
+            {/* Desktop navigation */}
+            <nav className="hidden md:flex items-center gap-1">
+              {navItems.map(({ to, label, icon }) => (
+                <NavLink
+                  key={to}
+                  to={to}
+                  className={({ isActive }) =>
+                    `top-nav-item ${isActive ? 'active' : ''}`
+                  }
+                >
+                  <Icon name={icon} className="h-4 w-4" />
+                  <span>{label}</span>
+                </NavLink>
+              ))}
+            </nav>
+          </div>
+
+          {/* Right side: user menu + mobile toggle */}
+          <div className="flex items-center gap-2">
+            {/* User menu (desktop) */}
+            <div className="relative hidden md:block" ref={userMenuRef}>
+              <button
+                type="button"
+                onClick={() => setUserMenuOpen(!userMenuOpen)}
+                className="flex items-center gap-2 rounded-lg px-2.5 py-1.5 text-sm text-neutral-700 hover:bg-neutral-100 transition-colors"
+              >
+                <div className="flex h-6 w-6 items-center justify-center rounded-full bg-primary-100 text-primary-700">
+                  <span className="text-xs font-medium">{userName.charAt(0).toUpperCase()}</span>
+                </div>
+                <span className="text-sm font-medium text-neutral-700">{userName}</span>
+                <Icon name="chevron-down" className="h-3.5 w-3.5 text-neutral-400" />
+              </button>
+              {userMenuOpen && (
+                <div className="absolute right-0 top-full z-50 mt-1 w-48 rounded-lg border border-neutral-200 bg-white py-1 shadow-lg">
+                  <div className="border-b border-neutral-100 px-3 py-2">
+                    <p className="text-sm font-medium text-neutral-900 truncate">{userName}</p>
+                    <p className="text-xs text-neutral-500 capitalize">{userRole}</p>
+                  </div>
+                  <Form method="post" action="/auth/logout">
+                    <input type="hidden" name="__csrfToken" value={csrfToken} />
+                    <button
+                      type="submit"
+                      className="flex w-full items-center gap-2 px-3 py-2 text-sm text-neutral-600 hover:bg-neutral-50 hover:text-neutral-900"
+                    >
+                      <Icon name="arrow-right-start-on-rectangle" className="h-4 w-4" />
+                      Log out
+                    </button>
+                  </Form>
+                </div>
+              )}
+            </div>
+
+            {/* Mobile hamburger */}
+            <button
+              type="button"
+              onClick={() => setMobileOpen(true)}
+              className="rounded-md p-2 text-neutral-600 hover:bg-neutral-100 md:hidden"
+              aria-label="Open navigation"
+            >
+              <Icon name="bars-3" className="h-5 w-5" />
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Mobile overlay */}
+      {mobileOpen && (
+        <div className="fixed inset-0 z-50 md:hidden">
+          <div className="fixed inset-0 bg-black/30" onClick={() => setMobileOpen(false)} />
+          <div className="fixed inset-y-0 right-0 z-50 w-72 bg-white shadow-xl">
+            <div className="flex items-center justify-between border-b border-neutral-200 px-4 py-3">
+              <span className="text-sm font-semibold text-neutral-900">{orgName}</span>
+              <button
+                type="button"
+                onClick={() => setMobileOpen(false)}
+                className="rounded-md p-1 text-neutral-400 hover:text-neutral-600"
+                aria-label="Close navigation"
+              >
+                <Icon name="x-mark" className="h-5 w-5" />
+              </button>
+            </div>
+            <nav className="px-2 py-3 space-y-0.5">
+              {navItems.map(({ to, label, icon }) => (
+                <NavLink
+                  key={to}
+                  to={to}
+                  className={({ isActive }) =>
+                    `flex items-center gap-2.5 rounded-md px-3 py-2 text-sm transition-colors ${
+                      isActive
+                        ? 'bg-primary-50 text-primary-700 font-medium'
+                        : 'text-neutral-600 hover:bg-neutral-100 hover:text-neutral-900'
+                    }`
+                  }
+                >
+                  <Icon name={icon} className="h-4 w-4" />
+                  <span>{label}</span>
+                </NavLink>
+              ))}
+            </nav>
+            <div className="absolute bottom-0 left-0 right-0 border-t border-neutral-200 px-4 py-3">
+              <div className="mb-2">
+                <p className="text-sm font-medium text-neutral-900 truncate">{userName}</p>
+                <p className="text-xs text-neutral-500 capitalize">{userRole}</p>
+              </div>
+              <Form method="post" action="/auth/logout">
+                <input type="hidden" name="__csrfToken" value={csrfToken} />
+                <button
+                  type="submit"
+                  className="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-500 hover:bg-neutral-100 hover:text-neutral-700"
+                >
+                  <Icon name="arrow-right-start-on-rectangle" className="h-4 w-4" />
+                  Log out
+                </button>
+              </Form>
+            </div>
+          </div>
+        </div>
+      )}
+    </header>
+  )
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/entry.client.tsx

@@ -0,0 +1,21 @@
+import * as Sentry from '@sentry/react-router'
+import { startTransition, StrictMode } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { HydratedRouter } from 'react-router/dom'
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  integrations: [Sentry.reactRouterTracingIntegration(), Sentry.replayIntegration()],
+  tracesSampleRate: 1.0,
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0
+})
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter />
+    </StrictMode>
+  )
+})

package/skills/maestro-examples/references/cadence/cadence-web/app/entry.server.tsx

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/react-router'
+import { createReadableStreamFromReadable } from '@react-router/node'
+import { renderToPipeableStream } from 'react-dom/server'
+import { ServerRouter } from 'react-router'
+import '~/services.server'
+
+export default Sentry.createSentryHandleRequest({
+  ServerRouter,
+  renderToPipeableStream,
+  createReadableStreamFromReadable
+})
+
+export const handleError = Sentry.createSentryHandleError({ logErrors: true })

package/skills/maestro-examples/references/cadence/cadence-web/app/features/csrf-middleware.server.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareFunction } from 'react-router'
+import { getRequestContext } from './request-context.server'
+
+export const csrfMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
+  const mutatingMethods = ['POST', 'PUT', 'DELETE']
+  if (mutatingMethods.includes(request.method)) {
+    const cloned = request.clone()
+    const formDataForMiddleware = await cloned.formData()
+    const clientCsrfToken = formDataForMiddleware.get('__csrfToken')
+    const requestContext = getRequestContext(context)
+    const sessionCsrfToken = requestContext.session.getCsrfToken()
+    if (clientCsrfToken !== sessionCsrfToken) {
+      throw new Response('Invalid CSRF token', { status: 403 })
+    }
+  }
+  return next()
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/features/custom-error-status-code-middleware.server.ts

@@ -0,0 +1,31 @@
+import * as Sentry from '@sentry/react-router'
+import { type MiddlewareFunction } from 'react-router'
+import { CustomErrors, Log } from '~/services.server'
+
+const log = Log.channel('http')
+
+export const customErrorStatusCodeMiddleware: MiddlewareFunction<Response> = async ({ request }, next) => {
+  try {
+    return await next()
+  } catch (e) {
+    if (e instanceof Response) throw e
+
+    const statusCode = CustomErrors.getHttpStatusCode(e)
+    if (statusCode) {
+      if (statusCode >= 500) {
+        log.error('Server error', {
+          status: statusCode,
+          url: request.url,
+          error: e instanceof Error ? e.message : String(e)
+        })
+      } else {
+        log.warn('Client error', { status: statusCode, url: request.url, error: e instanceof Error ? e.name : String(e) })
+      }
+      throw new Response(null, { status: statusCode })
+    } else {
+      Sentry.captureException(e)
+      log.error('Unhandled error', { url: request.url, error: e instanceof Error ? (e.stack ?? e.message) : String(e) })
+      throw e
+    }
+  }
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/features/rate-limiting-middleware.server.ts

@@ -0,0 +1,36 @@
+import { RateLimiting } from '~/services.server'
+import type { MiddlewareFunction } from 'react-router'
+
+const isTesting = process.env.IS_TESTING === 'true'
+
+export function rateLimitingMiddleware(
+  getOptions: (args: Parameters<MiddlewareFunction>[0]) =>
+    | {
+        key: string
+        maxAttemptsPerWindow: number
+        decaySeconds?: number | undefined
+      }
+    | Promise<{
+        key: string
+        maxAttemptsPerWindow: number
+        decaySeconds?: number | undefined
+      }>
+    | null
+) {
+  const middleware: MiddlewareFunction<Response> = async (args, next) => {
+    if (isTesting) return next()
+
+    const options = await getOptions(args)
+    if (options) {
+      if (await RateLimiting.tooManyAttempts(options.key, options.maxAttemptsPerWindow)) {
+        throw new Response('Too Many Requests', { status: 429 })
+      } else {
+        await RateLimiting.increment(options.key, 1, options.decaySeconds)
+        return await next()
+      }
+    } else {
+      return next()
+    }
+  }
+  return middleware
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/features/redirect-with-toast.server.ts

@@ -0,0 +1,14 @@
+import { redirect } from 'react-router'
+import type { Toast } from '~/components/toast'
+import type { Session } from '~/services.server'
+
+const TOAST_SESSION_KEY = '_toast'
+
+export function redirectWithToast(url: string, toast: Toast, session: Session) {
+  session.flash(TOAST_SESSION_KEY, toast)
+  return redirect(url)
+}
+
+export function getSessionToast(session: Session): Toast | null {
+  return (session.get(TOAST_SESSION_KEY) as Toast) ?? null
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/features/request-context.server.ts

@@ -0,0 +1,40 @@
+import { Auth, AuthService, Helpers, Session } from '~/services.server'
+import { createContext, RouterContextProvider, type MiddlewareFunction } from 'react-router'
+import { randomUUID } from 'node:crypto'
+import assert from 'node:assert'
+import type { UserSchemas } from '@cadence/schemas'
+
+interface RequestContext {
+  profile: UserSchemas.profileModel | null
+  requestId: string
+  session: Session
+  deviceContext: ReturnType<typeof Helpers.getDeviceContext>
+}
+
+const requestContext = createContext<RequestContext | null>(null)
+
+export const requestContextMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
+  const requestId = randomUUID()
+  const cookieHeader = request.headers.get('Cookie')
+  const session = await Session.getSession(cookieHeader)
+  const deviceContext = Helpers.getDeviceContext(request)
+  const authResult = await Auth.authenticate({ session, cookieHeader, deviceContext })
+  const profile = authResult.id ? await AuthService.GetProfileByUserId({ userId: authResult.id }) : null
+
+  context.set(requestContext, { profile, requestId, session, deviceContext })
+
+  const response = await next()
+
+  if (authResult.cookie) {
+    response.headers.append('Set-Cookie', authResult.cookie)
+  }
+  response.headers.append('Set-Cookie', await session.commit())
+
+  return response
+}
+
+export function getRequestContext(context: Readonly<RouterContextProvider>) {
+  const request = context.get(requestContext)
+  assert.ok(request)
+  return request
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/features/security-headers-middleware.server.ts

@@ -0,0 +1,10 @@
+import type { MiddlewareFunction } from 'react-router'
+
+export const securityHeadersMiddleware: MiddlewareFunction<Response> = async (_args, next) => {
+  const response = await next()
+  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+  response.headers.set('X-Content-Type-Options', 'nosniff')
+  response.headers.set('X-Frame-Options', 'DENY')
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
+  return response
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/icons/types.ts

@@ -0,0 +1,36 @@
+// This file is generated by icon spritesheet generator
+
+export const iconNames = [
+  'x-mark',
+  'users',
+  'trash',
+  'tag',
+  'queue-list',
+  'plus',
+  'pencil',
+  'minus',
+  'magnifying-glass',
+  'list-bullet',
+  'link',
+  'information-circle',
+  'exclamation-triangle',
+  'envelope',
+  'document-text',
+  'cog-6-tooth',
+  'code-bracket',
+  'clock',
+  'chevron-up',
+  'chevron-up-down',
+  'chevron-right',
+  'chevron-left',
+  'chevron-down',
+  'check',
+  'chat-bubble-bottom-center-text',
+  'calendar',
+  'bars-3',
+  'arrow-right-start-on-rectangle',
+  'arrow-path',
+  'archive-box'
+] as const
+
+export type IconName = (typeof iconNames)[number]