@softize/opus 8.6.6

package/src/mcp/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @softize/opus/mcp — expõe as actions `ai:enabled` de um runtime como **tools MCP**, pra
+ * uma IA de FORA (Claude Desktop, o agente de um parceiro, um hub próprio) alcançar o app
+ * pelo protocolo. É o MESMO bridge do agente co-locado (`runtime.aiTools`) e a MESMA execução
+ * (`runtime.execute`, com o contexto resolvido) — o MCP é só o transporte.
+ *
+ * Você monta o transporte (stdio pra local, HTTP/SSE pra remoto) e conecta:
+ * `await createOpusMcpServer(runtime, { resolveContext }).connect(transport)`.
+ *
+ * `@modelcontextprotocol/sdk` já é dep do pacote.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import type { ContextBase, Runtime } from '../core/index.ts'
+
+export interface OpusMcpOptions {
+  name?: string
+  version?: string
+  /** Resolve a identidade da requisição MCP → contexto do runtime (auth). O `extra` traz o
+   *  que o transporte capturou (headers/token). Sem isso, executa ANÔNIMO — o `can` nega, então
+   *  só actions públicas rodam. Pra "como o usuário", valide o token (IdP) aqui e devolva o base. */
+  resolveContext?: (extra: unknown) => Promise<ContextBase> | ContextBase
+  /** Conversor Schema → JSON Schema (injetável). Default: `zod-to-json-schema` inline. */
+  toJsonSchema?: (schema: unknown) => unknown
+}
+
+const ANON: ContextBase = { user: null, tenantId: null, can: () => false, meta: {} }
+
+/**
+ * Monta um `Server` MCP que expõe as actions `ai:enabled` do runtime como tools (ListTools) e
+ * as executa como o contexto resolvido (CallTool). Conecte num transporte com `.connect()`.
+ */
+export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {}): Server {
+  const toJsonSchema =
+    opts.toJsonSchema ?? ((schema: unknown) => zodToJsonSchema(schema as never, { $refStrategy: 'none' }))
+
+  const server = new Server(
+    { name: opts.name ?? 'opus', version: opts.version ?? '0.0.0' },
+    { capabilities: { tools: {} } },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: runtime.aiTools().map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
+    })),
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+    const base = opts.resolveContext ? await opts.resolveContext(extra) : ANON
+    const result = await runtime.execute(req.params.name, req.params.arguments ?? {}, base)
+    const payload = result.ok ? result.data : { error: result.error }
+    return {
+      content: [{ type: 'text', text: JSON.stringify(payload ?? null) }],
+      isError: !result.ok,
+    }
+  })
+
+  return server
+}

package/src/queue/drivers/bullmq.ts

