@softize/opus 12.6.3 → 12.7.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.7.0 — 2026-08-29
+
+Seeds persistentes ganham uma porta própria em `@softize/opus/seed`: declaração compartilhável,
+binding server-only, perfis, dependências, métricas esperadas e escopos permitidos. A CLI passa a
+listar, validar, planejar, aplicar e verificar esses datasets por `opus seed`, bloqueia qualquer
+operação com banco sem ambiente seguro e atestação do alvo real, e reprova comandos locais
+paralelos ou compostos no gate.
+
+O registry inclui as skills `create-opus-seed` e `apply-opus-seed`. O manifest projeta somente a
+declaração; conexão e funções do binding permanecem server-only. A mudança é aditiva. Projetos que
+adotarem a superfície devem migrar scripts `seed*`/`db:seed*` ou fazê-los delegar para a CLI.
+
+`DetailField` e `DetailGroup` oferecem a composição canônica para dados somente leitura, com
+labels, valores React ricos, grade responsiva, moldura externa e divisórias internas opcionais.
+`ActionForm` também passa a renderizar `widget: 'toggle-group'` de forma declarativa e aceita
+conteúdo rico nas opções pelo mesmo contrato usado pelos demais campos. O novo `FieldWidget` tipa
+os overrides reconhecidos pelo renderer. As mudanças são aditivas.
+
 ## 12.6.3 — 2026-08-26
 
 A skill `build-opus-ui` passa a orientar operacionalmente os patterns entregues em 12.6.0 e
@@ -46,7 +64,6 @@ Os patterns existentes passam a reutilizar os primitives canônicos: `ActionForm
 `FieldGroup`, descrições e erros associados ao controle; `ActionList` usa a moldura de `Table` e
 os estados seguros de `DataState`, preservando a tentativa de recuperação; e a confirmação de uma
 `ActionTrigger` destrutiva mantém o tratamento destrutivo mesmo quando o gatilho visual é discreto.
-
 ## 12.5.5 — 2026-08-25
 
 Só documentação: leva ao pacote a correção de nota que a 12.5.4 recebeu no repositório depois de

package/README.md

@@ -35,6 +35,7 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 | `@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) |
+| `@softize/opus/seed` | — | Declaração e binding de datasets verificáveis operados pela CLI |
 
 Drivers via subpath ESM (estilo Drizzle): `@softize/opus/server/fastify`, `@softize/opus/data/kysely`.
 
@@ -82,12 +83,29 @@ 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/copy/check/introspect/mcp) + libs
+bin/         # CLI (opus setup/gen/copy/check/seed/introspect/mcp) + libs
 docs/
   protocol.md   # contrato completo (16 seções)
