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

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

@@ -0,0 +1,303 @@
+import z from 'zod'
+import { Log } from '@maestro-js/log'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { TaskSchemas, UserSchemas } from '@setlist/schemas'
+import { dateFns, type Iso } from 'iso-fns'
+import { taskDbProvider } from './task-db-provider.ts'
+import { projectDbProvider } from '../project/project-db-provider.ts'
+import { generateKeyBetween } from '@setlist/schemas'
+
+const log = Log.channel('task')
+
+const Profile = UserSchemas.userModel.pick({ id: true })
+
+export const TaskNotFoundError = CustomErrors.create({
+  name: 'TaskNotFoundError',
+  message: 'Task not found',
+  httpStatusCode: 'notFound' as const
+})
+
+export const TaskNotOwnedError = CustomErrors.create({
+  name: 'TaskNotOwnedError',
+  message: 'Task does not belong to the authenticated user',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const ViewTask = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    return task
+  })
+
+export const CreateTask = z
+  .function({
+    input: [TaskSchemas.createTaskForm, Profile]
+  })
+  .implement(async ({ title, projectId, areaId, notes, scheduledDate }, profile) => {
+    const listPosition = await generateListPosition({ projectId, areaId, userId: profile.id })
+    const scheduledPosition = scheduledDate ? await generateScheduledPosition(profile.id, scheduledDate) : null
+
+    const taskId = await taskDbProvider.create({
+      userId: profile.id,
+      projectId,
+      areaId,
+      title,
+      notes,
+      scheduledDate,
+      listPosition,
+      scheduledPosition
+    })
+
+    log.info('Task created', { action: 'task.create', userId: profile.id, taskId })
+
+    return { taskId }
+  })
+
+export const EditTask = z
+  .function({
+    input: [TaskSchemas.taskModel.pick({ id: true }).merge(TaskSchemas.editTaskForm.partial()), Profile]
+  })
+  .implement(async ({ id, title, notes, scheduledDate }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    const newScheduledDate = scheduledDate !== undefined ? scheduledDate : task.scheduledDate
+    const newScheduledPosition =
+      scheduledDate === undefined || scheduledDate === task.scheduledDate
+        ? task.scheduledPosition
+        : scheduledDate
+          ? await generateScheduledPosition(profile.id, scheduledDate, id)
+          : null
+
+    await taskDbProvider.update(id, {
+      title: title ?? task.title,
+      notes: notes !== undefined ? notes : task.notes,
+      scheduledDate: newScheduledDate,
+      scheduledPosition: newScheduledPosition
+    })
+
+    log.info('Task edited', { action: 'task.edit', userId: profile.id, taskId: id })
+  })
+
+export const DeleteTask = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    await taskDbProvider.softDelete(id)
+
+    log.info('Task deleted', { action: 'task.delete', userId: profile.id, taskId: id })
+  })
+
+export const MoveTask = z
+  .function({
+    input: [z.object({ id: z.number(), projectId: z.number().nullable(), areaId: z.number().nullable() }), Profile]
+  })
+  .implement(async ({ id, projectId, areaId }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    const listPosition = await generateListPosition({ projectId, areaId, userId: profile.id })
+
+    await taskDbProvider.updateContainer(id, { projectId, areaId, listPosition })
+
+    log.info('Task moved', { action: 'task.move', userId: profile.id, taskId: id, projectId, areaId })
+  })
+
+export const CompleteTask = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    await taskDbProvider.complete(id)
+
+    log.info('Task completed', { action: 'task.complete', userId: profile.id, taskId: id })
+  })
+
+export const UncompleteTask = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    const listPosition = await generateListPosition({
+      projectId: task.projectId,
+      areaId: task.areaId,
+      userId: profile.id
+    })
+
+    await taskDbProvider.uncomplete(id)
+    await taskDbProvider.updatePosition(id, listPosition)
+
+    log.info('Task uncompleted', { action: 'task.uncomplete', userId: profile.id, taskId: id })
+  })
+
+export const ReorderTask = z
+  .function({
+    input: [
+      z.object({
+        id: z.number(),
+        beforeKey: z.string().nullable(),
+        afterKey: z.string().nullable(),
+        type: z.enum(['list', 'scheduled'])
+      }),
+      Profile
+    ]
+  })
+  .implement(async ({ id, beforeKey, afterKey, type }, profile) => {
+    const task = await taskDbProvider.getById(id)
+    if (!task) throw new TaskNotFoundError()
+    if (task.userId !== profile.id) throw new TaskNotOwnedError()
+
+    const position = generateKeyBetween(beforeKey, afterKey)
+
+    if (type === 'list') {
+      await taskDbProvider.updatePosition(id, position)
+    } else {
+      await taskDbProvider.update(id, {
+        title: task.title,
+        notes: task.notes,
+        scheduledDate: task.scheduledDate,
+        scheduledPosition: position
+      })
+    }
+
+    log.info('Task reordered', { action: 'task.reorder', userId: profile.id, taskId: id, type })
+  })
+
+export const GetSidebarCounts = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    const today = dateFns.now()
+    const [inboxCount, todayCount] = await Promise.all([
+      taskDbProvider.countInbox(profile.id),
+      taskDbProvider.countToday(profile.id, today)
+    ])
+    return { inboxCount, todayCount }
+  })
+
+export const ListTasksForInbox = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    const tasks = await taskDbProvider.listInbox(profile.id)
+    return { tasks }
+  })
+
+export const ListTasksForToday = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    const today = dateFns.now()
+    const tasks = await taskDbProvider.listToday(profile.id, today)
+    return { tasks }
+  })
+
+export const ListTasksForUpcoming = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    const today = dateFns.now()
+    const tasks = await taskDbProvider.listUpcoming(profile.id, today)
+
+    const groupMap = new Map<string, TaskSchemas.taskModel[]>()
+    for (const task of tasks) {
+      const dateStr = task.scheduledDate!
+      let group = groupMap.get(dateStr)
+      if (!group) {
+        group = []
+        groupMap.set(dateStr, group)
+      }
+      group.push(task)
+    }
+
+    const groups = Array.from(groupMap.entries()).map(([date, tasks]) => ({
+      date,
+      tasks
+    }))
+
+    return { groups }
+  })
+
+export const ListCompleted = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    const tasks = await taskDbProvider.listCompleted(profile.id)
+    const projects = await projectDbProvider.listCompleted(profile.id)
+    return { tasks, projects }
+  })
+
+export const ListTasksByProjectId = z
+  .function({
+    input: [z.object({ projectId: z.number() }), Profile]
+  })
+  .implement(async ({ projectId }, profile) => {
+    const project = await projectDbProvider.getById(projectId)
+    if (!project) throw new TaskNotFoundError()
+    if (project.userId !== profile.id) throw new TaskNotOwnedError()
+
+    return taskDbProvider.listByProjectId(projectId)
+  })
+
+async function generateListPosition({
+  projectId,
+  areaId,
+  userId
+}: {
+  projectId: number | null
+  areaId: number | null
+  userId: number
+}): Promise<string> {
+  const tasks = projectId
+    ? await taskDbProvider.listByProjectId(projectId)
+    : areaId
+      ? await taskDbProvider.listByAreaId(areaId)
+      : await taskDbProvider.listInbox(userId)
+  const lastTask = tasks.at(-1)
+  return generateKeyBetween(lastTask?.listPosition ?? null, null)
+}
+
+async function generateScheduledPosition(userId: number, dateStr: Iso.Date, excludeId?: number): Promise<string> {
+  const today = dateFns.now()
+  let tasks: TaskSchemas.taskModel[]
+
+  if (dateStr <= today) {
+    tasks = await taskDbProvider.listToday(userId, today)
+  } else {
+    tasks = await taskDbProvider.listUpcoming(userId, today)
+    tasks = tasks.filter((t) => t.scheduledDate === dateStr)
+  }
+
+  if (excludeId !== undefined) {
+    tasks = tasks.filter((t) => t.id !== excludeId)
+  }
+
+  const lastTask = tasks.at(-1)
+  return generateKeyBetween(lastTask?.scheduledPosition ?? null, null)
+}

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

