@softize/opus 8.6.6

package/bin/lib/db-check-runner.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * db-check-runner — subprocess via `tsx` que roda o drift-check.
+ *
+ * Por que subprocess: o CLI principal é `.mjs` puro (Node sem loader TS) e o
+ * drift-check precisa (a) importar TS do consumer (`opus.config.ts` + entidades)
+ * e (b) abrir conexão viva com o banco. Tudo isso roda aqui dentro do tsx.
+ *
+ * Contrato do `opus.config.ts` pros comandos `db`:
+ *   - `entities?: EntityConfig[]`        — entidades explícitas (opcional)
+ *   - `domains?: DomainConfig[]`         — entidades coletadas de `domain.models`
+ *   - `database: () => Kysely | Promise<Kysely>`  — factory LAZY do banco.
+ *     É factory (não instância) de propósito: o `gen` importa o mesmo config
+ *     sem nunca chamar `database()`, então não abre conexão.
+ *
+ * Protocolo de saída (igual gen-runner): última linha de stdout é um JSON
+ *   `{ ok: true, findings }` ou `{ ok: false, error }`. Resto é debug.
+ */
+
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { isEntityConfig } from '../../src/schema/entity.ts'
+import { kyselyDriftCheck } from '../../src/data/drivers/kysely.ts'
+
+function emit(obj) {
+  process.stdout.write(`\n${JSON.stringify(obj)}\n`)
+}
+
+function collectEntities(domain, out) {
+  if (domain === null || typeof domain !== 'object') return
+  const models = domain.models
+  if (models !== undefined && models !== null && typeof models === 'object') {
+    for (const value of Object.values(models)) {
+      if (isEntityConfig(value)) out.push(value)
+    }
+  }
+  if (Array.isArray(domain.subdomains)) {
+    for (const sub of domain.subdomains) collectEntities(sub, out)
+  }
+}
+
+async function main() {
+  const configPath = process.argv[2]
+  if (typeof configPath !== 'string') {
+    emit({ ok: false, error: 'config path ausente' })
+    return
+  }
+
+  const mod = await import(pathToFileURL(path.resolve(configPath)).href)
+  const config = mod.default ?? mod
+
+  const entities = []
+  if (Array.isArray(config.entities)) {
+    for (const e of config.entities) if (isEntityConfig(e)) entities.push(e)
+  }
+  if (Array.isArray(config.domains)) {
+    for (const d of config.domains) collectEntities(d, entities)
+  }
+
+  if (entities.length === 0) {
+    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.models)' })
+    return
+  }
+
+  if (typeof config.database !== 'function') {
+    emit({
+      ok: false,
+      error:
+        'config.database() ausente — exporte uma factory lazy que retorna um Kysely (ex: `database: () => new Kysely({...})`)',
+    })
+    return
+  }
+
+  const db = await config.database()
+  try {
+    const findings = await kyselyDriftCheck(db, entities, { naming: config.naming })
+    emit({ ok: true, findings })
+  } finally {
+    if (db !== null && typeof db.destroy === 'function') await db.destroy()
+  }
+}
+
+main().catch((err) => {
+  emit({ ok: false, error: err instanceof Error ? err.message : String(err) })
+})