-  data-layer.md · releasing.md · code-style.md
+  data-layer.md · seeds.md · releasing.md · code-style.md
 ```
 
+## Seeds de projeto
+
+Datasets persistentes de desenvolvimento, teste e demonstração usam `defineSeed` + `bindSeed` e
+ficam registrados em `opus.config.ts`. A CLI descobre e valida sem abrir conexão, exige escopo
+explícito para operar e bloqueia produção:
+
+```bash
+pnpm exec opus seed list
+pnpm exec opus seed check
+pnpm exec opus seed plan customers.scenarios --profile smoke --scope local
+pnpm exec opus seed apply customers.scenarios --profile smoke --scope local
+pnpm exec opus seed verify customers.scenarios --profile smoke --scope local
+```
+
+O contrato não oferece reset/truncate, e `apply` precisa convergir quando repetido. Veja
+[docs/seeds.md](docs/seeds.md).
+
 ## Status
 
 - **v0**: 12 superfícies, 430 tests, 100% coverage.

package/bin/cli.mjs

@@ -31,6 +31,7 @@ import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
 import { materializeOpus } from './lib/materialize.mjs'
+import { cmdSeed } from './lib/seed.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -393,7 +394,7 @@ function parseArgs(argv) {
   const positional = []
   const flags = { force: false, help: false }
   // Flags com valor — pega o próximo arg.
-  const VALUE_FLAGS = new Set(['--config', '--output'])
+  const VALUE_FLAGS = new Set(['--config', '--output', '--profile', '--scope'])
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
     if (arg === '--force' || arg === '-f') {
@@ -455,6 +456,7 @@ Comandos:
   check [dir]      Valida as convenções das actions (régua de padrão; exit ≠ 0 se violar)
   pre-push         Gate Git: freshness dos artefatos + convenções das actions
   db <verbo>       Comandos de banco. v1: db check (drift-check entidade ↔ banco)
+  seed <verbo>     Lista, valida, planeja, aplica e verifica seeds estruturados
   introspect [dir] Modelo da estrutura (actions/reactions/schedules + wiring); --json
   mcp              Server MCP (introspect/check/scaffold de action) — agentes via mcp_config
   help             Mostra esta mensagem
@@ -464,6 +466,8 @@ Flags:
   --check          Não escreve; falha se o inventário de copy estiver ausente/desatualizado
   --config <path>  (gen) Caminho do opus.config.ts
   --output <path>  (gen) Pasta de saída
+  --profile <name> (seed) Perfil do dataset
+  --scope <name>   (seed) Escopo explícito dos dados
 
 Exemplos:
   npx @softize/opus add action-form
@@ -606,6 +610,11 @@ Flags:
     return
   }
 
+  if (command === 'seed') {
+    await cmdSeed(rest, flags)
+    return
+  }
+
   if (command === 'introspect') {
     await cmdIntrospect(rest[0], flags)
     return

package/bin/lib/gen-manifest.mjs

@@ -14,6 +14,7 @@ export function buildManifest(payload) {
   return {
     version: '1',
     opusVersion: payload.opusVersion,
+    seeds: payload.seeds ?? [],
     domains: payload.domains.map(shapeDomain),
   }
 }

package/bin/lib/gen-runner.mjs

@@ -24,7 +24,8 @@
  *       opusVersion: string,
  *       sourceConfigDir: string,    // dirname absoluto do opus.config.ts
  *       output: string,             // pasta de saída declarada no config
- *       domains: SerializedDomain[]
+ *       domains: SerializedDomain[],
+ *       seeds: SerializedSeed[]
  *     }
  *
  *     SerializedDomain:
@@ -87,6 +88,12 @@ async function main() {
   ).href
   const { flattenDomain } = await import(opusCoreUrl)
 
+  const opusSeedUrl = pathToFileURL(
+    path.join(PACKAGE_ROOT, 'src', 'seed', 'index.ts'),
+  ).href
+  const { checkSeedRegistry, isSeedDefinition, publicSeedDefinition } =
+    await import(opusSeedUrl)
+
   // Acessar logical type meta dos dicts.
   const opusSchemaUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, 'src', 'schema', 'index.ts'),
@@ -127,17 +134,38 @@ async function main() {
   }
 
   const domains = cfg.domains.map((d) => serializeDomain(d, ctx))
+  if (cfg.seeds !== undefined && !Array.isArray(cfg.seeds)) {
+    throw new Error('config.seeds inválido — use um array de declarações registradas')
+  }
+  const registeredSeeds = cfg.seeds ?? []
+  const seedCheck = checkSeedRegistry(registeredSeeds)
+  if (!seedCheck.ok) {
+    throw new Error(
+      `config.seeds inválido — ${seedCheck.diagnostics.map((diagnostic) => diagnostic.message).join('; ')}`,
+    )
+  }
+  const seeds = registeredSeeds.map((seed) =>
+    serializeSeed(seed, isSeedDefinition, publicSeedDefinition),
+  )
 
   const payload = {
     opusVersion: pkg.version,
     sourceConfigDir: ctx.sourceConfigDir,
     output: outputDir,
     domains,
+    seeds,
   }
 
   emit({ ok: true, payload })
 }
 
+function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
+  if (!isSeedDefinition(seed)) {
+    throw new Error('config.seeds contém uma declaração inválida')
+  }
+  return publicSeedDefinition(seed)
+}
+
 // =============================================================================
 // Serialização
 // =============================================================================

package/bin/lib/seed-runner.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/** Carrega seeds TypeScript do consumidor num subprocesso isolado via tsx. */
+
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import {
+  assertSeedExecutionAllowed,
+  assertSeedExpectedMetrics,
+  checkSeedRegistry,
+  publicSeedDefinition,
+  resolveSeedProfile,
+  validateSeedPlan,
+  validateSeedReport,
+} from '../../src/seed/index.ts'
+
+function emit(value) {
+  process.stdout.write(`\n${JSON.stringify(value)}\n`)
+}
+
+function publicDefinition(seed) {
+  return publicSeedDefinition(seed)
+}
+
+async function main() {
+  const [configArg, command, name, requestedProfile, requestedScope] = process.argv.slice(2)
+  if (typeof configArg !== 'string') throw new Error('config path ausente')
+
+  const module = await import(pathToFileURL(path.resolve(configArg)).href)
+  const config = module.default ?? module.config ?? module
+  const seeds = config.seeds
+  if (!Array.isArray(seeds) || seeds.length === 0) {
+    throw new Error('nenhum seed registrado em config.seeds')
+  }
+
+  const check = checkSeedRegistry(seeds)
+  const targetDiagnostics =
+    typeof config.assertSeedTarget === 'function'
+      ? []
+      : [
+          {
+            code: 'seed.missing_target_assertion',
+            seed: 'opus.config.ts',
+            message:
+              'opus.config.ts precisa de assertSeedTarget para atestar a conexão antes dos bindings',
+          },
+        ]
+  if (command === 'check') {
+    emit({
+      ok: check.ok && targetDiagnostics.length === 0,
+      diagnostics: [...check.diagnostics, ...targetDiagnostics],
+      seeds: seeds.length,
+    })
+    return
+  }
+  if (!check.ok) {
+    emit({ ok: false, diagnostics: check.diagnostics })
+    return
+  }
+  if (command === 'list') {
+    emit({ ok: true, seeds: check.ordered.map(publicDefinition) })
+    return
+  }
+  if (targetDiagnostics.length > 0) {
+    emit({ ok: false, diagnostics: targetDiagnostics })
+    return
+  }
+  if (command !== 'plan' && command !== 'apply' && command !== 'verify') {
+    throw new Error(`operação de seed desconhecida: ${String(command)}`)
+  }
+
+  const seed = check.ordered.find((candidate) => candidate.name === name)
+  if (seed === undefined) {
+    throw new Error(`seed ${String(name)} não encontrado`)
+  }
+  const profile = resolveSeedProfile(seed, requestedProfile || undefined)
+  const scope = requestedScope || undefined
+  const executionSeeds = dependencyClosure(check.ordered, seed)
+  const selections = executionSeeds.map((candidate) => ({
+    seed: candidate,
+    profile: candidate.name === seed.name ? profile : resolveSeedProfile(candidate),
+  }))
+  for (const selection of selections) assertSeedExecutionAllowed(selection.seed, scope)
+
+  const database = typeof config.database === 'function' ? await config.database() : null
+  try {
+    const targetAttested = await config.assertSeedTarget({ database, scope })
+    if (targetAttested !== true) {
+      throw new Error('assertSeedTarget precisa retornar true após atestar o destino real')
+    }
+    if (command === 'plan') {
+      const steps = []
+      for (const selection of selections) {
+        const plan = validateSeedPlan(await selection.seed.binding.plan({
+          database,
+          profile: selection.profile,
+          scope,
+        }))
+        steps.push({ seed: publicDefinition(selection.seed), profile: selection.profile, plan })
+      }
+      emit({
+        ok: true,
+        command,
+        seed: publicDefinition(seed),
+        profile,
+        scope,
+        plan: steps.at(-1).plan,
+        steps,
+      })
+      return
+    }
+    const steps = []
+    for (const selection of selections) {
+      const report = validateSeedReport(await selection.seed.binding[command]({
+        database,
+        profile: selection.profile,
+        scope,
+      }))
+      if (command === 'verify') {
+        assertSeedExpectedMetrics(selection.seed, selection.profile, report)
+      }
+      steps.push({ seed: publicDefinition(selection.seed), profile: selection.profile, report })
+    }
+    emit({
+      ok: true,
+      command,
+      seed: publicDefinition(seed),
+      profile,
+      scope,
+      report: steps.at(-1).report,
+      steps,
+    })
+  } finally {
+    if (database !== null && typeof database.destroy === 'function') await database.destroy()
+  }
+}
+
+function dependencyClosure(ordered, target) {
+  const required = new Set()
+  const byName = new Map(ordered.map((seed) => [seed.name, seed]))
+  const collect = (seed) => {
+    if (required.has(seed.name)) return
+    for (const dependency of seed.dependsOn ?? []) collect(byName.get(dependency))
+    required.add(seed.name)
+  }
+  collect(target)
+  return ordered.filter((seed) => required.has(seed.name))
+}
+
+main().catch((error) => {
+  emit({ ok: false, error: error instanceof Error ? error.message : String(error) })
+})

package/bin/lib/seed.mjs

@@ -0,0 +1,229 @@
+/** Grupo `opus seed`: descoberta, gate e execução segura dos seeds do projeto. */
+
+import { execFile } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+
+import { canonicalProjectDirectory, readProjectFile, safeProjectPath } from '@softize/base/project-path'
+
+const execFileAsync = promisify(execFile)
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+
+const COLORS = {
+  info: '\x1b[36m',
+  success: '\x1b[32m',
+  error: '\x1b[31m',
+  warn: '\x1b[33m',
+  dim: '\x1b[2m',
+}
+const RESET = '\x1b[0m'
+
+function log(level, message) {
+  console.log(`${COLORS[level] ?? ''}${message}${RESET}`)
+}
+
+export function findAdHocSeedScripts(scripts = {}) {
+  return Object.entries(scripts).flatMap(([name, command]) => {
+    const isSeedName = /^seed(?::|$)/.test(name) || /^db:seed(?::|$)/.test(name)
+    const hasShellComposition =
+      typeof command === 'string' && /(?:&&|\|\||[;&|<>`\n\r]|\$\()/.test(command)
+    const delegatesToOpus =
+      typeof command === 'string' &&
+      !hasShellComposition &&
+      /^(?:npx |pnpm exec )?opus seed (?:list|check|plan|apply|verify)(?:\s|$)/.test(command.trim())
+    return isSeedName && !delegatesToOpus ? [{ name, command }] : []
+  })
+}
+
+export async function cmdSeed(rest, flags) {
+  const [command, name] = rest
+  if (flags.help || command === undefined || command === 'help') {
+    helpSeed()
+    return
+  }
+  if (!['list', 'check', 'plan', 'apply', 'verify'].includes(command)) {
+    fail(flags, `Subcomando seed desconhecido: ${command}`)
+    if (!flags.json) helpSeed()
+    return
+  }
+  if (['plan', 'apply', 'verify'].includes(command) && typeof name !== 'string') {
+    fail(flags, `Uso: opus seed ${command} <nome> --scope <escopo>`)
+    return
+  }
+
+  let resolved
+  try {
+    resolved = resolveConfig(flags)
+  } catch (error) {
+    fail(flags, error instanceof Error ? error.message : String(error))
+    return
+  }
+  const { cwd, configPath } = resolved
+  const result = await runRunner(configPath, [
+    command,
+    name ?? '',
+    flags.profile ?? '',
+    flags.scope ?? process.env.OPUS_SEED_SCOPE ?? '',
+  ])
+
+  if (command === 'check') {
+    const scriptFindings = readSeedScriptFindings(cwd)
+    const runnerFindings = result.error === undefined ? [] : [{
+      code: 'seed.invalid_registry',
+      seed: 'opus.config.ts',
+      message: result.error,
+    }]
+    const diagnostics = [...(result.diagnostics ?? []), ...runnerFindings, ...scriptFindings]
+    const checked = { ...result, ok: result.ok === true && diagnostics.length === 0, diagnostics }
+    if (flags.json) {
+      console.log(JSON.stringify(checked, null, 2))
+    } else if (checked.ok) {
+      log('success', `✓ seed check: ${checked.seeds} seed(s) estruturado(s); registro consistente.`)
+    } else {
+      printDiagnostics(diagnostics)
+      log('error', `✗ seed check: ${diagnostics.length} violação(ões).`)
+    }
+    if (!checked.ok) process.exitCode = 1
+    return
+  }
+
+  if (result.ok !== true) {
+    if (flags.json) console.log(JSON.stringify(result, null, 2))
+    else {
+      printDiagnostics(result.diagnostics ?? [])
+      log('error', `✗ opus seed ${command}: ${result.error ?? 'registro inconsistente'}`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+  if (command === 'list') printList(result.seeds)
+  else if (command === 'plan') printPlan(result)
+  else printReport(result)
+}
+
+function fail(flags, message) {
+  if (flags.json) console.log(JSON.stringify({ ok: false, error: message }, null, 2))
+  else log('error', `✗ opus seed: ${message}`)
+  process.exitCode = 1
+}
+
+function resolveConfig(flags) {
+  const cwd = canonicalProjectDirectory(process.cwd())
+  const configRel = flags.config ?? 'opus.config.ts'
+  const config = safeProjectPath(cwd, configRel)
+  if (!config.exists) throw new Error(`opus.config.ts não encontrado em ${config.path}`)
+  return { cwd, configPath: config.path }
+}
+
+function readSeedScriptFindings(cwd) {
+  const packageFile = readProjectFile(cwd, 'package.json', { allowMissing: true })
+  if (!packageFile.exists) return []
+  let parsed
+  try {
+    parsed = JSON.parse(packageFile.content)
+  } catch {
+    return [{ code: 'seed.invalid_package', seed: 'package.json', message: 'package.json não é JSON válido' }]
+  }
+  return findAdHocSeedScripts(parsed.scripts).map(({ name, command }) => ({
+    code: 'seed.ad_hoc_script',
+    seed: name,
+    message: `Script ${name} não delega para opus seed: ${String(command)}`,
+  }))
+}
+
+async function runRunner(configPath, extraArgs) {
+  const tsxBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
+  const command = (await fileExists(tsxBin)) ? tsxBin : 'tsx'
+  const runnerPath = path.join(__dirname, 'seed-runner.mjs')
+  try {
+    const { stdout } = await execFileAsync(command, [runnerPath, configPath, ...extraArgs], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      env: { ...process.env },
+    })
+    const line = lastJsonLine(stdout)
+    return line === null ? { ok: false, error: 'runner não emitiu JSON' } : JSON.parse(line)
+  } catch (error) {
+    const detail = typeof error.stderr === 'string' && error.stderr.trim() ? error.stderr.trim() : error.message
+    return { ok: false, error: detail }
+  }
+}
+
+function printList(seeds) {
+  log('info', `\nSeeds estruturados (${seeds.length}):`)
+  for (const seed of seeds) {
+    console.log(`  ${seed.name}@${seed.version} — ${seed.description}`)
+    console.log(`    perfis: ${Object.keys(seed.profiles).join(', ')}; default: ${seed.defaultProfile}`)
+    console.log(`    escopos: ${seed.safety.scopes.join(', ')}`)
+  }
+  console.log('')
+}
+
+function printPlan(result) {
+  log('info', `→ ${result.seed.name}@${result.seed.version} [${result.profile}] em ${result.scope}`)
+  for (const step of result.steps) {
+    console.log(`  ${step.seed.name} [${step.profile}] — ${step.plan.summary}`)
+    for (const operation of step.plan.operations) console.log(`    - ${operation}`)
+  }
+}
+
+function printReport(result) {
+  log('success', `✓ seed ${result.command}: ${result.seed.name}@${result.seed.version} [${result.profile}]`)
+  for (const step of result.steps) {
+    console.log(`  ${step.seed.name} [${step.profile}] — ${step.report.summary}`)
+    for (const [metric, value] of Object.entries(step.report.metrics)) console.log(`    ${metric}: ${value}`)
+  }
+}
+
+function printDiagnostics(diagnostics) {
+  for (const diagnostic of diagnostics) log('warn', `[${diagnostic.code}] ${diagnostic.message}`)
+}
+
+function lastJsonLine(stdout) {
+  const lines = stdout.split('\n').filter((line) => line.trim())
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = lines[index].trim()
+    if (line.startsWith('{') && line.endsWith('}')) return line
+  }
+  return null
+}
+
+async function fileExists(file) {
+  try {
+    await fs.access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function helpSeed() {
+  console.log(`
+@softize/opus seed — datasets estruturados do projeto
+
+  seed list                    Lista seeds, perfis, versões e escopos sem abrir o banco.
+  seed check                   Valida bindings, dependências, ciclos e scripts paralelos.
+  seed plan <nome>             Mostra as operações previstas sem escrever.
+  seed apply <nome>            Aplica o perfil de forma convergente.
+  seed verify <nome>           Confere métricas e invariantes do perfil.
+
+Flags:
+  --config <path>              Caminho interno ao projeto para opus.config.ts.
+  --profile <nome>             Perfil; usa defaultProfile quando omitido.
+  --scope <escopo>             Escopo explícito dos dados. Alternativa: OPUS_SEED_SCOPE.
+  --json                       Retorna o resultado estruturado.
+
+\`plan\`, \`apply\` e \`verify\` só abrem conexão com NODE_ENV=development ou NODE_ENV=test.
+O contrato não possui reset nem truncate; aplicação repetida precisa convergir para o mesmo estado
+observável.
+`)
+}