@maestro-js/agent-skills 1.0.0-alpha.23 → 1.0.0-alpha.25

package/package.json

@@ -11,9 +11,9 @@
   "devDependencies": {
     "@types/node": "^22.19.11"
   },
-  "version": "1.0.0-alpha.23",
+  "version": "1.0.0-alpha.25",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "files": [
     "dist",

package/skills/maestro-examples/references/cadence/cadence-web/package.json

@@ -14,10 +14,10 @@
     "@cadence/schemas": "workspace:*",
     "@cadence/services": "workspace:*",
     "@internationalized/date": "^3.11.0",
-    "@maestro-js/custom-errors": "^1.0.0-alpha.23",
-    "@maestro-js/log": "^1.0.0-alpha.23",
-    "@maestro-js/form": "^1.0.0-alpha.23",
-    "@maestro-js/permissions": "^1.0.0-alpha.23",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.25",
+    "@maestro-js/log": "^1.0.0-alpha.25",
+    "@maestro-js/form": "^1.0.0-alpha.25",
+    "@maestro-js/permissions": "^1.0.0-alpha.25",
     "@react-aria/interactions": "^3.27.0",
     "@react-aria/utils": "^3.33.0",
     "@react-router/node": "^7.9.0",
@@ -41,8 +41,8 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@maestro-js/cli": "^1.0.0-alpha.23",
-    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.23",
+    "@maestro-js/cli": "^1.0.0-alpha.25",
+    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.25",
     "@playwright/test": "^1.52.0",
     "@react-router/dev": "^7.9.0",
     "@tailwindcss/typography": "^0.5.19",

package/skills/maestro-examples/references/cadence/package.json

@@ -6,12 +6,12 @@
     "fks-restrict": "maestro config:run --config services -- node ./scripts/foreign-key-delete-behavior.ts restrict"
   },
   "dependencies": {
-    "@maestro-js/config": "^1.0.0-alpha.23"
+    "@maestro-js/config": "^1.0.0-alpha.25"
   },
   "devDependencies": {
-    "@maestro-js/cli": "^1.0.0-alpha.23",
-    "@maestro-js/db-migrate": "^1.0.0-alpha.23",
-    "@maestro-js/db": "^1.0.0-alpha.23",
+    "@maestro-js/cli": "^1.0.0-alpha.25",
+    "@maestro-js/db-migrate": "^1.0.0-alpha.25",
+    "@maestro-js/db": "^1.0.0-alpha.25",
     "@types/node": "^22.19.11"
   }
 }

package/skills/maestro-examples/references/cadence/packages/schemas/package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
     "zod": "^4.3.0",
-    "@maestro-js/iso-zod": "^1.0.0-alpha.23"
+    "@maestro-js/iso-zod": "^1.0.0-alpha.25"
   },
   "devDependencies": {}
 }

package/skills/maestro-examples/references/cadence/packages/services/package.json

