@softize/opus 13.0.0 → 14.0.0

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
   }

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -37,7 +37,10 @@ export interface ActionListDialogProps<TItem, TInput extends Record<string, unkn
   note?: ReactNode
   /** Ação à direita da linha — em geral o botão de criar. */
   actions?: ReactNode
-  emptyText?: string
+  /** Textos dos estados, repassados ao ActionList (e dele ao DataState). */
+  emptyMessage?: string
+  errorMessage?: string
+  retryLabel?: string
   /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto. */
   empty?: (items: TItem[]) => boolean
   /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
@@ -57,7 +60,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
   description,
   note,
   actions,
-  emptyText,
+  emptyMessage,
+  errorMessage,
+  retryLabel,
   empty,
   loading,
   className,
@@ -80,7 +85,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
           <ActionList<TInput, TItem>
             action={action as unknown as ListAction<TInput, TItem>}
             input={(input ?? {}) as TInput}
-            {...(emptyText !== undefined ? { emptyMessage: emptyText } : {})}
+            {...(emptyMessage !== undefined ? { emptyMessage } : {})}
+            {...(errorMessage !== undefined ? { errorMessage } : {})}
+            {...(retryLabel !== undefined ? { retryLabel } : {})}
             {...(empty !== undefined ? { empty } : {})}
             {...(loading !== undefined ? { loading } : {})}
           >

package/src/ui/components/patterns/confirm.tsx

@@ -12,7 +12,7 @@
  *
  * Namespace `dialog` de propósito: `window.alert/confirm/prompt` são globais do browser, e
  * um import esquecido cairia no nativo (cinza, sem tema) sem erro. `window.dialog` não
- * existe — a família fica imune ao footgun. `confirm()` segue exportado como alias.
+ * existe — a família fica imune ao footgun.
  *
  * Por baixo é o <Dialog mode="alert">: `role="alertdialog"`, não fecha no clique fora, foco preso
  * — a semântica que uma interrupção que EXIGE resposta pede. ESC/Cancelar resolve o "não"
@@ -59,16 +59,12 @@ export interface ConfirmOptions extends DialogBase {
   cancel?: string
   /** Contexto do botão de confirmação. */
   context?: Extract<UiContext, 'primary' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: 'default' | 'destructive'
 }
 
 /** `prompt` — uma string livre. Form de verdade (campos, contrato) → ActionFormDialog. */
 export interface PromptOptions extends DialogBase {
   cancel?: string
   context?: Extract<UiContext, 'primary' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: 'default' | 'destructive'
   placeholder?: string
   defaultValue?: string
 }
@@ -107,16 +103,6 @@ function requireHost(fn: string): Error | null {
   )
 }
 
-function rejectAmbiguousContext(
-  fn: string,
-  options: ConfirmOptions | PromptOptions,
-): Error | null {
-  if (options.context === undefined || options.variant === undefined) return null
-  return new Error(
-    `${fn} não permite combinar context com uma variante semântica legada.`,
-  )
-}
-
 function validateChoose<TResult extends string>(options: ChooseOptions<TResult>): Error | null {
   if (options.actions.length === 0) {
     return new Error('dialog.choose() exige pelo menos uma ação.')
@@ -145,8 +131,6 @@ export const dialog = {
   },
   /** Pergunta sim/não. `Promise<boolean>` — fechar/ESC resolve `false`. */
   confirm(options: ConfirmOptions): Promise<boolean> {
-    const ambiguous = rejectAmbiguousContext('dialog.confirm()', options)
-    if (ambiguous !== null) return Promise.reject(ambiguous)
     const err = requireHost('dialog.confirm()')
     if (err !== null) return Promise.reject(err)
     return new Promise<boolean>((resolve) => {
@@ -155,8 +139,6 @@ export const dialog = {
   },
   /** Pede uma string. `Promise<string | null>` — fechar/ESC/Cancelar resolve `null`. */
   prompt(options: PromptOptions): Promise<string | null> {
-    const ambiguous = rejectAmbiguousContext('dialog.prompt()', options)
-    if (ambiguous !== null) return Promise.reject(ambiguous)
     const err = requireHost('dialog.prompt()')
     if (err !== null) return Promise.reject(err)
     return new Promise<string | null>((resolve) => {
@@ -180,11 +162,6 @@ export const dialog = {
   },
 }
 
-/** Alias retrocompatível — `confirm()` é `dialog.confirm()`. */
-export function confirm(options: ConfirmOptions): Promise<boolean> {
-  return dialog.confirm(options)
-}
-
 /**
  * O host — um por app, no shell. Enfileira: uma por vez (duas caixas empilhadas seriam
  * ambíguas sobre qual clique respondeu o quê).
@@ -228,11 +205,8 @@ export function DialogHost(): React.ReactElement {
     else p.resolve(value)
   }
 
-  const variant = current !== undefined && (current.kind === 'confirm' || current.kind === 'prompt')
-    ? current.variant
-    : undefined
   const context = current !== undefined && (current.kind === 'confirm' || current.kind === 'prompt')
-    ? current.context ?? (variant === 'destructive' ? 'danger' : 'primary')
+    ? current.context ?? 'primary'
     : 'primary'
   const defaultAction = current?.kind === 'alert' ? 'OK' : 'Confirmar'
 
@@ -344,6 +318,3 @@ export function DialogHost(): React.ReactElement {
     </Dialog>
   )
 }
-
-/** Alias retrocompatível — `<ConfirmHost />` é `<DialogHost />`. */
-export const ConfirmHost = DialogHost