@softize/opus 12.11.0 → 13.1.0

package/src/dsl/loads.ts

@@ -31,7 +31,7 @@ export function parseLoad(src: string): LoadSpec {
   const trimmed = src.trim()
   const m = LOAD_RE.exec(trimmed)
   if (m === null) {
-    throw new Error(`DSL loads: invalid syntax '${src}'`)
+    throw new Error(`DSL loads: sintaxe inválida '${src}'`)
   }
   const entity = m[1]!
   const argsRaw = m[2]!.trim()

package/src/dsl/parser.ts

@@ -89,7 +89,7 @@ function tokenize(src: string): Token[] {
         }
       }
       if (i >= src.length) {
-        throw new Error(`DSL parse error: unterminated string at ${startPos}`)
+        throw new Error(`DSL parse: string não terminada na posição ${startPos}`)
       }
       i += 1 // skip closing quote
       tokens.push({ type: 'STRING', value: val, pos: startPos })
@@ -150,7 +150,7 @@ function tokenize(src: string): Token[] {
     }
 
     throw new Error(
-      `DSL parse error: unexpected character '${c}' at position ${i}`,
+      `DSL parse: caractere inesperado '${c}' na posição ${i}`,
     )
   }
   tokens.push({ type: 'EOF', value: '', pos: src.length })
@@ -184,7 +184,7 @@ class Parser {
     if (!this.match(type, value)) {
       const t = this.peek()
       throw new Error(
-        `DSL parse error: expected ${value ?? type}, got '${t.value}' at ${t.pos}`,
+        `DSL parse: esperado ${value ?? type}, recebido '${t.value}' na posição ${t.pos}`,
       )
     }
     return this.consume()
@@ -343,7 +343,7 @@ class Parser {
       const t = this.consume()
       const n = Number(t.value)
       if (Number.isNaN(n)) {
-        throw new Error(`DSL parse error: invalid number '${t.value}'`)
+        throw new Error(`DSL parse: número inválido '${t.value}'`)
       }
       return { kind: 'literal', value: n }
     }
@@ -409,7 +409,7 @@ class Parser {
     }
     const t = this.peek()
     throw new Error(
-      `DSL parse error: unexpected token '${t.value}' at ${t.pos}`,
+      `DSL parse: token inesperado '${t.value}' na posição ${t.pos}`,
     )
   }
 }

package/src/events/drivers/mitt.ts

