@softize/opus 8.6.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Softize
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# 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
+
+```bash
+pnpm add @softize/opus zod fastify
+```
+
+```ts
+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 (create-action) — geração, 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
+
+```bash
+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](docs/releasing.md).
+
+## Licença
+
+A decidir. Ver `docs/protocol.md` — Decisões em aberto.

package/bin/cli.mjs

@@ -0,0 +1,528 @@
+#!/usr/bin/env node
+/**
+ * @softize/opus CLI — copia templates do registry pro consumer.
+ *
+ * Uso:
+ *   npx @softize/opus add <name>             # copia registry/<name>.tsx
+ *   npx @softize/opus add <name> --force      # sobrescreve se existe
+ *   npx @softize/opus list                    # lista templates disponíveis
+ *   npx @softize/opus gen                     # gera manifest/openapi/docs/stubs
+ *
+ * Lê components.json do consumer pra resolver path destino (mesma config
+ * do shadcn). Default: <cwd>/src/components/action/<name>.tsx.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { cmdGen, helpGen } from './lib/gen.mjs'
+import { cmdDb } from './lib/db.mjs'
+import { scanDir, emptyScanVerdict } from './lib/check.mjs'
+import { createMonorepo, createProject } from './lib/create.mjs'
+import { initProject, setupUiFoundation } from './lib/init.mjs'
+import { introspect } from './lib/introspect.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const PACKAGE_ROOT = path.resolve(__dirname, '..')
+const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry')
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function log(level, msg) {
+  const colors = {
+    info: '\x1b[36m',
+    success: '\x1b[32m',
+    error: '\x1b[31m',
+    warn: '\x1b[33m',
+  }
+  const reset = '\x1b[0m'
+  console.log(`${colors[level]}${msg}${reset}`)
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function loadComponentsJson(cwd) {
+  const candidate = path.join(cwd, 'components.json')
+  if (!(await fileExists(candidate))) {
+    return null
+  }
+  try {
+    const raw = await fs.readFile(candidate, 'utf-8')
+    return JSON.parse(raw)
+  } catch (err) {
+    log('warn', `components.json existe mas não é JSON válido: ${err.message}`)
+    return null
+  }
+}
+
+function resolveAlias(alias, fallback) {
+  if (typeof alias !== 'string') return fallback
+  // Pega só a parte após "@/" pq path é relativo a src/.
+  // Ex: "@/components" → "components".
+  if (alias.startsWith('@/')) {
+    return alias.slice(2)
+  }
+  return alias
+}
+
+async function resolveDestination(cwd, name) {
+  const components = await loadComponentsJson(cwd)
+  if (components === null) {
+    log(
+      'warn',
+      'Sem components.json. Usando default ./src/components/action/. Roda `npx shadcn init` se quiser configurar.',
+    )
+    return path.join(cwd, 'src/components/action', `${name}.tsx`)
+  }
+  const aliasComponents =
+    components.aliases?.components ?? '@/components'
+  const componentsRel = resolveAlias(aliasComponents, 'components')
+  return path.join(cwd, 'src', componentsRel, 'action', `${name}.tsx`)
+}
+
+async function listTemplates() {
+  if (!(await fileExists(REGISTRY_DIR))) {
+    log('error', `Registry não encontrado em ${REGISTRY_DIR}.`)
+    process.exit(1)
+  }
+  const files = await fs.readdir(REGISTRY_DIR)
+  return files
+    .filter((f) => f.endsWith('.tsx') || f.endsWith('.ts'))
+    .map((f) => f.replace(/\.(tsx|ts)$/, ''))
+    .sort()
+}
+
+// =============================================================================
+// Commands
+// =============================================================================
+
+async function cmdList() {
+  const templates = await listTemplates()
+  if (templates.length === 0) {
+    log(
+      'info',
+      '\nSem templates de cópia (os componentes de UI agora são LIB, não se copiam):\n' +
+        '  • importe de `@softize/opus/ui/react` (Button, ActionForm, DropdownMenu…)\n' +
+        '  • descubra o catálogo via `opus mcp` → tool `opus_list_components`\n',
+    )
+    return
+  }
+  log('info', `\n@softize/opus templates disponíveis:\n`)
+  for (const t of templates) {
+    console.log(`  ${t}`)
+  }
+  console.log('')
+  log('info', `Adicionar: npx @softize/opus add <nome>\n`)
+}
+
+async function cmdAdd(name, options) {
+  if (typeof name !== 'string' || name.length === 0) {
+    log('error', 'Uso: npx @softize/opus add <name>')
+    process.exit(1)
+  }
+
+  const templates = await listTemplates()
+  if (!templates.includes(name)) {
+    log('error', `Template "${name}" não existe.`)
+    console.log(`\nDisponíveis: ${templates.join(', ')}\n`)
+    process.exit(1)
+  }
+
+  const cwd = process.cwd()
+  const src = path.join(REGISTRY_DIR, `${name}.tsx`)
+  const dest = await resolveDestination(cwd, name)
+
+  if (await fileExists(dest)) {
+    if (options.force !== true) {
+      log(
+        'warn',
+        `Já existe em ${path.relative(cwd, dest)} — passa --force pra sobrescrever.`,
+      )
+      process.exit(1)
+    }
+    log('warn', `Sobrescrevendo ${path.relative(cwd, dest)}`)
+  }
+
+  await fs.mkdir(path.dirname(dest), { recursive: true })
+  const content = await fs.readFile(src, 'utf-8')
+  await fs.writeFile(dest, content, 'utf-8')
+
+  log('success', `✓ Criado ${path.relative(cwd, dest)}`)
+  console.log(
+    '\n  Edita à vontade — esse arquivo é seu agora. Próximas runs com --force\n  sobrescrevem suas mudanças.\n',
+  )
+}
+
+async function cmdCheck(dir) {
+  const root = path.resolve(process.cwd(), dir ?? '.')
+  const rel = path.relative(process.cwd(), root) || '.'
+  const { files, actions, contracts, findings, hasMarker } = await scanDir(root)
+
+  if (actions === 0) {
+    const verdict = emptyScanVerdict({ hasMarker, contracts })
+    // Projeto MARCADO (opus.json) sem actions passa vacuamente — server/lib/app sem
+    // domínio ainda. Sem marcador, "0 actions" segue sintoma (diretório errado ou
+    // padrão que o check não enxerga), não aprovação.
+    if (verdict.ok) {
+      log('success', `✓ opus check: ${verdict.message}`)
+      return
+    }
+    log('error', `✗ opus check: nenhuma action encontrada em ${rel} (${files} arquivos .ts); ${verdict.message}`)
+    process.exit(1)
+  }
+  const viaContrato = contracts > 0 ? ` (${contracts} contrato(s))` : ''
+  if (findings.length === 0) {
+    log('success', `✓ opus check: ${actions} action(s)${viaContrato}, 0 violação — padrão ok.`)
+    return
+  }
+
+  const byFile = new Map()
+  for (const f of findings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, [])
+    byFile.get(f.file).push(f)
+  }
+  for (const [file, list] of byFile) {
+    log('warn', `\n${file}`)
+    for (const f of list.sort((a, b) => a.line - b.line)) {
+      console.log(`  ${String(f.line).padStart(4)}:  [${f.rule}] ${f.action} — ${f.message}`)
+    }
+  }
+  log('error', `\n✗ opus check: ${findings.length} violação(ões) em ${byFile.size}/${actions} action(s).`)
+  process.exit(1)
+}
+
+async function cmdCreate(dir, flags) {
+  if (!dir) {
+    log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
+    process.exit(1)
+  }
+  const target = path.resolve(process.cwd(), dir)
+  const name = path.basename(target)
+
+  if (flags.monorepo) {
+    const r = await createMonorepo(REGISTRY_DIR, target, name)
+    log('success', `✓ opus create: raiz do monorepo "${name}" criada (base v${r.version}).`)
+    console.log(`\n  ${r.files.length} arquivos (workspace apps/* + packages/*, registry, allowBuilds).`)
+    console.log(`
+  Próximos passos:
+    cd ${dir}
+    git init && git add -A && git commit -m "chore: raiz do monorepo"
+    opus create apps/<seu-app>   # o modo app detecta o workspace
+`)
+    return
+  }
+
+  const r = await createProject(REGISTRY_DIR, target, name)
+  const modeLabel = r.mode === 'app' ? 'app no monorepo (workspace detectado)' : 'repo standalone'
+  log('success', `✓ opus create: app "${name}" criado (base v${r.version}, ${modeLabel}).`)
+  console.log(`\n  ${r.files.length} arquivos do esqueleto + setup (${r.setup.created.join(', ')}).`)
+  const warnings = [...r.warnings, ...r.setup.warnings]
+  if (warnings.length) {
+    console.log('\n  falta plugar (à mão, pra não sobrescrever o seu):')
+    for (const w of warnings) console.log(`    ! ${w}`)
+  }
+  if (r.mode === 'app') {
+    console.log(`
+  Próximos passos (no monorepo):
+    pnpm install
+    pnpm --filter ${name} test && pnpm --filter ${name} manifest
+
+  Depois: cadastro do app no admin (root/run) → sessão no Maestro.
+`)
+  } else {
+    console.log(`
+  Próximos passos:
+    cd ${dir}
+    git init && git add -A && git commit -m "chore: esqueleto opus"
+    pnpm install
+    pnpm test && pnpm exec opus check src && pnpm manifest
+
+  Depois: repo no GitHub + cadastro no admin (workspace/repo/app/agentes) → sessão no Maestro.
+`)
+  }
+}
+
+async function cmdInit() {
+  const cwd = process.cwd()
+  const r = await initProject(REGISTRY_DIR, cwd)
+  log('success', `✓ opus setup: app v${r.version} ${r.wasInitialized ? 'atualizado' : 'inicializado'}.`)
+  if (r.created.length) {
+    console.log('\n  criados (per-app):')
+    for (const c of r.created) console.log(`    + ${c}`)
+  }
+  if (r.synced.length) {
+    console.log('\n  atualizados (bloco gerenciado):')
+    for (const c of r.synced) console.log(`    ~ ${c}`)
+  }
+  if (r.warnings.length) {
+    console.log('\n  falta plugar (à mão, pra não sobrescrever o seu):')
+    for (const w of r.warnings) console.log(`    ! ${w}`)
+  }
+
+  // Fundação de UI (só apps web): preset + tema + flags. Cria o que falta, avisa o resto.
+  const ui = await setupUiFoundation(cwd)
+  if (ui.applicable) {
+    if (ui.created.length) {
+      console.log('\n  fundação de UI criada:')
+      for (const c of ui.created) console.log(`    + ${c}`)
+    }
+    if (ui.warnings.length) {
+      console.log('\n  fundação de UI — falta plugar (à mão, pra não sobrescrever o seu):')
+      for (const w of ui.warnings) console.log(`    ! ${w}`)
+    }
+    if (!ui.created.length && !ui.warnings.length) {
+      console.log('\n  fundação de UI: ok (preset + tema + flags já plugados).')
+    }
+  }
+
+  console.log(
+    '\n  Per-app: opus.json (pin) + CLAUDE.md. A spec vive nas declarações (description → manifest).\n' +
+      '  A camada-base (.claude agents+skills) é REPO-LEVEL — o Maestro a materializa.\n' +
+      '  Gate de build: opus check.\n',
+  )
+}
+
+async function cmdIntrospect(dir, flags) {
+  const root = path.resolve(process.cwd(), dir ?? '.')
+  const model = await introspect(root)
+  if (flags.json) {
+    console.log(JSON.stringify(model, null, 2))
+    return
+  }
+  const rel = path.relative(process.cwd(), root) || '.'
+  log('info', `\nopus introspect — ${rel}`)
+  console.log(`  actions:   ${model.actions.length}`)
+  console.log(`  reactions: ${model.reactions.length}`)
+  console.log(`  schedules: ${model.schedules.length}`)
+  if (model.wiring.length > 0) {
+    log('info', '\nwiring:')
+    for (const e of model.wiring) {
+      if (e.kind === 'schedule') console.log(`  ⏱  ${e.from} → ${e.to}  (${e.via})`)
+      else console.log(`  ⚡ ${e.from} → ${e.to}  (evento: ${e.via})`)
+    }
+  }
+  console.log('')
+}
+
+// =============================================================================
+// Entry
+// =============================================================================
+
+function parseArgs(argv) {
+  const args = argv.slice(2)
+  const positional = []
+  const flags = { force: false, help: false }
+  // Flags com valor — pega o próximo arg.
+  const VALUE_FLAGS = new Set(['--config', '--output'])
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--force' || arg === '-f') {
+      flags.force = true
+      continue
+    }
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true
+      continue
+    }
+    if (arg === '--check') {
+      flags.check = true
+      continue
+    }
+    if (arg === '--json') {
+      flags.json = true
+      continue
+    }
+    if (arg === '--monorepo') {
+      flags.monorepo = true
+      continue
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const next = args[i + 1]
+      if (typeof next !== 'string' || next.startsWith('-')) {
+        log('error', `Flag ${arg} precisa de valor`)
+        process.exit(1)
+      }
+      // Strip leading "--" pra usar como key direto.
+      flags[arg.slice(2)] = next
+      i++
+      continue
+    }
+    if (arg.startsWith('--')) {
+      log('warn', `Flag desconhecida: ${arg}`)
+      continue
+    }
+    positional.push(arg)
+  }
+  return { positional, flags }
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv)
+  const [command, ...rest] = positional
+
+  if (command === undefined || command === 'help') {
+    console.log(`
+@softize/opus CLI
+
+Comandos:
+  create <dir>     Scaffolda um app opus-based canônico (vite+react+ui+domínio-exemplo);
+                   detecta workspace (app em monorepo); --monorepo cria a RAIZ do workspace
+  setup            Bootstrap PER-APP: grava opus.json + CLAUDE.md (se faltam)
+  add <name>       Copia template do registry pro consumer
+  list             Lista templates disponíveis
+  gen              Gera manifest/openapi/docs/stubs a partir do opus.config.ts
+  check [dir]      Valida as convenções das actions (régua de padrão; exit ≠ 0 se violar)
+  db <verbo>       Comandos de banco. v1: db check (drift-check entidade ↔ banco)
+  introspect [dir] Modelo da estrutura (actions/reactions/schedules + wiring); --json
+  mcp              Server MCP (introspect/check/create-action) — agentes via mcp_config
+  help             Mostra esta mensagem
+
+Flags:
+  --force, -f      Sobrescreve arquivo existente
+  --config <path>  (gen) Caminho do opus.config.ts
+  --output <path>  (gen) Pasta de saída
+
+Exemplos:
+  npx @softize/opus add action-form
+  npx @softize/opus add action-list --force
+  npx @softize/opus list
+  npx @softize/opus gen --config ./apps/api/opus.config.ts
+`)
+    return
+  }
+
+  if (command === 'create') {
+    if (flags.help) {
+      console.log(`
+@softize/opus create <dir>
+
+Scaffolda um app opus-based CANÔNICO no diretório <dir> (recusa dir não-vazio).
+O esqueleto versiona com a base — nasce com os pré-requisitos plugados:
+  protocolo   opus.config.ts + domínio-exemplo + manifest/scripts (+ teste verde)
+  UI          vite + react + tailwind v4 CSS-first (tema + @source do Opus)
+  Maestro     dev server na porta injetada (PORT) + allowedHosts do preview
+  dia zero    opus.json, CLAUDE.md (bloco), .claude/memory/, CI de fábrica
+
+Depois: git init && pnpm install && pnpm test — e cadastre repo/app no admin.
+`)
+      return
+    }
+    await cmdCreate(rest[0], flags)
+    return
+  }
+
+  if (command === 'setup') {
+    if (flags.help) {
+      console.log(`
+@softize/opus setup
+
+Bootstrap PER-APP de um projeto pra usar a base (idempotente):
+  opus.json        marcador com a versão da base pinada (fonte da verdade)
+  CLAUDE.md        pointer do protocolo — criado só se faltar (não sobrescreve)
+
+Fundação de UI (só apps web — preset Tailwind + tema + flags do Opus):
+  tailwind.config  criado se faltar; senão avisa pra estender o preset
+  tema/tsconfig/dep — avisa o que falta plugar (não edita seus arquivos: sem clobber)
+
+A camada-base (agents/skills) é REPO-LEVEL — materializada pelo MAESTRO (o regente),
+NÃO pelo setup. Roda manual ou via postinstall.
+`)
+      return
+    }
+    await cmdInit()
+    return
+  }
+
+  if (command === 'list') {
+    await cmdList()
+    return
+  }
+
+  if (command === 'add') {
+    if (flags.help) {
+      console.log(`
+@softize/opus add <name>
+
+Copia o template registry/<name>.tsx pra src/components/action/<name>.tsx
+(ou ao alias resolvido via components.json).
+
+Flags:
+  --force, -f      Sobrescreve existente
+`)
+      return
+    }
+    const [name] = rest
+    await cmdAdd(name, flags)
+    return
+  }
+
+  if (command === 'gen') {
+    if (flags.help) {
+      helpGen()
+      return
+    }
+    await cmdGen(flags)
+    return
+  }
+
+  if (command === 'check') {
+    if (flags.help) {
+      console.log(`
+@softize/opus check [dir]
+
+Valida as convenções das actions (estático, TS compiler API). Enxerga
+\`defineAction\` e o split \`defineContract\`+\`bindAction\`:
+  action-name             — <resource>.<verb> (minúsculo, ponto)
+  kind                    — simple|form|list|view
+  field-order             — identidade→docs→input/output→authorize→handler→comportamento
+  export                  — defineAction/defineContract/bindAction como \`export const\`
+  requires-sem-authorize  — \`requires\` é declarativo (o runtime não o executa);
+                            action com requires precisa de authorize (no contrato
+                            ou no binding — o join contrato↔bind é cross-file)
+
+Exit ≠ 0 se houver violação OU se não achar action nenhuma (gate vazio não
+passa verde). Default dir: cwd.
+`)
+      return
+    }
+    await cmdCheck(rest[0])
+    return
+  }
+
+  if (command === 'db') {
+    await cmdDb(rest, flags)
+    return
+  }
+
+  if (command === 'introspect') {
+    await cmdIntrospect(rest[0], flags)
+    return
+  }
+
+  if (command === 'mcp') {
+    // stdout é o canal do protocolo MCP — NÃO logar aqui.
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js')
+    const { buildServer } = await import('./lib/mcp.mjs')
+    await buildServer().connect(new StdioServerTransport())
+    return // processo segue vivo pelo listener do stdin
+  }
+
+  log('error', `Comando desconhecido: ${command}`)
+  process.exit(1)
+}
+
+main().catch((err) => {
+  log('error', `Erro: ${err.message}`)
+  process.exit(1)
+})