@maestro-js/agent-skills 1.0.0-alpha.0

package/dist/maestro-packages/rate-limiting.md

@@ -0,0 +1,206 @@
+---
+name: rate-limiting
+description: "Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login, API endpoints, or any action that needs throttling. Provides increment/check/clear workflow, guarded callback execution via attempt(), and ISO 8601 duration reporting. Requires a cache driver (e.g. from @maestro-js/cache)."
+---
+
+# @maestro-js/rate-limiting
+
+Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login,
+API endpoints, or any action that needs throttling.
+
+## Quick Setup
+
+```ts
+import { RateLimiting } from '@maestro-js/rate-limiting'
+import { Cache } from '@maestro-js/cache'
+
+// Create using a cache service as the driver
+const cacheService = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379 })
+})
+
+const rateLimiter = RateLimiting.Provider.create(cacheService)
+RateLimiting.Provider.register('default', rateLimiter)
+
+// Check before allowing an action
+await RateLimiting.increment('login:user@example.com', 1, 300)
+
+if (await RateLimiting.tooManyAttempts('login:user@example.com', 5)) {
+  const retryAfter = await RateLimiting.availableIn('login:user@example.com')
+  throw new Error(`Too many attempts. Try again in ${retryAfter}`)
+}
+```
+
+## API Reference
+
+### increment
+
+```ts
+RateLimiting.increment(key: string, amount?: number, decaySeconds?: number): Promise<number>
+```
+
+Records one or more hits against the bucket. Creates the bucket with the given decay window
+(default 60 seconds) if it doesn't exist. Returns the new hit count.
+
+```ts
+const hits = await RateLimiting.increment('api:client-123')        // +1, 60s window
+const hits = await RateLimiting.increment('api:client-123', 5, 120) // +5, 120s window
+```
+
+### tooManyAttempts
+
+```ts
+RateLimiting.tooManyAttempts(key: string, maxAttempts: number): Promise<boolean>
+```
+
+Returns `true` if the bucket has reached or exceeded `maxAttempts` and the decay window is still
+active. If the timer has expired but the counter remains, the counter is cleaned up and `false`
+is returned.
+
+```ts
+if (await RateLimiting.tooManyAttempts('login:user@example.com', 5)) {
+  return res.status(429).json({ error: 'Too many login attempts' })
+}
+```
+
+### remaining
+
+```ts
+RateLimiting.remaining(key: string, maxAttempts: number): Promise<number>
+```
+
+Returns the number of attempts left before `maxAttempts` is reached. Never returns a negative
+number.
+
+```ts
+const left = await RateLimiting.remaining('api:client-123', 100)
+res.setHeader('X-RateLimit-Remaining', left)
+```
+
+### clear
+
+```ts
+RateLimiting.clear(key: string): Promise<void>
+```
+
+Removes both the hit counter and timer for the bucket, fully resetting it.
+
+```ts
+// Reset after a successful login
+await RateLimiting.clear('login:user@example.com')
+```
+
+### availableIn
+
+```ts
+RateLimiting.availableIn(key: string): Promise<Iso.Duration | null>
+```
+
+Returns the time remaining until the decay window expires as an `Iso.Duration`, or `null` if no
+active window exists. The duration is rounded down to the nearest second.
+
+```ts
+const retryAfter = await RateLimiting.availableIn('api:client-123')
+if (retryAfter) {
+  res.setHeader('Retry-After', retryAfter) // e.g. "PT45S"
+}
+```
+
+### attempt
+
+```ts
+RateLimiting.attempt<T>(
+  key: string,
+  maxAttemptsPerWindow: number,
+  callback: () => T,
+  decaySeconds?: number
+): Promise<T | boolean>
+```
+
+Guarded callback execution. If the bucket is under the limit, increments and executes
+`callback`, returning its result. If the limit is exceeded, returns `false` without executing
+the callback.
+
+```ts
+const result = await RateLimiting.attempt('send-email:user-1', 10, async () => {
+  await sendEmail(to, subject, body)
+  return { sent: true }
+}, 3600)
+
+if (result === false) {
+  throw new Error('Email rate limit exceeded')
+}
+```
+
+## Common Patterns
+
+### Login throttling
+
+```ts
+async function handleLogin(email: string, password: string) {
+  const key = `login:${email}`
+
+  if (await RateLimiting.tooManyAttempts(key, 5)) {
+    const retryAfter = await RateLimiting.availableIn(key)
+    return { error: `Too many attempts. Try again in ${retryAfter}` }
+  }
+
+  await RateLimiting.increment(key, 1, 300) // 5-minute window
+
+  const user = await authenticate(email, password)
+  if (user) {
+    await RateLimiting.clear(key)
+    return { success: true }
+  }
+
+  return { error: 'Invalid credentials' }
+}
+```
+
+### API rate limiting with Retry-After header
+
+```ts
+async function rateLimitMiddleware(req: Request, res: Response, next: () => void) {
+  const key = `api:${req.ip}`
+
+  if (await RateLimiting.tooManyAttempts(key, 100)) {
+    const retryAfter = await RateLimiting.availableIn(key)
+    if (retryAfter) {
+      res.setHeader('Retry-After', retryAfter)
+    }
+    return res.status(429).json({ error: 'Rate limit exceeded' })
+  }
+
+  await RateLimiting.increment(key, 1, 60)
+  res.setHeader('X-RateLimit-Remaining', await RateLimiting.remaining(key, 100))
+  next()
+}
+```
+
+### Guarded action with attempt()
+
+```ts
+const result = await RateLimiting.attempt('report:org-5', 3, async () => {
+  return await generateExpensiveReport()
+}, 3600) // 3 per hour
+
+if (result === false) {
+  return { error: 'Report generation rate limit exceeded' }
+}
+```
+
+## Warnings and Gotchas
+
+- **No built-in drivers** — `RateLimiting.Provider.create()` takes a cache driver directly
+  (anything satisfying `RateLimiting.Driver`). Pass a `@maestro-js/cache` service instance.
+- **`attempt()` returns `T | boolean`** — check `=== false` to distinguish a rate-limited call
+  from a callback that returns a falsy value.
+- **`availableIn()` rounds down** — the returned duration is floored to the nearest second.
+- **Two cache keys per bucket** — each rate-limit key uses `_rate_limit:{key}` (counter) and
+  `_rate_limit:{key}:timer` (expiry instant). Keep this in mind when inspecting cache contents.
+- **Default decay is 60 seconds** — if you omit `decaySeconds`, the window is one minute.
+
+## Key Source Files
+
+- `packages/rate-limiting/src/index.ts` — single source file with create factory, Provider
+  pattern, and namespace types

