@softize/opus 8.6.6

package/src/schema/openapi.ts

@@ -0,0 +1,302 @@
+/**
+ * @softize/opus/schema/openapi — OpenAPI 3.1 spec generator.
+ *
+ * Varre lista de `ActionDef` e emite documento OpenAPI completo. Usa
+ * `zod-to-json-schema` pra converter schemas Zod em JSON Schema; consumers
+ * que rodam outro schema lib (ArkType, Valibot) devem passar um converter
+ * próprio via `options.toJsonSchema`.
+ *
+ * Convenção de rota espelha o que `@softize/opus/server` aplica:
+ *   - simple/form → POST /api/{name-com-slashes}
+ *   - search/view → GET /api/{name-com-slashes}
+ *
+ * Endpoints opcionais (/health, /ready, /openapi.json) não são incluídos
+ * — apenas actions registradas viram operations OpenAPI.
+ */
+
+import type { ActionDef, ErrorSpec } from '../core/index.ts'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+// =============================================================================
+// Tipos OpenAPI 3.1 (subset usado)
+// =============================================================================
+
+export interface OpenAPIInfo {
+  title: string
+  version: string
+  description?: string
+}
+
+export interface OpenAPIServer {
+  url: string
+  description?: string
+}
+
+export interface OpenAPISpec {
+  openapi: '3.1.0'
+  info: OpenAPIInfo
+  servers?: OpenAPIServer[]
+  paths: Record<string, Record<string, OpenAPIOperation>>
+  components: { schemas: Record<string, unknown> }
+}
+
+export interface OpenAPIOperation {
+  operationId: string
+  summary?: string
+  description?: string
+  tags?: string[]
+  deprecated?: boolean
+  requestBody?: {
+    required: true
+    content: { 'application/json': { schema: unknown } }
+  }
+  parameters?: Array<{
+    name: string
+    in: 'query'
+    required: boolean
+    schema: unknown
+  }>
+  responses: Record<string, OpenAPIResponse>
+  security?: Array<Record<string, string[]>>
+}
+
+export interface OpenAPIResponse {
+  description: string
+  content?: { 'application/json': { schema: unknown } }
+}
+
+// =============================================================================
+// Options
+// =============================================================================
+
+export interface ToOpenAPIOptions {
+  info: OpenAPIInfo
+  servers?: OpenAPIServer[]
+  apiPrefix?: string
+  /**
+   * Converter custom (caso schemas não sejam Zod). Default usa
+   * `zod-to-json-schema`. Recebe o schema e devolve JSON Schema.
+   */
+  toJsonSchema?: (schema: unknown) => unknown
+}
+
+// =============================================================================
+// Generator
+// =============================================================================
+
+export function toOpenAPISpec(
+  actions: ActionDef[],
+  options: ToOpenAPIOptions,
+): OpenAPISpec {
+  const {
+    info,
+    servers,
+    apiPrefix = '/api',
+    toJsonSchema = defaultToJsonSchema,
+  } = options
+
+  const paths: OpenAPISpec['paths'] = {}
+
+  for (const action of actions) {
+    if (action.internal === true) continue
+    const { path, method } = routeFor(action, apiPrefix)
+    const operation = buildOperation(action, method, toJsonSchema)
+    paths[path] = paths[path] ?? {}
+    paths[path]![method] = operation
+  }
+
+  return {
+    openapi: '3.1.0',
+    info,
+    ...(servers !== undefined && servers.length > 0 ? { servers } : {}),
+    paths,
+    components: { schemas: {} },
+  }
+}
+
+// =============================================================================
+// Internos
+// =============================================================================
+
+function defaultToJsonSchema(schema: unknown): unknown {
+  return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], {
+    target: 'openApi3',
+    $refStrategy: 'none',
+  })
+}
+
+function routeFor(
+  action: ActionDef,
+  apiPrefix: string,
+): { path: string; method: 'get' | 'post' } {
+  const segments = action.name.split('.').map(encodeURIComponent)
+  const path = `${apiPrefix}/${segments.join('/')}`
+  const method = action.kind === 'simple' || action.kind === 'form' ? 'post' : 'get'
+  return { path, method }
+}
+
+function buildOperation(
+  action: ActionDef,
+  method: 'get' | 'post',
+  toJsonSchema: (s: unknown) => unknown,
+): OpenAPIOperation {
+  const op: OpenAPIOperation = {
+    operationId: action.name,
+    responses: buildResponses(action, toJsonSchema),
+  }
+
+  if (action.summary !== undefined) op.summary = action.summary
+  if (action.description !== undefined) op.description = action.description
+  if (action.tags !== undefined && action.tags.length > 0) op.tags = action.tags
+
+  const inputSchema = toJsonSchema(action.input)
+
+  if (method === 'post') {
+    op.requestBody = {
+      required: true,
+      content: { 'application/json': { schema: inputSchema } },
+    }
+  } else {
+    const params = buildQueryParams(inputSchema)
+    if (params.length > 0) op.parameters = params
+  }
+
+  if (action.public !== true) {
+    op.security = [{ bearerAuth: [] }]
+  }
+
+  return op
+}
+
+function buildResponses(
+  action: ActionDef,
+  toJsonSchema: (s: unknown) => unknown,
+): Record<string, OpenAPIResponse> {
+  const successStatus = String(action.successStatus ?? 200)
+  const responses: Record<string, OpenAPIResponse> = {
+    [successStatus]: {
+      description: 'Success',
+      content: {
+        'application/json': {
+          schema: wrapEnvelope(toJsonSchema(action.output), action.kind),
+        },
+      },
+    },
+    '4XX': errorResponse('Client error', action.errors),
+    '5XX': errorResponse('Server error'),
+  }
+  return responses
+}
+
+function wrapEnvelope(outputSchema: unknown, kind: ActionDef['kind']): unknown {
+  // Search retorna Paginated<Output>; outros kinds retornam Output direto.
+  const data =
+    kind === 'list'
+      ? {
+          type: 'object',
+          properties: {
+            items: { type: 'array', items: outputSchema },
+            cursor: {
+              type: 'object',
+              properties: {
+                next: { type: ['string', 'null'] },
+                prev: { type: ['string', 'null'] },
+              },
+              required: ['next'],
+            },
+            total: { type: 'integer' },
+          },
+          required: ['items', 'cursor'],
+        }
+      : outputSchema
+
+  return {
+    type: 'object',
+    properties: {
+      ok: { const: true },
+      data,
+      meta: metaSchema(),
+    },
+    required: ['ok', 'data', 'meta'],
+  }
+}
+
+function errorResponse(description: string, errors?: ErrorSpec[]): OpenAPIResponse {
+  const errorCodes =
+    errors !== undefined && errors.length > 0
+      ? { enum: errors.map((e) => e.code) }
+      : { type: 'string' }
+
+  return {
+    description,
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            ok: { const: false },
+            error: {
+              type: 'object',
+              properties: {
+                code: errorCodes,
+                category: { type: 'string' },
+                message: { type: 'string' },
+                severity: { enum: ['warning', 'error', 'fatal'] },
+                retriable: { type: 'boolean' },
+              },
+              required: ['code', 'category', 'message', 'severity', 'retriable'],
+            },
+            meta: metaSchema(),
+          },
+          required: ['ok', 'error', 'meta'],
+        },
+      },
+    },
+  }
+}
+
+function metaSchema(): unknown {
+  return {
+    type: 'object',
+    properties: {
+      actionId: { type: 'string' },
+      action: { type: 'string' },
+      durationMs: { type: 'number' },
+      requestId: { type: 'string' },
+      cached: { type: 'boolean' },
+    },
+    required: ['actionId', 'action', 'durationMs'],
+  }
+}
+
+interface QueryParam {
+  name: string
+  in: 'query'
+  required: boolean
+  schema: unknown
+}
+
+function buildQueryParams(inputSchema: unknown): QueryParam[] {
+  // Flatten top-level object properties em query params individuais.
+  if (
+    typeof inputSchema !== 'object' ||
+    inputSchema === null ||
+    !('properties' in inputSchema) ||
+    typeof (inputSchema as { properties: unknown }).properties !== 'object'
+  ) {
+    return []
+  }
+
+  const props = (inputSchema as { properties: Record<string, unknown> }).properties
+  const requiredRaw = (inputSchema as { required?: unknown }).required
+  const required = new Set<string>(
+    Array.isArray(requiredRaw) ? (requiredRaw as string[]) : [],
+  )
+
+  return Object.entries(props).map(([name, schema]) => ({
+    name,
+    in: 'query' as const,
+    required: required.has(name),
+    schema,
+  }))
+}

