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

package/skills/maestro-examples/references/setlist/specs/use-cases.md

@@ -0,0 +1,55 @@
+# Use Cases
+
+Use cases for the personal task manager, grouped by entity.
+
+## Authentication
+
+| #   | Use Case                                                           | Auth Required | Actor  |
+| --- | ------------------------------------------------------------------ | ------------- | ------ |
+| A1  | Request a magic link (enter email, receive link + token via email) | No            | Anyone |
+| A2  | Log in via magic link URL or by pasting token into login form      | No            | Anyone |
+
+## Areas
+
+| #   | Use Case                                   | Auth Required | Actor |
+| --- | ------------------------------------------ | ------------- | ----- |
+| AR1 | List areas in sidebar                      | Yes           | User  |
+| AR2 | Create an area                             | Yes           | User  |
+| AR3 | Edit area title                            | Yes           | User  |
+| AR4 | Delete an area                             | Yes           | User  |
+| AR5 | Reorder areas in sidebar via drag-and-drop | Yes           | User  |
+
+## Projects
+
+| #   | Use Case                                         | Auth Required | Actor |
+| --- | ------------------------------------------------ | ------------- | ----- |
+| PR1 | View a project's tasks (ordered by user)         | Yes           | User  |
+| PR2 | Create a project (optionally in an area)         | Yes           | User  |
+| PR3 | Edit project title, notes, or scheduled date     | Yes           | User  |
+| PR4 | Move a project into or out of an area            | Yes           | User  |
+| PR5 | Complete a project (does not complete its tasks) | Yes           | User  |
+| PR6 | Uncomplete a project                             | Yes           | User  |
+| PR7 | Delete a project                                 | Yes           | User  |
+| PR8 | Reorder projects in sidebar via drag-and-drop    | Yes           | User  |
+
+## Tasks
+
+| #   | Use Case                                                     | Auth Required | Actor |
+| --- | ------------------------------------------------------------ | ------------- | ----- |
+| T1  | View task details (title, notes, scheduled date)             | Yes           | User  |
+| T2  | Create a task (lands in current view by default)             | Yes           | User  |
+| T3  | Edit task title, notes, or scheduled date                    | Yes           | User  |
+| T4  | Move a task to a different project or area via drag-and-drop | Yes           | User  |
+| T5  | Complete a task (moves to Completed view)                    | Yes           | User  |
+| T6  | Uncomplete a task (returns to original location)             | Yes           | User  |
+| T7  | Delete a task                                                | Yes           | User  |
+| T8  | Reorder tasks via drag-and-drop within any list              | Yes           | User  |
+
+## Views
+
+| #   | Use Case                                                                 | Auth Required | Actor |
+| --- | ------------------------------------------------------------------------ | ------------- | ----- |
+| V1  | View Inbox (tasks not assigned to a project, area, or scheduled date)    | Yes           | User  |
+| V2  | View Today (tasks scheduled for today + overdue tasks)                   | Yes           | User  |
+| V3  | View Upcoming (tasks grouped by scheduled date, looking forward)         | Yes           | User  |
+| V4  | View Completed (all completed tasks and projects, reverse chronological) | Yes           | User  |

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "es2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "checkJs": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noImplicitAny": false,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "exclude": ["node_modules"],
+  "include": ["./src", "./packages/*/src", "./packages/*/tests", "./scripts"]
+}

package/{dist → skills}/maestro-packages/SKILL.md

@@ -34,9 +34,9 @@ Each package has a linked detail page with its full API, driver options, and usa
 - **log** — Structured logging with pluggable transports and channel-based routing for the Maestro framework. Use when working with @maestro-js/log, adding or modifying log transports, configuring log channels, filtering log messages by level or channel, integrating logging into other packages, or writing tests that capture log output. Key capabilities: create loggers with pluggable transports (console, file, Sentry, stub), route messages through named channels, filter by level and channel, override Node.js console, custom formatters, and the silence transport for suppressing output. [View details](./log.md)
 - **mail** — Driver-based email sending with queued delivery, scheduled sending, and mailable templates for the @maestro-js/mail package. Use when working with @maestro-js/mail. Covers creating mail services with SendGrid/SES/MailTrap/Stub drivers, sending emails immediately or via queue, scheduling future delivery, building reusable mailable templates, processing webhook events, generating ICS calendar attachments, and testing with the stub driver. [View details](./mail.md)
 - **metrics** — Use when working with @maestro-js/metrics. Unified metrics collection piped through the Log transport system. Covers four metric types (counters, distributions, sets, gauges), provider setup, logger integration, Sentry transport, and custom transport authoring. Trigger on metrics emission, observability instrumentation, Sentry metrics integration, or application telemetry tasks. [View details](./metrics.md)
