@softize/opus 8.6.6

package/bin/lib/gen-openapi.mjs

@@ -0,0 +1,195 @@
+/**
+ * gen-openapi — gera OpenAPI 3.1 a partir do manifest serializado.
+ *
+ * Não reusa `src/schema/openapi.ts` direto pq aquele assume `ActionDef`
+ * vivo (com Zod schemas instanciados). Aqui já temos JSON Schema serializado
+ * pelo runner. Replicamos a convenção de rota e o envelope `ok/data/meta`
+ * pra manter contrato consistente.
+ *
+ * Convenção (mesma de src/schema/openapi.ts):
+ *   simple/form → POST /api/{name-com-slashes}
+ *   list/view → GET  /api/{name-com-slashes}
+ */
+
+import { flattenManifestActions } from './gen-manifest.mjs'
+
+export function buildOpenAPI(manifest, options = {}) {
+  const {
+    info = {
+      title: 'Generated by @softize/opus',
+      version: manifest.opusVersion,
+    },
+    servers,
+    apiPrefix = '/api',
+  } = options
+
+  const paths = {}
+  for (const action of flattenManifestActions(manifest)) {
+    if (action.internal === true) continue
+    const { path, method } = routeFor(action, apiPrefix)
+    const op = buildOperation(action, method)
+    paths[path] = paths[path] ?? {}
+    paths[path][method] = op
+  }
+
+  const spec = {
+    openapi: '3.1.0',
+    info,
+    paths,
+    components: { schemas: {} },
+  }
+  if (Array.isArray(servers) && servers.length > 0) spec.servers = servers
+  return spec
+}
+
+function routeFor(action, apiPrefix) {
+  const segments = action.name.split('.').map(encodeURIComponent)
+  const path = `${apiPrefix}/${segments.join('/')}`
+  const method =
+    action.kind === 'simple' || action.kind === 'form' ? 'post' : 'get'
+  return { path, method }
+}
+
+function buildOperation(action, method) {
+  const op = {
+    operationId: action.name,
+    responses: buildResponses(action),
+  }
+  if (typeof action.summary === 'string') op.summary = action.summary
+  if (typeof action.description === 'string') op.description = action.description
+  if (Array.isArray(action.tags) && action.tags.length > 0) op.tags = action.tags
+
+  const inputSchema = action.input
+
+  if (method === 'post' && inputSchema !== null) {
+    op.requestBody = {
+      required: true,
+      content: { 'application/json': { schema: inputSchema } },
+    }
+  } else if (method === 'get') {
+    const params = buildQueryParams(inputSchema)
+    if (params.length > 0) op.parameters = params
+  }
+
+  if (action.public !== true) {
+    op.security = [{ bearerAuth: [] }]
+  }
+
+  return op
+}
+
+function buildResponses(action) {
+  const successStatus = String(action.successStatus ?? 200)
+  return {
+    [successStatus]: {
+      description: 'Success',
+      content: {
+        'application/json': {
+          schema: wrapEnvelope(action.output, action.kind),
+        },
+      },
+    },
+    '4XX': errorResponse('Client error', action.errors),
+    '5XX': errorResponse('Server error'),
+  }
+}
+
+function wrapEnvelope(outputSchema, kind) {
+  const data =
+    kind === 'list'
+      ? {
+          type: 'object',
+          properties: {
+            items: { type: 'array', items: outputSchema ?? {} },
+            cursor: {
+              type: 'object',
+              properties: {
+                next: { type: ['string', 'null'] },
+                prev: { type: ['string', 'null'] },
+              },
+              required: ['next'],
+            },
+            total: { type: 'integer' },
+          },
+          required: ['items', 'cursor'],
+        }
+      : (outputSchema ?? {})
+
+  return {
+    type: 'object',
+    properties: {
+      ok: { const: true },
+      data,
+      meta: metaSchema(),
+    },
+    required: ['ok', 'data', 'meta'],
+  }
+}
+
+function errorResponse(description, errors) {
+  const codes =
+    Array.isArray(errors) && errors.length > 0
+      ? { enum: errors.map((e) => e.code) }
+      : { type: 'string' }
+  return {
+    description,
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            ok: { const: false },
+            error: {
+              type: 'object',
+              properties: {
+                code: codes,
+                category: { type: 'string' },
+                message: { type: 'string' },
+                severity: { enum: ['warning', 'error', 'fatal'] },
+                retriable: { type: 'boolean' },
+              },
+              required: ['code', 'category', 'message', 'severity', 'retriable'],
+            },
+            meta: metaSchema(),
+          },
+          required: ['ok', 'error', 'meta'],
+        },
+      },
+    },
+  }
+}
+
+function metaSchema() {
+  return {
+    type: 'object',
+    properties: {
+      actionId: { type: 'string' },
+      action: { type: 'string' },
+      durationMs: { type: 'number' },
+      requestId: { type: 'string' },
+      cached: { type: 'boolean' },
+    },
+    required: ['actionId', 'action', 'durationMs'],
+  }
+}
+
+function buildQueryParams(inputSchema) {
+  if (
+    inputSchema === null ||
+    typeof inputSchema !== 'object' ||
+    typeof inputSchema.properties !== 'object' ||
+    inputSchema.properties === null
+  ) {
+    return []
+  }
+  const props = inputSchema.properties
+  const required = new Set(
+    Array.isArray(inputSchema.required) ? inputSchema.required : [],
+  )
+  return Object.entries(props).map(([name, schema]) => ({
+    name,
+    in: 'query',
+    required: required.has(name),
+    schema,
+  }))
+}

