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

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import path from "path";
+import { spawnSync } from "child_process";
+import { parseArgs } from "util";
+var { values } = parseArgs({
+  options: {
+    interactive: { type: "boolean", default: false },
+    copy: { type: "boolean", default: false }
+  },
+  strict: false
+});
+var skillsPath = path.resolve(import.meta.dirname, "..");
+var args = ["skills", "add", skillsPath, "-a", "claude-code"];
+if (!values.interactive) args.push("-s", "*", "-y");
+if (values.copy) args.push("--copy");
+var result = spawnSync("npx", args, { stdio: "inherit" });
+if (result.status !== 0) process.exit(1);

package/package.json

@@ -2,21 +2,22 @@
   "name": "@maestro-js/agent-skills",
   "description": "Agent skills for the @maestro-js framework.",
   "type": "module",
+  "bin": {
+    "maestro-skills": "./dist/bin.js"
+  },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
+    "./package.json": "./package.json"
   },
   "devDependencies": {
     "@types/node": "^22.19.11"
   },
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "publishConfig": {
     "access": "restricted"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "license": "UNLICENSED",
   "engines": {
@@ -27,7 +28,7 @@
     "generate-skills": "node scripts/generate-package-skills.ts",
     "generate-choosing-npm-package-skill": "node scripts/generate-choosing-npm-package-skill.ts",
     "generate-maestro-cli-skill": "node scripts/generate-maestro-cli-skill.ts",
-    "build": "node scripts/generate-package-skills.ts && node scripts/generate-choosing-npm-package-skill.ts && node scripts/generate-maestro-cli-skill.ts",
+    "build": "node scripts/build.ts && tsup",
     "typecheck": "tsc --noEmit"
   }
 }

package/{dist → skills}/choosing-an-npm-package/SKILL.md

@@ -46,19 +46,20 @@ Before installing any dependency, check this list for the user's preferred packa
 - **@maestro-js/form** — Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion. Use when building custom form components that need native constraint validation, server error integration, file upload handling, or type-safe FormData parsing. Provides HeadlessForm root component, useValidation/useWarningState/useControlledState/useReset hooks, HiddenInput/HiddenFileInput/HiddenSelect components, parseFormData/parseFormDataClientSide utilities, and composeValidators.
 - **@maestro-js/hash** — Pluggable hashing and verification with driver-based backends for @maestro-js/hash. Use when working with @maestro-js/hash, hashing values, verifying hashes, detecting when a rehash is needed, or rotating signing keys. Built-in drivers: SHA256 (HMAC-SHA256 with key rotation and timing-safe comparison).
 - **@maestro-js/helpers** — Standalone utility functions for async control flow and file handling in the @maestro-js/helpers package. Use when working with @maestro-js/helpers. Key capabilities: retry with configurable attempts/delay/backoff, sleep, withMaxConcurrency for limiting parallel executions, withRateLimit with fixed or sliding window, raceWithFallback for promise racing with default values, AsyncIterableCollection for lazy async iteration (map, filter, reduce, forEach, toArray), sanitizeFilename for safe cross-platform filenames, and withRetry for wrapping functions with retry behavior.
+- **@maestro-js/init** — Project scaffolding for the Maestro framework. Generates a complete monorepo with config, schemas, services, web app, queue processor, and infrastructure.
+- **@maestro-js/iso-zod** — Zod custom schemas for ISO 8601 temporal types (Instant, DateTime, ZonedDateTime, Date, Time, YearMonth, MonthDay, Duration) backed by iso-fns validation. Use when defining Zod schemas that include ISO temporal fields. Provides isoZ factory functions that return typed Zod schemas and an isoZRegistry for introspecting registered ISO type metadata.
 - **@maestro-js/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.
 - **@maestro-js/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.
 - **@maestro-js/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.
 - **@maestro-js/password** — 
-- **@maestro-js/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.
-- **@maestro-js/queue2** — 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/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.
+- **@maestro-js/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.
 - **@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. 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/react-router-file-routes** — 
-- **@maestro-js/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.
+- **@maestro-js/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.
 - **@maestro-js/session** — 
 - **@maestro-js/signed-url** — URL signing and verification with pluggable hash drivers for @maestro-js/signed-url. Use when generating tamper-proof signed URLs with expiration (e.g. file download links, email verification) or validating signed URL parameters. Accepts any hash driver compatible with @maestro-js/hash.
 - **@maestro-js/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.
-- **@maestro-js/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.
 
 ## General Guidance
 