@@ -0,0 +1,190 @@
+/**
+ * @softize/opus/queue/bullmq — BullMQ queue driver
+ *
+ * Implementa `QueueAdapter` wrappando uma instância `Queue` do BullMQ.
+ * Faz mapping `JobSpec` ↔ BullMQ job e `BullMQ state` → `JobStatus`.
+ *
+ * Worker (consumer-side) é responsabilidade do consumer — esse adapter
+ * só **enfileira** e **consulta**. Pra processar, o consumer registra
+ * um `new Worker(queueName, processor, { connection })` que chama
+ * `runtime.execute()` no callback.
+ *
+ * Uso:
+ *   import { Queue } from 'bullmq'
+ *   import { bullmqQueue } from '@softize/opus/queue/bullmq'
+ *
+ *   const queue = new Queue('tbdlib-jobs', { connection: redisOpts })
+ *   createRuntime({ queue: bullmqQueue({ queue }) })
+ */
+
+import type {
+  JobHandle,
+  JobSpec,
+  JobStatus,
+  QueueAdapter,
+} from '../../core/index.ts'
+
+// =============================================================================
+// BullMQ-compatible interfaces (zero direct dep no tipo público)
+// =============================================================================
+
+/** Estado nativo do BullMQ retornado por `job.getState()`. */
+export type BullMQState =
+  | 'waiting'
+  | 'waiting-children'
+  | 'active'
+  | 'completed'
+  | 'failed'
+  | 'delayed'
+  | 'paused'
+  | 'prioritized'
+  | 'unknown'
+
+export interface BullMQJob {
+  id?: string | undefined
+  data: unknown
+  returnvalue?: unknown
+  failedReason?: string | undefined
+  attemptsMade: number
+  timestamp: number
+  processedOn?: number | undefined
+  finishedOn?: number | undefined
+  progress: number | object
+  getState(): Promise<BullMQState>
+  remove(): Promise<void>
+}
+
+export interface BullMQQueue {
+  add(
+    name: string,
+    data: unknown,
+    opts?: { jobId?: string },
+  ): Promise<BullMQJob>
+  getJob(jobId: string): Promise<BullMQJob | undefined | null>
+}
+
+// =============================================================================
+// Adapter factory
+// =============================================================================
+
+export interface BullmqQueueOptions {
+  queue: BullMQQueue
+  name?: string
+}
+
+export function bullmqQueue(options: BullmqQueueOptions): QueueAdapter {
+  const { queue, name = 'bullmq' } = options
+
+  return {
+    name,
+    kind: 'queue',
+
+    async enqueue(spec: JobSpec): Promise<JobHandle> {
+      const job = await queue.add(spec.action, spec, { jobId: spec.jobId })
+      return jobToHandle(spec.action, job, 'queued')
+    },
+
+    async status(jobId: string): Promise<JobHandle | null> {
+      const job = await queue.getJob(jobId)
+      if (job === undefined || job === null) return null
+      const state = await job.getState()
+      const action = readAction(job)
+      return jobToHandle(action, job, mapState(state))
+    },
+
+    async cancel(jobId: string): Promise<boolean> {
+      const job = await queue.getJob(jobId)
+      if (job === undefined || job === null) return false
+      await job.remove()
+      return true
+    },
+  }
+}
+
+// =============================================================================
+// Mapping
+// =============================================================================
+
+/**
+ * BullMQ state → tbdlib JobStatus.
+ *
+ * tbdlib não tem 'paused' nem 'delayed' separados — todos viram 'queued'.
+ * Distinção fina fica no `details.meta.bullmqState` se consumer precisar.
+ */
+export function mapState(state: BullMQState): JobStatus {
+  switch (state) {
+    case 'completed':
+      return 'done'
+    case 'failed':
+      return 'failed'
+    case 'active':
+      return 'running'
+    case 'waiting':
+    case 'waiting-children':
+    case 'delayed':
+    case 'paused':
+    case 'prioritized':
+      return 'queued'
+    /* v8 ignore next 3 — 'unknown' é defensivo; BullMQ documenta os estados acima */
+    case 'unknown':
+    default:
+      return 'queued'
+  }
+}
+
+function jobToHandle(
+  action: string,
+  job: BullMQJob,
+  status: JobStatus,
+): JobHandle {
+  const handle: JobHandle = {
+    jobId: job.id ?? '',
+    action,
+    status,
+    enqueuedAt: toIso(job.timestamp),
+    attempts: job.attemptsMade,
+  }
+  if (job.processedOn !== undefined) handle.startedAt = toIso(job.processedOn)
+  if (job.finishedOn !== undefined) handle.finishedAt = toIso(job.finishedOn)
+  if (status === 'done' && job.returnvalue !== undefined) handle.data = job.returnvalue
+  if (status === 'failed' && job.failedReason !== undefined) {
+    handle.error = {
+      code: 'queue.job_failed',
+      category: 'internal',
+      message: job.failedReason,
+      severity: 'error',
+      retriable: false,
+    }
+  }
+  const progress = readProgress(job)
+  if (progress !== undefined) handle.progress = progress
+  return handle
+}
+
+function readAction(job: BullMQJob): string {
+  if (
+    typeof job.data === 'object' &&
+    job.data !== null &&
+    'action' in job.data &&
+    typeof (job.data as { action: unknown }).action === 'string'
+  ) {
+    return (job.data as { action: string }).action
+  }
+  return ''
+}
+
+function readProgress(job: BullMQJob): JobHandle['progress'] | undefined {
+  const p = job.progress
+  if (typeof p === 'number') {
+    if (p === 0) return undefined
+    return { percent: p }
+  }
+  if (typeof p === 'object' && p !== null && Object.keys(p).length > 0) {
+    return p as JobHandle['progress']
+  }
+  return undefined
+}
+
+function toIso(ms: number): string {
+  return new Date(ms).toISOString()
+}

package/src/queue/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @softize/opus/queue — shared helpers/types for queue drivers.
+ *
+ * Drivers (bullmq, futuro: inngest, trigger-dev) implementam QueueAdapter
+ * do core. Espaço reservado pra helpers comuns (job status mapping,
+ * retry calculator universal).
+ */
+
+export {}

package/src/scheduler/drivers/node-cron.ts