-- **queue** — 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. [View details](./queue.md)
+- **permissions** — Subject-action authorization with type-safe action maps and profile-based rule resolution. Use when you need role-based access control, permission checks (can/cannot), or authorization gates that throw on denial. Provides a static driver for declarative allow/forbid rule definitions. Built on CASL. [View details](./permissions.md)
+- **queue** — Database-backed job queue with middleware, configurable retries, and backoff strategies. Use when dispatching background jobs, processing queues with concurrency control, scheduling delayed work, handling retries and permanent failures, or integrating with mail/recurring-jobs. Provides db (MySQL) and local (in-memory) drivers. [View details](./queue.md)
 - **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. 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). [View details](./rate-limiting.md)
 - **react-router-file-routes** —  [View details](./react-router-file-routes.md)
-- **recurring-jobs** — Use when working with @maestro-js/recurring-jobs. Cron-based job scheduling backed by the Queue package. Covers creating recurring jobs, managing schedules, start/stop processing, rescheduling, listing jobs, and inspecting upcoming runs. Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, deduplication across process restarts, per-job dedicated queues, structured log events, and paginated execution history. [View details](./recurring-jobs.md)
+- **recurring-jobs** — Use when working with @maestro-js/recurring-jobs. Cron-based recurring job scheduling with distributed lock-based deduplication. Use for cron scheduling, periodic background tasks, and recurring jobs that must run exactly once across processes. Drivers: Db (MySQL), Cache (Redis via @maestro-js/cache), Local (in-memory). Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, 60-second polling loop, per-job distributed locking, optional middleware wrapping, eager cron validation, structured lifecycle log events (jobDue, jobLockAcquired, jobFailed, jobProcessed), and graceful shutdown via abort/stopAllWork. [View details](./recurring-jobs.md)
 - **sql** — Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions (CTEs). Use when working with @maestro-js/sql, building dynamic SQL filters, constructing parameterized WHERE clauses, wrapping Db services with CTEs, or generating safe parameterized SQL fragments. Key capabilities: WhereClauseBuilder for incremental AND/OR conditions with nested sub-groups, CommonTableExpressionBuilder for wrapping a Db service so all queries auto-prepend WITH clauses, cloning builders, recursive CTEs, and dynamic parameter resolution. [View details](./sql.md)
-- **tracing** — Distributed tracing package built on OpenTelemetry with pluggable providers (Sentry, Maestro). Use when working with @maestro-js/tracing. Key capabilities: wrap functions for automatic span tracking, create active spans with duration measurement, proxy entire objects for tracing, serialize/deserialize trace context across process boundaries (dehydrate/hydrate), add custom log transports for span events, integrate Sentry as a tracing provider. [View details](./tracing.md)

package/skills/maestro-packages/permissions.md

