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

package/skills/maestro-examples/references/setlist/packages/services/src/auth/index.ts

@@ -0,0 +1,18 @@
+import {
+  RequestMagicLink,
+  VerifyMagicLink,
+  MagicLinkThrottledError,
+  MagicLinkInvalidTokenError
+} from './auth-use-cases.ts'
+
+export { authDbProvider } from './auth-db-provider.ts'
+export { verifyMagicLinkCredentials } from './verify-magic-link-credentials.ts'
+
+export const AuthService = {
+  RequestMagicLink,
+  VerifyMagicLink,
+  errors: {
+    MagicLinkThrottledError,
+    MagicLinkInvalidTokenError
+  }
+}

package/skills/maestro-examples/references/setlist/packages/services/src/auth/magic-link-db-provider.test.ts

@@ -0,0 +1,52 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { instantFns } from 'iso-fns'
+import { H } from '../testing/index.ts'
+import { magicLinkDbProvider } from './magic-link-db-provider.ts'
+
+const user = H.UserSeed({ id: 1 })
+const pipe = H.SeedPipe(user)
+
+test.beforeEach(async () => {
+  await pipe.setup()
+})
+test.afterEach(async () => {
+  await pipe.teardown()
+})
+
+test('create and getBySelector', async () => {
+  const now = instantFns.now()
+  const expiration = instantFns.add(now, { hours: 1 })
+
+  await magicLinkDbProvider.create({
+    userId: 1,
+    selector: 'sel-abc',
+    verifierHash: 'hash-xyz',
+    expirationDate: expiration,
+    createdDate: now
+  })
+
+  const link = await magicLinkDbProvider.getBySelector('sel-abc')
+  expect(link).not.toBeNull()
+  expect(link!.userId).toBe(1)
+  expect(link!.selector).toBe('sel-abc')
+  expect(link!.verifierHash).toBe('hash-xyz')
+  expect(link!.usedDate).toBeNull()
+})
+
+test('markAsUsed filters from getBySelector', async () => {
+  const now = instantFns.now()
+  const expiration = instantFns.add(now, { hours: 1 })
+
+  await magicLinkDbProvider.create({
+    userId: 1,
+    selector: 'sel-used',
+    verifierHash: 'hash-used',
+    expirationDate: expiration,
+    createdDate: now
+  })
+
+  await magicLinkDbProvider.markAsUsed('sel-used')
+  const link = await magicLinkDbProvider.getBySelector('sel-used')
+  expect(link).toBeNull()
+})

package/skills/maestro-examples/references/setlist/packages/services/src/auth/magic-link-db-provider.ts

@@ -0,0 +1,59 @@
+import { Db } from '@maestro-js/db'
+import { isoZ } from '@maestro-js/iso-zod'
+import { instantFns } from 'iso-fns'
+import { z } from 'zod'
+
+const magicLinkRecordModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  selector: z.string(),
+  verifierHash: z.string(),
+  usedDate: isoZ.instant().nullable(),
+  expirationDate: isoZ.instant(),
+  createdDate: isoZ.instant()
+})
+
+type MagicLinkRecord = z.infer<typeof magicLinkRecordModel>
+
+async function create(
+  record: Pick<MagicLinkRecord, 'userId' | 'selector' | 'verifierHash' | 'expirationDate' | 'createdDate'>
+): Promise<void> {
+  await Db.insert(
+    'INSERT INTO magicLinks (userId, selector, verifierHash, expirationDate, createdDate) VALUES (?, ?, ?, ?, ?)',
+    [
+      record.userId,
+      record.selector,
+      record.verifierHash,
+      instantFns.formatISO9075(record.expirationDate),
+      instantFns.formatISO9075(record.createdDate)
+    ]
+  )
+}
+
+async function getBySelector(selector: string): Promise<MagicLinkRecord | null> {
+  const rows = await Db.select('SELECT * FROM magicLinks WHERE selector = ? AND usedDate IS NULL', [selector])
+  const row = rows[0]
+  if (!row) return null
+  return magicLinkRecordModel.parse(row)
+}
+
+async function getByUserId(userId: number): Promise<MagicLinkRecord | null> {
+  const rows = await Db.select('SELECT * FROM magicLinks WHERE userId = ? ORDER BY createdDate DESC LIMIT 1', [userId])
+  const row = rows[0]
+  if (!row) return null
+  return magicLinkRecordModel.parse(row)
+}
+
+async function markAsUsed(selector: string): Promise<void> {
+  await Db.update('UPDATE magicLinks SET usedDate = ? WHERE selector = ?', [
+    instantFns.formatISO9075(instantFns.now()),
+    selector
+  ])
+}
+
+export const magicLinkDbProvider = {
+  create,
+  getBySelector,
+  getByUserId,
+  markAsUsed
+}