package/skills/iconify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: iconify
+description: Search the Iconify icon registry and download SVGs to a local directory. Use when the user asks to find an icon, download an icon, get an SVG for something, or says things like "find me a home icon", "I need an arrow SVG", "get me an icon for X", or "download heroicons:name".
+---
+
+# Iconify
+
+## Overview
+
+Search Iconify's icon registry and save SVG files locally. Prefers Heroicons v2 first, then other Heroicons variants, then Material Symbols. Uses the Node.js script at `.claude/skills/iconify/scripts/iconify.js` (requires Node 18+).
+
+## Workflow
+
+### 1. Search for icons
+
+```bash
+node .claude/skills/iconify/scripts/iconify.js search "<query>" --limit 10
+```
+
+- The script outputs a JSON array sorted by preference: `heroicons` → `heroicons-outline`/`heroicons-solid` → `material-symbols` → others
+- Each result has: `{ id, prefix, name }`
+
+### 2. Select the best match
+
+Pick the top result unless the user specified a different icon or pack. Preference order:
+
+1. `heroicons` — Heroicons v2 (current, preferred)
+2. `heroicons-outline` / `heroicons-solid` — Heroicons v1
+3. `material-symbols` — Google Material Symbols
+4. Others
+
+### 3. Determine the output directory
+
+- If the user specified a path, use it
+- Otherwise, infer from context (e.g., `src/assets/icons`, `public/icons`)
+- most typical will be /other/svg-icons .
+- Note the vite svg sprite generator outputs sprites to /app/icons . AVOID this directory!!! Use /other/svg-icons/\* instead
+- If unclear, ask the user
+
+### 4. Download the SVG
+
+```bash
+node .claude/skills/iconify/scripts/iconify.js download <prefix>:<name> <outputDir>
+```
+
+The script prints the resolved file path on success.
+
+### 5. Report back
+
+Tell the user the saved file path and which icon was chosen (e.g., `heroicons:home` → `src/assets/icons/home.svg`).
+
+## Examples
+
+**User:** "Find me a home icon and save it to src/assets/icons"
+
+```bash
+node .claude/skills/iconify/scripts/iconify.js search "home" --limit 10
+# → picks heroicons:home (rank 0)
+node .claude/skills/iconify/scripts/iconify.js download heroicons:home src/assets/icons
+# → /abs/path/src/assets/icons/home.svg
+```
+
+**User:** "Get me an arrow-left SVG"
+
+```bash
+node .claude/skills/iconify/scripts/iconify.js search "arrow left" --limit 10
+# → picks heroicons:arrow-left
+# Ask user for output dir if not specified, then download
+node .claude/skills/iconify/scripts/iconify.js download heroicons:arrow-left ./src/icons
+```
+
+## Script Reference
+
+**Script:** `.claude/skills/iconify/scripts/iconify.js`
+**Requires:** Node 18+
+
+| Subcommand | Signature                       | Output                                                    |
+| ---------- | ------------------------------- | --------------------------------------------------------- |
+| `search`   | `search <query> [--limit N]`    | JSON array of `{ id, prefix, name }` sorted by preference |
+| `download` | `download <iconId> <outputDir>` | Resolved file path on stdout; errors to stderr + exit 1   |
+
+Icon IDs follow `prefix:name` format, e.g. `heroicons:home`, `material-symbols:favorite`.

