@softize/opus 8.6.6

package/bin/lib/gen-dicts.mjs

@@ -0,0 +1,134 @@
+/**
+ * gen-dicts — emite módulos TS por domínio com `t.dict({...})`
+ * reconstruído a partir do manifest.
+ *
+ * Por quê: o `manifest.json` carrega `dicts: { Name: { keys, values } }`,
+ * mas o frontend precisa do código TS pra usar `dict.has() / .metaFor() /
+ * .options()` com inferência de tipo. Sem isso o consumer mantinha cópia
+ * manual sincronizada à mão — bug-source clássico.
+ *
+ * Estrutura emitida (um arquivo por domínio raiz, achata subdomains numa
+ * mesma saída pra refletir o agrupamento dos outros emits):
+ *
+ *   // AUTO-GERADO por @softize/opus gen. Não edite.
+ *   // Domínio raiz: ticket
+ *
+ *   import { t } from '@softize/opus/schema/zod'
+ *
+ *   export const TicketStatus = t.dict({
+ *     open:        { label: 'Aberto', color: 'info' },
+ *     ...
+ *   })
+ *
+ * Edge cases:
+ *   - Domínio sem dicts → não emite arquivo.
+ *   - Dict com `unknownShape: true` (vinda do runner pra dict-like
+ *     irreconhecível) → emite `t.dict({}) as never` com warning no topo.
+ *   - Valores em entries serializados via JSON.stringify pra escape correto.
+ */
+
+export function buildDictStubs(manifest) {
+  const out = []
+  for (const domain of manifest.domains) {
+    const dicts = collectDicts(domain)
+    if (dicts.length === 0) continue
+    out.push({
+      filename: `${domain.name}.ts`,
+      content: renderDomainDicts(domain.name, dicts),
+    })
+  }
+  return out
+}
+
+/**
+ * Agrupa dicts do domínio raiz + subdomains em uma única lista.
+ * Nome do export = chave declarada no domínio (`TicketStatus`, etc).
+ * Conflitos entre subdomínios são improváveis (dicts moram em namespaces
+ * separados na config) mas se acontecerem, ganha o primeiro encontrado.
+ */
+function collectDicts(domain) {
+  const seen = new Set()
+  const out = []
+  walk(domain)
+  function walk(d) {
+    if (d.dicts !== null && typeof d.dicts === 'object') {
+      for (const [name, dict] of Object.entries(d.dicts)) {
+        if (seen.has(name)) continue
+        seen.add(name)
+        out.push({ name, dict })
+      }
+    }
+    if (Array.isArray(d.subdomains)) {
+      for (const sub of d.subdomains) walk(sub)
+    }
+  }
+  return out
+}
+
+function renderDomainDicts(domainName, dicts) {
+  const lines = []
+  lines.push('// AUTO-GERADO por @softize/opus gen. Não edite.')
+  lines.push(`// Domínio raiz: ${domainName}`)
+  lines.push('')
+  lines.push("import { t } from '@softize/opus/schema/zod'")
+  lines.push('')
+  for (const { name, dict } of dicts) {
+    lines.push(...renderDict(name, dict))
+    lines.push('')
+  }
+  return lines.join('\n').trimEnd() + '\n'
+}
+
+function renderDict(name, dict) {
+  const lines = []
+  if (dict.unknownShape === true) {
+    lines.push(
+      `// AVISO: dict "${name}" tinha shape irreconhecível no runner — emit vazio.`,
+    )
+    lines.push(`export const ${name} = t.dict({} as Record<string, { label: string }>)`)
+    return lines
+  }
+  const keys = Array.isArray(dict.keys) ? dict.keys : []
+  const values = dict.values ?? {}
+  if (keys.length === 0) {
+    lines.push(
+      `// AVISO: dict "${name}" não tinha chaves no manifest — emit vazio.`,
+    )
+    lines.push(`export const ${name} = t.dict({} as Record<string, { label: string }>)`)
+    return lines
+  }
+  lines.push(`export const ${name} = t.dict({`)
+  for (const key of keys) {
+    const entry = values[key]
+    lines.push(`  ${formatKey(key)}: ${renderEntry(entry)},`)
+  }
+  lines.push('})')
+  return lines
+}
+
+/**
+ * Emite a chave como identifier nu (`open`) quando for válido em TS,
+ * senão como literal string (`'foo-bar'`).
+ */
+function formatKey(key) {
+  if (typeof key !== 'string') return JSON.stringify(String(key))
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) return key
+  return JSON.stringify(key)
+}
+
+function renderEntry(entry) {
+  if (entry === null || entry === undefined || typeof entry !== 'object') {
+    return '{ label: "" }'
+  }
+  const parts = []
+  // `label` primeiro pra preservar leitura.
+  if (Object.prototype.hasOwnProperty.call(entry, 'label')) {
+    parts.push(`label: ${JSON.stringify(entry.label ?? '')}`)
+  }
+  for (const [k, v] of Object.entries(entry)) {
+    if (k === 'label') continue
+    parts.push(`${formatKey(k)}: ${JSON.stringify(v)}`)
+  }
+  if (parts.length === 0) parts.push('label: ""')
+  return `{ ${parts.join(', ')} }`
+}