package/skills/maestro-examples/references/setlist/packages/services/src/auth/user-db-provider.test.ts

@@ -0,0 +1,33 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { userDbProvider } from './user-db-provider.ts'
+
+const createdIds: number[] = []
+
+test.afterEach(async () => {
+  for (const id of createdIds) {
+    await userDbProvider.hardDelete(id)
+  }
+  createdIds.length = 0
+})
+
+test('create and getById', async () => {
+  const id = await userDbProvider.create({ email: 'alice@test.com' })
+  createdIds.push(id)
+  const user = await userDbProvider.getById(id)
+  expect(user).not.toBeNull()
+  expect(user!.email).toBe('alice@test.com')
+  expect(user!.id).toBe(id)
+  expect(user!.credentialsInvalidBefore).toBeNull()
+})
+
+test('getByEmail', async () => {
+  const id = await userDbProvider.create({ email: 'bob@test.com' })
+  createdIds.push(id)
+  const user = await userDbProvider.getByEmail('bob@test.com')
+  expect(user).not.toBeNull()
+  expect(user!.email).toBe('bob@test.com')
+
+  const missing = await userDbProvider.getByEmail('nobody@test.com')
+  expect(missing).toBeNull()
+})

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

@@ -0,0 +1,55 @@
+import { Db } from '@maestro-js/db'
+import { UserSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+
+type User = UserSchemas.userModel
+
+async function getByEmail(email: string): Promise<User | null> {
+  const rows = await Db.select('SELECT * FROM users WHERE email = ?', [email])
+  const row = rows[0]
+  if (!row) return null
+  return UserSchemas.userModel.parse(row)
+}
+
+async function getById(id: number): Promise<User | null> {
+  const rows = await Db.select('SELECT * FROM users WHERE id = ?', [id])
+  const row = rows[0]
+  if (!row) return null
+  return UserSchemas.userModel.parse(row)
+}
+
+async function create(data: Pick<User, 'email'>): Promise<number> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  const result = await Db.insert('INSERT INTO users (email, createdDate, lastModifiedDate) VALUES (?, ?, ?)', [
+    data.email,
+    now,
+    now
+  ])
+  return result.insertId
+}
+
+async function seedCreate(data: User): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.insert(
+    'INSERT INTO users (id, email, credentialsInvalidBefore, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?)',
+    [
+      data.id,
+      data.email,
+      data.credentialsInvalidBefore ? instantFns.formatISO9075(data.credentialsInvalidBefore) : null,
+      now,
+      now
+    ]
+  )
+}
+
+async function hardDelete(id: number): Promise<void> {
+  await Db.delete('DELETE FROM users WHERE id = ?', [id])
+}
+
+export const userDbProvider = {
+  getByEmail,
+  getById,
+  create,
+  seedCreate,
+  hardDelete
+}

package/skills/maestro-examples/references/setlist/packages/services/src/auth/verify-magic-link-credentials.ts

@@ -0,0 +1,39 @@
+import { Hash } from '@maestro-js/hash'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { instantFns } from 'iso-fns'
+import { magicLinkDbProvider } from './magic-link-db-provider.ts'
+import { authDbProvider } from './auth-db-provider.ts'
+
+export const MagicLinkExpiredTokenError = CustomErrors.create({
+  name: 'MagicLinkExpiredTokenError',
+  message: 'Magic link token has expired',
+  httpStatusCode: 'badRequest' as const
+})
+
+function decodeMagicLinkToken(token: string): { selector: string; verifier: string } | null {
+  const [selector, verifier] = token.split('|')
+  if (!selector || !verifier) return null
+  return { selector, verifier }
+}
+
+export async function verifyMagicLinkCredentials({ token }: { token: string }) {
+  const decoded = decodeMagicLinkToken(token)
+  if (!decoded) return null
+
+  const record = await magicLinkDbProvider.getBySelector(decoded.selector)
+  if (!record) return null
+
+  const isValid = await Hash.provider('bcrypt').verify({
+    plaintext: decoded.verifier,
+    hash: record.verifierHash
+  })
+  if (!isValid) return null
+
+  if (record.expirationDate < instantFns.now()) {
+    throw new MagicLinkExpiredTokenError()
+  }
+
+  await magicLinkDbProvider.markAsUsed(decoded.selector)
+
+  return authDbProvider.getAuthenticatableById(record.userId)
+}

