@softize/opus 12.11.0 → 13.1.0

package/bin/lib/cli-shared.mjs

@@ -0,0 +1,131 @@
+/**
+ * Utilitários compartilhados pelos comandos do CLI `opus`.
+ *
+ * Concentra o que mais de um comando repetia: log colorido no terminal, teste de
+ * existência de arquivo, resolução do `opus.config.ts` do consumer e o spawn do `tsx`
+ * que carrega esse config TypeScript num runner isolado (`gen`, `db` e `seed` usam a
+ * mesma infra: o runner emite uma linha JSON na última linha de stdout).
+ */
+
+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, safeProjectPath } from '@softize/base/project-path'
+
+const execFileAsync = promisify(execFile)
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+export const CONFIG_FILE = 'opus.config.ts'
+
+// =============================================================================
+// Log
+// =============================================================================
+
+const COLORS = {
+  info: '\x1b[36m',
+  success: '\x1b[32m',
+  error: '\x1b[31m',
+  warn: '\x1b[33m',
+  dim: '\x1b[2m',
+}
+const RESET = '\x1b[0m'
+
+/** Escreve uma linha colorida em stdout. Nível desconhecido sai sem cor. */
+export function log(level, message) {
+  console.log(`${COLORS[level] ?? ''}${message}${RESET}`)
+}
+
+// =============================================================================
+// FS
+// =============================================================================
+
+export async function fileExists(file) {
+  try {
+    await fs.access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// =============================================================================
+// Config do consumer
+// =============================================================================
+
+/**
+ * Resolve o `opus.config.ts` a partir de `flags.config` (default: `./opus.config.ts`),
+ * contido no projeto. Lança `Error` com uma mensagem única quando o arquivo não existe;
+ * cada comando decide o canal (texto ou JSON) e o código de saída.
+ */
+export function resolveConfig(flags, cwd = process.cwd()) {
+  const root = canonicalProjectDirectory(cwd)
+  const config = safeProjectPath(root, flags.config ?? CONFIG_FILE)
+  if (!config.exists) {
+    throw new Error(
+      `${CONFIG_FILE} não encontrado em ${config.path}. ` +
+        'Passe o caminho com --config <path> ou crie o arquivo na raiz do projeto.',
+    )
+  }
+  return { cwd: root, configPath: config.path }
+}
+
+// =============================================================================
+// Runner via tsx
+// =============================================================================
+
+/**
+ * Binário do tsx: o empacotado em `<package>/node_modules/.bin/tsx` quando existe
+ * (independe do PATH do consumer); senão confia no `tsx` do PATH.
+ */
+export async function resolveTsxBin() {
+  const local = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
+  return (await fileExists(local)) ? local : 'tsx'
+}
+
+/**
+ * Executa `tsx <runnerPath> ...args` capturando stdout/stderr em utf8 e herdando o
+ * ambiente. Rejeita como o `execFile` (o erro traz `stdout` e `stderr`) quando o
+ * processo falha.
+ */
+export async function spawnTsx(runnerPath, args, { maxBuffer = 16 * 1024 * 1024 } = {}) {
+  const command = await resolveTsxBin()
+  return execFileAsync(command, [runnerPath, ...args], {
+    encoding: 'utf8',
+    maxBuffer,
+    env: { ...process.env },
+  })
+}
+
+/**
+ * Última linha de stdout que parece um objeto JSON. Logs do consumer durante o
+ * import do config vão para o início; o runner emite o payload por último.
+ */
+export function lastJsonLine(stdout) {
+  const lines = stdout.split('\n').filter((line) => line.trim().length > 0)
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = lines[index].trim()
+    if (line.startsWith('{') && line.endsWith('}')) return line
+  }
+  return null
+}
+
+/**
+ * Roda um runner que responde `{ ok, ... }` em JSON. Nunca rejeita: falha de spawn ou
+ * ausência de payload viram `{ ok: false, error }` para o comando reportar.
+ */
+export async function runJsonRunner(runnerPath, args, options) {
+  try {
+    const { stdout } = await spawnTsx(runnerPath, args, options)
+    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().length > 0
+        ? error.stderr.trim()
+        : error.message
+    return { ok: false, error: detail }
+  }
+}

package/bin/lib/copy.mjs

@@ -71,10 +71,6 @@ const JSX_CHILD_ROLES = new Map([
   ['ActionFormCard', 'message'],
   ['ActionFormDialog', 'message'],
   ['AlertDescription', 'message'],
-  ['AlertDialogAction', 'button'],
-  ['AlertDialogCancel', 'button'],
-  ['AlertDialogDescription', 'dialog-body'],
-  ['AlertDialogTitle', 'title'],
   ['AlertTitle', 'title'],
   ['Badge', 'badge'],
   ['BreadcrumbLink', 'breadcrumb'],
@@ -215,7 +211,7 @@ const JSX_PROP_STYLE = new Map([
 ])
 
 const JSX_PORTAL_BOUNDARIES = new Set([
-  'AlertDialogContent', 'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
+  'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
   'PopoverContent', 'TooltipContent',
 ])
 

package/bin/lib/db.mjs

@@ -10,31 +10,12 @@
  * 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'
-import { canonicalProjectDirectory, safeProjectPath } from '@softize/base/project-path'
 
-const execFileAsync = promisify(execFile)
+import { log, resolveConfig, runJsonRunner } from './cli-shared.mjs'
 
-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}`)
-}
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 // =============================================================================
 // Dispatch
@@ -67,17 +48,13 @@ export async function cmdDb(rest, flags) {
 // Config
 // =============================================================================
 
-async function resolveConfig(flags) {
-  const cwd = canonicalProjectDirectory(process.cwd())
-  const configRel = flags.config ?? 'opus.config.ts'
-  const config = safeProjectPath(cwd, configRel)
-  const configPath = config.path
-  if (!config.exists) {
-    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.')
+function resolveConfigOrExit(flags) {
+  try {
+    return resolveConfig(flags)
+  } catch (error) {
+    log('error', error instanceof Error ? error.message : String(error))
     process.exit(1)
   }
-  return { cwd, configPath }
 }
 
 // =============================================================================
@@ -85,7 +62,7 @@ async function resolveConfig(flags) {
 // =============================================================================
 
 async function cmdDbCheck(flags) {
-  const { cwd, configPath } = await resolveConfig(flags)
+  const { cwd, configPath } = resolveConfigOrExit(flags)
   log('info', `→ drift-check via ${path.relative(cwd, configPath)}...`)
 
   const result = await runRunner('db-check-runner.mjs', configPath)
@@ -128,7 +105,7 @@ async function cmdDbMigrate(sub2, flags) {
     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)
+  const { cwd, configPath } = resolveConfigOrExit(flags)
   log('info', `→ db migrate via ${path.relative(cwd, configPath)}...`)
 
   const result = await runRunner('db-migrate-runner.mjs', configPath)
@@ -163,7 +140,7 @@ async function cmdDbMigrate(sub2, flags) {
 // =============================================================================
 
 async function cmdDbScaffold(flags) {
-  const { cwd, configPath } = await resolveConfig(flags)
+  const { cwd, configPath } = resolveConfigOrExit(flags)
   log('info', `→ db scaffold via ${path.relative(cwd, configPath)}...`)
 
   const result = await runRunner('db-scaffold-runner.mjs', configPath)
@@ -188,46 +165,8 @@ async function cmdDbScaffold(flags) {
 // 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
-  }
+function runRunner(runnerFile, configPath, extraArgs = []) {
+  return runJsonRunner(path.join(__dirname, runnerFile), [configPath, ...extraArgs])
 }
 
 // =============================================================================
@@ -245,9 +184,12 @@ export function helpDb() {
                    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).
+  db migrate down  Aposentado: encerra com erro. O schema é um script idempotente sem
+                   histórico a reverter; rollback = editar o script e rodar db migrate.
 
 Flags:
   --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
+  --help, -h        Mostra esta mensagem
 
 O opus.config.ts precisa expor, pros comandos db:
   database: () => Kysely          factory LAZY do banco (gen não a chama)
@@ -258,6 +200,6 @@ O opus.config.ts precisa expor, pros comandos db:
 Exemplos:
   npx @softize/opus db check
   npx @softize/opus db migrate
-  npx @softize/opus db migrate down --config ./apps/api/opus.config.ts
+  npx @softize/opus db scaffold --config ./apps/api/opus.config.ts
 `)
 }