package/bin/lib/gen-docs.mjs

@@ -0,0 +1,288 @@
+/**
+ * gen-docs — emite Markdown human-readable por domínio.
+ *
+ * Um arquivo por domínio raiz (subdomains entram embaixo do raiz pra
+ * preservar agrupamento). Estrutura:
+ *
+ *   # Domínio: <name>
+ *   ## Dicts
+ *   ## Actions
+ *   ## Reactions
+ *   ## Schedules
+ *   ## Subdomínios
+ *     ### <subname>
+ *
+ * Foco em legibilidade — não é spec, é overview pra humano. Schema cru
+ * fica no manifest; aqui só descrição amigável.
+ */
+
+export function buildDocs(manifest) {
+  const out = []
+  for (const domain of manifest.domains) {
+    out.push({
+      filename: `${domain.name}.md`,
+      content: renderDomain(domain, 1),
+    })
+  }
+  return out
+}
+
+function renderDomain(domain, level) {
+  const heading = '#'.repeat(level)
+  const sub = '#'.repeat(level + 1)
+  const lines = []
+  lines.push(`${heading} Domínio: ${domain.name}`)
+  lines.push('')
+
+  if (Object.keys(domain.dicts).length > 0) {
+    lines.push(`${sub} Dicts`)
+    lines.push('')
+    for (const [name, dict] of Object.entries(domain.dicts)) {
+      lines.push(...renderDict(name, dict, level + 2))
+    }
+  }
+
+  if (domain.actions.length > 0) {
+    lines.push(`${sub} Actions`)
+    lines.push('')
+    for (const action of domain.actions) {
+      lines.push(...renderAction(action, level + 2))
+    }
+  }
+
+  if (domain.reactions.length > 0) {
+    lines.push(`${sub} Reactions`)
+    lines.push('')
+    for (const reaction of domain.reactions) {
+      lines.push(...renderReaction(reaction, level + 2))
+    }
+  }
+
+  if (domain.schedules.length > 0) {
+    lines.push(`${sub} Schedules`)
+    lines.push('')
+    for (const schedule of domain.schedules) {
+      lines.push(...renderSchedule(schedule, level + 2))
+    }
+  }
+
+  if (domain.subdomains.length > 0) {
+    lines.push(`${sub} Subdomínios`)
+    lines.push('')
+    for (const subdomain of domain.subdomains) {
+      lines.push(renderDomain(subdomain, level + 2))
+    }
+  }
+
+  return lines.join('\n').trimEnd() + '\n'
+}
+
+function renderDict(name, dict, level) {
+  const heading = '#'.repeat(level)
+  const lines = []
+  lines.push(`${heading} ${name}`)
+  lines.push('')
+  // Tabela: detecta colunas extras (color, icon, order, ...) dinamicamente
+  // a partir das chaves de qualquer entry.
+  const allCols = new Set(['label'])
+  for (const v of Object.values(dict.values)) {
+    if (v === null || typeof v !== 'object') continue
+    for (const k of Object.keys(v)) allCols.add(k)
+  }
+  const cols = ['value', ...allCols]
+  lines.push(`| ${cols.join(' | ')} |`)
+  lines.push(`| ${cols.map(() => '---').join(' | ')} |`)
+  for (const key of dict.keys) {
+    const entry = dict.values[key]
+    const row = cols.map((col) => {
+      if (col === 'value') return key
+      if (entry === null || typeof entry !== 'object') return ''
+      const v = entry[col]
+      if (v === undefined || v === null) return ''
+      return String(v)
+    })
+    lines.push(`| ${row.join(' | ')} |`)
+  }
+  lines.push('')
+  return lines
+}
+
+function renderAction(action, level) {
+  const heading = '#'.repeat(level)
+  const lines = []
+  lines.push(`${heading} ${action.name} (${action.kind})`)
+  lines.push('')
+  if (typeof action.summary === 'string') {
+    lines.push(`> ${action.summary}`)
+    lines.push('')
+  } else if (typeof action.description === 'string') {
+    lines.push(`> ${action.description.split('\n')[0]}`)
+    lines.push('')
+  }
+
+  const bullets = []
+  if (Array.isArray(action.permission)) {
+    // requires em lista = ANY: qualquer uma das permissões alcança a action.
+    bullets.push(`**Permission:** ${action.permission.map((p) => `\`${p}\``).join(' | ')} (qualquer uma)`)
+  } else if (action.permission !== null) {
+    bullets.push(`**Permission:** \`${action.permission}\``)
+  } else if (action.public === true) {
+    bullets.push('**Permission:** público')
+  }
+  bullets.push(`**HTTP:** \`${httpFor(action)}\``)
+  if (Array.isArray(action.emits) && action.emits.length > 0) {
+    bullets.push(`**Emite:** ${action.emits.map((e) => `\`${e}\``).join(', ')}`)
+  }
+  if (Array.isArray(action.invalidates) && action.invalidates.length > 0) {
+    bullets.push(
+      `**Invalida:** ${action.invalidates.map((e) => `\`${e}\``).join(', ')}`,
+    )
+  } else if (action.invalidates === '<function>') {
+    bullets.push('**Invalida:** (computado em runtime)')
+  }
+  if (action.background === true) bullets.push('**Background:** sim')
+  if (typeof action.successStatus === 'number') {
+    bullets.push(`**Status sucesso:** \`${action.successStatus}\``)
+  }
+  for (const b of bullets) lines.push(`- ${b}`)
+  if (bullets.length > 0) lines.push('')
+
+  if (action.input !== null) {
+    lines.push('**Input:**')
+    lines.push('')
+    lines.push(...renderSchemaShape(action.input))
+    lines.push('')
+  }
+
+  if (action.output !== null) {
+    lines.push('**Output:**')
+    lines.push('')
+    lines.push(...renderSchemaShape(action.output))
+    lines.push('')
+  }
+
+  if (action.kind === 'form' && action.fields && Object.keys(action.fields).length > 0) {
+    lines.push('**Campos:**')
+    lines.push('')
+    for (const [name, spec] of Object.entries(action.fields)) {
+      const label = typeof spec.label === 'string' ? ` — ${spec.label}` : ''
+      const widget =
+        typeof spec.widget === 'string' ? ` (widget: \`${spec.widget}\`)` : ''
+      lines.push(`- \`${name}\`${label}${widget}`)
+    }
+    lines.push('')
+  }
+
+  if (action.kind === 'list' && action.filters && Object.keys(action.filters).length > 0) {
+    lines.push('**Filtros:**')
+    lines.push('')
+    for (const [name, spec] of Object.entries(action.filters)) {
+      const label = typeof spec.label === 'string' ? ` — ${spec.label}` : ''
+      lines.push(`- \`${name}\` (${spec.type ?? 'text'})${label}`)
+    }
+    lines.push('')
+  }
+
+  return lines
+}
+
+function renderReaction(reaction, level) {
+  const heading = '#'.repeat(level)
+  const lines = []
+  lines.push(`${heading} ${reaction.name}`)
+  lines.push('')
+  const ons = Array.isArray(reaction.on) ? reaction.on : [reaction.on]
+  lines.push(`- **Escuta:** ${ons.map((o) => `\`${o}\``).join(', ')}`)
+  if (typeof reaction.description === 'string') {
+    lines.push(`- **Descrição:** ${reaction.description}`)
+  }
+  if (reaction.retry !== null) {
+    lines.push(`- **Retry:** ${JSON.stringify(reaction.retry)}`)
+  }
+  lines.push('')
+  return lines
+}
+
+function renderSchedule(sched, level) {
+  const heading = '#'.repeat(level)
+  const lines = []
+  lines.push(`${heading} ${sched.name}`)
+  lines.push('')
+  lines.push(`- **Action:** \`${sched.action}\``)
+  if (typeof sched.cron === 'string') lines.push(`- **Cron:** \`${sched.cron}\``)
+  if (typeof sched.every === 'string') lines.push(`- **Every:** \`${sched.every}\``)
+  if (typeof sched.timezone === 'string') {
+    lines.push(`- **Timezone:** \`${sched.timezone}\``)
+  }
+  if (sched.enabled === false) lines.push('- **Status:** desabilitado')
+  if (typeof sched.description === 'string') {
+    lines.push(`- **Descrição:** ${sched.description}`)
+  }
+  lines.push('')
+  return lines
+}
+
+/**
+ * Render leve do shape de um JSON Schema — só top level, não recursivo.
+ * Pra schema completo, o consumidor vai pro manifest.
+ */
+function renderSchemaShape(schema) {
+  if (schema === null || typeof schema !== 'object') return ['_(vazio)_']
+  if (schema.__unserializable === true) {
+    return [`_(schema não-serializável: ${schema.reason})_`]
+  }
+  if (schema.type !== 'object' || typeof schema.properties !== 'object') {
+    // Schema escalar ou union — emite raw curto.
+    const oneLine = JSON.stringify(schema)
+    if (oneLine.length <= 100) return ['```json', oneLine, '```']
+    return [
+      '```json',
+      JSON.stringify(schema, null, 2),
+      '```',
+    ]
+  }
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required : [],
+  )
+  const lines = []
+  for (const [name, prop] of Object.entries(schema.properties)) {
+    const isReq = required.has(name)
+    const type = describeProp(prop)
+    lines.push(`- \`${name}${isReq ? '' : '?'}: ${type}\``)
+  }
+  return lines
+}
+
+function describeProp(prop) {
+  if (prop === null || typeof prop !== 'object') return 'unknown'
+  if (Array.isArray(prop.enum)) {
+    return `enum<${prop.enum.join(', ')}>`
+  }
+  if (Array.isArray(prop.type)) {
+    return prop.type.join('|')
+  }
+  if (typeof prop.type === 'string') {
+    if (prop.type === 'array') {
+      return `array<${describeProp(prop.items)}>`
+    }
+    if (prop.type === 'string' && typeof prop.format === 'string') {
+      return `string<${prop.format}>`
+    }
+    const constraints = []
+    if (typeof prop.minLength === 'number') constraints.push(`min=${prop.minLength}`)
+    if (typeof prop.maxLength === 'number') constraints.push(`max=${prop.maxLength}`)
+    if (typeof prop.minimum === 'number') constraints.push(`>=${prop.minimum}`)
+    if (typeof prop.maximum === 'number') constraints.push(`<=${prop.maximum}`)
+    const suffix = constraints.length > 0 ? ` (${constraints.join(', ')})` : ''
+    return `${prop.type}${suffix}`
+  }
+  if (Array.isArray(prop.oneOf) || Array.isArray(prop.anyOf)) return 'union'
+  return 'object'
+}
+
+function httpFor(action) {
+  const method =
+    action.kind === 'simple' || action.kind === 'form' ? 'POST' : 'GET'
+  const path = `/api/${action.name.split('.').join('/')}`
+  return `${method} ${path}`
+}