package/skills/maestro-examples/references/setlist/packages/services/src/index.ts

@@ -0,0 +1,20 @@
+import './maestro.ts'
+export { type DeviceContext } from './maestro.ts'
+export { MagicLinkExpiredTokenError } from './auth/verify-magic-link-credentials.ts'
+export { AuthService } from './auth/index.ts'
+export { AreaService } from './area/index.ts'
+export { ProjectService } from './project/index.ts'
+export { TaskService } from './task/index.ts'
+export { Db } from '@maestro-js/db'
+export { Cache } from '@maestro-js/cache'
+export { Hash } from '@maestro-js/hash'
+export { Crypt } from '@maestro-js/crypt'
+export { Auth } from '@maestro-js/auth'
+export { Helpers } from '@maestro-js/helpers'
+export { Session } from '@maestro-js/session'
+export { RateLimiting } from '@maestro-js/rate-limiting'
+export { Queue } from '@maestro-js/queue'
+export { RecurringJobs } from '@maestro-js/recurring-jobs'
+export { Log } from '@maestro-js/log'
+export { CustomErrors } from '@maestro-js/custom-errors'
+export { H } from './testing/index.ts'

package/skills/maestro-examples/references/setlist/packages/services/src/maestro.ts

@@ -0,0 +1,175 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { Db } from '@maestro-js/db'
+import { Cache } from '@maestro-js/cache'
+import { Hash } from '@maestro-js/hash'
+import { Crypt } from '@maestro-js/crypt'
+import { Auth } from '@maestro-js/auth'
+import { Session } from '@maestro-js/session'
+import { RateLimiting } from '@maestro-js/rate-limiting'
+import { Queue } from '@maestro-js/queue'
+import { RecurringJobs } from '@maestro-js/recurring-jobs'
+import { Mail } from '@maestro-js/mail'
+import { Log } from '@maestro-js/log'
+import type { Helpers } from '@maestro-js/helpers'
+import { SESClient, SendRawEmailCommand, type SendRawEmailCommandInput } from '@aws-sdk/client-ses'
+import { authDbProvider } from './auth/auth-db-provider.ts'
+import { verifyMagicLinkCredentials } from './auth/verify-magic-link-credentials.ts'
+
+type Credentials = { token: string }
+export type DeviceContext = ReturnType<(typeof Helpers)['getDeviceContext']>
+
+Db.Provider.register(
+  'default',
+  Db.Provider.create({
+    driver: Db.drivers.mysql({
+      user: process.env.DB_USER!,
+      password: process.env.DB_PASSWORD!,
+      host: process.env.DB_HOST!,
+      database: process.env.DB_DATABASE!,
+      port: Number(process.env.DB_PORT!)
+    })
+  })
+)
+
+Cache.Provider.register(
+  'default',
+  Cache.Provider.create({
+    driver:
+      process.env.ENV_NAME === 'local'
+        ? Cache.drivers.mockRedis({})
+        : Cache.drivers.redis({ url: process.env.REDIS_URL!, port: Number(process.env.REDIS_PORT!) })
+  })
+)
+
+Hash.Provider.register(
+  'default',
+  Hash.Provider.create(Hash.drivers.sha256({ key: process.env.HASH_KEY!, previousKeys: [] }))
+)
+Hash.Provider.register('bcrypt', Hash.Provider.create(Hash.drivers.bcrypt({ rounds: 12 })))
+
+Crypt.Provider.register(
+  'default',
+  Crypt.Provider.create({
+    key: process.env.ENCRYPTION_KEY!,
+    previousKeys: []
+  })
+)
+
+Auth.Provider.register(
+  'default',
+  Auth.Provider.create<number, Credentials, DeviceContext>({
+    name: 'default',
+    getAuthenticatableById: authDbProvider.getAuthenticatableById,
+    verifyCredentials: verifyMagicLinkCredentials,
+    updateCredentialsInvalidBefore: authDbProvider.updateCredentialsInvalidBefore,
+    hash: Hash,
+    crypt: Crypt
+  })
+)
+
+Session.Provider.register(
+  'default',
+  Session.Provider.create({
+    driver: Session.drivers.store({
+      store: Cache,
+      crypt: Crypt,
+      cookie: {
+        name: 'setlist_session',
+        secure: process.env.ENV_NAME !== 'local',
+        httpOnly: true,
+        sameSite: 'Lax',
+        maxAge: 30 * 24 * 60 * 60
+      }
+    })
+  })
+)
+
+RateLimiting.Provider.register('default', RateLimiting.Provider.create(Cache))
+
+Queue.Provider.register(
+  'default',
+  Queue.Provider.create({
+    driver: Queue.drivers.db({
+      db: Db,
+      databaseTable: 'queueMessages'
+    }),
+    logger: Log
+  })
+)
+
+RecurringJobs.Provider.register(
+  'default',
+  RecurringJobs.Provider.create({
+    driver: RecurringJobs.drivers.db({
+      db: Db,
+      databaseTable: 'recurringJobs'
+    }),
+    logger: Log
+  })
+)
+
+if (process.env.ENV_NAME === 'local') {
+  const e2eMailDir = path.resolve(process.cwd(), '.e2e-mail')
+  fs.mkdirSync(e2eMailDir, { recursive: true })
+  Mail.Provider.register(
+    'default',
+    Mail.Provider.create({
+      driver: Mail.drivers.stub({
+        logger: {
+          info(envelope: Mail.Envelope) {
+            fs.writeFileSync(path.join(e2eMailDir, 'latest.json'), JSON.stringify(envelope, null, 2))
+          }
+        } as any
+      }),
+      name: 'default',
+      globalFrom: process.env.MAIL_FROM!,
+      logger: Log,
+      queue: Queue
+    })
+  )
+} else {
+  const sesClient = new SESClient({ region: process.env.AWS_REGION! })
+  Mail.Provider.register(
+    'default',
+    Mail.Provider.create({
+      driver: Mail.drivers.ses({
+        send(command: { input: SendRawEmailCommandInput }) {
+          return sesClient.send(new SendRawEmailCommand(command.input))
+        },
+        configurationSetName: 'setlist'
+      }),
+      name: 'default',
+      globalFrom: process.env.MAIL_FROM!,
+      logger: Log,
+      queue: Queue
+    })
+  )
+}
+
+Log.addTransport(Log.transports.console())
+
+declare module '@maestro-js/auth' {
+  namespace Auth {
+    namespace Provider {
+      interface Keys {
+        default: {
+          Credentials: Credentials
+          DeviceContext: DeviceContext
+          Id: number
+        }
+      }
+    }
+  }
+}
+
+declare module '@maestro-js/hash' {
+  namespace Hash {
+    namespace Provider {
+      interface Keys {
+        default: true
+        bcrypt: true
+      }
+    }
+  }
+}