package/skills/iconify/scripts/iconify.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// iconify.js — search and download SVG icons from Iconify API
+// Requires Node 18+ (built-in fetch)
+// Usage:
+//   node iconify.js search "arrow left" [--limit N]
+//   node iconify.js download heroicons:arrow-left ./output/dir
+
+import { writeFile, mkdir } from 'fs/promises'
+import { resolve, join } from 'path'
+
+const ICONIFY_API = 'https://api.iconify.design'
+const HEROICONS_PREFIXES = new Set(['heroicons', 'heroicons-outline', 'heroicons-solid'])
+const MATERIAL_PREFIXES = new Set(['material-symbols', 'material-symbols-light', 'material-symbols-rounded'])
+
+function rankIcon(prefix) {
+  if (prefix === 'heroicons') return 0
+  if (HEROICONS_PREFIXES.has(prefix)) return 1
+  if (MATERIAL_PREFIXES.has(prefix)) return 2
+  return 3
+}
+
+async function search(query, limit = 10) {
+  const preferredPrefixes = 'heroicons,heroicons-outline,heroicons-solid,material-symbols'
+
+  const [preferredRes, allRes] = await Promise.all([
+    fetch(`${ICONIFY_API}/search?query=${encodeURIComponent(query)}&prefixes=${preferredPrefixes}&limit=${limit}`),
+    fetch(`${ICONIFY_API}/search?query=${encodeURIComponent(query)}&limit=${limit}`)
+  ])
+
+  if (!preferredRes.ok) {
+    process.stderr.write(`Search failed: ${preferredRes.status} ${preferredRes.statusText}\n`)
+    process.exit(1)
+  }
+
+  const preferredData = await preferredRes.json()
+  const allData = allRes.ok ? await allRes.json() : { icons: [] }
+
+  // Merge results, deduplicating by icon id
+  const seen = new Set()
+  const icons = []
+
+  for (const id of [...(preferredData.icons ?? []), ...(allData.icons ?? [])]) {
+    if (seen.has(id)) continue
+    seen.add(id)
+    const colonIdx = id.indexOf(':')
+    const prefix = colonIdx >= 0 ? id.slice(0, colonIdx) : ''
+    const name = colonIdx >= 0 ? id.slice(colonIdx + 1) : id
+    icons.push({ id, prefix, name })
+  }
+
+  // Sort by preference rank
+  icons.sort((a, b) => rankIcon(a.prefix) - rankIcon(b.prefix))
+
+  process.stdout.write(JSON.stringify(icons, null, 2) + '\n')
+}
+
+async function download(iconId, outputDir) {
+  const colonIdx = iconId.indexOf(':')
+  if (colonIdx < 0) {
+    process.stderr.write(`Invalid icon id "${iconId}" — expected format "prefix:name"\n`)
+    process.exit(1)
+  }
+
+  const prefix = iconId.slice(0, colonIdx)
+  const name = iconId.slice(colonIdx + 1)
+
+  const url = `${ICONIFY_API}/${prefix}/${name}.svg`
+  const res = await fetch(url)
+
+  if (!res.ok) {
+    process.stderr.write(`Download failed for "${iconId}": ${res.status} ${res.statusText}\n`)
+    process.exit(1)
+  }
+
+  const svg = await res.text()
+  const dir = resolve(outputDir)
+  await mkdir(dir, { recursive: true })
+  const filePath = join(dir, `${name}.svg`)
+  await writeFile(filePath, svg, 'utf8')
+
+  process.stdout.write(filePath + '\n')
+}
+
+// --- CLI entrypoint ---
+
+const [, , subcommand, ...rest] = process.argv
+
+if (subcommand === 'search') {
+  const limitIdx = rest.indexOf('--limit')
+  const limit = limitIdx >= 0 ? parseInt(rest[limitIdx + 1], 10) : 10
+  const queryParts = rest.filter((_, i) => i !== limitIdx && i !== limitIdx + 1)
+  const query = queryParts.join(' ')
+
+  if (!query) {
+    process.stderr.write('Usage: iconify.js search <query> [--limit N]\n')
+    process.exit(1)
+  }
+
+  await search(query, limit)
+} else if (subcommand === 'download') {
+  const [iconId, outputDir] = rest
+  if (!iconId || !outputDir) {
+    process.stderr.write('Usage: iconify.js download <iconId> <outputDir>\n')
+    process.exit(1)
+  }
+
+  await download(iconId, outputDir)
+} else {
+  process.stderr.write('Usage:\n  iconify.js search <query> [--limit N]\n  iconify.js download <iconId> <outputDir>\n')
+  process.exit(1)
+}