package/bin/lib/gen-manifest.mjs

@@ -0,0 +1,102 @@
+/**
+ * gen-manifest — transforma o payload do gen-runner no manifest.json
+ * público que vai ser emitido.
+ *
+ * O payload do runner já vem quase no formato certo (ver gen-runner.mjs
+ * pra spec). Aqui é só re-shape leve + adicionar headers (`version`,
+ * `generatedAt`, `opusVersion`).
+ */
+
+// SEM `generatedAt`: o manifest é commitado (build artifact estilo lockfile) e o
+// check de frescura compara bytes — um timestamp tornaria todo run diferente. O
+// histórico do git é o "quando". `opusVersion` fica (muda só com upgrade da base).
+export function buildManifest(payload) {
+  return {
+    version: '1',
+    opusVersion: payload.opusVersion,
+    domains: payload.domains.map(shapeDomain),
+  }
+}
+
+function shapeDomain(d) {
+  return {
+    name: d.name,
+    description: d.description ?? null,
+    dicts: d.dicts,
+    repository: d.hasRepository,
+    service: d.hasService,
+    // `entities` = a fonte estrutural+negócio (campos + docs). `models` = nomes
+    // (legado, removido no PR de rename). Ambos por ora pra não quebrar a lente.
+    entities: d.entities ?? [],
+    models: d.modelNames,
+    actions: d.actions.map(shapeAction),
+    reactions: d.reactions,
+    schedules: d.schedules,
+    subdomains: d.subdomains.map(shapeDomain),
+  }
+}
+
+function shapeAction(a) {
+  // Já vem no formato certo do runner; cópia rasa preserva ordem das chaves
+  // pra ficar consistente entre runs.
+  const out = {
+    name: a.name,
+    kind: a.kind,
+    summary: a.summary,
+    description: a.description,
+    label: a.label,
+    title: a.title,
+    icon: a.icon,
+    color: a.color,
+    tags: a.tags,
+    permission: a.permission,
+    authorize: a.authorize,
+    public: a.public,
+    internal: a.internal,
+    successStatus: a.successStatus,
+    input: a.input,
+    output: a.output,
+    invalidates: a.invalidates,
+    confirm: a.confirm,
+    rateLimit: a.rateLimit,
+    messages: a.messages,
+    examples: a.examples,
+    errors: a.errors,
+  }
+  if (a.kind === 'simple' || a.kind === 'form') {
+    out.emits = a.emits ?? []
+    out.background = a.background === true
+  }
+  if (a.kind === 'form') out.fields = a.fields ?? {}
+  if (a.kind === 'list') {
+    out.filters = a.filters ?? {}
+    out.sort = a.sort
+    out.paginate = a.paginate
+    out.text = a.text
+    out.periods = a.periods
+  }
+  if (a.kind === 'view') {
+    out.projection = a.projection ?? []
+    out.expand = a.expand
+  }
+  return out
+}
+
+/**
+ * Achata um manifest em uma lista plana de actions (com domínio raiz pra
+ * cada). Usado pra gerar OpenAPI a partir do manifest.
+ */
+export function flattenManifestActions(manifest) {
+  const out = []
+  for (const domain of manifest.domains) walk(domain, out)
+  return out
+}
+
+function walk(domain, out) {
+  for (const action of domain.actions) {
+    out.push({ ...action, domainName: domain.name })
+  }
+  if (Array.isArray(domain.subdomains)) {
+    for (const sub of domain.subdomains) walk(sub, out)
+  }
+}