Opus

Status: v0 — pacote único @softize/opus com subpath exports (core + adapters). Uma versão, sem semver por módulo.

End-to-end action protocol for TypeScript. Declare once — input, authorization, execution, audit, feedback — and let adapters materialize it across UI, client, server, and log.

O Opus não é framework. Não tem ciclo de vida próprio. É o contrato comum que todas as camadas falam.

Filosofia

• Pipeline declarado, não escrita declarada. Action é qualquer unidade que flui pelo pipeline (validate → load → authorize → execute → audit → return), independente de mudar estado. Cobre write (form, simple) e read estruturado (list, view).
• Três primitivas declarativas. Action (humano/AI dispara) + Reaction (evento dispara) + Schedule (tempo dispara). Fecha o ciclo de ação proativa.
• Provenance rastreável. Toda execução carrega origem estruturada (http, schedule, reaction, ai-agent, background, ...) com cadeia preservada via originalProvenance. Audit registra a árvore de causalidade do user até a action final.
• Kind como discriminator. v0 suporta simple, form, list, view.
• Contrato, não feature. Tudo que entra no core padroniza forma; tudo que faz trabalho usa lib externa.
• Fail-closed por default. Action sem authorize é negada. Audit default-on.
• Adapters plugáveis. Cada categoria é uma superfície (subpath) com interface fechada e drivers trocáveis.
• Doc é fonte da verdade. docs/protocol.md — 16 seções fechadas (15 + glossário).

Superfícies

Um pacote (@softize/opus), uma versão. Cada categoria abaixo é um subpath ESM, não um pacote separado.

| Superfície | Drivers | Propósito | |---|---|---| | @softize/opus (core) | — | Protocolo, defineAction, defineEntity, runtime | | @softize/opus/schema | /zod, /openapi | Logical types (t.*) + OpenAPI generator | | @softize/opus/server | /fastify | HTTP transport + endpoint mount | | @softize/opus/client | /fetch | Client adapter pra invocar actions | | @softize/opus/ui | /react | Componentes + Provider + hooks (useAction, useListAction) | | @softize/opus/data | /kysely | Data adapter (ctx.db, ctx.repo) | | @softize/opus/auth | /jwt, /better-auth | Auth adapter (ctx.user, ctx.can) | | @softize/opus/audit | /console, /pg | Audit sinks | | @softize/opus/log | /pino | Logger adapter (console default no core) | | @softize/opus/queue | /bullmq | Background job execution | | @softize/opus/events | /mitt | EventBus (in-process) | | @softize/opus/scheduler | /node-cron | Schedule adapter (ação iniciada por tempo) |

Drivers via subpath ESM (estilo Drizzle): @softize/opus/server/fastify, @softize/opus/data/kysely.

Quick start

pnpm add @softize/opus zod fastify

import Fastify from 'fastify'
import { z } from 'zod'
import { createRuntime, defineAction } from '@softize/opus'
import { t } from '@softize/opus/schema/zod'
import { fastifyServer } from '@softize/opus/server/fastify'

const archiveDeal = defineAction({
  name: 'deal.archive',
  kind: 'simple',
  input: z.object({ dealId: z.string() }),
  output: z.object({ archivedAt: t.datetime() }),
  authorize: (ctx) => ctx.can('deal:archive'),
  handler: async (_ctx, input) => ({ archivedAt: new Date().toISOString() }),
})

const app = Fastify()
const server = fastifyServer({ app })
const runtime = createRuntime({ server })

runtime.register([archiveDeal])
await runtime.start()
server.mountEndpoints({ openapi: true })

await app.listen({ port: 3000 })
// POST http://localhost:3000/api/deal/archive
// GET  http://localhost:3000/openapi.json
// GET  http://localhost:3000/health
// GET  http://localhost:3000/ready

Estrutura

src/
  core/      schema/    server/    client/    ui/
  data/      auth/      audit/     log/       queue/   events/   scheduler/   dsl/
registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não runtime
bin/         # CLI (opus setup/gen/check/introspect/mcp) + libs
docs/
  protocol.md   # contrato completo (16 seções)
  data-layer.md · releasing.md · code-style.md

Status

• v0: 12 superfícies, 430 tests, 100% coverage.
• v1+: drivers adicionais (Hono, Drizzle, ArkType, Vue, Inngest, Redis events), camada de entidades (defineEntity), Conversya migration plan.

Desenvolvimento

pnpm install        # instala deps
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest run
pnpm test:cov       # com coverage report

Publicar

Publicado no registry compartilhado da Softize (registry.softize.com.br), não no npm público. pnpm release [patch|minor|major|x.y.z] bumpa + publica. Passo a passo (verificar, testar local, auth) em docs/releasing.md.

Licença

A decidir. Ver docs/protocol.md — Decisões em aberto.