package/skills/iso-fns/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: iso-fns
+description: String-based date/time library using ISO 8601 strings instead of Date objects. Use when code imports `iso-fns`, uses `Iso.*` types (`Iso.Date`, `Iso.Instant`, `Iso.ZonedDateTime`, etc.), or calls `dateFns`, `timeFns`, `dateTimeFns`, `instantFns`, `zonedDateTimeFns`, `yearMonthFns`, `monthDayFns`, or `durationFns`. Also use when the user asks about iso-fns patterns, date/time handling with ISO strings, or temporal arithmetic.
+---
+
+# iso-fns
+
+A functional, immutable date/time library where all temporal values are ISO 8601 strings. No class instances, no hidden state -- just strings in, strings out.
+
+## Quick Reference
+
+```ts
+import {
+  dateFns,
+  timeFns,
+  dateTimeFns,
+  instantFns,
+  zonedDateTimeFns,
+  durationFns,
+  yearMonthFns,
+  monthDayFns,
+  type Iso
+} from 'iso-fns'
+```
+
+**8 types** -- each a branded string:
+
+| Type                | Example                                        | Use for                   |
+| ------------------- | ---------------------------------------------- | ------------------------- |
+| `Iso.Date`          | `'2024-01-15'`                                 | Calendar dates            |
+| `Iso.Time`          | `'09:30:00'`                                   | Wall-clock times          |
+| `Iso.DateTime`      | `'2024-01-15T09:30:00'`                        | Date + time, no timezone  |
+| `Iso.Instant`       | `'2024-01-15T15:30:00.000Z'`                   | Exact point in time (UTC) |
+| `Iso.ZonedDateTime` | `'2024-01-15T09:30:00-06:00[America/Chicago]'` | Timezone-aware date/time  |
+| `Iso.YearMonth`     | `'2024-01'`                                    | Month precision           |
+| `Iso.MonthDay`      | `'--01-15'`                                    | Recurring monthly dates   |
+| `Iso.Duration`      | `'P1Y2M3D'`                                    | Lengths of time           |
+
+**8 function namespaces** -- one per type, each with a consistent API surface: `now()`, `from()`, `with()`, `add()`, `subtract()`, `until()`, `since()`, `equals()`, `compare()`, `format()`, `chain()`, getters, and type conversions.
+
+## Choosing the Right Type
+
+- **Store timestamps / "when did this happen"** -> `Iso.Instant` (exact UTC point)
+- **Display to user in their timezone** -> `Iso.ZonedDateTime`
+- **Date picker value / birthday** -> `Iso.Date`
+- **Alarm / schedule time** -> `Iso.Time`
+- **Form with date + time, no timezone yet** -> `Iso.DateTime`
+- **"3 months from now"** -> `Iso.Duration`
+- **Credit card expiry** -> `Iso.YearMonth`
+- **Annual holiday** -> `Iso.MonthDay`
+
+## Common Patterns
+
+### Get current date/time
+
+```ts
+dateFns.now() // '2024-01-15'
+instantFns.now() // '2024-01-15T15:30:00.000Z'
+zonedDateTimeFns.now('America/Chicago') // '2024-01-15T09:30:00.000-06:00[America/Chicago]'
+```
+
+### Create from components
+
+```ts
+dateFns.fromNumbers(2024, 1, 15) // '2024-01-15'
+dateTimeFns.fromNumbers(2024, 1, 15, 9, 30) // '2024-01-15T09:30:00.000'
+instantFns.fromEpochMilliseconds(Date.now()) // Iso.Instant from epoch
+```
+
+### Arithmetic
+
+```ts
+dateFns.add('2024-01-15', { months: 1 }) // '2024-02-15'
+dateFns.subtract('2024-01-15', { days: 20 }) // '2023-12-26'
+dateFns.until('2024-01-01', '2024-03-01', { largestUnit: 'months' }) // 'P2M'
+```
+
+### Comparison
+
+```ts
+dateFns.isBefore('2024-01-01', '2024-06-01') // true
+dateFns.isAfter('2024-06-01', '2024-01-01') // true
+dateFns.isEqualOrBefore('2024-01-01', '2024-01-01') // true
+instantFns.compare(a, b) // -1, 0, or 1
+```
+
+### Modify specific fields
+
+```ts
+dateFns.with('2024-01-15', { month: 6 }) // '2024-06-15'
+dateTimeFns.withTime('2024-01-15T09:30:00', '17:00:00') // '2024-01-15T17:00:00'
+zonedDateTimeFns.withTimeZone(zdt, 'Europe/London') // convert timezone
+```
+
+### Type conversions
+
+```ts
+dateFns.toDateTime('2024-01-15', '09:30:00') // '2024-01-15T09:30:00'
+dateFns.toZonedDateTime('2024-01-15', { timeZone: 'America/Chicago', time: '09:30:00' })
+instantFns.toZonedDateTime(instant, 'America/Chicago')
+zonedDateTimeFns.toDate(zdt) // extract Iso.Date
+zonedDateTimeFns.toInstant(zdt) // extract Iso.Instant
+```
+
+### Formatting
+
+```ts
+dateFns.format('2024-02-11', 'MM/dd/yyyy') // '02/11/2024'
+dateFns.format('2024-02-11', 'MMMM do, yyyy') // 'February 11th, 2024'
+zonedDateTimeFns.format(zdt, 'PPpp') // 'Feb 11, 2024, 9:30:00 AM'
+```
+
+### Chaining
+
+```ts
+dateFns.chain('2024-01-15').add({ months: 1 }).with({ day: 1 }).value() // '2024-02-01'
+```
+
+### Validation
+
+```ts
+dateFns.isValid('2024-01-15') // true (type guard)
+dateFns.assertIsValid(input) // throws if invalid
+```
+
+### Duration math
+
+```ts
+durationFns.total('P1Y6M', { unit: 'months' }) // 18
+durationFns.add('P1Y', 'P6M') // 'P1Y6M'
+durationFns.negated('P1D') // '-P1D'
+durationFns.abs('-P1D') // 'P1D'
+```
+
+## Full API Reference
+
+See [references/api_reference.md](references/api_reference.md) for complete function signatures for all 8 namespaces.