package/bin/lib/gen-openapi.mjs

@@ -82,15 +82,15 @@ function buildResponses(action) {
   const successStatus = String(action.successStatus ?? 200)
   return {
     [successStatus]: {
-      description: 'Success',
+      description: 'Sucesso',
       content: {
         'application/json': {
           schema: wrapEnvelope(action.output, action.kind),
         },
       },
     },
-    '4XX': errorResponse('Client error', action.errors),
-    '5XX': errorResponse('Server error'),
+    '4XX': errorResponse('Erro do cliente', action.errors),
+    '5XX': errorResponse('Erro do servidor'),
   }
 }
 

package/bin/lib/gen-runner.mjs

@@ -75,7 +75,7 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
 async function main() {
   const configPath = process.argv[2]
   if (typeof configPath !== 'string' || configPath.length === 0) {
-    return emitError('Missing config path argv[2]')
+    return emitError('Caminho do config ausente (argv[2])')
   }
 
   const configAbs = path.resolve(configPath)

package/bin/lib/gen.mjs

@@ -16,17 +16,13 @@
  *   - config: ./opus.config.ts (no cwd)
  *   - output: o que o config disser, ou ./.gen
  *
- * Flag `--force`: sobrescreve arquivos existentes (default sobrescreve
- * silenciosamente — opus gen é idempotente e o output mora num dir
- * dedicado, então não há valor real em bloquear sem --force. Mantemos a
- * flag pra paridade com `add`).
+ * Flag `--force`: aceita por compatibilidade, sem efeito — o gen sempre
+ * sobrescreve (é idempotente e o output mora num dir dedicado, então não
+ * há valor real em bloquear a escrita).
  */
 
-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'
 import {
   canonicalProjectDirectory,
   ensureProjectDirectory,
@@ -42,46 +38,25 @@ import { buildOpenAPI } from './gen-openapi.mjs'
 import { buildDocs } from './gen-docs.mjs'
 import { buildClientStubs } from './gen-stubs.mjs'
 import { buildDictStubs } from './gen-dicts.mjs'
-
-const execFileAsync = promisify(execFile)
+import { lastJsonLine, log, resolveConfig, spawnTsx } from './cli-shared.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
-const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
 const RUNNER_PATH = path.join(__dirname, 'gen-runner.mjs')
 
-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}`)
-}
-
 // =============================================================================
 // Comando
 // =============================================================================
 
 export async function cmdGen(flags) {
-  const cwd = canonicalProjectDirectory(process.cwd())
-  const configRel = flags.config ?? 'opus.config.ts'
-  const config = safeProjectPath(cwd, configRel)
-  const configPath = config.path
-
-  if (!config.exists) {
-    log('error', `opus.config.ts não encontrado em ${configPath}`)
-    log(
-      'dim',
-      '  Cria um arquivo na raiz do projeto exportando `{ domains: [...] }` como default,',
-    )
-    log('dim', '  ou passa o path via --config <path>.')
+  let resolved
+  try {
+    resolved = resolveConfig(flags)
+  } catch (error) {
+    log('error', error instanceof Error ? error.message : String(error))
     process.exit(1)
   }
+  const { cwd, configPath } = resolved
 
   log('info', `→ Carregando ${path.relative(cwd, configPath)}...`)
 
@@ -190,22 +165,12 @@ function auditDocs(manifest, cwd) {
 // =============================================================================
 
 async function loadConfig(configPath) {
-  // tsx mora em <package>/node_modules/.bin/tsx — usamos absoluto pra
-  // evitar depender de PATH do consumer.
-  const tsxBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
-  const hasLocalTsx = await fileExists(tsxBin)
-
-  // Args do runner: <runner.mjs> <configPath>. tsx aceita .mjs também
-  // (passthrough) e nos permite resolver TS na cadeia de imports.
-  const args = [RUNNER_PATH, configPath]
-  const cmd = hasLocalTsx ? tsxBin : 'tsx'
-
+  // tsx aceita .mjs também (passthrough) e nos permite resolver TS na cadeia
+  // de imports do config.
   try {
     // Buffer grande pra acomodar manifests gordos.
-    const { stdout, stderr } = await execFileAsync(cmd, args, {
-      encoding: 'utf8',
+    const { stdout, stderr } = await spawnTsx(RUNNER_PATH, [configPath], {
       maxBuffer: 64 * 1024 * 1024,
-      env: { ...process.env },
     })
 
     // Runner emite a linha JSON na ÚLTIMA linha de stdout. Qualquer log do
@@ -236,30 +201,10 @@ async function loadConfig(configPath) {
   }
 }
 
-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
-}
-
 // =============================================================================
 // FS helpers
 // =============================================================================
 
-async function fileExists(p) {
-  try {
-    await fs.access(p)
-    return true
-  } catch {
-    return false
-  }
-}
-
 function ensureProjectTree(root, requested) {
   let cursor = '.'
   for (const segment of requested.split(path.sep).filter((item) => item !== '' && item !== '.')) {
@@ -332,7 +277,7 @@ Lê opus.config.ts do consumer e gera:
 Flags:
   --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
   --output <path>   Pasta interna ao projeto. Default: do config (ou ./.gen)
-  --force, -f       Sobrescreve existente (atualmente sempre sobrescreve)
+  --force, -f       Aceita por compatibilidade; sem efeito, o gen sempre sobrescreve a saída
 
 Exemplos:
   npx @softize/opus gen

package/bin/lib/mcp.mjs

@@ -11,6 +11,7 @@
  *   opus_get_component   — detalhe de um componente pelo nome
  */
 
+import { createRequire } from 'node:module'
 import path from 'node:path'
 import { z } from 'zod'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -23,10 +24,11 @@ const asText = (data) => ({
   content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
 })
 const dirOf = (d) => path.resolve(process.cwd(), d ?? '.')
+const { version: OPUS_VERSION } = createRequire(import.meta.url)('../../package.json')
 
 /** Monta o McpServer com as tools da base. Exportado pra testar (transport in-memory). */
 export function buildServer() {
-  const server = new McpServer({ name: 'opus', version: '0.0.0' })
+  const server = new McpServer({ name: 'opus', version: OPUS_VERSION })
 
   server.registerTool(
     'opus_introspect',

package/bin/lib/seed.mjs

@@ -1,30 +1,13 @@
 /** 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'
+import { readProjectFile } 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, '..', '..')
+import { log, resolveConfig, runJsonRunner } from './cli-shared.mjs'
 
-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}`)
-}
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 export function findAdHocSeedScripts(scripts = {}) {
   return Object.entries(scripts).flatMap(([name, command]) => {
@@ -116,14 +99,6 @@ function fail(flags, 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 []
@@ -140,22 +115,8 @@ function readSeedScriptFindings(cwd) {
   }))
 }
 
-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 runRunner(configPath, extraArgs) {
+  return runJsonRunner(path.join(__dirname, 'seed-runner.mjs'), [configPath, ...extraArgs])
 }
 
 function printList(seeds) {
@@ -188,24 +149,6 @@ 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