package/bin/lib/db-migrate-runner.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * db-migrate-runner — subprocess via `tsx` que aplica o SCHEMA IDEMPOTENTE.
+ *
+ * O padrão da casa não é migration versionada: é UM script SQL evolutivo
+ * (config.schema, ex. `src/db/schema.sql`) re-rodável — CREATE IF NOT EXISTS +
+ * guards `DO $$ IF EXISTS` cobrem nascer do zero E upgrade de prod no mesmo
+ * artefato. Depois de aplicar, roda o drift-check (entidade ↔ banco) na mesma
+ * conexão: migrar e continuar divergente é estado quebrado que o deploy precisa
+ * ver na hora. (A era Kysely Migrator foi aposentada — o formato .ts de
+ * migration gerava DDL camelCase errado e ninguém o usava.)
+ *
+ * argv: [config path]
+ * Saída: última linha JSON `{ ok, schema?, findings?, error? }` (resto é debug).
+ */
+
+import path from 'node:path'
+import { promises as fs } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { sql } from 'kysely'
+
+import { isEntityConfig } from '../../src/schema/entity.ts'
+import { kyselyDriftCheck } from '../../src/data/drivers/kysely.ts'
+
+function emit(obj) {
+  process.stdout.write(`\n${JSON.stringify(obj)}\n`)
+}
+
+function collectEntities(domain, out) {
+  if (domain === null || typeof domain !== 'object') return
+  const models = domain.models
+  if (models !== undefined && models !== null && typeof models === 'object') {
+    for (const value of Object.values(models)) if (isEntityConfig(value)) out.push(value)
+  }
+  if (Array.isArray(domain.subdomains)) for (const sub of domain.subdomains) collectEntities(sub, out)
+}
+
+async function main() {
+  const configPath = process.argv[2]
+  if (typeof configPath !== 'string') {
+    emit({ ok: false, error: 'config path ausente' })
+    return
+  }
+
+  const mod = await import(pathToFileURL(path.resolve(configPath)).href)
+  const config = mod.default ?? mod
+
+  if (typeof config.database !== 'function') {
+    emit({ ok: false, error: 'config.database() ausente — exporte uma factory que retorna um Kysely' })
+    return
+  }
+
+  const configDir = path.dirname(path.resolve(configPath))
+  const schemaPath = path.resolve(configDir, config.schema ?? 'db/schema.sql')
+  let schemaSql
+  try {
+    schemaSql = await fs.readFile(schemaPath, 'utf8')
+  } catch {
+    emit({
+      ok: false,
+      error: `schema não encontrado em ${schemaPath} — aponte via \`schema\` no opus.config.ts (script SQL idempotente).`,
+    })
+    return
+  }
+
+  // Entidades pro drift-check pós-apply (explícitas ou via domains).
+  const entities = []
+  if (Array.isArray(config.entities)) for (const e of config.entities) if (isEntityConfig(e)) entities.push(e)
+  if (Array.isArray(config.domains)) for (const d of config.domains) collectEntities(d, entities)
+
+  const db = await config.database()
+  try {
+    // Um shot, sem parâmetros → protocolo simples do pg aceita multi-statement,
+    // igual ao pool.query(SQL) que este runner substitui.
+    await sql.raw(schemaSql).execute(db)
+    const findings = entities.length > 0 ? await kyselyDriftCheck(db, entities) : []
+    emit({
+      ok: true,
+      schema: schemaPath,
+      findings: findings.map((f) => ({ table: f.table, kind: f.kind, message: f.message })),
+    })
+  } finally {
+    if (db !== null && typeof db.destroy === 'function') await db.destroy()
+  }
+}
+
+main().catch((err) => {
+  emit({ ok: false, error: err instanceof Error ? err.message : String(err) })
+})