package/src/schema/scaffold.ts

@@ -0,0 +1,160 @@
+/**
+ * @softize/opus/schema — scaffold de migration a partir do diff entidade↔banco.
+ *
+ * Puro: recebe entidades + `DriftFinding[]` (do drift-check) e emite o **código**
+ * de uma migration Kysely (`up`/`down`) como string. Não toca banco nem fs.
+ *
+ * Filosofia (ver `docs/data-layer.md`): best-effort, **humano revisa**.
+ *   - `missing_table`  → `createTable` completo / `dropTable`  (caso limpo, gerado)
+ *   - `missing_column` → `addColumn` / `dropColumn`            (caso limpo, gerado)
+ *   - `nullable_mismatch` / `extra_column` → vira **nota `// TODO`**, nunca um
+ *     ALTER/DROP automático (arriscado, dialect-específico).
+ */
+
+import {
+  entityColumns,
+  entityTable,
+  type DriftFinding,
+  type EntityConfig,
+  type ResolvedColumn,
+} from './entity.ts'
+
+// =============================================================================
+// logicalType → tipo de coluna Kysely (Postgres-leaning)
+// =============================================================================
+
+const SQL_TYPE: Record<string, string> = {
+  uuid: 'uuid',
+  int: 'integer',
+  bigint: 'bigint',
+  money: 'bigint',
+  decimal: 'numeric',
+  boolean: 'boolean',
+  datetime: 'timestamptz',
+  date: 'date',
+  json: 'jsonb',
+  string: 'text',
+  text: 'text',
+  email: 'text',
+  phone: 'text',
+  url: 'text',
+  slug: 'text',
+  currency: 'text',
+  country: 'text',
+  locale: 'text',
+  markdown: 'text',
+  html: 'text',
+  timezone: 'text',
+  time: 'text',
+  duration: 'text',
+  enum: 'text',
+}
+
+/** Tipo de coluna Kysely pro tipo lógico. Fallback `text`. */
+export function kyselyColumnType(logicalType: string | undefined): string {
+  if (logicalType === undefined) return 'text'
+  return SQL_TYPE[logicalType] ?? 'text'
+}
+
+// =============================================================================
+// Scaffold
+// =============================================================================
+
+export interface ScaffoldResult {
+  up: string
+  down: string
+  /** Divergências que exigem revisão humana (não geradas automaticamente). */
+  notes: string[]
+  /** Quantidade de statements gerados automaticamente. */
+  statements: number
+}
+
+function columnLine(col: ResolvedColumn): string {
+  const type = kyselyColumnType(col.logicalType)
+  const mods: string[] = []
+  if (col.column.pk === true) {
+    mods.push('primaryKey()', 'notNull()')
+  } else if (col.column.nullable !== true) {
+    mods.push('notNull()')
+  }
+  const builder = mods.length > 0 ? `, (c) => c.${mods.join('.')}` : ''
+  return `    .addColumn('${col.name}', '${type}'${builder})`
+}
+
+/**
+ * Gera o corpo de uma migration a partir do diff. Retorna `null` se não há nada
+ * a fazer (sem statements e sem notas).
+ */
+export function scaffoldMigration(
+  entities: EntityConfig[],
+  findings: DriftFinding[],
+): ScaffoldResult | null {
+  const byTable = new Map<string, DriftFinding[]>()
+  for (const f of findings) {
+    const list = byTable.get(f.table) ?? []
+    list.push(f)
+    byTable.set(f.table, list)
+  }
+
+  const up: string[] = []
+  const down: string[] = []
+  const notes: string[] = []
+  let statements = 0
+
+  for (const entity of entities) {
+    const table = entityTable(entity)
+    const list = byTable.get(table)
+    if (list === undefined) continue
+    const cols = entityColumns(entity)
+
+    if (list.some((f) => f.kind === 'missing_table')) {
+      const lines = cols.map(columnLine).join('\n')
+      up.push(`  await db.schema.createTable('${table}')\n${lines}\n    .execute()`)
+      down.push(`  await db.schema.dropTable('${table}').execute()`)
+      statements++
+      continue
+    }
+
+    const missing = new Set(
+      list.filter((f) => f.kind === 'missing_column').map((f) => f.column),
+    )
+    for (const col of cols) {
+      if (missing.has(col.name)) {
+        up.push(`  await db.schema.alterTable('${table}')\n${columnLine(col)}\n    .execute()`)
+        down.push(
+          `  await db.schema.alterTable('${table}').dropColumn('${col.name}').execute()`,
+        )
+        statements++
+      }
+    }
+
+    for (const f of list) {
+      if (f.kind === 'nullable_mismatch' || f.kind === 'extra_column') {
+        notes.push(`${f.table}.${f.column ?? ''}: ${f.kind} — ${f.message}`)
+      }
+    }
+  }
+
+  if (statements === 0 && notes.length === 0) return null
+  return { up: up.join('\n\n'), down: down.join('\n\n'), notes, statements }
+}
+
+/** Monta o arquivo `.ts` completo (imports + up/down) a partir do resultado. */
+export function scaffoldFileContent(result: ScaffoldResult): string {
+  const todo =
+    result.notes.length > 0
+      ? `\n  // TODO (revisar à mão — arriscado/dialect-específico, não gerado):\n` +
+        result.notes.map((n) => `  //   - ${n}`).join('\n') +
+        '\n'
+      : ''
+  return `import type { Kysely } from 'kysely'
+
+export async function up(db: Kysely<any>): Promise<void> {
+${result.up}${todo}
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+${result.down}
+}
+`
+}