@@ -39,6 +39,7 @@ export interface MittEventsOptions {
  */
 type EventMap = Record<string, DomainEvent>
 
+/** EventBusAdapter in-process baseado em `mitt`; entrega no mesmo processo, sem persistência. */
 export function mittEvents(options: MittEventsOptions = {}): EventBusAdapter {
   const { name = 'mitt' } = options
   const emitter: Emitter<EventMap> = mitt<EventMap>()

package/src/mcp/index.ts

@@ -13,6 +13,7 @@ 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'
+import { readPackageVersion } from '../core/package-version.ts'
 
 export interface OpusMcpOptions {
   name?: string
@@ -36,7 +37,7 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
     opts.toJsonSchema ?? ((schema: unknown) => zodToJsonSchema(schema as never, { $refStrategy: 'none' }))
 
   const server = new Server(
-    { name: opts.name ?? 'opus', version: opts.version ?? '0.0.0' },
+    { name: opts.name ?? 'opus', version: opts.version ?? readPackageVersion() },
     { capabilities: { tools: {} } },
   )
 

package/src/observability/drivers/opentelemetry.ts

@@ -40,6 +40,7 @@ export interface OpenTelemetryObservabilityOptions {
   healthCheck?: () => Promise<HealthStatus> | HealthStatus
 }
 
+/** ObservabilityAdapter que abre um span OpenTelemetry por action/reaction e propaga o trace context. */
 export function openTelemetryObservability(
   options: OpenTelemetryObservabilityOptions = {},
 ): ObservabilityAdapter {

package/src/queue/drivers/bullmq.ts

@@ -13,7 +13,7 @@
  *   import { Queue } from 'bullmq'
  *   import { bullmqQueue } from '@softize/opus/queue/bullmq'
  *
- *   const queue = new Queue('tbdlib-jobs', { connection: redisOpts })
+ *   const queue = new Queue('opus-jobs', { connection: redisOpts })
  *   createRuntime({ queue: bullmqQueue({ queue }) })
  */
 
@@ -139,9 +139,9 @@ function bullmqOptions(spec: JobSpec): BullMQAddOptions {
 // =============================================================================
 
 /**
- * BullMQ state → tbdlib JobStatus.
+ * BullMQ state → Opus JobStatus.
  *
- * tbdlib não tem 'paused' nem 'delayed' separados — todos viram 'queued'.
+ * O Opus 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 {

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

@@ -31,6 +31,7 @@ export interface NodeCronOptions {
   onError?: (err: unknown, schedule: ScheduleDef) => void
 }
 
+/** SchedulerAdapter sobre `node-cron`; aceita `cron` ou o atalho `every` de cada schedule. */
 export function nodeCronScheduler(
   options: NodeCronOptions = {},
 ): SchedulerAdapter {
@@ -83,11 +84,11 @@ 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'.`,
+    `O schedule "${spec.name}" precisa declarar 'cron' ou 'every'.`,
   )
 }
 
 function defaultOnError(err: unknown, schedule: ScheduleDef): void {
   // eslint-disable-next-line no-console
-  console.error(`[tbdlib/scheduler] schedule "${schedule.name}" fire failed:`, err)
+  console.error(`[opus/scheduler] falha ao disparar o schedule "${schedule.name}":`, err)
 }

package/src/scheduler/every.ts

@@ -15,30 +15,30 @@ 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").`,
+      `Atalho 'every' inválido: "${every}". ` +
+        `Formato esperado "<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}".`)
+    throw new Error(`O valor de 'every' precisa ser maior que 0; recebido "${every}".`)
   }
 
   switch (unit) {
     case 's':
-      if (n > 59) throw new Error(`'every' seconds must be <= 59, got ${n}.`)
+      if (n > 59) throw new Error(`Segundos em 'every' precisam ser no máximo 59; recebido ${n}.`)
       return `*/${n} * * * * *`
     case 'm':
-      if (n > 59) throw new Error(`'every' minutes must be <= 59, got ${n}.`)
+      if (n > 59) throw new Error(`Minutos em 'every' precisam ser no máximo 59; recebido ${n}.`)
       return `*/${n} * * * *`
     case 'h':
-      if (n > 23) throw new Error(`'every' hours must be <= 23, got ${n}.`)
+      if (n > 23) throw new Error(`Horas em 'every' precisam ser no máximo 23; recebido ${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.`)
+        throw new Error(`Dias em 'every' aceitam somente 1d. Para intervalos maiores, use cron.`)
       }
       return '0 0 * * *'
   }

package/src/schema/openapi.ts

@@ -175,15 +175,15 @@ function buildResponses(
   const successStatus = String(action.successStatus ?? 200)
   const responses: Record<string, OpenAPIResponse> = {
     [successStatus]: {
-      description: 'Success',
+      description: 'Sucesso',
       content: {
         'application/json': {
           schema: wrapEnvelope(toJsonSchema(action.output), action.kind),
         },
       },
     },
-    '4XX': errorResponse('Client error', action.errors),
-    '5XX': errorResponse('Server error'),
+    '4XX': errorResponse('Erro do cliente', action.errors),
+    '5XX': errorResponse('Erro do servidor'),
   }
   return responses
 }

package/src/seed/index.ts

@@ -5,6 +5,7 @@
  * implementação server-only que a CLI carrega pelo `opus.config.ts`.
  */
 
+/** Variante de dados que um seed sabe aplicar (ex.: `minimal`, `demo`). */
 export interface SeedProfile {
   /** Situação que este perfil representa para quem vai aplicá-lo. */
   description: string
@@ -12,13 +13,16 @@ export interface SeedProfile {
   expected?: Readonly<Record<string, number>>
 }
 
+/** Limites de onde o seed pode rodar. */
 export interface SeedSafety {
   /** Escopos de dados em que o seed pode abrir conexão. */
   scopes: readonly SeedScope[]
 }
 
+/** Escopos de banco em que seeds podem abrir conexão; nunca produção. */
 export type SeedScope = 'local' | 'test' | 'isolated-preview'
 
+/** Declaração pura de um seed — o que `defineSeed` valida e o manifesto publica. */
 export interface SeedDefinition {
   /** Identidade estável, em segmentos lowercase separados por ponto. */
   name: string
@@ -31,12 +35,14 @@ export interface SeedDefinition {
   safety: SeedSafety
 }
 
+/** Contexto entregue a `plan`, `apply` e `verify` do binding. */
 export interface SeedContext<Database = unknown> {
   database: Database | null
   profile: string
   scope: SeedScope
 }
 
+/** Contexto da asserção de alvo, executada antes de qualquer binding. */
 export interface SeedTargetContext<Database = unknown> {
   database: Database | null
   scope: SeedScope
@@ -50,28 +56,34 @@ export type SeedTargetAssertion<Database = unknown> = (
   context: SeedTargetContext<Database>,
 ) => boolean | Promise<boolean>
 
+/** Resultado de `plan`: o que a aplicação faria, sem tocar o banco. */
 export interface SeedPlan {
   summary: string
   operations: readonly string[]
 }
 
+/** Resultado de `apply` e `verify`: resumo e métricas observadas. */
 export interface SeedReport {
   summary: string
   metrics: Readonly<Record<string, number>>
 }
 
+/** Implementação server-only de um seed, ligada à declaração por `bindSeed`. */
 export interface SeedBinding<Database = unknown> {
   plan(context: SeedContext<Database>): SeedPlan | Promise<SeedPlan>
   apply(context: SeedContext<Database>): SeedReport | Promise<SeedReport>
   verify(context: SeedContext<Database>): SeedReport | Promise<SeedReport>
 }
 
+/** Seed com declaração e binding — a forma que o registro em `opus.config.ts` consome. */
 export interface BoundSeed<Database = unknown> extends SeedDefinition {
   readonly binding: SeedBinding<Database>
 }
 
+/** Item aceito no registro; declaração sem binding é diagnosticada como `seed.unbound`. */
 export type SeedRegistryItem = SeedDefinition | BoundSeed
 
+/** Problema encontrado ao verificar o registro de seeds. */
 export interface SeedDiagnostic {
   code:
     | 'seed.duplicate'
@@ -82,6 +94,7 @@ export interface SeedDiagnostic {
   seed: string
 }
 
+/** Resultado de `checkSeedRegistry`. */
 export interface SeedRegistryCheck {
   ok: boolean
   diagnostics: readonly SeedDiagnostic[]
@@ -94,6 +107,7 @@ const PROFILE_RE = /^[a-z][a-z0-9-]*$/
 const SCOPE_RE = /^[a-z][a-z0-9-]*$/
 const SEED_SCOPES = new Set<SeedScope>(['local', 'test', 'isolated-preview'])
 
+/** Valida e devolve a declaração de um seed, preservando o tipo literal. Lança em declaração inválida. */
 export function defineSeed<const Definition extends SeedDefinition>(
   definition: Definition,
 ): Definition {
@@ -129,6 +143,7 @@ export function publicSeedDefinition(seed: SeedDefinition): SeedDefinition {
   }
 }
 
+/** Liga a implementação server-only (`plan`, `apply`, `verify`) a uma declaração validada. */
 export function bindSeed<Database = unknown>(
   definition: SeedDefinition,
   binding: SeedBinding<Database>,
@@ -138,6 +153,7 @@ export function bindSeed<Database = unknown>(
   return { ...definition, binding }
 }
 
+/** Type guard: `true` se o valor é uma declaração de seed válida. */
 export function isSeedDefinition(value: unknown): value is SeedDefinition {
   try {
     validateDefinition(value)
@@ -147,6 +163,7 @@ export function isSeedDefinition(value: unknown): value is SeedDefinition {
   }
 }
 
+/** Type guard: `true` se o valor é um seed declarado e com binding completo. */
 export function isBoundSeed(value: unknown): value is BoundSeed {
   if (!isSeedDefinition(value)) return false
   try {
@@ -157,6 +174,10 @@ export function isBoundSeed(value: unknown): value is BoundSeed {
   }
 }
 
+/**
+ * Verifica o registro de seeds: duplicidade, binding ausente, dependência
+ * inexistente e ciclo. Devolve a ordem topológica quando não há ciclo.
+ */
 export function checkSeedRegistry(items: readonly SeedRegistryItem[]): SeedRegistryCheck {
   const diagnostics: SeedDiagnostic[] = []
   const byName = new Map<string, BoundSeed>()
@@ -237,6 +258,7 @@ export function checkSeedRegistry(items: readonly SeedRegistryItem[]): SeedRegis
   }
 }
 
+/** Resolve o perfil a aplicar (`requested` ou `defaultProfile`); lança se não existir no seed. */
 export function resolveSeedProfile(seed: SeedDefinition, requested?: string): string {
   const profile = requested ?? seed.defaultProfile
   if (!Object.hasOwn(seed.profiles, profile)) {
@@ -247,6 +269,10 @@ export function resolveSeedProfile(seed: SeedDefinition, requested?: string): st
   return profile
 }
 
+/**
+ * Falha fechado antes de abrir conexão: exige `NODE_ENV` de desenvolvimento ou
+ * teste, escopo informado e permitido por `safety.scopes`.
+ */
 export function assertSeedExecutionAllowed(
   seed: SeedDefinition,
   scope: string | undefined,
@@ -274,6 +300,7 @@ function runtimeNodeEnvironment(): string | undefined {
   ).process?.env?.NODE_ENV
 }
 
+/** Garante que o retorno de `plan` tem a forma `{ summary, operations }`. */
 export function validateSeedPlan(value: unknown): SeedPlan {
   if (!isRecord(value) || !isNonEmptyString(value.summary) || !Array.isArray(value.operations)) {
     throw new Error('plan precisa retornar { summary, operations }')
@@ -284,6 +311,7 @@ export function validateSeedPlan(value: unknown): SeedPlan {
   return value as unknown as SeedPlan
 }
 
+/** Garante que o retorno de `apply`/`verify` tem a forma `{ summary, metrics }` com números finitos. */
 export function validateSeedReport(value: unknown): SeedReport {
   if (!isRecord(value) || !isNonEmptyString(value.summary) || !isMetrics(value.metrics)) {
     throw new Error('apply/verify precisa retornar { summary, metrics } com valores numéricos finitos')
@@ -291,6 +319,7 @@ export function validateSeedReport(value: unknown): SeedReport {
   return value as unknown as SeedReport
 }
 
+/** Compara as métricas do relatório com `profiles[profile].expected`; lança listando as divergências. */
 export function assertSeedExpectedMetrics(
   seed: SeedDefinition,
   profile: string,

package/src/server/drivers/fastify.ts

@@ -28,6 +28,7 @@ import type {
   RuntimeRef,
   ServerAdapter,
 } from '../../core/index.ts'
+import { readPackageVersion } from '../../core/package-version.ts'
 import {
   toOpenAPISpec,
   type OpenAPIInfo,
@@ -58,7 +59,8 @@ export interface FastifyServerOptions {
 
   /**
    * Info do OpenAPI document (title, version, description). Quando ausente,
-   * usa um default genérico — sobrescreva pra publicar API decente.
+   * usa `{ title: 'Opus API', version: <versão do SDK> }` — sobrescreva pra
+   * publicar a identidade da sua API.
    */
   openapiInfo?: OpenAPIInfo
 
@@ -73,11 +75,12 @@ export interface FastifyServerOptions {
 // Adapter factory
 // =============================================================================
 
+/** ServerAdapter que monta as actions como rotas numa instância Fastify existente. */
 export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
   const {
     app,
     apiPrefix = '/api',
-    openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
+    openapiInfo = { title: 'Opus API', version: readPackageVersion() },
     openapiServers,
     traceContext = false,
   } = options

package/src/server/drivers/node.ts

@@ -34,7 +34,8 @@ import type {
   RuntimeRef,
   ServerAdapter,
 } from '../../core/index.ts'
-import { error } from '../../core/index.ts'
+import { error, UNHANDLED_ERROR_MESSAGE } from '../../core/index.ts'
+import { readPackageVersion } from '../../core/package-version.ts'
 import {
   toOpenAPISpec,
   type OpenAPIInfo,
@@ -68,7 +69,8 @@ export interface NodeServerOptions {
 
   /**
    * Info do OpenAPI document (title, version, description). Quando ausente,
-   * usa um default genérico — sobrescreva pra publicar API decente.
+   * usa `{ title: 'Opus API', version: <versão do SDK> }` — sobrescreva pra
+   * publicar a identidade da sua API.
    */
   openapiInfo?: OpenAPIInfo
 
@@ -97,11 +99,12 @@ export interface NodeServerHandle {
 
 type RouteFn = (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<void>
 
+/** ServerAdapter sobre `node:http` puro, sem framework; expõe `handler` pra plugar em qualquer servidor. */
 export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
   const {
     apiPrefix = '/api',
     endpoints,
-    openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
+    openapiInfo = { title: 'Opus API', version: readPackageVersion() },
     openapiServers,
     traceContext = false,
   } = options
@@ -164,7 +167,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
                 res,
                 400,
                 driverResult(
-                  { code: 'server.invalid_json', category: 'validation', message: 'Request body is not valid JSON' },
+                  { code: 'server.invalid_json', category: 'validation', message: 'O corpo da requisição não é um JSON válido' },
                   action.name,
                   requestId,
                 ),
@@ -205,7 +208,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
           res,
           500,
           driverResult(
-            { code: 'server.unhandled', category: 'internal', message: String(err) },
+            { code: 'server.unhandled', category: 'internal', message: UNHANDLED_ERROR_MESSAGE, cause: String(err) },
             deriveActionName(url.pathname, apiPrefix),
             crypto.randomUUID(),
           ),
@@ -319,7 +322,7 @@ function driverResult(
 
 function routeNotFound(pathname: string, apiPrefix: string): ActionResult<never> {
   return driverResult(
-    { code: 'server.route_not_found', category: 'not_found', message: `No route for ${pathname}` },
+    { code: 'server.route_not_found', category: 'not_found', message: `Rota não encontrada: ${pathname}` },
     deriveActionName(pathname, apiPrefix),
     crypto.randomUUID(),
   )

package/src/server/index.ts

@@ -181,7 +181,9 @@ function serializeError(err: ActionError): Record<string, unknown> {
   if (err.i18nParams !== undefined) out.i18nParams = err.i18nParams
   if (err.field !== undefined) out.field = err.field
   if (err.issues !== undefined) out.issues = err.issues
-  if (err.cause !== undefined) out.cause = String(err.cause)
+  // Erro interno não leva `cause` para a wire: é o texto cru da exceção (driver, SQL), que
+  // pertence ao log do servidor, não à pessoa nem ao cliente.
+  if (err.cause !== undefined && err.category !== 'internal') out.cause = String(err.cause)
   if (err.meta !== undefined) out.meta = err.meta
   return out
 }

package/src/storage/drivers/fs.ts

@@ -29,6 +29,7 @@ function metaPathOf(filePath: string): string {
   return `${filePath}.meta.json`
 }
 
+/** StorageAdapter que grava objetos no sistema de arquivos local, com metadados em `<arquivo>.meta.json`. */
 export function fsStorage(options: FsStorageOptions): StorageAdapter {
   const root = path.resolve(options.root)
   const baseUrl = options.baseUrl?.replace(/\/+$/, '')

package/src/testing/index.ts

@@ -250,7 +250,7 @@ async function validate<T>(
   throw error({
     code: kind === 'input' ? 'validation.invalid_input' : 'validation.invalid_output',
     category: kind === 'input' ? 'validation' : 'internal',
-    message: kind === 'input' ? 'Input validation failed' : 'Output validation failed (dev)',
+    message: kind === 'input' ? 'Dados de entrada inválidos' : 'Dados de saída inválidos (validação em dev)',
     issues: result.issues.map((iss) => ({
       path: (iss.path ?? []).join('.'),
       code: 'invalid',
@@ -294,7 +294,7 @@ export async function runAction<In, Out, ParsedIn = In>(
     throw error({
       code: 'auth.unauthenticated',
       category: 'authentication',
-      message: 'Authentication required',
+      message: 'Autenticação necessária',
     })
   }
 
@@ -305,7 +305,7 @@ export async function runAction<In, Out, ParsedIn = In>(
         ? Boolean(evalExpression(parseExpression(spec), { user: ctx.user, input: parsed, ctx, ...(loaded ?? {}) }))
         : await spec(ctx, parsed, loaded)
     if (decision === false) {
-      throw error({ code: 'auth.forbidden', category: 'authorization', message: 'Forbidden' })
+      throw error({ code: 'auth.forbidden', category: 'authorization', message: 'Acesso negado' })
     }
     if (decision !== true) throw decision
   }