package/bin/lib/db-scaffold-runner.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * db-scaffold-runner — subprocess via `tsx` que gera um rascunho de migration.
+ *
+ * Roda o drift-check (precisa de banco) → gera o corpo da migration (puro) →
+ * escreve `migrations/<timestamp>_scaffold.ts`. Best-effort; humano revisa.
+ *
+ * argv: [config path]
+ * Saída: última linha JSON `{ ok, file?, statements?, notes?, error? }`.
+ */
+
+import path from 'node:path'
+import { promises as fs } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+import { isEntityConfig } from '../../src/schema/entity.ts'
+import { scaffoldMigration, scaffoldFileContent } from '../../src/schema/scaffold.ts'
+import { kyselyDriftCheck } from '../../src/data/drivers/kysely.ts'
+
+function emit(obj) {
+  process.stdout.write(`\n${JSON.stringify(obj)}\n`)
+}
+
+function collectEntities(domain, out) {
+  if (domain === null || typeof domain !== 'object') return
+  const models = domain.models
+  if (models !== undefined && models !== null && typeof models === 'object') {
+    for (const value of Object.values(models)) if (isEntityConfig(value)) out.push(value)
+  }
+  if (Array.isArray(domain.subdomains)) for (const sub of domain.subdomains) collectEntities(sub, out)
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14)
+}
+
+async function main() {
+  const configPath = process.argv[2]
+  if (typeof configPath !== 'string') {
+    emit({ ok: false, error: 'config path ausente' })
+    return
+  }
+
+  const mod = await import(pathToFileURL(path.resolve(configPath)).href)
+  const config = mod.default ?? mod
+
+  const entities = []
+  if (Array.isArray(config.entities)) for (const e of config.entities) if (isEntityConfig(e)) entities.push(e)
+  if (Array.isArray(config.domains)) for (const d of config.domains) collectEntities(d, entities)
+  if (entities.length === 0) {
+    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.models)' })
+    return
+  }
+  if (typeof config.database !== 'function') {
+    emit({ ok: false, error: 'config.database() ausente — exporte uma factory que retorna um Kysely' })
+    return
+  }
+
+  const db = await config.database()
+  let result
+  try {
+    const findings = await kyselyDriftCheck(db, entities)
+    result = scaffoldMigration(entities, findings)
+  } finally {
+    if (db !== null && typeof db.destroy === 'function') await db.destroy()
+  }
+
+  if (result === null) {
+    emit({ ok: true, file: null })
+    return
+  }
+
+  const configDir = path.dirname(path.resolve(configPath))
+  const migrationFolder = path.resolve(configDir, config.migrations ?? 'migrations')
+  await fs.mkdir(migrationFolder, { recursive: true })
+  const file = path.join(migrationFolder, `${timestamp()}_scaffold.ts`)
+  await fs.writeFile(file, scaffoldFileContent(result), 'utf8')
+
+  emit({ ok: true, file, statements: result.statements, notes: result.notes })
+}
+
+main().catch((err) => {
+  emit({ ok: false, error: err instanceof Error ? err.message : String(err) })
+})

package/bin/lib/db.mjs

