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

package/skills/react-use-effect/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: react-use-effect
+description: Guide for writing React useEffect correctly and avoiding unnecessary Effects. TRIGGER when writing or reviewing useEffect, syncing state with props, fetching data in components, chaining Effects, or when code has redundant state derived from other state/props. Covers all patterns from "You Might Not Need an Effect" — derived state, expensive calculations, resetting state with keys, event handler logic, data fetching cleanup, and external store subscriptions.
+---
+
+# React useEffect
+
+Effects are escape hatches for synchronizing with **external systems** (network, DOM, third-party widgets). Do not use Effects to transform data or handle user events.
+
+## Decision: Do You Need an Effect?
+
+Ask two questions:
+
+1. **Can this be calculated during rendering?** If yes, use a `const`, `useMemo`, or derive from props/state. No Effect needed.
+2. **Is this responding to a user event?** If yes, put it in the event handler. No Effect needed.
+
+Use an Effect only when synchronizing with something **outside React** (subscriptions, DOM mutations, analytics on mount).
+
+## Patterns
+
+For each anti-pattern below, see [references/patterns.md](references/patterns.md) for full before/after code examples.
+
+### Derive state during render — don't sync with Effects
+
+Calculate values from existing state/props inline. Never store derived data in state and sync it with an Effect.
+
+### Cache expensive calculations with useMemo — not Effects
+
+Wrap expensive computations in `useMemo` with the same dependency array you'd put on the Effect.
+
+### Reset component state with `key` — not Effects
+
+When a prop change means "this is a different thing," render with `key={prop}` so React unmounts/remounts and resets all state automatically.
+
+### Adjust partial state during render — not Effects
+
+If only some state needs to reset when a prop changes, compare previous props during render and call setState conditionally. Better yet, derive the value so no state is needed.
+
+### Put event logic in event handlers — not Effects
+
+If code runs **because the user did something**, it belongs in the handler. Extract shared logic into a helper function called from multiple handlers.
+
+### Avoid Effect chains
+
+Multiple Effects that set state to trigger each other cause extra renders and are hard to follow. Move the logic into the event handler that started the chain, or derive values during render.
+
+### App initialization: module-level — not Effects
+
+Code that runs once per app load (auth checks, localStorage reads) belongs at the module level or behind a `didInit` flag. Effects run twice in dev mode.
+
+### Notify parents from event handlers — not Effects
+
+Call the parent's callback in the same handler that updates local state. Or make the component fully controlled (no local state, parent owns it).
+
+### Lift data fetching up — not down with Effects
+
+The parent should own the fetch and pass data as props. Children that fetch and then notify parents via Effects create unnecessary complexity.
+
+### Subscribe to external stores with useSyncExternalStore
+
+For browser APIs (online status, media queries) or third-party stores, `useSyncExternalStore` handles subscription, SSR, and tearing correctly.
+
+### Data fetching Effects need cleanup
+
+When fetching is appropriate in an Effect, always return a cleanup function with an `ignore` flag to prevent race conditions from stale responses.

package/skills/react-use-effect/references/patterns.md

