@softize/opus 8.6.6

package/bin/lib/gen.mjs

@@ -0,0 +1,311 @@
+/**
+ * gen — orquestra o comando `opus gen`.
+ *
+ * Fluxo:
+ *   1. Resolve config path (--config ou ./opus.config.ts).
+ *   2. Spawn `tsx <package>/bin/lib/gen-runner.mjs <configPath>` capturando
+ *      stdout. Runner emite linha JSON com payload serializado.
+ *   3. Constrói manifest, openapi, docs, client-stubs.
+ *   4. Escreve em <output>/manifest.json, openapi.json, docs/*.md,
+ *      client-stubs/*.ts.
+ *   5. Poda órfãos: .md/.ts que rodada anterior gerou e esta não gerou saem
+ *      do disco (docs/ é a superfície de spec que o AGENTE lê — doc órfã
+ *      anuncia endpoint que já dá 404).
+ *
+ * Defaults:
+ *   - 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`).
+ */
+
+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 { buildManifest } from './gen-manifest.mjs'
+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)
+
+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 = process.cwd()
+  const configRel = flags.config ?? 'opus.config.ts'
+  const configPath = path.isAbsolute(configRel)
+    ? configRel
+    : path.resolve(cwd, configRel)
+
+  if (!(await fileExists(configPath))) {
+    log('error', `opus.config.ts não encontrado em ${configPath}`)
+    log(
+      'dim',
+      '  Cria um arquivo na raiz do projeto exportando `{ domains: [...] }` como default,',
+    )
+    log('dim', '  ou passa o path via --config <path>.')
+    process.exit(1)
+  }
+
+  log('info', `→ Carregando ${path.relative(cwd, configPath)}...`)
+
+  const payload = await loadConfig(configPath)
+
+  // Output: flag > config > default.
+  const outputDir = flags.output ?? payload.output ?? '.gen'
+  const outputAbs = path.isAbsolute(outputDir)
+    ? outputDir
+    : path.resolve(cwd, outputDir)
+
+  const manifest = buildManifest(payload)
+  const openapi = buildOpenAPI(manifest)
+  const docs = buildDocs(manifest)
+  const stubs = buildClientStubs(manifest)
+  const dictStubs = buildDictStubs(manifest)
+
+  await fs.mkdir(outputAbs, { recursive: true })
+  await fs.mkdir(path.join(outputAbs, 'docs'), { recursive: true })
+  await fs.mkdir(path.join(outputAbs, 'client-stubs'), { recursive: true })
+  if (dictStubs.length > 0) {
+    await fs.mkdir(path.join(outputAbs, 'client-stubs', 'dicts'), {
+      recursive: true,
+    })
+  }
+
+  await writeJson(path.join(outputAbs, 'manifest.json'), manifest, flags.force)
+  await writeJson(path.join(outputAbs, 'openapi.json'), openapi, flags.force)
+
+  for (const doc of docs) {
+    await writeText(path.join(outputAbs, 'docs', doc.filename), doc.content, flags.force)
+  }
+  for (const stub of stubs) {
+    await writeText(
+      path.join(outputAbs, 'client-stubs', stub.filename),
+      stub.content,
+      flags.force,
+    )
+  }
+  for (const dict of dictStubs) {
+    await writeText(
+      path.join(outputAbs, 'client-stubs', 'dicts', dict.filename),
+      dict.content,
+      flags.force,
+    )
+  }
+
+  const pruned = [
+    ...(await pruneOrphans(path.join(outputAbs, 'docs'), new Set(docs.map((d) => d.filename)), ['.md'])).map(
+      (f) => `docs/${f}`,
+    ),
+    ...(await pruneOrphans(path.join(outputAbs, 'client-stubs'), new Set(stubs.map((s) => s.filename)), ['.ts'])).map(
+      (f) => `client-stubs/${f}`,
+    ),
+    ...(
+      await pruneOrphans(path.join(outputAbs, 'client-stubs', 'dicts'), new Set(dictStubs.map((d) => d.filename)), ['.ts'])
+    ).map((f) => `client-stubs/dicts/${f}`),
+  ]
+
+  log('success', `✓ Gerado em ${path.relative(cwd, outputAbs)}`)
+  log('dim', `  manifest.json`)
+  log('dim', `  openapi.json`)
+  log('dim', `  docs/ (${docs.length} arquivo${docs.length === 1 ? '' : 's'})`)
+  log(
+    'dim',
+    `  client-stubs/ (${stubs.length} arquivo${stubs.length === 1 ? '' : 's'})`,
+  )
+  if (dictStubs.length > 0) {
+    log(
+      'dim',
+      `  client-stubs/dicts/ (${dictStubs.length} arquivo${dictStubs.length === 1 ? '' : 's'})`,
+    )
+  }
+  if (pruned.length > 0) {
+    log('dim', `  podado${pruned.length === 1 ? '' : 's'} ${pruned.length} órfão${pruned.length === 1 ? '' : 's'}: ${pruned.join(', ')}`)
+  }
+
+  // Auditoria de doc: o `description` é a fonte de entendimento (negócio + contrato) e
+  // flui pro manifest/lente. O gen vê a descrição RESOLVIDA (concatenada inclusive) —
+  // por isso a checagem mora aqui, não no opus check estático. Avisa, não reprova.
+  auditDocs(manifest, cwd)
+}
+
+/** Lista as actions sem `description` no manifest (o doc de negócio — a fonte). */
+function auditDocs(manifest, cwd) {
+  const missing = []
+  const walk = (d) => {
+    for (const a of d.actions ?? []) {
+      const doc = typeof a.description === 'string' ? a.description.trim() : ''
+      if (doc.length === 0) missing.push(a.name)
+    }
+    for (const sub of d.subdomains ?? []) walk(sub)
+  }
+  for (const d of manifest.domains ?? []) walk(d)
+  if (missing.length === 0) {
+    log('success', '  ✓ doc: todas as actions documentadas (spec abrange tudo).')
+    return
+  }
+  log('warn', `\n  ⚠ doc: ${missing.length} action(s) sem \`description\` (o doc de negócio — a fonte):`)
+  for (const name of missing) log('dim', `    • ${name}`)
+}
+
+// =============================================================================
+// Runner spawn
+// =============================================================================
+
+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'
+
+  try {
+    // Buffer grande pra acomodar manifests gordos.
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      env: { ...process.env },
+    })
+
+    // Runner emite a linha JSON na ÚLTIMA linha de stdout. Qualquer log do
+    // consumer durante o import vai pro inicio — varremos de trás pra
+    // frente.
+    const line = lastJsonLine(stdout)
+    if (line === null) {
+      log('error', 'Runner não emitiu payload JSON válido.')
+      if (stderr.length > 0) log('dim', stderr.trim())
+      if (stdout.length > 0) log('dim', stdout.trim())
+      process.exit(1)
+    }
+    const parsed = JSON.parse(line)
+    if (parsed.ok !== true) {
+      log('error', `Falha ao carregar config: ${parsed.error}`)
+      process.exit(1)
+    }
+    return parsed.payload
+  } catch (err) {
+    log('error', `Falha ao executar tsx: ${err.message}`)
+    if (typeof err.stderr === 'string' && err.stderr.length > 0) {
+      log('dim', err.stderr.trim())
+    }
+    if (typeof err.stdout === 'string' && err.stdout.length > 0) {
+      log('dim', err.stdout.trim())
+    }
+    process.exit(1)
+  }
+}
+
+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
+  }
+}
+
+async function writeJson(p, value, _force) {
+  await fs.writeFile(p, JSON.stringify(value, null, 2) + '\n', 'utf8')
+}
+
+/**
+ * Poda órfãos de um dir gerenciado pelo gen: arquivo com extensão gerada (`exts`)
+ * que NÃO saiu desta rodada (`keep`) é removido. Só olha arquivos do próprio dir
+ * (subdirs têm chamada própria) e só as extensões geradas — qualquer outra coisa
+ * que o consumer tenha posto lá fica intacta. Exportada pra teste.
+ */
+export async function pruneOrphans(dir, keep, exts) {
+  let entries
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true })
+  } catch {
+    return [] // dir nem existe → nada a podar
+  }
+  const removed = []
+  for (const e of entries) {
+    if (!e.isFile()) continue
+    if (!exts.some((x) => e.name.endsWith(x))) continue
+    if (keep.has(e.name)) continue
+    await fs.unlink(path.join(dir, e.name))
+    removed.push(e.name)
+  }
+  return removed.sort()
+}
+
+async function writeText(p, content, _force) {
+  await fs.writeFile(p, content, 'utf8')
+}
+
+// =============================================================================
+// Help
+// =============================================================================
+
+export function helpGen() {
+  console.log(`
+@softize/opus gen
+
+Lê opus.config.ts do consumer e gera:
+  - <output>/manifest.json                   Spec serializada (JSON Schema dos inputs/outputs)
+  - <output>/openapi.json                    OpenAPI 3.1 derivada do manifest
+  - <output>/docs/<domain>.md                Doc human-readable por domínio
+  - <output>/client-stubs/<domain>.ts        Stubs com schema Zod reconstruído pro frontend
+  - <output>/client-stubs/dicts/<domain>.ts  Dicts (t.dict({...})) prontos pro frontend
+
+Flags:
+  --config <path>   Caminho do opus.config.ts. Default: ./opus.config.ts
+  --output <path>   Pasta de saída. Default: do config (ou ./.gen)
+  --force, -f       Sobrescreve existente (atualmente sempre sobrescreve)
+
+Exemplos:
+  npx @softize/opus gen
+  npx @softize/opus gen --config ./apps/api/opus.config.ts
+  npx @softize/opus gen --output ./custom/gen
+`)
+}