package/bin/lib/gen-runner.mjs

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+/**
+ * gen-runner — subprocess executado via `tsx` pra carregar e serializar
+ * o `opus.config.ts` do consumer.
+ *
+ * Por que subprocess: o CLI principal roda como `.mjs` puro (Node sem
+ * loader TS). Pra avaliar TypeScript do consumer com `import`, precisamos
+ * de `tsx` no caminho. Spawn isolado mantém o CLI puro e evita poluir o
+ * process do usuário.
+ *
+ * Protocolo:
+ *   Entrada via argv:
+ *     [0] node
+ *     [1] gen-runner.mjs
+ *     [2] config path absoluto (.ts/.mts/.mjs/.js)
+ *
+ *   Saída:
+ *     stdout: única linha JSON com `{ ok: true, payload }` ou
+ *             `{ ok: false, error }`. Tudo que não for essa linha é debug
+ *             (vai pra stderr).
+ *
+ *   `payload` shape (ver gen-manifest.mjs pra consumidor):
+ *     {
+ *       opusVersion: string,
+ *       sourceConfigDir: string,    // dirname absoluto do opus.config.ts
+ *       output: string,             // pasta de saída declarada no config
+ *       domains: SerializedDomain[]
+ *     }
+ *
+ *     SerializedDomain:
+ *     {
+ *       name, dicts, actions, reactions, schedules, subdomains,
+ *       hasRepository, hasService, hasModels
+ *     }
+ *
+ *     SerializedAction (todos os ActionDef preservam suas strings):
+ *     {
+ *       name, kind, summary, description, label, title, icon, color, tags,
+ *       permission: string | string[] | null, // requires fiel (lista = ANY)
+ *       authorize: '<function>' | string?,    // DSL string preservada
+ *       input: JSONSchema,                    // zod-to-json-schema
+ *       output: JSONSchema,                   // zod-to-json-schema
+ *       fields?: Record<string, FieldSpecSerialized>,
+ *       filters?, sort?, paginate?, text?, periods?,  // search
+ *       projection?, expand?,                          // view
+ *       background?: boolean,
+ *       emits?: string[],
+ *       invalidates?: string[] | '<function>',
+ *       successStatus?: number,
+ *       public?: boolean,
+ *       internal?: boolean,
+ *       rateLimit?: { window, max },
+ *       confirm?: ConfirmSpec,
+ *       messages?, examples?, errors?,
+ *       sourceModule?: string | null  // path absoluto onde a action foi declarada (best-effort)
+ *     }
+ *
+ * Closures não serializáveis (authorize fn, handler, etc) viram a string
+ * literal `"<function>"`. Mantém o nome do campo no payload pra docs e
+ * stubs poderem indicar que existe lógica.
+ */
+
+import path from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+
+// =============================================================================
+// Entrada
+// =============================================================================
+
+async function main() {
+  const configPath = process.argv[2]
+  if (typeof configPath !== 'string' || configPath.length === 0) {
+    return emitError('Missing config path argv[2]')
+  }
+
+  const configAbs = path.resolve(configPath)
+  const configUrl = pathToFileURL(configAbs).href
+
+  // Importa opus (a partir do PACKAGE_ROOT, não do consumer) — precisamos
+  // do `flattenDomain` + helpers internos pra serializar.
+  const opusCoreUrl = pathToFileURL(
+    path.join(PACKAGE_ROOT, 'src', 'core', 'index.ts'),
+  ).href
+  const { flattenDomain } = await import(opusCoreUrl)
+
+  // Acessar logical type meta dos dicts.
+  const opusSchemaUrl = pathToFileURL(
+    path.join(PACKAGE_ROOT, 'src', 'schema', 'index.ts'),
+  ).href
+  const opusSchema = await import(opusSchemaUrl)
+
+  // Pra serializar Zod → JSON Schema reusa o caminho que `toOpenAPISpec`
+  // usa. Importação direta do npm pq é dep regular da opus.
+  const { zodToJsonSchema } = await import('zod-to-json-schema')
+
+  const pkgUrl = pathToFileURL(path.join(PACKAGE_ROOT, 'package.json')).href
+  const pkg = await import(pkgUrl, { with: { type: 'json' } }).then(
+    (m) => m.default,
+  )
+
+  // Import dinâmico do config do consumer.
+  const mod = await import(configUrl)
+  const cfg = mod.default ?? mod.config ?? mod
+  if (cfg === undefined || cfg === null || typeof cfg !== 'object') {
+    return emitError(
+      `Config em ${configAbs} não exporta um objeto default ou named "config"`,
+    )
+  }
+
+  if (!Array.isArray(cfg.domains)) {
+    return emitError(
+      `Config em ${configAbs} precisa de \`domains: DomainConfig[]\` no export default`,
+    )
+  }
+
+  const outputDir = typeof cfg.output === 'string' ? cfg.output : '.gen'
+
+  const ctx = {
+    flattenDomain,
+    toJsonSchema: (schema) =>
+      zodToJsonSchema(schema, { target: 'openApi3', $refStrategy: 'none' }),
+    sourceConfigDir: path.dirname(configAbs),
+  }
+
+  const domains = cfg.domains.map((d) => serializeDomain(d, ctx))
+
+  const payload = {
+    opusVersion: pkg.version,
+    sourceConfigDir: ctx.sourceConfigDir,
+    output: outputDir,
+    domains,
+  }
+
+  emit({ ok: true, payload })
+}
+
+// =============================================================================
+// Serialização
+// =============================================================================
+
+function serializeDomain(domain, ctx) {
+  // `entities` é o nome preferido; `models` é o legado (alias). Lê os dois.
+  const entitySrc = domain.entities ?? domain.models
+  const entityList = serializeEntities(entitySrc)
+  return {
+    name: domain.name,
+    description: nullable(domain.description),
+    hasRepository: domain.repository !== undefined,
+    hasService: domain.service !== undefined,
+    // Compat: nomes ainda expostos; `entities` traz a estrutura+doc completa.
+    hasModels: entityList.length > 0,
+    modelNames: entityList.map((e) => e.name),
+    entities: entityList,
+    dicts: serializeDicts(domain.dicts),
+    actions: Array.from(iterateActions(domain.actions), (a) =>
+      serializeAction(a, ctx),
+    ),
+    reactions: Array.isArray(domain.reactions)
+      ? domain.reactions.map(serializeReaction)
+      : [],
+    schedules: Array.isArray(domain.schedules)
+      ? domain.schedules.map(serializeSchedule)
+      : [],
+    subdomains: Array.isArray(domain.subdomains)
+      ? domain.subdomains.map((s) => serializeDomain(s, ctx))
+      : [],
+  }
+}
+
+/** Serializa as entidades (`defineEntity`) com campos + docs — a fonte que vai pro
+ *  manifest/lente. Ignora valores que não parecem EntityConfig (name+fields). */
+function serializeEntities(src) {
+  if (src === undefined || src === null || typeof src !== 'object') return []
+  const out = []
+  for (const [key, ent] of Object.entries(src)) {
+    if (ent === null || typeof ent !== 'object' || typeof ent.fields !== 'object') continue
+    const fields = []
+    for (const [fname, f] of Object.entries(ent.fields)) {
+      const col = f?.column ?? {}
+      fields.push({
+        name: fname,
+        logicalType: f?.meta?.logicalType ?? null,
+        nullable: col.nullable === true,
+        pk: col.pk === true,
+        references: col.references ?? null,
+        doc: col.doc ?? null,
+      })
+    }
+    out.push({
+      name: typeof ent.name === 'string' ? ent.name : key,
+      description: typeof ent.description === 'string' ? ent.description : null,
+      table: typeof ent.table === 'string' ? ent.table : null,
+      fields,
+      relations: ent.relations ?? null,
+    })
+  }
+  return out
+}
+
+function serializeDicts(dicts) {
+  if (dicts === undefined || dicts === null || typeof dicts !== 'object') {
+    return {}
+  }
+  const out = {}
+  for (const [name, dict] of Object.entries(dicts)) {
+    if (dict === null || typeof dict !== 'object') continue
+    // DictType expõe `meta.params.entries`. Fallback: tenta `.keys()` +
+    // `.metaFor(k)` caso seja shape custom.
+    const meta = dict.meta
+    if (
+      meta !== undefined &&
+      meta !== null &&
+      meta.logicalType === 'dict' &&
+      meta.params !== undefined
+    ) {
+      const params = meta.params
+      const keys = Array.isArray(params.keys) ? params.keys : []
+      const entries =
+        params.entries !== undefined && params.entries !== null
+          ? params.entries
+          : {}
+      const values = {}
+      for (const k of keys) {
+        values[k] = entries[k] ?? null
+      }
+      // `doc` = entendimento do vocabulário inteiro (o que esse dict representa).
+      out[name] = { keys, values, doc: typeof params.doc === 'string' ? params.doc : null }
+      continue
+    }
+    // Fallback: dict-like com `keys()` + `metaFor()`.
+    if (
+      typeof dict.keys === 'function' &&
+      typeof dict.metaFor === 'function'
+    ) {
+      const keys = dict.keys()
+      const values = {}
+      for (const k of keys) values[k] = dict.metaFor(k)
+      out[name] = { keys, values }
+      continue
+    }
+    // Não-reconhecível: registra placeholder pra não silenciar.
+    out[name] = { keys: [], values: {}, unknownShape: true }
+  }
+  return out
+}
+
+function serializeAction(action, ctx) {
+  const base = {
+    name: action.name,
+    kind: action.kind,
+    summary: nullable(action.summary),
+    description: nullable(action.description),
+    label: nullable(action.label),
+    title: nullable(action.title),
+    icon: nullable(action.icon),
+    color: nullable(action.color),
+    tags: Array.isArray(action.tags) ? action.tags : [],
+    permission: derivePermission(action),
+    authorize: serializeAuthorize(action.authorize),
+    public: action.public === true,
+    internal: action.internal === true,
+    successStatus: action.successStatus,
+    input: safeToJsonSchema(action.input, ctx),
+    output: safeToJsonSchema(action.output, ctx),
+    invalidates: serializeInvalidates(action.invalidates),
+    confirm: action.confirm ?? null,
+    rateLimit:
+      action.rateLimit !== undefined
+        ? { window: action.rateLimit.window, max: action.rateLimit.max }
+        : null,
+    messages: action.messages ?? null,
+    examples: Array.isArray(action.examples) ? action.examples : [],
+    errors: Array.isArray(action.errors) ? action.errors : [],
+    sourceModule: lookupSourceModule(action, ctx),
+  }
+
+  if (action.kind === 'simple' || action.kind === 'form') {
+    base.emits = Array.isArray(action.emits) ? action.emits : []
+    base.background =
+      action.background !== undefined &&
+      action.background !== null &&
+      action.background.enabled === true
+  }
+
+  if (action.kind === 'form') {
+    base.fields = serializeFields(action.fields)
+  }
+
+  if (action.kind === 'list') {
+    base.filters = serializeFilters(action.filters)
+    base.sort = action.sort ?? null
+    base.paginate = action.paginate ?? null
+    base.text = action.text ?? null
+    base.periods = Array.isArray(action.periods) ? action.periods : []
+  }
+
+  if (action.kind === 'view') {
+    base.projection = Array.isArray(action.projection) ? action.projection : []
+    base.expand = action.expand ?? null
+  }
+
+  return base
+}
+
+function serializeFields(fields) {
+  if (fields === undefined || fields === null || typeof fields !== 'object') {
+    return {}
+  }
+  const out = {}
+  for (const [name, spec] of Object.entries(fields)) {
+    if (spec === null || typeof spec !== 'object') continue
+    out[name] = {
+      label: spec.label ?? null,
+      placeholder: spec.placeholder ?? null,
+      hint: spec.hint ?? null,
+      default: spec.default ?? null,
+      mask: spec.mask ?? null,
+      depends: spec.depends ?? null,
+      group: spec.group ?? null,
+      order: spec.order ?? null,
+      widget: spec.widget ?? null,
+      options: spec.options ?? null,
+      hasShowWhen: typeof spec.showWhen === 'function',
+      hasRequireWhen: typeof spec.requireWhen === 'function',
+      aiDescription: spec.aiDescription ?? null,
+    }
+  }
+  return out
+}
+
+function serializeFilters(filters) {
+  if (filters === undefined || filters === null || typeof filters !== 'object') {
+    return {}
+  }
+  const out = {}
+  for (const [name, spec] of Object.entries(filters)) {
+    if (spec === null || typeof spec !== 'object') continue
+    out[name] = {
+      label: spec.label ?? null,
+      placeholder: spec.placeholder ?? null,
+      type: spec.type ?? null,
+      multiple: spec.multiple === true,
+      mode: spec.mode ?? null,
+      operators: Array.isArray(spec.operators) ? spec.operators : null,
+      path: spec.path ?? null,
+      section: spec.section ?? null,
+      depends: spec.depends ?? null,
+      options: spec.options ?? null,
+      aiDescription: spec.aiDescription ?? null,
+    }
+  }
+  return out
+}
+
+function serializeReaction(reaction) {
+  return {
+    name: reaction.name,
+    on: reaction.on,
+    description: nullable(reaction.description),
+    tags: Array.isArray(reaction.tags) ? reaction.tags : [],
+    handler: '<function>',
+    retry: reaction.retry ?? null,
+    timeout: reaction.timeout ?? null,
+    concurrency: reaction.concurrency ?? null,
+    hasDedup: typeof reaction.dedup === 'function',
+    hasAuthorize: typeof reaction.authorize === 'function',
+  }
+}
+
+function serializeSchedule(sched) {
+  return {
+    name: sched.name,
+    action: sched.action,
+    cron: nullable(sched.cron),
+    every: nullable(sched.every),
+    timezone: nullable(sched.timezone),
+    enabled: sched.enabled !== false,
+    description: nullable(sched.description),
+    tags: Array.isArray(sched.tags) ? sched.tags : [],
+    input:
+      typeof sched.input === 'function' ? '<function>' : (sched.input ?? null),
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function* iterateActions(actions) {
+  if (actions === undefined) return
+  if (Array.isArray(actions)) {
+    for (const a of actions) yield a
+    return
+  }
+  for (const value of Object.values(actions)) {
+    if (Array.isArray(value)) {
+      for (const a of value) yield a
+    } else {
+      yield value
+    }
+  }
+}
+
+function derivePermission(action) {
+  // Projeção FIEL do `requires`: lista sai lista (semântica ANY) — projetar só a
+  // 1ª string faria a spec mentir por omissão pra quem lê o manifest.
+  const req = action.requires
+  if (typeof req === 'string') return req
+  if (Array.isArray(req)) {
+    const strs = req.filter((r) => typeof r === 'string')
+    return strs.length > 0 ? strs : null
+  }
+  return null
+}
+
+function serializeAuthorize(authorize) {
+  if (authorize === undefined || authorize === null) return null
+  // DSL: pode chegar como string em frameworks (versão futura). Hoje é fn.
+  if (typeof authorize === 'string') return authorize
+  if (typeof authorize === 'function') return '<function>'
+  return null
+}
+
+function serializeInvalidates(inv) {
+  if (inv === undefined || inv === null) return null
+  if (Array.isArray(inv)) return inv
+  if (typeof inv === 'function') return '<function>'
+  return null
+}
+
+function safeToJsonSchema(schema, ctx) {
+  if (schema === undefined || schema === null) return null
+  try {
+    return ctx.toJsonSchema(schema)
+  } catch (err) {
+    return { __unserializable: true, reason: err.message }
+  }
+}
+
+function lookupSourceModule(_action, _ctx) {
+  // Não há mecanismo confiável pra extrair o source module a partir do
+  // ActionDef em runtime (ESM não expõe). Reservamos o campo pra futura
+  // integração com `import.meta.url` no defineAction.
+  return null
+}
+
+function nullable(value) {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'string' && value.length === 0) return null
+  return value
+}
+
+// =============================================================================
+// IPC
+// =============================================================================
+
+function emit(payload) {
+  process.stdout.write(JSON.stringify(payload) + '\n')
+}
+
+function emitError(message) {
+  emit({ ok: false, error: message })
+  process.exit(1)
+}
+
+main().catch((err) => {
+  emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`)
+})