@@ -0,0 +1,283 @@
+# useEffect Anti-Patterns and Fixes
+
+Complete before/after code examples for every pattern.
+
+## 1. Derived State
+
+```jsx
+// BAD: redundant state + Effect
+const [firstName, setFirstName] = useState('Taylor')
+const [lastName, setLastName] = useState('Swift')
+const [fullName, setFullName] = useState('')
+useEffect(() => {
+  setFullName(firstName + ' ' + lastName)
+}, [firstName, lastName])
+
+// GOOD: calculate during render
+const [firstName, setFirstName] = useState('Taylor')
+const [lastName, setLastName] = useState('Swift')
+const fullName = firstName + ' ' + lastName
+```
+
+## 2. Expensive Calculations
+
+```jsx
+// BAD: Effect to filter
+const [visibleTodos, setVisibleTodos] = useState([])
+useEffect(() => {
+  setVisibleTodos(getFilteredTodos(todos, filter))
+}, [todos, filter])
+
+// GOOD: useMemo
+const visibleTodos = useMemo(
+  () => getFilteredTodos(todos, filter),
+  [todos, filter]
+)
+```
+
+## 3. Reset State with Key
+
+```jsx
+// BAD: Effect to reset
+export default function ProfilePage({ userId }) {
+  const [comment, setComment] = useState('')
+  useEffect(() => { setComment('') }, [userId])
+}
+
+// GOOD: key prop
+export default function ProfilePage({ userId }) {
+  return <Profile userId={userId} key={userId} />
+}
+function Profile({ userId }) {
+  const [comment, setComment] = useState('')
+}
+```
+
+## 4. Adjust Partial State on Prop Change
+
+```jsx
+// BAD: Effect to clear selection
+function List({ items }) {
+  const [selection, setSelection] = useState(null)
+  useEffect(() => { setSelection(null) }, [items])
+}
+
+// OK: compare previous during render
+function List({ items }) {
+  const [selection, setSelection] = useState(null)
+  const [prevItems, setPrevItems] = useState(items)
+  if (items !== prevItems) {
+    setPrevItems(items)
+    setSelection(null)
+  }
+}
+
+// BEST: derive from ID
+function List({ items }) {
+  const [selectedId, setSelectedId] = useState(null)
+  const selection = items.find(item => item.id === selectedId) ?? null
+}
+```
+
+## 5. Event Logic in Handlers
+
+```jsx
+// BAD: Effect reacting to state set by event
+function ProductPage({ product, addToCart }) {
+  useEffect(() => {
+    if (product.isInCart) {
+      showNotification(`Added ${product.name} to the shopping cart!`)
+    }
+  }, [product])
+
+  function handleBuyClick() { addToCart(product) }
+  function handleCheckoutClick() { addToCart(product); navigateTo('/checkout') }
+}
+
+// GOOD: shared helper called from handlers
+function ProductPage({ product, addToCart }) {
+  function buyProduct() {
+    addToCart(product)
+    showNotification(`Added ${product.name} to the shopping cart!`)
+  }
+  function handleBuyClick() { buyProduct() }
+  function handleCheckoutClick() { buyProduct(); navigateTo('/checkout') }
+}
+```
+
+## 6. POST Requests
+
+```jsx
+// BAD: state + Effect to trigger POST
+const [jsonToSubmit, setJsonToSubmit] = useState(null)
+useEffect(() => {
+  if (jsonToSubmit !== null) post('/api/register', jsonToSubmit)
+}, [jsonToSubmit])
+function handleSubmit(e) {
+  e.preventDefault()
+  setJsonToSubmit({ firstName, lastName })
+}
+
+// GOOD: POST in handler directly
+function handleSubmit(e) {
+  e.preventDefault()
+  post('/api/register', { firstName, lastName })
+}
+```
+
+Note: analytics on mount (`useEffect(() => { post('/analytics/event', { eventName: 'visit_form' }) }, [])`) IS a valid Effect — it runs because the component was displayed, not because of a user event.
+
+## 7. Effect Chains
+
+```jsx
+// BAD: chain of Effects triggering each other
+useEffect(() => {
+  if (card !== null && card.gold) setGoldCardCount(c => c + 1)
+}, [card])
+useEffect(() => {
+  if (goldCardCount > 3) { setRound(r => r + 1); setGoldCardCount(0) }
+}, [goldCardCount])
+useEffect(() => {
+  if (round > 5) setIsGameOver(true)
+}, [round])
+
+// GOOD: derive + compute in handler
+const isGameOver = round > 5
+
+function handlePlaceCard(nextCard) {
+  if (isGameOver) throw Error('Game already ended.')
+  setCard(nextCard)
+  if (nextCard.gold) {
+    if (goldCardCount < 3) {
+      setGoldCardCount(goldCardCount + 1)
+    } else {
+      setGoldCardCount(0)
+      setRound(round + 1)
+      if (round === 5) alert('Good game!')
+    }
+  }
+}
+```
+
+## 8. App Initialization
+
+```jsx
+// OK: guard flag
+let didInit = false
+function App() {
+  useEffect(() => {
+    if (!didInit) {
+      didInit = true
+      loadDataFromLocalStorage()
+      checkAuthToken()
+    }
+  }, [])
+}
+
+// BETTER: module-level
+if (typeof window !== 'undefined') {
+  checkAuthToken()
+  loadDataFromLocalStorage()
+}
+function App() { /* ... */ }
+```
+
+## 9. Notify Parent
+
+```jsx
+// BAD: Effect to call parent onChange
+function Toggle({ onChange }) {
+  const [isOn, setIsOn] = useState(false)
+  useEffect(() => { onChange(isOn) }, [isOn, onChange])
+  function handleClick() { setIsOn(!isOn) }
+}
+
+// GOOD: call both in handler
+function Toggle({ onChange }) {
+  const [isOn, setIsOn] = useState(false)
+  function updateToggle(nextIsOn) {
+    setIsOn(nextIsOn)
+    onChange(nextIsOn)
+  }
+  function handleClick() { updateToggle(!isOn) }
+}
+
+// ALSO GOOD: fully controlled
+function Toggle({ isOn, onChange }) {
+  function handleClick() { onChange(!isOn) }
+}
+```
+
+## 10. Pass Data Up
+
+```jsx
+// BAD: child fetches, notifies parent via Effect
+function Child({ onFetched }) {
+  const data = useSomeAPI()
+  useEffect(() => { if (data) onFetched(data) }, [onFetched, data])
+}
+
+// GOOD: parent fetches, passes down
+function Parent() {
+  const data = useSomeAPI()
+  return <Child data={data} />
+}
+```
+
+## 11. External Store Subscription
+
+```jsx
+// BAD: manual subscription in Effect
+function useOnlineStatus() {
+  const [isOnline, setIsOnline] = useState(true)
+  useEffect(() => {
+    function updateState() { setIsOnline(navigator.onLine) }
+    updateState()
+    window.addEventListener('online', updateState)
+    window.addEventListener('offline', updateState)
+    return () => {
+      window.removeEventListener('online', updateState)
+      window.removeEventListener('offline', updateState)
+    }
+  }, [])
+  return isOnline
+}
+
+// GOOD: useSyncExternalStore
+function subscribe(callback) {
+  window.addEventListener('online', callback)
+  window.addEventListener('offline', callback)
+  return () => {
+    window.removeEventListener('online', callback)
+    window.removeEventListener('offline', callback)
+  }
+}
+
+function useOnlineStatus() {
+  return useSyncExternalStore(
+    subscribe,
+    () => navigator.onLine,
+    () => true // server snapshot
+  )
+}
+```
+
+## 12. Data Fetching with Cleanup
+
+```jsx
+// BAD: no cleanup — race condition
+useEffect(() => {
+  fetchResults(query, page).then(json => setResults(json))
+}, [query, page])
+
+// GOOD: ignore flag prevents stale updates
+useEffect(() => {
+  let ignore = false
+  fetchResults(query, page).then(json => {
+    if (!ignore) setResults(json)
+  })
+  return () => { ignore = true }
+}, [query, page])
+```
+
+For production apps, prefer a data-fetching library (TanStack Query, SWR, etc.) or your framework's built-in data fetching over raw Effects.