package/src/server/drivers/fastify.ts

@@ -0,0 +1,224 @@
+/**
+ * @softize/opus/server/fastify — Fastify driver
+ *
+ * Implementa `ServerAdapter` em cima do Fastify 5.x. Auto-monta actions
+ * como rotas REST, expõe endpoints opcionais (/health, /ready, ...),
+ * resolve contexto via AuthAdapter, mapeia errors → HTTP status.
+ *
+ * Uso:
+ *   import Fastify from 'fastify'
+ *   import { createRuntime } from '@softize/opus/core'
+ *   import { fastifyServer } from '@softize/opus/server/fastify'
+ *
+ *   const app = Fastify()
+ *   const runtime = createRuntime({
+ *     server: fastifyServer({ app }),
+ *     auth: ...,
+ *   })
+ *   runtime.register([...])
+ *   await runtime.start()
+ *   await app.listen({ port: 3000 })
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import type {
+  ActionDef,
+  ContextBase,
+  EndpointSpec,
+  RuntimeRef,
+  ServerAdapter,
+} from '../../core/index.ts'
+import {
+  toOpenAPISpec,
+  type OpenAPIInfo,
+  type OpenAPIServer,
+} from '../../schema/openapi.ts'
+import {
+  httpStatusFor,
+  inputSourceFor,
+  methodFor,
+  pathFor,
+  serializeResult,
+  shouldMountPublicly,
+  successStatusFor,
+} from '../index.ts'
+
+// =============================================================================
+// Options
+// =============================================================================
+
+export interface FastifyServerOptions {
+  /** Instância Fastify onde rotas serão registradas. */
+  app: FastifyInstance
+
+  /** Prefixo do path. Default '/api'. */
+  apiPrefix?: string
+
+  /**
+   * Info do OpenAPI document (title, version, description). Quando ausente,
+   * usa um default genérico — sobrescreva pra publicar API decente.
+   */
+  openapiInfo?: OpenAPIInfo
+
+  /** Servers do OpenAPI document. */
+  openapiServers?: OpenAPIServer[]
+}
+
+// =============================================================================
+// Adapter factory
+// =============================================================================
+
+export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
+  const {
+    app,
+    apiPrefix = '/api',
+    openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
+    openapiServers,
+  } = options
+  let runtime: RuntimeRef | undefined
+  const mountedActions: ActionDef[] = []
+
+  const requireRuntime = (): RuntimeRef => {
+    /* v8 ignore next 3 — defensivo; init() é sempre chamado antes de mount/etc */
+    if (runtime === undefined) {
+      throw new Error('fastifyServer: runtime not initialized (init not called)')
+    }
+    return runtime
+  }
+
+  return {
+    name: 'fastify',
+    kind: 'server',
+
+    init(rt) {
+      runtime = rt
+    },
+
+    mount(action) {
+      if (!shouldMountPublicly(action)) return
+      mountedActions.push(action)
+
+      const method = methodFor(action)
+      const path = pathFor(action, apiPrefix)
+      const source = inputSourceFor(action)
+
+      const handler = async (req: FastifyRequest, reply: FastifyReply) => {
+        const rt = requireRuntime()
+        const ctx = await resolveCtx(rt, req)
+        const input = source === 'body' ? req.body : req.query
+
+        const result = await rt.execute(action.name, input, ctx)
+        const status = result.ok
+          ? successStatusFor(action)
+          : httpStatusFor(result.error)
+
+        reply.code(status).send(serializeResult(result))
+      }
+
+      if (method === 'POST') app.post(path, handler)
+      else app.get(path, handler)
+    },
+
+    mountEndpoints(spec) {
+      mountHealth(app, spec)
+      mountReady(app, spec, requireRuntime)
+      mountOpenAPI(app, spec, mountedActions, {
+        info: openapiInfo,
+        ...(openapiServers !== undefined ? { servers: openapiServers } : {}),
+        apiPrefix,
+      })
+    },
+  }
+}
+
+// =============================================================================
+// Context resolution
+// =============================================================================
+
+async function resolveCtx(
+  rt: RuntimeRef,
+  req: FastifyRequest,
+): Promise<ContextBase> {
+  const base = await resolveAuthBase(rt, req)
+  // Fastify sempre popula req.id (auto-gen ou via genReqId opt). Não é optional.
+  return {
+    ...base,
+    requestId: req.id,
+    provenance: {
+      kind: 'http',
+      userId: base.user?.id ?? null,
+      requestId: req.id,
+    },
+  }
+}
+
+async function resolveAuthBase(
+  rt: RuntimeRef,
+  req: FastifyRequest,
+): Promise<{ user: ContextBase['user']; tenantId: string | null; can: ContextBase['can'] }> {
+  if (rt.auth === undefined) {
+    return { user: null, tenantId: null, can: () => false }
+  }
+  const resolved = await rt.auth.resolveContext(req)
+  return {
+    user: resolved.user,
+    tenantId: resolved.tenantId ?? null,
+    can: resolved.can,
+  }
+}
+
+// =============================================================================
+// Endpoints
+// =============================================================================
+
+function mountHealth(app: FastifyInstance, spec: EndpointSpec): void {
+  const cfg = spec.health
+  if (cfg === false) return
+  const path = pathFromSpec(cfg, '/health')
+  app.get(path, async () => ({ ok: true }))
+}
+
+function mountReady(
+  app: FastifyInstance,
+  spec: EndpointSpec,
+  getRuntime: () => RuntimeRef,
+): void {
+  const cfg = spec.ready
+  if (cfg === false) return
+  const path = pathFromSpec(cfg, '/ready')
+  app.get(path, async (_req, reply) => {
+    const status = await getRuntime().healthCheck()
+    reply.code(status.ok ? 200 : 503).send(status)
+  })
+}
+
+function pathFromSpec(
+  cfg: boolean | { path?: string } | undefined,
+  fallback: string,
+): string {
+  if (typeof cfg === 'object' && cfg.path !== undefined) return cfg.path
+  return fallback
+}
+
+function mountOpenAPI(
+  app: FastifyInstance,
+  spec: EndpointSpec,
+  actions: ActionDef[],
+  options: {
+    info: OpenAPIInfo
+    servers?: OpenAPIServer[]
+    apiPrefix: string
+  },
+): void {
+  const cfg = spec.openapi
+  if (cfg === false) return
+  const path =
+    typeof cfg === 'object' && cfg.path !== undefined ? cfg.path : '/openapi.json'
+  app.get(path, async () =>
+    toOpenAPISpec(actions, {
+      info: options.info,
+      ...(options.servers !== undefined ? { servers: options.servers } : {}),
+      apiPrefix: options.apiPrefix,
+    }),
+  )
+}