@@ -0,0 +1,25 @@
+import type { AreaSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+import { areaDbProvider } from '../area/area-db-provider.ts'
+
+export function AreaSeed(area: Partial<AreaSchemas.areaModel> & { id: number; userId: number }) {
+  const mock: Omit<AreaSchemas.areaModel, 'id' | 'userId'> = {
+    title: 'Test Area',
+    position: 'a0',
+    deletedDate: null,
+    createdDate: instantFns.now(),
+    lastModifiedDate: instantFns.now()
+  }
+  const merged = { ...mock, ...area }
+
+  async function setup() {
+    await teardown()
+    await areaDbProvider.seedCreate(merged)
+  }
+
+  async function teardown() {
+    await areaDbProvider.hardDelete(area.id)
+  }
+
+  return { setup, teardown }
+}

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

@@ -0,0 +1,13 @@
+import { AreaSeed } from './area-seed.ts'
+import { ProjectSeed } from './project-seed.ts'
+import { SeedPipe } from './seed-pipe.ts'
+import { TaskSeed } from './task-seed.ts'
+import { UserSeed } from './user-seed.ts'
+
+export const H = {
+  AreaSeed,
+  ProjectSeed,
+  SeedPipe,
+  TaskSeed,
+  UserSeed
+}

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

@@ -0,0 +1,29 @@
+import type { ProjectSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+import { projectDbProvider } from '../project/project-db-provider.ts'
+
+export function ProjectSeed(project: Partial<ProjectSchemas.projectModel> & { id: number; userId: number }) {
+  const mock: Omit<ProjectSchemas.projectModel, 'id' | 'userId'> = {
+    areaId: null,
+    title: 'Test Project',
+    notes: null,
+    scheduledDate: null,
+    position: 'a0',
+    completedDate: null,
+    deletedDate: null,
+    createdDate: instantFns.now(),
+    lastModifiedDate: instantFns.now()
+  }
+  const merged = { ...mock, ...project }
+
+  async function setup() {
+    await teardown()
+    await projectDbProvider.seedCreate(merged)
+  }
+
+  async function teardown() {
+    await projectDbProvider.hardDelete(project.id)
+  }
+
+  return { setup, teardown }
+}

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

@@ -0,0 +1,38 @@
+export type SeedFn = { setup(): Promise<void>; teardown: () => Promise<void> }
+
+export function SeedPipe(...seeds: SeedFn[]): SeedFn {
+  const seedFnMap = new Map<() => Promise<SeedFn>, Promise<SeedFn>>()
+
+  function resolveSeeder(seeder: SeedFn | (() => Promise<SeedFn>)): Promise<SeedFn> {
+    if (typeof seeder === 'function') {
+      const existing = seedFnMap.get(seeder)
+      if (existing) {
+        return existing
+      } else {
+        seedFnMap.set(seeder, seeder())
+        return seedFnMap.get(seeder)!
+      }
+    } else {
+      return Promise.resolve(seeder)
+    }
+  }
+
+  async function setup() {
+    for (const seed of seeds) {
+      const seeder = await resolveSeeder(seed)
+      await seeder.setup()
+    }
+  }
+
+  async function teardown() {
+    const seedsReversed = [...seeds].reverse()
+    for (const seed of seedsReversed) {
+      const seeder = await resolveSeeder(seed)
+      await seeder.teardown()
+    }
+  }
+  return {
+    setup,
+    teardown
+  }
+}

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

@@ -0,0 +1,31 @@
+import type { TaskSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+import { taskDbProvider } from '../task/task-db-provider.ts'
+
+export function TaskSeed(task: Partial<TaskSchemas.taskModel> & { id: number; userId: number }) {
+  const mock: Omit<TaskSchemas.taskModel, 'id' | 'userId'> = {
+    projectId: null,
+    areaId: null,
+    title: 'Test Task',
+    notes: null,
+    scheduledDate: null,
+    listPosition: 'a0',
+    scheduledPosition: null,
+    completedDate: null,
+    deletedDate: null,
+    createdDate: instantFns.now(),
+    lastModifiedDate: instantFns.now()
+  }
+  const merged = { ...mock, ...task }
+
+  async function setup() {
+    await teardown()
+    await taskDbProvider.seedCreate(merged)
+  }
+
+  async function teardown() {
+    await taskDbProvider.hardDelete(task.id)
+  }
+
+  return { setup, teardown }
+}

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

@@ -0,0 +1,24 @@
+import type { UserSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+import { userDbProvider } from '../auth/user-db-provider.ts'
+
+export function UserSeed(user: Partial<UserSchemas.userModel> & { id: number }) {
+  const mock: Omit<UserSchemas.userModel, 'id'> = {
+    email: `test-${user.id}@example.com`,
+    credentialsInvalidBefore: null,
+    createdDate: instantFns.now(),
+    lastModifiedDate: instantFns.now()
+  }
+  const merged = { ...mock, ...user }
+
+  async function setup() {
+    await teardown()
+    await userDbProvider.seedCreate(merged)
+  }
+
+  async function teardown() {
+    await userDbProvider.hardDelete(merged.id)
+  }
+
+  return { setup, teardown }
+}

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

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

package/skills/maestro-examples/references/setlist/queue-processor/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@setlist/queue-processor",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "maestro config:run --config queue-processor -- tsx src/index.ts"
+  },
+  "dependencies": {
+    "@maestro-js/config": "^1.0.0-alpha.21",
+    "@setlist/services": "workspace:*"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@types/node": "^22.19.11",
+    "tsx": "^4.21.0"
+  }
+}

package/skills/maestro-examples/references/setlist/queue-processor/src/index.ts

@@ -0,0 +1,29 @@
+import { Queue, RecurringJobs, Log } from '@setlist/services'
+import './recurring-jobs.ts'
+
+const log = Log.channel('queue-processor')
+
+const concurrency = Number(process.env.QUEUE_CONCURRENCY ?? '1')
+const sleepSeconds = Number(process.env.QUEUE_POLL_INTERVAL ?? '5000') / 1000
+
+log.info({ event: 'queueProcessorStarting', concurrency, sleepSeconds })
+
+const queueHandle = Queue.work({ concurrency, sleepSeconds })
+const recurringJobsHandle = RecurringJobs.work()
+
+process.on('SIGTERM', () => {
+  log.info({ event: 'queueProcessorStopping', reason: 'SIGTERM' })
+  queueHandle.abort('SIGTERM')
+  recurringJobsHandle.abort()
+})
+
+process.on('SIGINT', () => {
+  log.info({ event: 'queueProcessorStopping', reason: 'SIGINT' })
+  queueHandle.abort('SIGINT')
+  recurringJobsHandle.abort()
+})
+
+queueHandle.then(() => {
+  log.info({ event: 'queueProcessorStopped' })
+  process.exit(0)
+})

package/skills/maestro-examples/references/setlist/queue-processor/src/recurring-jobs.ts

@@ -0,0 +1,13 @@
+import { Db, RecurringJobs, Log } from '@setlist/services'
+
+const log = Log.channel('system')
+
+RecurringJobs.create({
+  name: 'purge-expired-magic-links',
+  cron: '0 3 * * *',
+  async handle() {
+    const result = await Db.delete('DELETE FROM magicLinks WHERE expirationDate < DATE_SUB(NOW(), INTERVAL 7 DAY)', [])
+    log.info({ event: 'purgeExpiredMagicLinks', deletedCount: result.affectedRows })
+    return { deletedCount: result.affectedRows }
+  }
+})

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

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["src"]
+}

package/skills/maestro-examples/references/setlist/scripts/foreign-key-delete-behavior.ts

@@ -0,0 +1,107 @@
+import { Db } from '@maestro-js/db'
+
+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!)
+    })
+  })
+)
+
+const FKS = {
+  fk_magicLinks_userId: 'CASCADE',
+  fk_areas_userId: 'CASCADE',
+  fk_projects_userId: 'CASCADE',
+  fk_projects_areaId: 'CASCADE',
+  fk_tasks_userId: 'CASCADE',
+  fk_tasks_projectId: 'CASCADE',
+  fk_tasks_areaId: 'CASCADE'
+}
+
+type ForeignKey = {
+  TABLE_NAME: string
+  COLUMN_NAME: string
+  REFERENCED_TABLE_NAME: string
+  REFERENCED_COLUMN_NAME: string
+  CONSTRAINT_NAME: string
+}
+
+const foreignKeys = await Db.select<ForeignKey>(
+  `SELECT
+    TABLE_NAME,
+    COLUMN_NAME,
+    REFERENCED_TABLE_NAME,
+    REFERENCED_COLUMN_NAME,
+    CONSTRAINT_NAME
+  FROM information_schema.KEY_COLUMN_USAGE
+  WHERE TABLE_SCHEMA = ?
+    AND REFERENCED_TABLE_NAME IS NOT NULL
+  ORDER BY TABLE_NAME, COLUMN_NAME`,
+  [process.env.DB_DATABASE!]
+)
+
+const dbFkNames = new Set(foreignKeys.map((fk) => fk.CONSTRAINT_NAME))
+const localFkNames = new Set(Object.keys(FKS))
+
+const missingFromLocal = [...dbFkNames].filter((name) => !localFkNames.has(name))
+const extraInLocal = [...localFkNames].filter((name) => !dbFkNames.has(name))
+
+if (missingFromLocal.length > 0) {
+  console.error('Foreign keys in database but missing from FKS:', missingFromLocal)
+}
+if (extraInLocal.length > 0) {
+  console.error('Foreign keys in FKS but not in database:', extraInLocal)
+}
+if (missingFromLocal.length > 0 || extraInLocal.length > 0) {
+  process.exit(1)
+}
+
+console.log('FKS matches database foreign keys')
+
+async function applyOnDeleteRestrict() {
+  for (const constraintName of Object.keys(FKS)) {
+    const fk = foreignKeys.find((f) => f.CONSTRAINT_NAME === constraintName)!
+    await Db.statement(`ALTER TABLE ${fk.TABLE_NAME} DROP FOREIGN KEY ${constraintName}`)
+    await Db.statement(
+      `ALTER TABLE ${fk.TABLE_NAME}
+        ADD CONSTRAINT ${constraintName}
+        FOREIGN KEY (${fk.COLUMN_NAME})
+        REFERENCES ${fk.REFERENCED_TABLE_NAME}(${fk.REFERENCED_COLUMN_NAME})
+        ON DELETE RESTRICT`
+    )
+    console.log(`${constraintName}: ON DELETE RESTRICT applied`)
+  }
+}
+
+async function applyOnDeleteCascade() {
+  for (const [constraintName, behavior] of Object.entries(FKS)) {
+    const fk = foreignKeys.find((f) => f.CONSTRAINT_NAME === constraintName)!
+    await Db.statement(`ALTER TABLE ${fk.TABLE_NAME} DROP FOREIGN KEY ${constraintName}`)
+    await Db.statement(
+      `ALTER TABLE ${fk.TABLE_NAME}
+        ADD CONSTRAINT ${constraintName}
+        FOREIGN KEY (${fk.COLUMN_NAME})
+        REFERENCES ${fk.REFERENCED_TABLE_NAME}(${fk.REFERENCED_COLUMN_NAME})
+        ON DELETE ${behavior}`
+    )
+    console.log(`${constraintName}: ON DELETE ${behavior} applied`)
+  }
+}
+
+const action = process.argv[2]
+
+if (action === 'cascade') {
+  await applyOnDeleteCascade()
+} else if (action === 'restrict') {
+  await applyOnDeleteRestrict()
+} else {
+  console.error('Usage: foreign-key-delete-behavior <cascade|restrict>')
+  process.exit(1)
+}
+
+process.exit(0)