@softize/opus 13.0.0 → 14.0.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

@@ -107,8 +107,16 @@ const JSX_CHILD_ROLES = new Map([
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsTrigger', 'tab'],
+  // A Base não tem papel `tooltip`. O tooltip nomeia um controle icon-only, logo é um
+  // fragmento (sem ponto final), não uma frase; `label` é o papel que reflete isso.
+  ['TooltipContent', 'label'],
 ])
 
+// Componentes cuja copy entra pelas próprias props e que, como filhos, não acrescentam
+// texto ao pai: `<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>` inventaria `Nome`
+// como label e a ajuda como helper-text, sem tornar o filho opaco.
+const SELF_CONTAINED_CHILD_COMPONENTS = new Set(['LabelHelp'])
+
 const OPTIONAL_CHILD_COMPONENTS = new Set(['ActionForm', 'ActionFormCard', 'ActionFormDialog'])
 const JSX_ACTION_CONSUMERS = new Set([
   'ActionForm', 'ActionFormCard', 'ActionFormDialog', 'ActionList', 'ActionListDialog', 'ActionTrigger', 'ActionView',
@@ -125,6 +133,14 @@ const JSX_PROP_ROLES = new Map([
   ['ActionForm', new Map([['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormCard', new Map([['title', 'title'], ['description', 'description'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormDialog', new Map([['title', 'title'], ['description', 'dialog-body'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  // Estados unificados (14.0): a mesma tríade de mensagens em ActionList, ActionListDialog,
+  // DataState e PageState; ActionView só tem o vazio.
+  ['ActionList', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
+  ['ActionListDialog', new Map([
+    ['title', 'title'], ['description', 'dialog-body'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
+  ['ActionView', new Map([['emptyMessage', 'empty-state']])],
   // `itemLabel` identifica o dado alvo (por exemplo, `customer.name`); não é
   // microcopy estável e, por isso, não pertence ao inventário editorial.
   ['ActionTrigger', new Map([['label', 'button']])],
@@ -132,7 +148,7 @@ const JSX_PROP_ROLES = new Map([
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
   ['Content', new Map([['title', 'title'], ['description', 'description']])],
   ['ContentHeader', new Map([['title', 'title'], ['description', 'description']])],
-  ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  ['DataState', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
   // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
   // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
   ['Dock', new Map([['label', 'label']])],
@@ -140,8 +156,14 @@ const JSX_PROP_ROLES = new Map([
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],
+  // A ajuda vive num tooltip (portal): não herda transformação nem classe do label.
+  ['LabelHelp', new Map([['help', 'helper-text']])],
   ['MetricCard', new Map([['label', 'label'], ['description', 'description']])],
   ['Page', new Map([['title', 'title'], ['description', 'description']])],
+  ['PageState', new Map([
+    ['title', 'title'], ['description', 'description'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
   ['Select', new Map([
     ['placeholder', 'placeholder'],
     ['searchPlaceholder', 'placeholder'],
@@ -215,6 +237,36 @@ const JSX_PORTAL_BOUNDARIES = new Set([
   'PopoverContent', 'TooltipContent',
 ])
 
+// Respostas imperativas `dialog.*` da UI Opus. O DialogHost renderiza em portal com classes
+// próprias; nenhuma transformação do chamador alcança o texto.
+const DIALOG_METHOD_ROLES = new Map([
+  ['alert', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'], ['action', 'button']])],
+  ['confirm', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'],
+  ])],
+  ['prompt', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'], ['placeholder', 'placeholder'],
+  ])],
+  ['choose', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body']])],
+])
+
+// Métodos de array que não mutam o receptor. Os que devolvem os próprios elementos (num
+// array novo ou avulsos) exigem que o resultado também seja usado de forma estável; os
+// demais só produzem primitivos, novos objetos ou nada.
+const ARRAY_RETURNING_ARRAY_METHODS = new Set(['concat', 'filter', 'flat', 'slice', 'toReversed', 'toSorted'])
+const ELEMENT_PICKING_ARRAY_METHODS = new Set(['at', 'find', 'findLast'])
+const ELEMENT_ITERATING_ARRAY_METHODS = new Set([
+  'every', 'filter', 'find', 'findIndex', 'findLast', 'findLastIndex', 'flatMap', 'forEach', 'map', 'some',
+])
+const READ_ONLY_ARRAY_METHODS = new Set([
+  ...ARRAY_RETURNING_ARRAY_METHODS, ...ELEMENT_PICKING_ARRAY_METHODS, ...ELEMENT_ITERATING_ARRAY_METHODS,
+  'includes', 'indexOf', 'join', 'lastIndexOf',
+])
+// Cadeia que preserva os elementos entre o array literal e a iteração que os lê.
+const ELEMENT_PRESERVING_ARRAY_METHODS = new Set(['filter', 'slice', 'toReversed', 'toSorted'])
+
 const digest = (content) => createHash('sha256').update(content).digest('hex')
 const portable = (value) => value.split(path.sep).join('/')
 
@@ -421,6 +473,17 @@ function knownBindAction(call, checker) {
   return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
 }
 
+/** Reconhece `dialog.confirm({...})` e `Opus.dialog.alert({...})` importados da UI Opus. */
+function knownDialogCall(call, checker) {
+  const callee = unwrap(call.expression)
+  if (
+    ts.isPropertyAccessExpression(callee) &&
+    DIALOG_METHOD_ROLES.has(callee.name.text) &&
+    importedMemberName(callee.expression, checker, uiModule) === 'dialog'
+  ) return { method: callee.name.text, field: `dialog.${callee.name.text}()` }
+  return null
+}
+
 function safeBindActionBinding(call, checker) {
   if (call.arguments.length < 2) return false
   const binding = unwrap(call.arguments[1])
@@ -521,6 +584,16 @@ function stableExpressionUse(node, checker, mode, stack) {
   const parent = carrier.parent
 
   if (assignmentTarget(carrier)) return false
+  if (consumerMode === 'aggregate' && ts.isCallExpression(parent) && parent.expression === carrier) {
+    const access = unwrap(carrier)
+    return (
+      ts.isPropertyAccessExpression(access) && arrayValued(access.expression, checker) &&
+      readOnlyArrayMethodUse(access.name.text, parent, checker, stack)
+    )
+  }
+  if (ts.isForOfStatement(parent) && parent.expression === carrier) {
+    return consumerMode === 'aggregate' && arrayValued(carrier, checker) && readOnlyForOfBinding(parent, checker)
+  }
   if (ts.isVariableDeclaration(parent) && parent.initializer === carrier) {
     if (!ts.isVariableDeclarationList(parent.parent) || (parent.parent.flags & ts.NodeFlags.Const) === 0) return false
     const aliases = bindingNames(parent.name, checker)
@@ -534,6 +607,8 @@ function stableExpressionUse(node, checker, mode, stack) {
   if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
     if (consumerMode === 'aggregate') {
       if (knownDictionaryFactory(parent, checker)) return true
+      // O DialogHost copia as opções (`{ ...options }`) e só as lê; nada muta o literal.
+      if (parent.arguments[0] === carrier && knownDialogCall(parent, checker) !== null) return true
       return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
     }
     if (
@@ -573,6 +648,166 @@ function stableReferences(binding, checker, mode, stack) {
   return stable
 }
 
+/**
+ * Um parâmetro de callback (ou variável de `for…of`) é somente leitura quando cada uso é
+ * `elemento.chave` fora de posição de atribuição. Strings são imutáveis, então uma leitura de
+ * propriedade nunca altera o rótulo literal; qualquer outro uso (spread, argumento, retorno,
+ * atribuição) poderia mutar ou fazer o objeto escapar e é rejeitado. Destructuring copia os
+ * valores de primeiro nível e, por isso, também não alcança o literal.
+ */
+function readOnlyElementBinding(name, checker) {
+  if (ts.isObjectBindingPattern(name)) return true
+  if (!ts.isIdentifier(name)) return false
+  const symbol = bindingSymbol(name, checker)
+  if (symbol === undefined) return false
+  let readOnly = true
+  const visit = (node) => {
+    if (!readOnly) return
+    if (ts.isIdentifier(node) && sameBinding(node, symbol, checker) && !declarationIdentifier(node, symbol)) {
+      const carrier = transparentCarrier(node)
+      const access = carrier.parent
+      readOnly =
+        (ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access)) &&
+        access.expression === carrier && !assignmentTarget(access)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(name.getSourceFile())
+  return readOnly
+}
+
+function readOnlyCallback(callback, checker) {
+  const value = callback === undefined ? null : unwrap(callback)
+  if (value === null || (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value))) return false
+  // O terceiro parâmetro expõe o próprio array ao callback; índice e `thisArg` não.
+  if (value.parameters.length > 2) return false
+  const element = value.parameters[0]
+  if (element === undefined) return true
+  if (element.dotDotDotToken !== undefined || element.initializer !== undefined) return false
+  return readOnlyElementBinding(element.name, checker)
+}
+
+function readOnlyArrayMethodUse(method, call, checker, stack) {
+  if (!READ_ONLY_ARRAY_METHODS.has(method)) return false
+  if (ELEMENT_ITERATING_ARRAY_METHODS.has(method) && !readOnlyCallback(call.arguments[0], checker)) return false
+  if (ARRAY_RETURNING_ARRAY_METHODS.has(method) || ELEMENT_PICKING_ARRAY_METHODS.has(method)) {
+    return stableExpressionUse(call, checker, 'aggregate', stack)
+  }
+  return true
+}
+
+/**
+ * A semântica somente leitura de `map`, `filter`… vale para arrays. Um objeto literal pode
+ * declarar um método com o mesmo nome e mutar o que quiser; por isso o receptor precisa ser
+ * um `const` com array literal ou o resultado de um método que devolve array sobre ele.
+ */
+function arrayValued(node, checker) {
+  const value = unwrap(node)
+  if (ts.isIdentifier(value)) {
+    const binding = constInitializer(value, checker)
+    return binding !== null && ts.isArrayLiteralExpression(unwrap(binding.initializer))
+  }
+  if (ts.isCallExpression(value)) {
+    const callee = unwrap(value.expression)
+    return ts.isPropertyAccessExpression(callee) && ARRAY_RETURNING_ARRAY_METHODS.has(callee.name.text) &&
+      arrayValued(callee.expression, checker)
+  }
+  return ts.isArrayLiteralExpression(value)
+}
+
+function readOnlyForOfBinding(statement, checker) {
+  const initializer = statement.initializer
+  if (!ts.isVariableDeclarationList(initializer) || initializer.declarations.length !== 1) return false
+  return readOnlyElementBinding(initializer.declarations[0].name, checker)
+}
+
+/**
+ * Localiza o array literal do qual um identificador é elemento: parâmetro de callback de
+ * `map`/`forEach`/`filter`… ou variável de `for…of`, possivelmente atrás de `filter`,
+ * `slice`, `toSorted` e `toReversed`, que preservam os elementos. Só arrays literais no
+ * mesmo arquivo entram; qualquer outra origem devolve null.
+ */
+function elementSource(identifier, checker) {
+  const symbol = bindingSymbol(identifier, checker)
+  const declaration = symbol?.declarations?.find(
+    (item) => ts.isParameter(item) || ts.isBindingElement(item) || ts.isVariableDeclaration(item),
+  )
+  if (declaration === undefined) return null
+
+  let key = null
+  let binding = declaration
+  if (ts.isBindingElement(declaration)) {
+    if (declaration.dotDotDotToken !== undefined || declaration.initializer !== undefined) return null
+    const pattern = declaration.parent
+    if (!ts.isObjectBindingPattern(pattern) || (!ts.isParameter(pattern.parent) && !ts.isVariableDeclaration(pattern.parent))) return null
+    const keyNode = declaration.propertyName ?? declaration.name
+    if (!ts.isIdentifier(keyNode) && !ts.isStringLiteral(keyNode)) return null
+    key = keyNode.text
+    binding = pattern.parent
+  }
+
+  let receiver
+  if (ts.isParameter(binding)) {
+    if (binding.dotDotDotToken !== undefined || binding.initializer !== undefined) return null
+    const callback = binding.parent
+    if ((!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) || callback.parameters[0] !== binding) return null
+    const call = transparentCarrier(callback).parent
+    if (!ts.isCallExpression(call) || call.arguments[0] !== transparentCarrier(callback)) return null
+    const callee = unwrap(call.expression)
+    if (!ts.isPropertyAccessExpression(callee) || !ELEMENT_ITERATING_ARRAY_METHODS.has(callee.name.text)) return null
+    receiver = callee.expression
+  } else if (ts.isVariableDeclaration(binding)) {
+    const list = binding.parent
+    if (!ts.isVariableDeclarationList(list) || !ts.isForOfStatement(list.parent) || list.parent.initializer !== list) return null
+    receiver = list.parent.expression
+  } else return null
+
+  let source = unwrap(receiver)
+  while (
+    ts.isCallExpression(source) && ts.isPropertyAccessExpression(unwrap(source.expression)) &&
+    ELEMENT_PRESERVING_ARRAY_METHODS.has(unwrap(source.expression).name.text)
+  ) source = unwrap(unwrap(source.expression).expression)
+  const array = resolveBinding(source, checker)
+  return ts.isArrayLiteralExpression(array) ? { array, key } : null
+}
+
+/**
+ * Resolve `elemento.chave` (ou a chave destruturada) para o texto literal de cada elemento
+ * do array de origem. Um único elemento opaco ou sem texto estático torna o conjunto todo
+ * inextraível: o inventário não pode listar só parte do que a superfície renderiza.
+ */
+function elementTexts(node, checker) {
+  const value = unwrap(node)
+  let identifier
+  let key = null
+  if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.name.text
+  } else if (ts.isElementAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.argumentExpression === undefined ? null : staticText(value.argumentExpression, checker)?.text ?? null
+  } else if (ts.isIdentifier(value)) {
+    identifier = value
+  } else return null
+  const source = elementSource(identifier, checker)
+  if (source === null) return null
+  if (ts.isIdentifier(value)) key = source.key
+  else if (source.key !== null) return null
+  if (key === null) return null
+
+  const listed = objects(source.array, checker)
+  if (listed.opaque.length > 0 || listed.values.length === 0) return null
+  const texts = []
+  for (const element of listed.values) {
+    const resolved = property(element, key, element.getSourceFile(), checker)
+    if (resolved.opaque !== undefined || resolved.candidate === undefined) return null
+    const text = staticText(propertyValue(resolved.candidate), checker)
+    if (text === null) return null
+    texts.push(text)
+  }
+  return texts
+}
+
 /**
  * Objetos e arrays `const` continuam mutáveis. A extração só faz fold quando cada uso
  * está numa allowlist observável: composição `const` igualmente estável, factory Opus
@@ -982,7 +1217,6 @@ export function extractCopyFromSource(file, sourceText) {
   const field = (object, prefix) => {
     addProperty(object, 'label', 'label', prefix)
     addProperty(object, 'placeholder', 'placeholder', prefix)
-    addProperty(object, 'hint', 'helper-text', prefix)
     addProperty(object, 'help', 'helper-text', prefix)
     nestedObject(object, 'options', optionItems, prefix)
   }
@@ -1384,6 +1618,11 @@ export function extractCopyFromSource(file, sourceText) {
         ? { kind: 'decorative' }
         : { kind: 'text', ...text, uppercase: inheritedUppercase }
     }
+    const listed = elementTexts(value, checker)
+    if (listed !== null) {
+      const values = listed.map((item) => ({ kind: 'text', ...item, uppercase: inheritedUppercase }))
+      return values.length === 1 ? values[0] : { kind: 'alternatives', values, node: values[0].node }
+    }
     if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value)) {
       return childNode(value, inheritedUppercase, hiddenAncestor)
     }
@@ -1439,6 +1678,9 @@ export function extractCopyFromSource(file, sourceText) {
     if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
       const opening = ts.isJsxElement(child) ? child.openingElement : child
       const component = opusComponent(opening.tagName)
+      if (component !== null && SELF_CONTAINED_CHILD_COMPONENTS.has(component) && ts.isJsxSelfClosingElement(child)) {
+        return { kind: 'decorative' }
+      }
       const provenElement = transformableElement(opening, component)
       const hidden = attribute(opening.attributes, 'aria-hidden')
       if (hidden.opaque !== undefined) return { kind: 'opaque', node: hidden.opaque }
@@ -1593,7 +1835,10 @@ export function extractCopyFromSource(file, sourceText) {
     if (component === null) return
     let inherited
     const inheritedFor = (className, styleName, portal = false) => {
-      if (portal || localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
+      // Um componente que renderiza em portal (TooltipContent) não é descendente visual
+      // dos ancestrais no JSX; a transformação deles não alcança o texto.
+      if (portal || JSX_PORTAL_BOUNDARIES.has(component)) return false
+      if (localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
       inherited ??= ancestorTransform(element)
       return inherited.opaque ? false : inherited.uppercase
     }
@@ -1676,7 +1921,11 @@ export function extractCopyFromSource(file, sourceText) {
           }
         } else {
           const value = raw === null ? null : attributeText(item)
-          if (value === null) {
+          // `title={group.label}` dentro de `GROUPS.map(...)`: cada literal do array local
+          // vira um texto na própria linha, em vez de um diagnóstico sobre a prop.
+          const listed = value === null && raw !== null ? elementTexts(raw, checker) : null
+          const texts = value !== null ? [value] : listed ?? []
+          if (texts.length === 0) {
             diagnostics.push(diagnostic(
               file,
               sourceFile,
@@ -1685,8 +1934,8 @@ export function extractCopyFromSource(file, sourceText) {
               raw === null ? 'missing-content' : 'content',
             ))
           }
-          else {
-            const entry = { source: file, line: lineOf(sourceFile, value.node), role, text: value.text }
+          for (const text of texts) {
+            const entry = { source: file, line: lineOf(sourceFile, text.node), role, text: text.text }
             if (transformed.uppercase) entry.transform = 'uppercase'
             entries.push(entry)
           }
@@ -1838,7 +2087,28 @@ export function extractCopyFromSource(file, sourceText) {
     }
   }
 
+  /**
+   * `dialog.confirm({ title, description, action })` é copy tão editorial quanto a de um
+   * `<ActionFormDialog>`; a chamada só é imperativa. Um template com interpolação
+   * (`description: describe(name)`) cai no diagnóstico `content` normal, declarável em
+   * `copy.dynamic` como `message-template`.
+   */
+  function extractDialog(call, { method, field }) {
+    const raw = call.arguments[0]
+    const options = raw === undefined ? null : resolveBinding(raw, checker)
+    if (options === null || !ts.isObjectLiteralExpression(options)) {
+      diagnostics.push(diagnostic(file, sourceFile, raw ?? call, `${field} options`, 'structure'))
+      return
+    }
+    for (const [name, role] of DIALOG_METHOD_ROLES.get(method)) addVisualObjectProperty(options, name, role, `${field}.`)
+    if (method === 'choose') {
+      nestedObject(options, 'actions', (action, prefix) => addVisualObjectProperty(action, 'label', 'button', prefix), `${field}.`)
+    }
+  }
+
   function visit(node) {
+    const dialogCall = ts.isCallExpression(node) ? knownDialogCall(node, checker) : null
+    if (dialogCall !== null) extractDialog(node, dialogCall)
     const factory = ts.isCallExpression(node) ? contractFactory(node.expression) : null
     if (ts.isCallExpression(node) && factory !== null && node.arguments.length > 0) {
       hasContract = true

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
 `)
 }