@@ -0,0 +1,261 @@
+/**
+ * db — grupo de comandos de banco (`opus db <verbo>`).
+ *
+ * `db check` (drift-check entidade ↔ banco), `db migrate` (aplica o SCHEMA
+ * IDEMPOTENTE — o padrão da casa: um script SQL evolutivo re-rodável, não
+ * migration versionada — e cobra o drift na sequência) e `db scaffold`
+ * (rascunho-referência a partir do diff). Diferente do `opus check` (estático,
+ * source-only), os comandos `db` carregam o `opus.config.ts` e abrem conexão —
+ * por isso rodam via `tsx` num runner isolado (mesma infra do `gen`).
+ * Ver `docs/data-layer.md`.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+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, msg) {
+  console.log(`${COLORS[level] ?? ''}${msg}${RESET}`)
+}
+
+// =============================================================================
+// Dispatch
+// =============================================================================
+
+export async function cmdDb(rest, flags) {
+  const [sub] = rest
+  if (flags.help || sub === undefined || sub === 'help') {
+    helpDb()
+    return
+  }
+  if (sub === 'check') {
+    await cmdDbCheck(flags)
+    return
+  }
+  if (sub === 'migrate') {
+    await cmdDbMigrate(rest[1], flags)
+    return
+  }
+  if (sub === 'scaffold') {
+    await cmdDbScaffold(flags)
+    return
+  }
+  log('error', `Subcomando db desconhecido: ${sub}`)
+  helpDb()
+  process.exit(1)
+}
+
+// =============================================================================
+// Config
+// =============================================================================
+
+async function resolveConfig(flags) {
+  const cwd = process.cwd()
+  const configRel = flags.config ?? 'opus.config.ts'
+  const configPath = path.isAbsolute(configRel) ? configRel : path.resolve(cwd, configRel)
+  if (!(await fileExists(configPath))) {
+    log('error', `opus.config.ts não encontrado em ${configPath}`)
+    log('dim', '  Passa o path via --config <path> ou cria um na raiz do projeto.')
+    process.exit(1)
+  }
+  return { cwd, configPath }
+}
+
+// =============================================================================
+// db check
+// =============================================================================
+
+async function cmdDbCheck(flags) {
+  const { cwd, configPath } = await resolveConfig(flags)
+  log('info', `→ drift-check via ${path.relative(cwd, configPath)}...`)
+
+  const result = await runRunner('db-check-runner.mjs', configPath)
+  if (result.ok !== true) {
+    log('error', `Falha no drift-check: ${result.error}`)
+    process.exit(1)
+  }
+
+  const findings = result.findings ?? []
+  if (findings.length === 0) {
+    log('success', '✓ db check: schema do banco em dia com as entidades.')
+    return
+  }
+
+  const byTable = new Map()
+  for (const f of findings) {
+    if (!byTable.has(f.table)) byTable.set(f.table, [])
+    byTable.get(f.table).push(f)
+  }
+  for (const [table, list] of byTable) {
+    log('warn', `\n${table}`)
+    for (const f of list) {
+      console.log(`  [${f.kind}] ${f.message}`)
+    }
+  }
+  log('error', `\n✗ db check: ${findings.length} divergência(s) em ${byTable.size} tabela(s).`)
+  process.exit(1)
+}
+
+// =============================================================================
+// db migrate — aplica o schema idempotente + drift-check na sequência
+// =============================================================================
+
+async function cmdDbMigrate(sub2, flags) {
+  if (sub2 === 'down') {
+    // O padrão da casa é schema EVOLUTIVO (um script idempotente), não migration
+    // versionada — não existe "voltar uma": rollback = editar o script e re-rodar
+    // (catástrofe = snapshot pré-deploy). A era Kysely Migrator foi aposentada.
+    log('error', 'db migrate down foi aposentado: o schema é um script idempotente, sem histórico a reverter.')
+    log('dim', '  Rollback = editar o schema e re-rodar `opus db migrate`; catástrofe = snapshot pré-deploy.')
+    process.exit(1)
+  }
+  const { cwd, configPath } = await resolveConfig(flags)
+  log('info', `→ db migrate via ${path.relative(cwd, configPath)}...`)
+
+  const result = await runRunner('db-migrate-runner.mjs', configPath)
+  if (result.ok !== true) {
+    log('error', `✗ db migrate: ${result.error}`)
+    process.exit(1)
+  }
+  log('success', `✓ schema aplicado (${path.relative(cwd, result.schema)}).`)
+
+  // Drift-check embutido: migrou mas diverge das entidades = o schema ficou pra trás
+  // da declaração — estado quebrado que o deploy precisa ver AQUI, não depois.
+  const findings = result.findings ?? []
+  if (findings.length === 0) {
+    log('success', '✓ db migrate: banco em dia com as entidades.')
+    return
+  }
+  const byTable = new Map()
+  for (const f of findings) {
+    if (!byTable.has(f.table)) byTable.set(f.table, [])
+    byTable.get(f.table).push(f)
+  }
+  for (const [table, list] of byTable) {
+    log('warn', `\n${table}`)
+    for (const f of list) console.log(`  [${f.kind}] ${f.message}`)
+  }
+  log('error', `\n✗ db migrate: schema aplicado, mas ${findings.length} divergência(s) com as entidades — atualize o script.`)
+  process.exit(1)
+}
+
+// =============================================================================
+// db scaffold
+// =============================================================================
+
+async function cmdDbScaffold(flags) {
+  const { cwd, configPath } = await resolveConfig(flags)
+  log('info', `→ db scaffold via ${path.relative(cwd, configPath)}...`)
+
+  const result = await runRunner('db-scaffold-runner.mjs', configPath)
+  if (result.ok !== true) {
+    log('error', `Falha no scaffold: ${result.error}`)
+    process.exit(1)
+  }
+  if (result.file === null || result.file === undefined) {
+    log('success', '✓ db scaffold: nada a gerar (schema em dia).')
+    return
+  }
+  log('success', `✓ db scaffold: ${path.relative(cwd, result.file)} (${result.statements} statement(s)).`)
+  const notes = result.notes ?? []
+  if (notes.length > 0) {
+    log('warn', `\n  ${notes.length} ponto(s) pra revisar à mão (gerados como // TODO):`)
+    for (const n of notes) console.log(`    ! ${n}`)
+  }
+  log('dim', '\n  Rascunho — revise antes de `opus db migrate`.')
+}
+
+// =============================================================================
+// Runner spawn (via tsx)
+// =============================================================================
+
+async function runRunner(runnerFile, configPath, extraArgs = []) {
+  const tsxBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
+  const hasLocalTsx = await fileExists(tsxBin)
+  const runnerPath = path.join(__dirname, runnerFile)
+  const cmd = hasLocalTsx ? tsxBin : 'tsx'
+
+  try {
+    const { stdout } = await execFileAsync(cmd, [runnerPath, configPath, ...extraArgs], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      env: { ...process.env },
+    })
+    const line = lastJsonLine(stdout)
+    if (line === null) return { ok: false, error: 'runner não emitiu JSON' }
+    return JSON.parse(line)
+  } catch (err) {
+    const detail =
+      typeof err.stderr === 'string' && err.stderr.trim().length > 0
+        ? err.stderr.trim()
+        : err.message
+    return { ok: false, error: detail }
+  }
+}
+
+function lastJsonLine(stdout) {
+  const lines = stdout.split('\n').filter((l) => l.trim().length > 0)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const trimmed = lines[i].trim()
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) return trimmed
+  }
+  return null
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// =============================================================================
+// Help
+// =============================================================================
+
+export function helpDb() {
+  console.log(`
+@softize/opus db — comandos de banco
+
+  db check         Compara o schema do banco com as entidades (defineEntity) — drift-check.
+                   Read-only. Exit ≠ 0 se divergir. Gate de CI/deploy.
+  db migrate       Aplica o SCHEMA IDEMPOTENTE (config \`schema\`, script SQL evolutivo:
+                   IF NOT EXISTS + guards — nasce do zero E faz upgrade no mesmo artefato,
+                   re-rodável) e roda o drift-check na sequência. Exit ≠ 0 se divergir.
+  db scaffold      Gera um rascunho kysely a partir do diff — REFERÊNCIA pra escrever o
+                   SQL no schema (a verdade é o script; revise à mão).
+
+Flags:
+  --config <path>   Caminho do opus.config.ts. Default: ./opus.config.ts
+
+O opus.config.ts precisa expor, pros comandos db:
+  database: () => Kysely          factory LAZY do banco (gen não a chama)
+  entities | domains              entidades (explícitas ou via domain.models)
+  schema?: string                 script SQL idempotente (default: ./db/schema.sql)
+  migrations?: string             pasta dos rascunhos do scaffold (default: ./migrations)
+
+Exemplos:
+  npx @softize/opus db check
+  npx @softize/opus db migrate
+  npx @softize/opus db migrate down --config ./apps/api/opus.config.ts
+`)
+}

package/bin/lib/docs-include.mjs

@@ -0,0 +1,48 @@
+/**
+ * docs-include — transclusão de páginas da doc pra dentro de SKILLS na materialização.
+ *
+ * O modelo da casa: a DOC é a fonte do conhecimento (humano lê no site; viaja no
+ * pacote); a SKILL é o gatilho do agente. Ponteiro não garante consulta — transclusão
+ * garante: a skill declara `<!-- opus-doc: <página>.md -->` e quem MATERIALIZA (o
+ * prepare do admin; o caminho vivo do Maestro) expande o conteúdo da página pra dentro
+ * do corpo, que o mecanismo de skill carrega no contexto. Edita-se a página, nunca a
+ * cópia — fonte única, entrega derivada (o mesmo padrão do manifest).
+ *
+ * Página inexistente = ERRO (deploy para — skill apontando doc morta é defeito, igual
+ * ao gate de frontmatter). A expansão tira o frontmatter e o H1 da página (a skill já
+ * titula a própria seção).
+ */
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CONTENT_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'src',
+  'ui',
+  'docs',
+  'content',
+)
+
+const MARKER_RE = /^[ \t]*<!--\s*opus-doc:\s*([\w./-]+)\s*-->[ \t]*$/gm
+
+/** Expande os markers `<!-- opus-doc: x.md -->` de um corpo de skill. */
+export function expandDocIncludes(md) {
+  return md.replace(MARKER_RE, (_marker, file) => {
+    const name = path.basename(String(file)) // só o nome — sem traversal.
+    const full = path.join(CONTENT_DIR, name)
+    let raw
+    try {
+      raw = readFileSync(full, 'utf8')
+    } catch {
+      throw new Error(`opus-doc include: a página "${name}" não existe em ${CONTENT_DIR} — corrija a skill.`)
+    }
+    return raw
+      .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
+      .replace(/^\s*# .*\r?\n/, '')
+      .trim()
+  })
+}