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

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

@@ -0,0 +1,17 @@
+{
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "fks-cascade": "maestro config:run --config services -- node ./scripts/foreign-key-delete-behavior.ts cascade",
+    "fks-restrict": "maestro config:run --config services -- node ./scripts/foreign-key-delete-behavior.ts restrict"
+  },
+  "dependencies": {
+    "@maestro-js/config": "^1.0.0-alpha.21"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@maestro-js/db-migrate": "^1.0.0-alpha.21",
+    "@maestro-js/db": "^1.0.0-alpha.21",
+    "@types/node": "^22.19.11"
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "name": "@cadence/schemas",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
+    "zod": "^4.3.0",
+    "@maestro-js/iso-zod": "^1.0.0-alpha.21"
+  },
+  "devDependencies": {}
+}

package/skills/maestro-examples/references/cadence/packages/schemas/src/contact/index.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+const contactModel = z.object({
+  id: z.number(),
+  organizationId: z.number(),
+  firstName: z.string(),
+  lastName: z.string().nullable(),
+  email: z.string().nullable(),
+  phone: z.string().nullable(),
+  jobTitle: z.string().nullable(),
+  tags: z.array(z.string()),
+  archivedDate: isoZ.instant().nullable(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+
+const contactWithLastContactedModel = contactModel.extend({
+  lastContactedDate: isoZ.instant().nullable()
+})
+
+const createContactForm = z.object({
+  firstName: z.string().min(1),
+  lastName: z.string().optional(),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  jobTitle: z.string().optional()
+})
+
+const editContactForm = z.object({
+  firstName: z.string().min(1),
+  lastName: z.string().optional(),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  jobTitle: z.string().optional()
+})
+
+const updateTagsForm = z.object({
+  tags: z.array(z.string())
+})
+
+export const ContactSchemas = {
+  contactModel,
+  contactWithLastContactedModel,
+  createContactForm,
+  editContactForm,
+  updateTagsForm
+}
+
+export declare namespace ContactSchemas {
+  export type contactModel = z.infer<typeof contactModel>
+  export type contactWithLastContactedModel = z.infer<typeof contactWithLastContactedModel>
+  export type createContactForm = z.infer<typeof createContactForm>
+  export type editContactForm = z.infer<typeof editContactForm>
+  export type updateTagsForm = z.infer<typeof updateTagsForm>
+}

package/skills/maestro-examples/references/cadence/packages/schemas/src/index.ts

@@ -0,0 +1,4 @@
+export { OrganizationSchemas } from './organization/index.ts'
+export { UserSchemas } from './user/index.ts'
+export { ContactSchemas } from './contact/index.ts'
+export { InteractionSchemas } from './interaction/index.ts'

package/skills/maestro-examples/references/cadence/packages/schemas/src/interaction/index.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+const interactionTypeOptions = ['email', 'note'] as const
+
+const interactionModel = z.object({
+  id: z.number(),
+  contactId: z.number(),
+  userId: z.number(),
+  type: z.enum(interactionTypeOptions),
+  subject: z.string().nullable(),
+  body: z.string(),
+  date: isoZ.instant(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+
+const createInteractionForm = z.object({
+  contactId: z.number(),
+  type: z.enum(interactionTypeOptions),
+  subject: z.string().optional(),
+  body: z.string().min(1).max(50000),
+  date: isoZ.instant()
+})
+
+const editInteractionForm = z.object({
+  type: z.enum(interactionTypeOptions),
+  subject: z.string().optional(),
+  body: z.string().min(1).max(50000),
+  date: isoZ.instant()
+})
+
+export const InteractionSchemas = {
+  interactionTypeOptions,
+  interactionModel,
+  createInteractionForm,
+  editInteractionForm
+}
+
+export declare namespace InteractionSchemas {
+  export type interactionModel = z.infer<typeof interactionModel>
+  export type createInteractionForm = z.infer<typeof createInteractionForm>
+  export type editInteractionForm = z.infer<typeof editInteractionForm>
+}

package/skills/maestro-examples/references/cadence/packages/schemas/src/organization/index.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+const organizationModel = z.object({
+  id: z.number(),
+  name: z.string(),
+  slug: z.string(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+
+const createOrganizationForm = z.object({
+  name: z.string().min(1).max(255),
+  slug: z.string().min(2).max(100).regex(/^[a-z0-9-]+$/)
+})
+
+const editOrganizationForm = z.object({
+  name: z.string().min(1).max(255)
+})
+
+export const OrganizationSchemas = {
+  organizationModel,
+  createOrganizationForm,
+  editOrganizationForm
+}
+
+export declare namespace OrganizationSchemas {
+  export type organizationModel = z.infer<typeof organizationModel>
+  export type createOrganizationForm = z.infer<typeof createOrganizationForm>
+  export type editOrganizationForm = z.infer<typeof editOrganizationForm>
+}

package/skills/maestro-examples/references/cadence/packages/schemas/src/user/index.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+const emailSchema = z
+  .email({ error: 'Email is invalid' })
+  .min(3, { message: 'Email is too short' })
+  .max(100, { message: 'Email is too long' })
+
+const passwordSchema = z
+  .string({ error: 'Password is required' })
+  .min(6, { message: 'Password is too short' })
+  // NOTE: bcrypt has a limit of 72 bytes (which should be plenty long)
+  // https://github.com/epicweb-dev/epic-stack/issues/918
+  .refine((val) => new TextEncoder().encode(val).length <= 72, {
+    message: 'Password is too long'
+  })
+
+const roleOptions = ['admin', 'member', 'viewer'] as const
+
+const userModel = z.object({
+  id: z.number(),
+  organizationId: z.number(),
+  name: z.string(),
+  email: z.string(),
+  passwordHash: z.string(),
+  role: z.enum(roleOptions),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+
+const profileModel = z.object({
+  userId: z.number(),
+  organizationId: z.number(),
+  role: z.enum(roleOptions)
+})
+
+const inviteUserForm = z.object({
+  email: emailSchema,
+  name: z.string().min(1),
+  role: z.enum(roleOptions)
+})
+
+const changeRoleForm = z.object({
+  role: z.enum(roleOptions)
+})
+
+const loginForm = z.object({
+  orgSlug: z.string().min(1),
+  email: emailSchema,
+  password: passwordSchema
+})
+
+export const UserSchemas = {
+  roleOptions,
+  userModel,
+  profileModel,
+  inviteUserForm,
+  changeRoleForm,
+  loginForm
+}
+
+export declare namespace UserSchemas {
+  export type userModel = z.infer<typeof userModel>
+  export type profileModel = z.infer<typeof profileModel>
+  export type inviteUserForm = z.infer<typeof inviteUserForm>
+  export type changeRoleForm = z.infer<typeof changeRoleForm>
+  export type loginForm = z.infer<typeof loginForm>
+}

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

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true
+  },
+  "include": ["./src"]
+}

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

@@ -0,0 +1,43 @@
+{
+  "name": "@cadence/services",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "maestro config:run --config services --root $PWD/../.. -- node ./run-tests.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-ses": "^3.1004.0",
+    "@cadence/schemas": "workspace:*",
+    "@maestro-js/auth": "^1.0.0-alpha.21",
+    "@maestro-js/cache": "^1.0.0-alpha.21",
+    "@maestro-js/config": "^1.0.0-alpha.21",
+    "@maestro-js/crypt": "^1.0.0-alpha.21",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.21",
+    "@maestro-js/db": "^1.0.0-alpha.21",
+    "@maestro-js/exceptions": "^1.0.0-alpha.21",
+    "@maestro-js/hash": "^1.0.0-alpha.21",
+    "@maestro-js/helpers": "^1.0.0-alpha.21",
+    "@maestro-js/iso-zod": "^1.0.0-alpha.21",
+    "@maestro-js/log": "^1.0.0-alpha.21",
+    "@maestro-js/mail": "^1.0.0-alpha.21",
+    "@maestro-js/password": "^1.0.0-alpha.21",
+    "@maestro-js/permissions": "^1.0.0-alpha.21",
+    "@maestro-js/queue": "^1.0.0-alpha.21",
+    "@maestro-js/rate-limiting": "^1.0.0-alpha.21",
+    "@maestro-js/recurring-jobs": "^1.0.0-alpha.21",
+    "@maestro-js/session": "^1.0.0-alpha.21",
+    "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.21",
+    "@types/node": "^22.0.0",
+    "@types/sanitize-html": "^2.16.1",
+    "beartest-js": "^8.0.2"
+  }
+}

package/skills/maestro-examples/references/cadence/packages/services/run-tests.ts

@@ -0,0 +1,59 @@
+import './src/index.ts'
+import { run } from 'beartest-js'
+import { promises } from 'node:fs'
+import { sep, resolve, isAbsolute, parse, relative } from 'node:path'
+
+const INCLUDE = ['**/*.{test,spec}.{js,ts,jsx,tsx}']
+const EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/build/**', '**/coverage/**']
+
+const hasGlob = (s: string) => /[*?\[\]{}()!]/.test(s)
+const norm = (p: string) => p.split(sep).join('/')
+
+async function discoverAll() {
+  const seen = new Set<string>()
+  for (const pat of INCLUDE) {
+    for await (const f of promises.glob(pat, { ignore: EXCLUDE })) seen.add(norm(f))
+  }
+  return [...seen].sort()
+}
+
+async function applyFilters(files: string[], args: string) {
+  if (!args.length) return files
+
+  let out = files
+  for (const arg of args) {
+    if (hasGlob(arg)) {
+      const gset = new Set()
+      for await (const f of promises.glob(arg, { ignore: EXCLUDE })) gset.add(norm(f))
+      out = out.filter((f) => gset.has(f)) // glob filter
+    } else {
+      const needle = norm(arg)
+      out = out.filter((f) => f.includes(needle)) // substring filter
+    }
+  }
+  return out
+}
+
+async function cli() {
+  const discovered = await discoverAll()
+  const selected = await applyFilters(discovered, process.argv.slice(2))
+
+  for await (let event of run({ files: selected.map((f) => resolve(f)) })) {
+    const prefix = '  '.repeat(event.data.nesting)
+    if (event.type === 'test:start' && event.data.type === 'suite') {
+      if (isAbsolute(event.data.name)) {
+        console.log(`\x1b[36m${prefix}${parse(event.data.name).name} (${relative('./', event.data.name)})\x1b[0m`)
+      } else {
+        console.log(`\x1b[36m${prefix}${event.data.name}\x1b[0m`)
+      }
+    } else if (event.type === 'test:pass' && event.data.details.type === 'test' && !event.data.skip) {
+      process.stdout.write(`\x1b[32m${prefix}✓\x1b[0m\x1b[90m ${event.data.name}\n\x1b[0m`)
+    } else if (event.type === 'test:fail' && event.data.details.type === 'test') {
+      process.stdout.write(`\x1b[31m\n${prefix}✗ ${event.data.name} \n\n\x1b[0m`)
+    }
+  }
+
+  process.exit(0)
+}
+
+cli()

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

@@ -0,0 +1,202 @@
+import { Auth } from '@maestro-js/auth'
+import type { Password } from '@maestro-js/password'
+import { Db } from '@maestro-js/db'
+import { isoZ } from '@maestro-js/iso-zod'
+import { instantFns, type Iso } from 'iso-fns'
+import { z } from 'zod'
+
+// ─── Authenticatable ────────────────────────────────────────────────────────────
+
+const authenticatableModel = z.object({
+  id: z.number(),
+  credentialsInvalidBefore: isoZ.instant().nullable()
+})
+
+const passwordAuthenticatableModel = z.object({
+  id: z.number(),
+  passwordHash: z.string(),
+  credentialsInvalidBefore: isoZ.instant().nullable()
+})
+
+async function getAuthenticatableByCredentials({
+  orgSlug,
+  email
+}: {
+  orgSlug: string
+  email: string
+}): Promise<(Password.Authenticatable<number> & { passwordHash: string }) | null> {
+  const rows = await Db.select(
+    `SELECT u.id, u.passwordHash, u.credentialsInvalidBefore
+     FROM users u
+     JOIN organizations o ON u.organizationId = o.id
+     WHERE o.slug = ? AND u.email = ? AND o.deletedDate IS NULL AND u.deletedDate IS NULL`,
+    [orgSlug, email]
+  )
+  const row = rows[0]
+  if (!row) return null
+  return passwordAuthenticatableModel.parse(row)
+}
+
+async function getAuthenticatableById(id: number): Promise<Auth.Authenticatable | null> {
+  const rows = await Db.select('SELECT id, credentialsInvalidBefore FROM users WHERE id = ? AND deletedDate IS NULL', [id])
+  return rows.length ? authenticatableModel.parse(rows[0]) : null
+}
+
+async function updateCredentialsInvalidBefore(id: number, date: Iso.Instant): Promise<void> {
+  await Db.update('UPDATE users SET credentialsInvalidBefore = ?, lastModifiedDate = ? WHERE id = ?', [
+    instantFns.formatISO9075(date),
+    instantFns.formatISO9075(instantFns.now()),
+    id
+  ])
+}
+
+async function updatePasswordHash(id: number, passwordHash: string): Promise<void> {
+  await Db.update('UPDATE users SET passwordHash = ?, lastModifiedDate = ? WHERE id = ?', [
+    passwordHash,
+    instantFns.formatISO9075(instantFns.now()),
+    id
+  ])
+}
+
+// ─── Remember Me Tokens ─────────────────────────────────────────────────────────
+
+const rememberMeTokenRecordModel = z.object({
+  authenticatableId: z.number(),
+  selector: z.string(),
+  verifierHash: z.string(),
+  deviceContext: z.object({
+    ip: z.string().nullable(),
+    userAgent: z.string().nullable()
+  }),
+  expirationDate: isoZ.instant().nullable(),
+  rotatedDate: isoZ.instant().nullable()
+})
+
+type RememberMeTokenRecord = z.infer<typeof rememberMeTokenRecordModel>
+
+async function createRememberMeToken(options: RememberMeTokenRecord): Promise<void> {
+  await Db.insert(
+    'INSERT INTO rememberMeTokens (userId, selector, verifierHash, deviceContext, expirationDate, rotatedDate, createdDate) VALUES (?, ?, ?, ?, ?, ?, ?)',
+    [
+      options.authenticatableId,
+      options.selector,
+      options.verifierHash,
+      JSON.stringify(options.deviceContext),
+      options.expirationDate ? instantFns.formatISO9075(options.expirationDate) : null,
+      options.rotatedDate ? instantFns.formatISO9075(options.rotatedDate) : null,
+      instantFns.formatISO9075(instantFns.now())
+    ]
+  )
+}
+
+async function getRememberMeTokenBySelector(selector: string): Promise<RememberMeTokenRecord | null> {
+  const rows = await Db.select('SELECT * FROM rememberMeTokens WHERE selector = ?', [selector])
+  const row = rows[0]
+  if (!row) return null
+  return rememberMeTokenRecordModel.parse({
+    ...row,
+    authenticatableId: row.userId,
+    deviceContext: JSON.parse((row.deviceContext as string) ?? '{}')
+  })
+}
+
+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(
+      `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]
+    )
+  })
+}
+
+async function revokeRememberMeTokenBySelector(selector: string): Promise<void> {
+  await Db.delete('DELETE FROM rememberMeTokens WHERE selector = ?', [selector])
+}
+
+async function revokeRememberMeTokenByAuthenticatableId(id: number): Promise<void> {
+  await Db.delete('DELETE FROM rememberMeTokens WHERE userId = ?', [id])
+}
+
+// ─── Password Reset Tokens ──────────────────────────────────────────────────────
+
+const passwordResetTokenRecordModel = z.object({
+  authenticatableId: z.number(),
+  selector: z.string(),
+  verifierHash: z.string(),
+  expirationDate: isoZ.instant(),
+  createdDate: isoZ.instant()
+})
+
+async function createPasswordResetToken(record: Password.ResetTokenRecord<number>): Promise<void> {
+  await Db.insert(
+    'INSERT INTO passwordResetTokens (userId, selector, verifierHash, expirationDate, createdDate) VALUES (?, ?, ?, ?, ?)',
+    [
+      record.authenticatableId,
+      record.selector,
+      record.verifierHash,
+      instantFns.formatISO9075(record.expirationDate),
+      instantFns.formatISO9075(record.createdDate)
+    ]
+  )
+}
+
+async function getPasswordResetTokenBySelector(selector: string): Promise<Password.ResetTokenRecord<number> | null> {
+  const rows = await Db.select('SELECT * FROM passwordResetTokens WHERE selector = ?', [selector])
+  const row = rows[0]
+  if (!row) return null
+  return passwordResetTokenRecordModel.parse({
+    ...row,
+    authenticatableId: row.userId
+  })
+}
+
+async function getPasswordResetTokenByUserId(userId: number): Promise<Password.ResetTokenRecord<number> | null> {
+  const rows = await Db.select('SELECT * FROM passwordResetTokens WHERE userId = ?', [userId])
+  const row = rows[0]
+  if (!row) return null
+  return passwordResetTokenRecordModel.parse({
+    ...row,
+    authenticatableId: row.userId
+  })
+}
+
+async function deletePasswordResetTokenBySelector(selector: string): Promise<void> {
+  await Db.delete('DELETE FROM passwordResetTokens WHERE selector = ?', [selector])
+}
+
+async function deletePasswordResetTokenByUserId(userId: number): Promise<void> {
+  await Db.delete('DELETE FROM passwordResetTokens WHERE userId = ?', [userId])
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────────
+
+export const authDbProvider = {
+  getAuthenticatableByCredentials,
+  getAuthenticatableById,
+  updateCredentialsInvalidBefore,
+  updatePasswordHash,
+  rememberMeToken: {
+    create: createRememberMeToken,
+    getBySelector: getRememberMeTokenBySelector,
+    rotateBySelector: rotateRememberMeTokenBySelector,
+    revokeBySelector: revokeRememberMeTokenBySelector,
+    revokeByAuthenticatableId: revokeRememberMeTokenByAuthenticatableId
+  },
+  passwordResetToken: {
+    create: createPasswordResetToken,
+    getBySelector: getPasswordResetTokenBySelector,
+    getByAuthenticatableId: getPasswordResetTokenByUserId,
+    deleteBySelector: deletePasswordResetTokenBySelector,
+    deleteByAuthenticatableId: deletePasswordResetTokenByUserId
+  }
+}