@@ -0,0 +1,215 @@
+---
+name: permissions
+description: "Subject-action authorization with type-safe action maps and profile-based rule resolution. Use when you need role-based access control, permission checks (can/cannot), or authorization gates that throw on denial. Provides a static driver for declarative allow/forbid rule definitions. Built on CASL."
+---
+
+# @maestro-js/permissions
+
+Subject-action authorization with type-safe action maps and profile-based rule resolution.
+
+## Quick Setup
+
+```ts
+import { Permissions } from '@maestro-js/permissions'
+
+type ActionMap = {
+  Post: ['create', 'read', 'update', 'delete']
+  Comment: ['create', 'read', 'delete']
+  Settings: ['read', 'update']
+}
+type Profile = { role: 'admin' | 'editor' | 'viewer' }
+
+// Define rules with the static driver
+const driver = Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  if (profile.role === 'admin') {
+    allow('Post', ['create', 'read', 'update', 'delete'])
+    allow('Comment', ['create', 'read', 'delete'])
+    allow('Settings', ['read', 'update'])
+  } else if (profile.role === 'editor') {
+    allow('Post', ['create', 'read', 'update'])
+    allow('Comment', ['create', 'read'])
+    allow('Settings', 'read')
+    forbid('Settings', 'update', 'Editors cannot modify settings')
+  } else {
+    allow('Post', 'read')
+    allow('Comment', 'read')
+    allow('Settings', 'read')
+  }
+})
+
+// Create and register
+const permissions = Permissions.Provider.create<ActionMap, Profile>({ driver })
+Permissions.Provider.register('default', permissions)
+
+// Check permissions via the facade
+Permissions.can({ role: 'editor' }, 'Post', 'create') // true
+```
+
+## Drivers
+
+### Static
+
+The only built-in driver. Accepts a callback that receives the profile and `allow`/`forbid` helpers
+to declaratively define rules:
+
+```ts
+Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  allow('Post', ['create', 'read'])          // single subject, multiple actions
+  allow(['Post', 'Comment'], 'read')         // multiple subjects, single action
+  forbid('Settings', 'update', 'Not allowed') // forbid with optional reason
+})
+```
+
+- `allow(subject, action)` -- grant access to one or more subjects/actions
+- `forbid(subject, action, reason?)` -- deny access, optionally with a reason string
+
+Rules are evaluated top-to-bottom per call. A `forbid` overrides any prior `allow` for the same
+subject/action pair.
+
+Source: `packages/permissions/src/static-permissions-driver.ts`
+
+## API Reference
+
+### can
+
+```ts
+Permissions.can(profile: P, subject: S, action: M[S][number]): boolean
+```
+Return `true` if the profile is allowed to perform the action on the subject.
+
+```ts
+if (Permissions.can(user, 'Post', 'delete')) {
+  await deletePost(postId)
+}
+```
+
+### cannot
+
+```ts
+Permissions.cannot(profile: P, subject: S, action: M[S][number]): boolean
+```
+Return `true` if the profile is **not** allowed -- the inverse of `can`.
+
+```ts
+if (Permissions.cannot(user, 'Settings', 'update')) {
+  showReadOnlyView()
+}
+```
+
+### gate
+
+```ts
+Permissions.gate(profile: P, subject: S, action: M[S][number]): void
+```
+Assert the profile is allowed. Throws `ForbiddenError` (from `@casl/ability`) on denial.
+
+```ts
+Permissions.gate(user, 'Post', 'update') // throws if denied
+await updatePost(postId, data)
+```
+
+### listRules
+
+```ts
+Permissions.listRules(profile: P): Permissions.Rule[]
+```
+Return the full list of rules generated for the profile. Useful for debugging or serializing
+permissions to a client.
+
+```ts
+const rules = Permissions.listRules({ role: 'editor' })
+// [{ subject: 'Post', action: ['create', 'read', 'update'] }, ...]
+```
+
+## Common Patterns
+
+### Role-based branching
+
+```ts
+function getNavItems(profile: Profile) {
+  const items = [{ label: 'Posts', href: '/posts' }]
+  if (Permissions.can(profile, 'Settings', 'update')) {
+    items.push({ label: 'Settings', href: '/settings' })
+  }
+  return items
+}
+```
+
+### Forbid overrides allow
+
+A `forbid` placed after a broader `allow` removes that specific permission:
+
+```ts
+const driver = Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  allow('Post', ['create', 'read', 'update', 'delete'])
+  forbid('Post', 'delete') // everyone can CRUD except delete
+})
+```
+
+### Authorization gate in a request handler
+
+```ts
+app.put('/posts/:id', async (req, res) => {
+  try {
+    Permissions.gate(req.user, 'Post', 'update')
+    await updatePost(req.params.id, req.body)
+    res.json({ ok: true })
+  } catch (e) {
+    if (e instanceof ForbiddenError) {
+      res.status(403).json({ error: 'Forbidden' })
+    }
+  }
+})
+```
+
+## Warnings and Gotchas
+
+- **`gate()` throws `ForbiddenError`** -- this is `ForbiddenError` from `@casl/ability`, not a
+  plain `Error`. Import it from `@casl/ability` if you need to catch it specifically.
+- **Forbid order matters** -- `forbid` must come after a broader `allow` for the same
+  subject/action to take effect. A `forbid` with no matching `allow` has no impact.
+- **Rules are re-evaluated per call** -- the driver callback runs on every `can`, `cannot`, `gate`,
+  or `listRules` invocation. There is no internal caching of rule sets.
+
+## Testing
+
+```ts
+import { Permissions } from '@maestro-js/permissions'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+type ActionMap = { Post: ['create', 'read'] }
+type Profile = { role: 'admin' | 'viewer' }
+
+const driver = Permissions.drivers.static<Profile>((profile, allow) => {
+  if (profile.role === 'admin') allow('Post', ['create', 'read'])
+  else allow('Post', 'read')
+})
+const permissions = Permissions.Provider.create<ActionMap, Profile>({ driver })
+
+test('admin can create posts', () => {
+  expect(permissions.can({ role: 'admin' }, 'Post', 'create')).toBe(true)
+})
+
+test('viewer cannot create posts', () => {
+  expect(permissions.cannot({ role: 'viewer' }, 'Post', 'create')).toBe(true)
+})
+```
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/permissions test
+cd packages/permissions && npx beartest ./tests/permissions.test.ts
+```
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation),
+  `@casl/ability` (rule engine and `ForbiddenError`)
+
+## Key Source Files
+
+- `packages/permissions/src/index.ts` -- main export, Provider pattern, `create()`, type namespace
+- `packages/permissions/src/static-permissions-driver.ts` -- static driver with `allow`/`forbid` helpers
+- `packages/permissions/tests/permissions.test.ts` -- runtime and type-level tests