@@ -12,30 +12,30 @@
   "dependencies": {
     "@aws-sdk/client-ses": "^3.1004.0",
     "@cadence/schemas": "workspace:*",
-    "@maestro-js/auth": "^1.0.0-alpha.23",
-    "@maestro-js/cache": "^1.0.0-alpha.23",
-    "@maestro-js/config": "^1.0.0-alpha.23",
-    "@maestro-js/crypt": "^1.0.0-alpha.23",
-    "@maestro-js/custom-errors": "^1.0.0-alpha.23",
-    "@maestro-js/db": "^1.0.0-alpha.23",
-    "@maestro-js/exceptions": "^1.0.0-alpha.23",
-    "@maestro-js/hash": "^1.0.0-alpha.23",
-    "@maestro-js/helpers": "^1.0.0-alpha.23",
-    "@maestro-js/iso-zod": "^1.0.0-alpha.23",
-    "@maestro-js/log": "^1.0.0-alpha.23",
-    "@maestro-js/mail": "^1.0.0-alpha.23",
-    "@maestro-js/password": "^1.0.0-alpha.23",
-    "@maestro-js/permissions": "^1.0.0-alpha.23",
-    "@maestro-js/queue": "^1.0.0-alpha.23",
-    "@maestro-js/rate-limiting": "^1.0.0-alpha.23",
-    "@maestro-js/recurring-jobs": "^1.0.0-alpha.23",
-    "@maestro-js/session": "^1.0.0-alpha.23",
+    "@maestro-js/auth": "^1.0.0-alpha.25",
+    "@maestro-js/cache": "^1.0.0-alpha.25",
+    "@maestro-js/config": "^1.0.0-alpha.25",
+    "@maestro-js/crypt": "^1.0.0-alpha.25",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.25",
+    "@maestro-js/db": "^1.0.0-alpha.25",
+    "@maestro-js/exceptions": "^1.0.0-alpha.25",
+    "@maestro-js/hash": "^1.0.0-alpha.25",
+    "@maestro-js/helpers": "^1.0.0-alpha.25",
+    "@maestro-js/iso-zod": "^1.0.0-alpha.25",
+    "@maestro-js/log": "^1.0.0-alpha.25",
+    "@maestro-js/mail": "^1.0.0-alpha.25",
+    "@maestro-js/password": "^1.0.0-alpha.25",
+    "@maestro-js/permissions": "^1.0.0-alpha.25",
+    "@maestro-js/queue": "^1.0.0-alpha.25",
+    "@maestro-js/rate-limiting": "^1.0.0-alpha.25",
+    "@maestro-js/recurring-jobs": "^1.0.0-alpha.25",
+    "@maestro-js/session": "^1.0.0-alpha.25",
     "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
     "sanitize-html": "^2.17.2",
     "zod": "^4.3.0"
   },
   "devDependencies": {
-    "@maestro-js/cli": "^1.0.0-alpha.23",
+    "@maestro-js/cli": "^1.0.0-alpha.25",
     "@types/node": "^22.0.0",
     "@types/sanitize-html": "^2.16.1",
     "beartest-js": "^8.0.2"

package/skills/maestro-examples/references/cadence/packages/services/src/auth/auth-db-provider.ts

@@ -69,7 +69,8 @@ const rememberMeTokenRecordModel = z.object({
     userAgent: z.string().nullable()
   }),
   expirationDate: isoZ.instant().nullable(),
-  rotatedDate: isoZ.instant().nullable()
+  rotatedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant()
 })
 
 type RememberMeTokenRecord = z.infer<typeof rememberMeTokenRecordModel>
@@ -84,7 +85,7 @@ async function createRememberMeToken(options: RememberMeTokenRecord): Promise<vo
       JSON.stringify(options.deviceContext),
       options.expirationDate ? instantFns.formatISO9075(options.expirationDate) : null,
       options.rotatedDate ? instantFns.formatISO9075(options.rotatedDate) : null,
-      instantFns.formatISO9075(instantFns.now())
+      instantFns.formatISO9075(options.createdDate)
     ]
   )
 }