package/skills/maestro-examples/references/setlist/packages/services/src/project/index.ts

@@ -0,0 +1,29 @@
+import {
+  ViewProjectTasks,
+  CreateProject,
+  EditProject,
+  DeleteProject,
+  MoveProject,
+  CompleteProject,
+  UncompleteProject,
+  ReorderProject,
+  ListProjects,
+  ProjectNotFoundError,
+  ProjectNotOwnedError
+} from './project-use-cases.ts'
+
+export const ProjectService = {
+  ViewProjectTasks,
+  CreateProject,
+  EditProject,
+  DeleteProject,
+  MoveProject,
+  CompleteProject,
+  UncompleteProject,
+  ReorderProject,
+  ListProjects,
+  errors: {
+    ProjectNotFoundError,
+    ProjectNotOwnedError
+  }
+}

package/skills/maestro-examples/references/setlist/packages/services/src/project/project-db-provider.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { H } from '../testing/index.ts'
+import { projectDbProvider } from './project-db-provider.ts'
+
+const user = H.UserSeed({ id: 1 })
+const pipe = H.SeedPipe(user)
+
+test.beforeEach(async () => { await pipe.setup() })
+test.afterEach(async () => { await pipe.teardown() })
+
+test('create and getById', async () => {
+  const id = await projectDbProvider.create({
+    userId: 1,
+    areaId: null,
+    title: 'Launch',
+    notes: null,
+    scheduledDate: null,
+    position: 'a0'
+  })
+  const project = await projectDbProvider.getById(id)
+  expect(project).not.toBeNull()
+  expect(project!.title).toBe('Launch')
+  expect(project!.userId).toBe(1)
+  expect(project!.completedDate).toBeNull()
+})
+
+test('complete, uncomplete, and listCompleted', async () => {
+  const id = await projectDbProvider.create({
+    userId: 1,
+    areaId: null,
+    title: 'Ship',
+    notes: null,
+    scheduledDate: null,
+    position: 'a0'
+  })
+
+  await projectDbProvider.complete(id)
+  const completed = await projectDbProvider.listCompleted(1)
+  expect(completed).toHaveLength(1)
+  expect(completed[0]!.title).toBe('Ship')
+
+  await projectDbProvider.uncomplete(id)
+  const afterUncomplete = await projectDbProvider.listCompleted(1)
+  expect(afterUncomplete).toHaveLength(0)
+})