@@ -0,0 +1,93 @@
+/**
+ * @softize/opus/scheduler/node-cron — in-process cron scheduler driver.
+ *
+ * Wrappa `node-cron` implementando `SchedulerAdapter`. Roda na mesma
+ * process; suficiente pra monolitos. Pra ambientes distribuídos (múltiplos
+ * pods rodando o mesmo schedule), use o driver `/bullmq` (a vir) ou
+ * `/temporal` que coordenam via Redis/storage.
+ *
+ * Uso:
+ *   import { nodeCronScheduler } from '@softize/opus/scheduler/node-cron'
+ *
+ *   createRuntime({
+ *     scheduler: nodeCronScheduler(),
+ *     // ...
+ *   })
+ */
+
+import { schedule as cronSchedule, type ScheduledTask } from 'node-cron'
+import type {
+  ScheduleDef,
+  SchedulerAdapter,
+  Unsubscribe,
+} from '../../core/index.ts'
+import { everyToCron } from '../every.ts'
+
+export interface NodeCronOptions {
+  /** Nome do adapter. Default 'node-cron'. */
+  name?: string
+
+  /** Override do logger de erros. Default console.error. */
+  onError?: (err: unknown, schedule: ScheduleDef) => void
+}
+
+export function nodeCronScheduler(
+  options: NodeCronOptions = {},
+): SchedulerAdapter {
+  const { name = 'node-cron', onError = defaultOnError } = options
+  const tasks: ScheduledTask[] = []
+
+  return {
+    name,
+    kind: 'scheduler',
+
+    register(spec, fire): Unsubscribe {
+      const cron = resolveCron(spec)
+      const cronOptions: { scheduled: true; timezone?: string } = {
+        scheduled: true,
+      }
+      if (spec.timezone !== undefined) cronOptions.timezone = spec.timezone
+      const task = cronSchedule(
+        cron,
+        () => {
+          // Wrap sync throws + async rejects no mesmo handler
+          void (async () => {
+            try {
+              await fire()
+            } catch (err) {
+              onError(err, spec)
+            }
+          })()
+        },
+        cronOptions,
+      )
+      tasks.push(task)
+      return () => {
+        task.stop()
+        const idx = tasks.indexOf(task)
+        if (idx >= 0) tasks.splice(idx, 1)
+      }
+    },
+
+    async dispose() {
+      for (const task of tasks.splice(0)) task.stop()
+    },
+
+    async healthCheck() {
+      return { ok: true, details: { tasks: tasks.length } }
+    },
+  }
+}
+
+function resolveCron(spec: ScheduleDef): string {
+  if (spec.cron !== undefined) return spec.cron
+  if (spec.every !== undefined) return everyToCron(spec.every)
+  throw new Error(
+    `Schedule "${spec.name}" must declare either 'cron' or 'every'.`,
+  )
+}
+
+function defaultOnError(err: unknown, schedule: ScheduleDef): void {
+  // eslint-disable-next-line no-console
+  console.error(`[tbdlib/scheduler] schedule "${schedule.name}" fire failed:`, err)
+}

package/src/scheduler/every.ts

@@ -0,0 +1,45 @@
+/**
+ * Conversão de `every` shorthand → expressão cron de 5 campos.
+ *
+ * Suporta unidades: 's' (segundo), 'm' (minuto), 'h' (hora).
+ *   - '15s'  → '*\/15 * * * * *' (6-field cron com segundos)
+ *   - '5m'   → '*\/5 * * * *'
+ *   - '1h'   → '0 * * * *'      (toda hora cheia)
+ *   - '6h'   → '0 *\/6 * * *'
+ *   - '1d'   → '0 0 * * *'      (meia-noite)
+ *
+ * Não há "every 3 days" — limita ao que faz sentido em cron.
+ */
+
+export function everyToCron(every: string): string {
+  const match = /^(\d+)(s|m|h|d)$/.exec(every.trim())
+  if (match === null) {
+    throw new Error(
+      `Invalid 'every' shorthand: "${every}". ` +
+        `Expected formato "<n><s|m|h|d>" (ex: "15s", "5m", "1h", "1d").`,
+    )
+  }
+  const n = Number.parseInt(match[1] as string, 10)
+  const unit = match[2] as 's' | 'm' | 'h' | 'd'
+
+  if (n <= 0) {
+    throw new Error(`'every' value must be > 0, got "${every}".`)
+  }
+
+  switch (unit) {
+    case 's':
+      if (n > 59) throw new Error(`'every' seconds must be <= 59, got ${n}.`)
+      return `*/${n} * * * * *`
+    case 'm':
+      if (n > 59) throw new Error(`'every' minutes must be <= 59, got ${n}.`)
+      return `*/${n} * * * *`
+    case 'h':
+      if (n > 23) throw new Error(`'every' hours must be <= 23, got ${n}.`)
+      return n === 1 ? '0 * * * *' : `0 */${n} * * *`
+    case 'd':
+      if (n !== 1) {
+        throw new Error(`'every' days only supports 1d. For longer intervals use cron.`)
+      }
+      return '0 0 * * *'
+  }
+}

package/src/scheduler/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @softize/opus/scheduler — shared helpers/types for scheduler drivers.
+ *
+ * Drivers (node-cron, futuro: bullmq-repeatable, temporal) implementam
+ * SchedulerAdapter do core. Conversões cron ↔ shorthand `every` moram
+ * aqui pra serem reusadas entre drivers.
+ */
+
+export { everyToCron } from './every.ts'