@@ -103,19 +104,23 @@ async function getRememberMeTokenBySelector(selector: string): Promise<RememberM
 async function rotateRememberMeTokenBySelector(
   selector: string,
   token: { verifierHash: string; selector: string }
-): Promise<void> {
-  await Db.transaction(async () => {
-    await Db.update('UPDATE rememberMeTokens SET rotatedDate = ? WHERE selector = ?', [
-      instantFns.formatISO9075(instantFns.now()),
-      selector
-    ])
-    await Db.update(
+): Promise<boolean> {
+  return Db.transaction(async () => {
+    const { affectedRows } = await Db.update(
+      'UPDATE rememberMeTokens SET rotatedDate = ? WHERE selector = ? AND rotatedDate IS NULL',
+      [instantFns.formatISO9075(instantFns.now()), selector]
+    )
+    if (affectedRows !== 1) {
+      return false
+    }
+    await Db.insert(
       `INSERT INTO rememberMeTokens (userId, selector, verifierHash, deviceContext, expirationDate, rotatedDate, createdDate)
        SELECT userId, ? as selector, ? as verifierHash, deviceContext, expirationDate, NULL as rotatedDate, createdDate
        FROM rememberMeTokens
        WHERE selector = ?`,
       [token.selector, token.verifierHash, selector]
     )
+    return true
   })
 }
 

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/_auth/forgot-password.tsx

@@ -44,8 +44,9 @@ export async function action({ request, context }: ActionFunctionArgs) {
   const parsed = await Form.serverSafeParse(formSchema, formData)
   if (parsed.success) {
     const { email } = parsed.data
-    const resetUrl = new URL('/reset-password', request.url).toString()
-    await AuthService.ForgotPassword({ email, url: resetUrl })
+    // The reset link origin is derived from a trusted server config inside the service
+    // (APP_URL), not from `request.url` / the Host header, to prevent reset poisoning.
+    await AuthService.ForgotPassword({ email })
     return redirect('/forgot-password?sent=true')
   } else {
     return Form.validationError(parsed)

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/_auth/reset-password.tsx

@@ -46,9 +46,11 @@ export async function action({ request, context }: ActionFunctionArgs) {
 
   const searchParams = new URL(request.url).searchParams
   const token = searchParams.get('token')
-  const id = searchParams.get('id')
 
-  if (!token || !id) {
+  // Re-verify the signed URL on the action (POST) path, not just the loader. Otherwise the
+  // signed query params (token/id) could be tampered with on submit. The account to reset
+  // is derived from the token by the service — the `id` query param is never trusted.
+  if (!token || !(await SignedUrl.hasValidSignature(searchParams))) {
     return data({ error: 'Invalid reset link' }, { status: 400 })
   }
 
@@ -61,7 +63,6 @@ export async function action({ request, context }: ActionFunctionArgs) {
   try {
     const { cookie } = await AuthService.ResetPassword({
       token,
-      authenticatableId: Number(id),
       newPassword: parsed.data.newPassword,
       deviceContext: requestContext.deviceContext,
       session: requestContext.session

package/skills/maestro-examples/references/chorus/chorus-web/package.json

@@ -6,45 +6,51 @@
     "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' maestro config:run --config chorus-web --root $PWD/.. -- react-router dev",
     "dev-test": "IS_TESTING=true pnpm dev",
     "build": "react-router build",
-    "start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js",
+    "start": "NODE_ENV=production NODE_OPTIONS='--import ./instrument.server.mjs' node ./server/index.ts",
     "typecheck": "react-router typegen && tsc --noEmit",
     "test:e2e": "maestro config:run --config chorus-web --root $PWD/.. -- playwright test"
   },
   "dependencies": {
     "@bundled-es-modules/pdfjs-dist": "3.6.172-alpha.1",
     "@internationalized/date": "^3.11.0",
-    "@maestro-js/form": "^1.0.0-alpha.23",
-    "@maestro-js/permissions": "^1.0.0-alpha.23",
-    "@maestro-js/custom-errors": "^1.0.0-alpha.23",
+    "@maestro-js/form": "^1.0.0-alpha.25",
+    "@maestro-js/permissions": "^1.0.0-alpha.25",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.25",
+    "@maestro-js/config": "^1.0.0-alpha.25",
+    "@maestro-js/log": "^1.0.0-alpha.25",
+    "@hono/node-server": "^2.0.5",
     "@react-aria/interactions": "^3.27.0",
     "@react-aria/utils": "^3.33.0",
     "@react-router/node": "^7.9.0",
-    "@react-router/serve": "^7.9.0",
     "@chorus/schemas": "workspace:*",
     "@chorus/services": "workspace:*",
+    "hono": "^4.12.26",
     "isbot": "^5",
     "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
     "match-sorter": "^8.2.0",
     "react": "^19.0.0",
     "react-aria-components": "^1.15.1",
     "react-dom": "^19.0.0",
-    "react-pdf-hook": "^1.0.4",
+    "react-pdf-hook": "2.0.0",
     "react-router": "^7.9.0",
+    "remix-hono": "^0.0.18",
     "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1",
     "vaul": "^1.1.2",
     "zod": "^4.0.0",
     "@sentry/react-router": "^9"
   },
   "devDependencies": {
-    "@maestro-js/cli": "^1.0.0-alpha.23",
-    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.23",
+    "@hono/vite-dev-server": "^0.26.0",
+    "@maestro-js/cli": "^1.0.0-alpha.25",
+    "@maestro-js/react-router-file-routes": "^1.0.0-alpha.25",
     "@playwright/test": "^1.58.2",
     "@react-router/dev": "^7.9.0",
     "@tailwindcss/vite": "^4.2.0",
     "@types/node": "^22.19.11",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "tailwindcss": "^4.2.1",
+    "prettier": "^3.8.0",
     "typescript": "^5.7.0",
     "vite": "^8.0.0",
     "vite-env-only": "^3.0.2",

package/skills/maestro-examples/references/chorus/chorus-web/react-router.config.ts

@@ -1,12 +1,16 @@
 import type { Config } from '@react-router/dev/config'
 import { sentryOnBuildEnd } from '@sentry/react-router'
 
+// Matches the guard in vite.config.ts: without upload credentials sentryOnBuildEnd shells out to the
+// Sentry CLI, which aborts with "An organization ID or slug is required". Skip it unless CI set them.
+const sentryEnabled = Boolean(process.env.SENTRY_ORG && process.env.SENTRY_PROJECT && process.env.SENTRY_AUTH_TOKEN)
+
 export default {
   ssr: true,
   future: {
     v8_middleware: true
   },
   async buildEnd({ viteConfig, reactRouterConfig, buildManifest }) {
-    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })
+    if (sentryEnabled) await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })
   }
 } satisfies Config

package/skills/maestro-examples/references/chorus/chorus-web/server/index.ts

@@ -0,0 +1,89 @@
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Hono } from 'hono'
+import { Log } from '@maestro-js/log'
+import { type AppLoadContext, RouterContextProvider, type ServerBuild } from 'react-router'
+import { reactRouter } from 'remix-hono/handler'
+
+const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development'
+
+const app = new Hono()
+
+// Log every request once it has been handled, capturing the response status and
+// how long it took. Registered first so it wraps the full middleware chain —
+// health checks, static assets, and React Router routes alike.
+app.use('*', async (c, next) => {
+  const start = performance.now()
+  await next()
+  Log.info({
+    channel: 'http',
+    action: 'request',
+    method: c.req.method,
+    path: c.req.path,
+    status: c.res.status,
+    durationMs: Math.round(performance.now() - start)
+  })
+})
+
+// Liveness probe for the ALB target group. Answer before serveStatic and React
+// Router so the health check proves only that the process can accept a request —
+// never coupled to the on-disk server build, the root middleware chain, or
+// session/auth. A slow or throwing app must not read as an unhealthy target.
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+// In production the built client assets are served directly by Hono. In
+// development Vite (via @hono/vite-dev-server) serves modules and assets.
+if (mode === 'production') {
+  const { serveStatic } = await import('@hono/node-server/serve-static')
+  app.use('/assets/*', serveStatic({ root: './build/client' }))
+  app.use('*', serveStatic({ root: './build/client' }))
+}
+
+// Hand every remaining request to React Router. The server build comes from the
+// Vite virtual module in development and from the on-disk build in production.
+app.use('*', async (c, next) => {
+  const build = await loadServerBuild()
+  return reactRouter({
+    build,
+    mode,
+    // With `future.v8_middleware` enabled the load context must be a fresh
+    // `RouterContextProvider` per request; the app's middlewares populate it
+    // via `context.set(...)`.
+    getLoadContext: () => new RouterContextProvider() as unknown as AppLoadContext
+  })(c, next)
+})
+
+export default app
+
+// Only start a long-lived Node server in production; in development the request
+// handling is driven by Vite's dev server.
+if (mode === 'production') {
+  const { serve } = await import('@hono/node-server')
+  const port = Number(process.env.PORT ?? 3001)
+  const server = serve({ fetch: app.fetch, port }, (info) => {
+    console.log(`Chorus web listening on http://localhost:${info.port}`)
+  })
+
+  // Exit promptly on the signal ECS sends to roll the service. This process is PID 1 (the bootstrap
+  // `exec`s it), so SIGTERM arrives here directly. By the time it does, the ALB has already drained this
+  // task's connections (target-group deregistration delay), so stop accepting requests and exit instead
+  // of idling until ECS's 30s stopTimeout forces a SIGKILL — that wait is dead time on every deploy.
+  // Force-exit if close() stalls on a lingering keep-alive socket.
+  const shutdown = () => {
+    server.close(() => process.exit(0))
+    setTimeout(() => process.exit(0), 5000).unref()
+  }
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+}
+
+async function loadServerBuild(): Promise<ServerBuild> {
+  if (mode === 'production') {
+    // Resolve the built server relative to the working directory (the artifact
+    // root at runtime); the URL is dynamic so Vite never tries to resolve it.
+    const buildUrl = pathToFileURL(join(process.cwd(), 'build/server/index.js')).href
+    return (await import(/* @vite-ignore */ buildUrl)) as unknown as ServerBuild
+  }
+  // @ts-expect-error - virtual module provided by the React Router Vite plugin in development
+  return (await import('virtual:react-router/server-build')) as unknown as ServerBuild
+}

package/skills/maestro-examples/references/chorus/chorus-web/tsconfig.json

@@ -10,5 +10,5 @@
       "~/*": ["./app/*"]
     }
   },
-  "include": ["app", "vite.config.ts", "react-router.config.ts", ".react-router", "./environment.d.ts"]
+  "include": ["app", "server", "vite.config.ts", "react-router.config.ts", ".react-router", "./environment.d.ts"]
 }

package/skills/maestro-examples/references/chorus/chorus-web/vite.config.ts

@@ -1,4 +1,5 @@
 import { reactRouter } from '@react-router/dev/vite'
+import devServer from '@hono/vite-dev-server'
 import { sentryReactRouter } from '@sentry/react-router'
 import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
@@ -6,20 +7,40 @@ import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { envOnlyMacros } from 'vite-env-only'
 
+// Only wire up Sentry when its upload credentials are present. The plugin otherwise (a) aborts every
+// build with "An organization ID or slug is required" and (b) still forces `sourcemap: 'hidden'`, so it
+// emits ~10MB of .map files that — because the failed upload never deletes them — get packed into the
+// deploy artifact, inflating the S3 upload and every cold task's download + extract. CI sets these vars
+// to ship real source maps; local/dev deploys skip the plugin and build leaner.
+const sentryEnabled = Boolean(process.env.SENTRY_ORG && process.env.SENTRY_PROJECT && process.env.SENTRY_AUTH_TOKEN)
+
 export default defineConfig((config) => ({
   plugins: [
     envOnlyMacros(),
     tsconfigPaths(),
     tailwindcss(),
     reactRouter(),
-    sentryReactRouter(
-      {
-        org: process.env.SENTRY_ORG,
-        project: process.env.SENTRY_PROJECT,
-        authToken: process.env.SENTRY_AUTH_TOKEN
-      },
-      config
-    ),
+    devServer({
+      entry: 'server/index.ts',
+      // Vite serves app source modules, its internals and deps; everything else
+      // (document and React Router `.data` requests) goes to the Hono server.
+      exclude: [/^\/(app)\/.+/, /^\/@.+$/, /^\/node_modules\/.*/],
+      // React Router injects its own dev/HMR scripts via <Scripts/>, so the Vite
+      // client must not be injected a second time.
+      injectClientScript: false
+    }),
+    ...(sentryEnabled
+      ? [
+          sentryReactRouter(
+            {
+              org: process.env.SENTRY_ORG,
+              project: process.env.SENTRY_PROJECT,
+              authToken: process.env.SENTRY_AUTH_TOKEN
+            },
+            config
+          )
+        ]
+      : []),
     iconsSpritesheet({
       inputDir: './other/svg-icons',
       outputDir: './app/icons',
@@ -31,8 +52,5 @@ export default defineConfig((config) => ({
   server: {
     port: 3001,
     strictPort: true
-  },
-  ssr: {
-    noExternal: ['react-pdf-hook']
   }
 }))

package/skills/maestro-examples/references/chorus/config/services.ts

@@ -8,6 +8,10 @@ export default async function (env: Record<string, string | undefined>) {
     CRYPT_KEY: env.CRYPT_KEY,
     HASH_KEY: env.HASH_KEY,
     ENV_NAME: env.ENV_NAME ?? 'local',
+    // Trusted canonical origin used to build absolute links (e.g. password-reset emails).
+    // Never derive these from the incoming request / Host header. Production deployments
+    // must set APP_URL to the real origin.
+    APP_URL: env.APP_URL ?? 'http://localhost:3001',
     AWS_REGION: 'us-east-1',
     SENTRY_DSN: env.SENTRY_DSN ?? '',
     VITE_SENTRY_DSN: env.SENTRY_DSN ?? ''