package/skills/maestro-examples/references/setlist/packages/services/src/project/project-db-provider.ts

@@ -0,0 +1,114 @@
+import { Db } from '@maestro-js/db'
+import { ProjectSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+
+type Project = ProjectSchemas.projectModel
+
+async function create(
+  data: Pick<Project, 'userId' | 'areaId' | 'title' | 'notes' | 'scheduledDate' | 'position'>
+): Promise<number> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  const result = await Db.insert(
+    'INSERT INTO projects (userId, areaId, title, notes, scheduledDate, position, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    [data.userId, data.areaId, data.title, data.notes, data.scheduledDate, data.position, now, now]
+  )
+  return result.insertId
+}
+
+async function getById(id: number): Promise<Project | null> {
+  const rows = await Db.select('SELECT * FROM projects WHERE id = ?', [id])
+  const row = rows[0]
+  if (!row) return null
+  return ProjectSchemas.projectModel.parse(row)
+}
+
+async function listByUserId(userId: number): Promise<Project[]> {
+  const rows = await Db.select(
+    'SELECT * FROM projects WHERE userId = ? AND deletedDate IS NULL ORDER BY position COLLATE utf8mb4_bin ASC',
+    [userId]
+  )
+  return rows.map((row) => ProjectSchemas.projectModel.parse(row))
+}
+
+async function listByAreaId(areaId: number): Promise<Project[]> {
+  const rows = await Db.select(
+    'SELECT * FROM projects WHERE areaId = ? AND deletedDate IS NULL ORDER BY position COLLATE utf8mb4_bin ASC',
+    [areaId]
+  )
+  return rows.map((row) => ProjectSchemas.projectModel.parse(row))
+}
+
+async function update(id: number, data: Pick<Project, 'title' | 'notes' | 'scheduledDate' | 'areaId'>): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update(
+    'UPDATE projects SET title = ?, notes = ?, scheduledDate = ?, areaId = ?, lastModifiedDate = ? WHERE id = ?',
+    [data.title, data.notes, data.scheduledDate, data.areaId, now, id]
+  )
+}
+
+async function softDelete(id: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE projects SET deletedDate = ?, lastModifiedDate = ? WHERE id = ?', [now, now, id])
+}
+
+async function complete(id: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE projects SET completedDate = ?, lastModifiedDate = ? WHERE id = ?', [now, now, id])
+}
+
+async function uncomplete(id: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE projects SET completedDate = NULL, lastModifiedDate = ? WHERE id = ?', [now, id])
+}
+
+async function listCompleted(userId: number): Promise<Project[]> {
+  const rows = await Db.select(
+    'SELECT * FROM projects WHERE userId = ? AND completedDate IS NOT NULL AND deletedDate IS NULL ORDER BY completedDate DESC',
+    [userId]
+  )
+  return rows.map((row) => ProjectSchemas.projectModel.parse(row))
+}
+
+async function updatePosition(id: number, position: string): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE projects SET position = ?, lastModifiedDate = ? WHERE id = ?', [position, now, id])
+}
+
+async function seedCreate(data: Project): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.insert(
+    'INSERT INTO projects (id, userId, areaId, title, notes, scheduledDate, position, completedDate, deletedDate, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [
+      data.id,
+      data.userId,
+      data.areaId,
+      data.title,
+      data.notes,
+      data.scheduledDate,
+      data.position,
+      data.completedDate ? instantFns.formatISO9075(data.completedDate) : null,
+      data.deletedDate ? instantFns.formatISO9075(data.deletedDate) : null,
+      now,
+      now
+    ]
+  )
+}
+
+async function hardDelete(id: number): Promise<void> {
+  await Db.delete('DELETE FROM projects WHERE id = ?', [id])
+}
+
+export const projectDbProvider = {
+  create,
+  getById,
+  listByUserId,
+  listByAreaId,
+  update,
+  softDelete,
+  complete,
+  uncomplete,
+  listCompleted,
+  updatePosition,
+  seedCreate,
+  hardDelete
+}