package/dist/maestro-packages/queue.md

@@ -1,284 +0,0 @@
----
-name: queue
-description: "Database-backed job queue for deferring work beyond the current request with scheduled execution, concurrency control, and distributed tracing. Use when working with @maestro-js/queue, including dispatching jobs, processing queues, configuring the db driver, writing queue consumers, handling retries/stuck jobs, integrating with mail or recurring-jobs, and understanding the queue database schema."
----
-
-# @maestro-js/queue
-
-Database-backed job queue that stores messages in MySQL via a pluggable driver and processes them asynchronously. Follows the Provider pattern from `@maestro-js/service-registry` with a producer/consumer split supporting scheduled execution, concurrency, and distributed trace propagation.
-
-## Quick Setup
-
-```ts
-import { Queue } from '@maestro-js/queue'
-import { Db } from '@maestro-js/db'
-import { Log } from '@maestro-js/log'
-
-// Register the queue service with the db driver
-Queue.Provider.register(
-  'default',
-  Queue.Provider.create({
-    driver: Queue.drivers.db({
-      db: Db.provider('default'),
-      databaseTable: 'jobs'
-    }),
-    logger: Log
-  })
-)
-
-// Create a named queue with a work function
-const orderQueue = Queue.create({
-  name: 'fulfill-orders',
-  workFn: async (body) => {
-    await fulfillOrder(body.orderId)
-    return { fulfilled: true }
-  },
-  concurrency: 3
-})
-
-// Enqueue a message
-await orderQueue.addMessage({ orderId: 'ord_123' }, { scheduledDate: null })
-
-// Start processing
-orderQueue.startProcessing()
-```
-
-## Database Schema
-
-The db driver expects a MySQL table (name configurable via `databaseTable`). The column-to-field mapping used internally:
-
-| Column          | Type          | Description                                              |
-| --------------- | ------------- | -------------------------------------------------------- |
-| `id`            | int (PK, AI)  | Message ID                                               |
-| `batch_id`      | int / NULL    | Lock batch for concurrent dequeue                        |
-| `job_type`      | varchar       | Queue name string                                        |
-| `body`          | text (JSON)   | Serialized message body                                  |
-| `trace`         | text (JSON)   | Serialized `DehydratedTrace` for distributed tracing     |
-| `status`        | enum          | `waiting`, `processing`, `success`, `error`, `stuck`     |
-| `scheduledDate` | datetime      | Earliest time the message can be processed               |
-| `enqueuedDate`  | datetime      | When the message was inserted                            |
-| `started_ts`    | datetime      | When processing began                                    |
-| `result`        | text          | JSON result on success, error stack on failure           |
-| `recovered`     | tinyint       | 1 if the message was recovered from stuck state          |
-| `running_time`  | int / NULL    | Seconds elapsed during processing                        |
-| `unique_key`    | int / NULL    | MD5-derived dedup key (nullable)                         |
-| `priority`      | bigint / NULL | Lower value = higher priority (defaults to `Date.now()`) |
-
-The driver requires a `FORCE INDEX (locking_update)` index on `(batch_id, status, job_type, scheduledDate)` for efficient locking queries.
-
-## API Reference
-
-### Provider Setup
-
-```ts
-Queue.Provider.create(config: {
-  driver: Queue.Driver
-  logger: Log.Logger<[Queue.LogMessage]>
-  tracing?: Queue.Tracing  // optional distributed tracing adapter
-}): Queue.QueueService
-```
-
-```ts
-Queue.Provider.register(name: Queue.Provider.Key, service: Queue.QueueService): void
-```
-
-### Drivers
-
-```ts
-Queue.drivers.db(config: {
-  db: { update, select, insert }  // Db provider interface
-  databaseTable: string
-  extraFields?: string[]           // additional columns to insert
-  fastestPollingRateMs?: number    // default 100
-  slowestPollingRateMs?: number    // default 10_000
-  pollingBackoffRate?: number      // default 1.1
-}): Queue.Driver
-```
-
-### Queue Instance Methods
-
-Create a queue:
-
-```ts
-const queue = Queue.create<MessageBody, Result>({
-  name: string,
-  workFn: (body: MessageBody) => Promise<Result>,
-  logger?: Log.LogFunctions<[Queue.LogMessage]>,  // additional per-queue logger
-  concurrency?: number  // default 1
-})
-```
-
-Dispatch a message:
-
-```ts
-await queue.addMessage(body, {
-  scheduledDate: Iso.Instant | null,   // null = process immediately
-  tracingContext?: DehydratedTrace | null
-})
-```
-
-Update a waiting message:
-
-```ts
-await queue.updateMessage({
-  messageId: number,
-  scheduledDate: Iso.Instant,
-  body: MessageBody
-})
-```
-
-List messages (paginated):
-
-```ts
-const messages = await queue.listMessages({ pageSize: 50, pageNumber: 0 })
-```
-
-Processing control:
-
-```ts
-queue.startProcessing()     // begin polling and processing
-queue.stopProcessing()      // stop polling
-await queue.processUntilEmpty({ pollingMs?: number })  // process then resolve when empty
-```
-
-### Service-Level Methods
-
-```ts
-Queue.list() // names of all registered queues
-Queue.get<Body, Result>(name) // retrieve a queue by name
-Queue.startProcessing() // start all queues
-Queue.stopProcessing() // stop all queues
-```
-
-### Message Statuses
-
-| Status       | Meaning                                                        |
-| ------------ | -------------------------------------------------------------- |
-| `waiting`    | Queued and eligible for processing when scheduled time arrives |
-| `processing` | Locked by a worker and currently executing                     |
-| `success`    | Work function completed without error                          |
-| `error`      | Work function threw or timed out                               |
-| `stuck`      | Processing exceeded timeout; recovered or marked stuck         |
-
-### Log Events
-
-The queue emits structured log messages with these `event` values:
-
-- `messageEnqueued` -- message added to the queue
-- `messageDequeued` -- message picked up by a worker
-- `messageProcessed` -- work function completed successfully
-- `messageFailed` -- work function threw an error
-- `queueStarted` -- queue processing started
-- `queueStopped` -- queue processing stopped
-
-## Common Patterns
-
-### Schedule a Future Job
-
-```ts
-import { instantFns } from 'iso-fns2'
-
-// Schedule 1 hour from now
-const oneHourLater = instantFns.add(instantFns.now(), { hours: 1 })
-await queue.addMessage({ task: 'reminder' }, { scheduledDate: oneHourLater })
-```
-
-### Deduplication with Unique Keys
-
-The db driver supports unique keys via the `addMessage` options on the driver level. When a duplicate `uniqueKey` is inserted, the row is not duplicated -- instead the priority is updated if the new priority is higher (lower number).
-
-### Process Until Empty (Worker Scripts)
-
-```ts
-// Useful for one-off batch processing or tests
-await queue.processUntilEmpty({ pollingMs: 1000 })
-// Resolves when no waiting/processing messages remain
-```
-
-### Concurrency Control
-
-```ts
-// High-concurrency queue for lightweight jobs
-const emailQueue = Queue.create({
-  name: 'send-emails',
-  workFn: async (body) => sendEmail(body),
-  concurrency: 10
-})
-```
-
-### Stuck Job Recovery
-
-The db driver automatically recovers stuck jobs every 60 seconds. Jobs in `processing` status that exceed the timeout (default 45 minutes) are reset to `waiting` and reprocessed. Set `shouldRecoverStuckJobs: false` in the driver `start` options to mark them as `stuck` instead of recovering.
-
-### Distributed Tracing
-
-Pass a `tracing` adapter when creating the service to propagate trace context across producer/consumer boundaries:
-
-```ts
-Queue.Provider.register(
-  'default',
-  Queue.Provider.create({
-    driver: Queue.drivers.db({ db: Db.provider('default'), databaseTable: 'jobs' }),
-    logger: Log,
-    tracing: {
-      hydrate: (trace, callback) => {
-        /* restore trace context */ return callback()
-      },
-      dehydrate: () => {
-        /* return current trace context */ return null
-      },
-      startActiveSpan: (name, fn) => fn(),
-      getActiveSpan: () => undefined
-    }
-  })
-)
-```
-
-The trace data is serialized as `DehydratedTrace` (traceId, spanId, traceFlags, traceState) and stored in the `trace` column.
-
-## Testing
-
-This package has no tests yet (`pnpm --filter @maestro-js/queue test` prints "No tests yet"). To test queue behavior in consuming packages, mock the driver interface:
-
-```ts
-const mockDriver: Queue.Driver = {
-  start: () => {},
-  stop: () => {},
-  listMessages: async () => [],
-  addMessage: async () => ({ id: 1 }),
-  updateMessage: async () => {},
-  isQueueEmpty: async () => true
-}
-
-Queue.Provider.register(
-  'default',
-  Queue.Provider.create({
-    driver: mockDriver,
-    logger: Log
-  })
-)
-```
-
-## Cross-Package Integration
-
-### Mail (async email sending)
-
-The `@maestro-js/mail` package uses Queue to dispatch email-sending jobs asynchronously. Mail enqueues messages; a queue consumer processes them via the configured mail driver.
-
-### Recurring Jobs (cron scheduling)
-
-The `@maestro-js/recurring-jobs` package uses Queue to execute scheduled/cron-based jobs. It dispatches queue messages on a schedule and relies on the queue's processing infrastructure.
-
-### Db (database driver)
-
-The db driver requires a `Db` provider that exposes `select`, `update`, and `insert` methods. Pass `Db.provider('default')` as the `db` config option.
-
-### Tracing
-
-Integrate with `@maestro-js/tracing` by implementing the `Queue.Tracing` interface to propagate OpenTelemetry-compatible trace context across the producer/consumer boundary.
-
-## Source Files
-
-- `packages/queue/src/index.ts` -- Provider pattern, facade, queue creation and lifecycle
-- `packages/queue/src/queue-types.ts` -- TypeScript interfaces for QueueMessage, QueueDriver, QueueTracing, log events
-- `packages/queue/src/db-queue-driver.ts` -- MySQL-backed driver with polling, batched locking, stuck job recovery