package/dist/maestro-packages/react-router-file-routes.md

@@ -0,0 +1,337 @@
+---
+name: react-router-file-routes
+description: ""
+---
+
+# Route File Naming (Polaris Adventures)
+
+Adapted from https://remix.run/docs/en/main/file-conventions/route-files-v2
+
+## Basic Routes
+
+Any JavaScript or TypeScript files in the `app/routes/` directory will become routes in your application. The filename maps to the route's URL pathname, except for `index.tsx` which is the [index route](https://remix.run/docs/en/main/guides/routing#index-routes) for the [root route](https://remix.run/docs/en/main/file-conventions/route-files-v2#root-route).
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── index.tsx
++ │   └── about.tsx
+  └── root.tsx
+```
+
+| URL      | Matched Routes |
+| -------- | -------------- |
+| `/`      | `index.tsx`    |
+| `/about` | `about.tsx`    |
+
+Note that these routes will be rendered in the outlet of `app/root.tsx` because of [nested-routing](https://remix.run/docs/en/main/guides/routing#what-is-nested-routing).
+
+### Dot Delimiters
+
+Adding a `.` to a route filename will create a `/` in the URL.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   ├── concerts.trending.tsx
++ │   ├── concerts.salt-lake-city.tsx
++ │   └── concerts.san-diego.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route                 |
+| -------------------------- | ----------------------------- |
+| `/concerts/trending`       | `concerts.trending.tsx`       |
+| `/concerts/salt-lake-city` | `concerts.salt-lake-city.tsx` |
+| `/concerts/san-diego`      | `concerts.san-diego.tsx`      |
+
+### Folder Structure
+
+Adding a parent folder to a route file will also create a `/` in the URL.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── trending.tsx
++ │       ├── salt-lake-city.tsx
++ │       └── san-diego.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route                 |
+| -------------------------- | ----------------------------- |
+| `/concerts/trending`       | `concerts/trending.tsx`       |
+| `/concerts/salt-lake-city` | `concerts/salt-lake-city.tsx` |
+| `/concerts/san-diego`      | `concerts/san-diego.tsx`      |
+
+### Dynamic Segments
+
+Usually your URLs aren't static but data-driven. Dynamic segments allow you to match segments of the URL and use that value in your code. You create them with the `$` prefix.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── trending.tsx
++ │       └── $city.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route           |
+| -------------------------- | ----------------------- |
+| `/concerts/trending`       | `concerts/trending.tsx` |
+| `/concerts/salt-lake-city` | `concerts/$city.tsx`    |
+| `/concerts/san-diego`      | `concerts/$city.tsx`    |
+
+### Nested Routes
+
+You can create nested routes with nested folders. By default, a file with the name `_layout` will become the layout for all routes in that folder.
+
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── _layout.tsx
++ │       ├── $city.tsx
++ │       ├── index.tsx
++ │       └── trending.tsx
+  └── root.tsx
+```
+
+All the routes in the `concerts` folder will be child routes of `concerts/_layout.tsx` and render inside the parent route's outlet.
+
+| URL                      | Matched Route         | Layout                              |
+| ------------------------ | --------------------- | ----------------------------------- |
+| /                        | index.tsx             | `root.tsx`                          |
+| /about                   | about.tsx             | `root.tsx`                          |
+| /concerts                | concerts/index.tsx    | `root.tsx` > `concerts/_layout.tsx` |
+| /concerts/trending       | concerts/trending.tsx | `root.tsx` > `concerts/_layout.tsx` |
+| /concerts/salt-lake-city | concerts/$city.tsx    | `root.tsx` > `concerts/_layout.tsx` |
+
+Note you typically want to add an index route when you add nested routes so that something renders inside the parent's outlet when users visit the parent URL directly.
+
+### Nested Layouts without Nested URLs
+
+We call these **Pathless Routes**
+
+Sometimes you want to share a layout with a group of routes without adding any path segments to the URL. A common example is a set of authentication routes that have a different header/footer than the public pages or the logged in app experience. You can do this with a `_leading` underscore in the folder name.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── _auth
++ │   │   ├── login.tsx
++ │   │   ├── _layout.tsx
++ │   │   └── register.tsx
+  │   ├── index.tsx
+  │   └── concerts
+  │       ├── _layout.tsx
+  │       └── $city.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route        | Layout                              |
+| -------------------------- | -------------------- | ----------------------------------- |
+| `/`                        | `index.tsx`          | `root.tsx`                          |
+| `/login`                   | `_auth/login.tsx`    | `root.tsx` > `_auth/_layout.tsx`    |
+| `/register`                | `_auth/register.tsx` | `root.tsx` > `_auth/_layout.tsx`    |
+| `/concerts/salt-lake-city` | `concerts/$city.tsx` | `root.tsx` > `concerts/_layout.tsx` |
+
+Think of the `_leading` underscore as a blanket you're pulling over the filename, hiding the filename from the URL.
+
+Pathless routes can be used at any nesting level to create additional shared layouts. 
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── _sales/
+  │   │   ├── _invoices/
+  │   │   │   ├── $invoiceId.tsx
+  │   │   │   ├── index.tsx
+  │   │   │   └── _layout.tsx
+  │   │   ├── overview.tsx
+  │   │   └── _layout.tsx
+  │   └── about.tsx
+  └── root.tsx
+```
+
+| URL         | Matched Route                     | Layout                                                      |
+| ----------- | --------------------------------- | ----------------------------------------------------------- |
+| `/`         | `_sales/_invoices/index.tsx`      | `root.tsx` > `_sales/_layout.tsx` > `_invoices/_layout.tsx` |
+| `/about`    | `about.tsx`                       | `root.tsx`                                                  |
+| `/overview` | `_sales/overview.tsx`             | `root.tsx` > `_sales/_layout.tsx`                           |
+| `/102000`   | `_sales/_invoices/$invoiceId.tsx` | `root.tsx` > `_sales/_layout.tsx` > `_invoices/_layout.tsx` |
+
+
+> Note: Additional `_leading` underscores in a folder name have no effect so that `__sales/` is interpreted the same as `_sales/`. Files with a `_leading` underscore in the name are given no special treatment (`_about.tsx` matches the url `/_about`)
+
+### Optional Segments
+
+Wrapping a route segment in parentheses will make the segment optional.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── ($lang).tsx
++ │   ├── ($lang).$productId.tsx
++ │   └── ($lang).categories.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route            |
+| -------------------------- | ------------------------ |
+| `/`                        | `($lang).tsx`            |
+| `/categories`              | `($lang).categories.tsx` |
+| `/en/categories`           | `($lang).categories.tsx` |
+| `/fr/categories`           | `($lang).categories.tsx` |
+| `/american-flag-speedo`    | `($lang).tsx`            |
+| `/en/american-flag-speedo` | `($lang).$productId.tsx` |
+| `/fr/american-flag-speedo` | `($lang).$productId.tsx` |
+
+You may wonder why `/american-flag-speedo` is matching the `($lang).tsx` route instead of `($lang).$productId.tsx`. This is because when you have an optional dynamic param segment followed by another dynamic param, Remix cannot reliably determine if a single-segment URL such as `/american-flag-speedo` should match `/:lang` `/:productId`. Optional segments match eagerly and thus it will match `/:lang`. If you have this type of setup it's recommended to look at `params.lang` in the `($lang).tsx` loader and redirect to `/:lang/american-flag-speedo` for the current/default language if `params.lang` is not a valid language code.
+
+### Splat Routes
+
+While [dynamic segments](#dynamic-segments) match a single path segment (the stuff between two `/` in a URL), a splat route will match the rest of a URL, including the slashes.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
++ │   ├── $.tsx
+  │   ├── about.tsx
++ │   └── files.$.tsx
+  └── root.tsx
+```
+
+| URL                                          | Matched Route |
+| -------------------------------------------- | ------------- |
+| `/`                                          | `index.tsx`   |
+| `/beef/and/cheese`                           | `$.tsx`       |
+| `/files`                                     | `files.$.tsx` |
+| `/files/talks/remix-conf_old.pdf`            | `files.$.tsx` |
+| `/files/talks/remix-conf_final.pdf`          | `files.$.tsx` |
+| `/files/talks/remix-conf-FINAL-MAY_2022.pdf` | `files.$.tsx` |
+
+### Escaping Special Characters
+
+If you want one of the special characters Remix uses for these route conventions to actually be a part of the URL, you can escape the conventions with `[]` characters.
+
+| Filename                       | URL                |
+| ------------------------------ | ------------------ |
+| `routes/sitemap[.]xml.tsx`     | `/sitemap.xml`     |
+| `routes/[sitemap.xml].tsx`     | `/sitemap.xml`     |
+| `routes/weird-url.[index].tsx` | `/weird-url/index` |
+| `routes/dolla-bills-[$].tsx`   | `/dolla-bills-$`   |
+| `routes/[[so-weird]].tsx`      | `/[so-weird]`      |
+
+## Folders for Organization
+
+All files or folders with a `trailing_` underscore will be excluded from the file based routing. This allows you to organize your code closer to the routes that use them instead of repeating the feature names across other folders.
+
+Consider these routes:
+
+```diff
+  app/
+  ├── routes/
+  │   ├── _landing/
+  │   │   ├── _layout.tsx
+  │   │   ├── about.tsx
+  │   │   └── index.tsx
+  │   ├── work/
+  │   │   ├── _layout.tsx
+  │   │   ├── projects.tsx
+  │   │   └── index.tsx
+  │   └── work.projects.$id.roadmap.tsx
+  └── root.tsx
+```
+
+Some, or all of them can be folders holding additional helper files.
+
+```diff
+  app/
+  ├── routes/
+  │   ├── _landing/
+  │   │   ├── _layout.tsx
+  │   │   ├── about/
+  │   │   │   ├── helpers_
+  │   │   │   │   ├── employee-profile-card.tsx
+  │   │   │   │   ├── get-employee-data.server.tsx
+  │   │   │   │   └── team-photo.jpg
+  │   │   │   └── index.tsx
+  │   │   ├── footer_.tsx
+  │   │   ├── header_.tsx
+  │   │   ├── scroll-experience_.tsx
+  │   │   └── index.tsx
+  │   ├── work/
+  │   │   ├── _layout.tsx
+  │   │   ├── projects/
+  │   │   │   ├── get-projects.server_.tsx
+  │   │   │   ├── project-card_.tsx
+  │   │   │   ├── project-buttons_.tsx
+  │   │   │   └── index.tsx
+  │   │   ├── primary-nav_.tsx
+  │   │   ├── footer_.tsx
+  │   │   ├── stats_.tsx
+  │   │   └── index.tsx
+  │   └── work.projects.$id.roadmap/
+  │       ├── chart_.tsx
+  │       ├── update-timeline.server_.tsx
+  │       └── index.tsx
+  └── root.tsx
+```
+
+```
+# these are the same route:
+routes/work.tsx
+routes/work/index.tsx
+```
+
+# Differences with Remix Routing v1, Remix Routing v2, and Remix Flat Routes 
+
+This routing convention aims to be more flexible than Remix Routing v1, more intuitive than Remix Routing v2, and simpler than 
+Remix Flat Routes. Ultimately this is a matter of choosing your trade-offs and matching personal preferences, but this is the 
+convention which makes most sense for us. 
+
+### Which files are treated as route files? 
+
+**Remix Routing v1:** All files in the `routes` directory becomes routes in the application.
+
+**Remix Routing v2:** All *top-level* files in the `routes` directory become routes in the application, but folders with a `route.tsx`
+file inside will also become routes in the application. Any files in a folder not named `route.tsx` will be ignored. 
+
+**Remix Flat Routes:**  By default all files in the `routes` directory becomes routes in the application. If a folder is suffixed with 
+`+`, only the `index.tsx` file in that folder is treated as a route file.
+
+**Pa Routes**: All files in the `routes` directory becomes routes in the application, unless it (or one or its parent folders) is suffixed with `_`.
+
+
+### How do I define the layout for a set of routes?
+
+**Remix Routing v1:** A file who's name matches the name of an adjacent folder serves as the layout for all files in that folder. 
+
+**Remix Routing v2:**  All the routes that start with `app/routes/concerts.` will be child routes of `app/routes/concerts.tsx`. Sometimes you want 
+the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment.
+
+**Remix Flat Routes:** All the routes that start with `app/routes/concerts.` will be child routes of `app/routes/concerts.tsx`. Sometimes you want 
+the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment.
+`app/routes/concerts/_layout.tsx` is equivalent to `app/routes/concerts.tsx`.
+
+**Pa Routes**: Files named `_layout` serve as a layout for all other routes in the same folder.