@softize/opus 15.2.2 → 16.1.0

package/bin/lib/gen-manifest.mjs

@@ -12,11 +12,12 @@
 // histórico do git é o "quando". `opusVersion` fica (muda só com upgrade da base).
 export function buildManifest(payload) {
   return {
-    version: '1',
+    version: "1",
     opusVersion: payload.opusVersion,
     seeds: payload.seeds ?? [],
+    presentations: payload.presentations ?? [],
     domains: payload.domains.map(shapeDomain),
-  }
+  };
 }
 
 function shapeDomain(d) {
@@ -32,7 +33,7 @@ function shapeDomain(d) {
     reactions: d.reactions,
     schedules: d.schedules,
     subdomains: d.subdomains.map(shapeDomain),
-  }
+  };
 }
 
 function shapeAction(a) {
@@ -61,24 +62,24 @@ function shapeAction(a) {
     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 === '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 === "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
+  if (a.kind === "view") {
+    out.projection = a.projection ?? [];
+    out.expand = a.expand;
   }
-  return out
+  return out;
 }
 
 /**
@@ -86,16 +87,16 @@ function shapeAction(a) {
  * 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
+  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 })
+    out.push({ ...action, domainName: domain.name });
   }
   if (Array.isArray(domain.subdomains)) {
-    for (const sub of domain.subdomains) walk(sub, out)
+    for (const sub of domain.subdomains) walk(sub, out);
   }
 }

package/bin/lib/gen-runner.mjs

@@ -25,7 +25,8 @@
  *       sourceConfigDir: string,    // dirname absoluto do opus.config.ts
  *       output: string,             // pasta de saída declarada no config
  *       domains: SerializedDomain[],
- *       seeds: SerializedSeed[]
+ *       seeds: SerializedSeed[],
+ *       presentations: PresentationDefinition[]
  *     }
  *
  *     SerializedDomain:
@@ -61,92 +62,113 @@
  * stubs poderem indicar que existe lógica.
  */
 
-import path from 'node:path'
-import { pathToFileURL, fileURLToPath } from 'node:url'
+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, '..', '..')
+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('Caminho do config ausente (argv[2])')
+  const configPath = process.argv[2];
+  if (typeof configPath !== "string" || configPath.length === 0) {
+    return emitError("Caminho do config ausente (argv[2])");
   }
 
-  const configAbs = path.resolve(configPath)
-  const configUrl = pathToFileURL(configAbs).href
+  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)
+    path.join(PACKAGE_ROOT, "src", "core", "index.ts"),
+  ).href;
+  const { flattenDomain } = await import(opusCoreUrl);
 
   const opusSeedUrl = pathToFileURL(
-    path.join(PACKAGE_ROOT, 'src', 'seed', 'index.ts'),
-  ).href
+    path.join(PACKAGE_ROOT, "src", "seed", "index.ts"),
+  ).href;
   const { checkSeedRegistry, isSeedDefinition, publicSeedDefinition } =
-    await import(opusSeedUrl)
+    await import(opusSeedUrl);
+
+  const opusPresentationUrl = pathToFileURL(
+    path.join(PACKAGE_ROOT, "src", "presentation", "index.ts"),
+  ).href;
+  const { validatePresentations } = await import(opusPresentationUrl);
 
   // Acessar logical type meta dos dicts.
   const opusSchemaUrl = pathToFileURL(
-    path.join(PACKAGE_ROOT, 'src', 'schema', 'index.ts'),
-  ).href
-  const opusSchema = await import(opusSchemaUrl)
+    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 { 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(
+  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') {
+  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 outputDir = typeof cfg.output === "string" ? cfg.output : ".gen";
 
   const ctx = {
     flattenDomain,
     toJsonSchema: (schema) =>
-      zodToJsonSchema(schema, { target: 'openApi3', $refStrategy: 'none' }),
+      zodToJsonSchema(schema, { target: "openApi3", $refStrategy: "none" }),
     sourceConfigDir: path.dirname(configAbs),
-  }
+  };
 
-  const domains = cfg.domains.map((d) => serializeDomain(d, ctx))
+  const domains = cfg.domains.map((d) => serializeDomain(d, ctx));
+  if (cfg.presentations !== undefined && !Array.isArray(cfg.presentations)) {
+    throw new Error(
+      "config.presentations inválido — use um array de declarações registradas",
+    );
+  }
+  const actionRegistry = Object.fromEntries(
+    cfg.domains
+      .flatMap((domain) => collectDomainActions(domain))
+      .map((action) => [action.name, action]),
+  );
+  const presentations = validatePresentations(
+    cfg.presentations ?? [],
+    actionRegistry,
+  );
   if (cfg.seeds !== undefined && !Array.isArray(cfg.seeds)) {
-    throw new Error('config.seeds inválido — use um array de declarações registradas')
+    throw new Error(
+      "config.seeds inválido — use um array de declarações registradas",
+    );
   }
-  const registeredSeeds = cfg.seeds ?? []
-  const seedCheck = checkSeedRegistry(registeredSeeds)
+  const registeredSeeds = cfg.seeds ?? [];
+  const seedCheck = checkSeedRegistry(registeredSeeds);
   if (!seedCheck.ok) {
     throw new Error(
-      `config.seeds inválido — ${seedCheck.diagnostics.map((diagnostic) => diagnostic.message).join('; ')}`,
-    )
+      `config.seeds inválido — ${seedCheck.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`,
+    );
   }
   const seeds = registeredSeeds.map((seed) =>
     serializeSeed(seed, isSeedDefinition, publicSeedDefinition),
-  )
+  );
 
   const payload = {
     opusVersion: pkg.version,
@@ -154,16 +176,27 @@ async function main() {
     output: outputDir,
     domains,
     seeds,
-  }
+    presentations,
+  };
 
-  emit({ ok: true, payload })
+  emit({ ok: true, payload });
+}
+
+function collectDomainActions(domain) {
+  const actions = Array.from(iterateActions(domain.actions));
+  for (const subdomain of Array.isArray(domain.subdomains)
+    ? domain.subdomains
+    : []) {
+    actions.push(...collectDomainActions(subdomain));
+  }
+  return actions;
 }
 
 function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
   if (!isSeedDefinition(seed)) {
-    throw new Error('config.seeds contém uma declaração inválida')
+    throw new Error("config.seeds contém uma declaração inválida");
   }
-  return publicSeedDefinition(seed)
+  return publicSeedDefinition(seed);
 }
 
 // =============================================================================
@@ -171,7 +204,7 @@ function serializeSeed(seed, isSeedDefinition, publicSeedDefinition) {
 // =============================================================================
 
 function serializeDomain(domain, ctx) {
-  const entityList = serializeEntities(domain.entities)
+  const entityList = serializeEntities(domain.entities);
   return {
     name: domain.name,
     description: nullable(domain.description),
@@ -192,7 +225,7 @@ function serializeDomain(domain, ctx) {
     subdomains: Array.isArray(domain.subdomains)
       ? domain.subdomains.map((s) => serializeDomain(s, ctx))
       : [],
-  }
+  };
 }
 
 function serializeDataProducts(source) {
@@ -243,13 +276,18 @@ function serializeDataProducts(source) {
 /** 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 = []
+  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 = []
+    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 ?? {}
+      const col = f?.column ?? {};
       fields.push({
         name: fname,
         logicalType: f?.meta?.logicalType ?? null,
@@ -257,70 +295,68 @@ function serializeEntities(src) {
         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,
+      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
+  return out;
 }
 
 function serializeDicts(dicts) {
-  if (dicts === undefined || dicts === null || typeof dicts !== 'object') {
-    return {}
+  if (dicts === undefined || dicts === null || typeof dicts !== "object") {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, dict] of Object.entries(dicts)) {
-    if (dict === null || typeof dict !== 'object') continue
+    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
+    const meta = dict.meta;
     if (
       meta !== undefined &&
       meta !== null &&
-      meta.logicalType === 'dict' &&
+      meta.logicalType === "dict" &&
       meta.params !== undefined
     ) {
-      const params = meta.params
-      const keys = Array.isArray(params.keys) ? params.keys : []
+      const params = meta.params;
+      const keys = Array.isArray(params.keys) ? params.keys : [];
       const entries =
         params.entries !== undefined && params.entries !== null
           ? params.entries
-          : {}
-      const values = {}
+          : {};
+      const values = {};
       for (const k of keys) {
-        values[k] = entries[k] ?? null
+        values[k] = entries[k] ?? null;
       }
       // `doc` = entendimento do vocabulário inteiro (o que esse dict representa);
       // `presentation` = papel de apresentação declarado (ADR 0003) — null quando ausente.
       out[name] = {
         keys,
         values,
-        doc: typeof params.doc === 'string' ? params.doc : null,
-        presentation: typeof params.presentation === 'string' ? params.presentation : null,
-      }
-      continue
+        doc: typeof params.doc === "string" ? params.doc : null,
+        presentation:
+          typeof params.presentation === "string" ? params.presentation : 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
+    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 }
+    out[name] = { keys: [], values: {}, unknownShape: true };
   }
-  return out
+  return out;
 }
 
 function serializeAction(action, ctx) {
@@ -351,43 +387,43 @@ function serializeAction(action, ctx) {
     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 : []
+  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
+      action.background.enabled === true;
   }
 
-  if (action.kind === 'form') {
-    base.fields = serializeFields(action.fields)
+  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 === "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
+  if (action.kind === "view") {
+    base.projection = Array.isArray(action.projection) ? action.projection : [];
+    base.expand = action.expand ?? null;
   }
 
-  return base
+  return base;
 }
 
 function serializeFields(fields) {
-  if (fields === undefined || fields === null || typeof fields !== 'object') {
-    return {}
+  if (fields === undefined || fields === null || typeof fields !== "object") {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, spec] of Object.entries(fields)) {
-    if (spec === null || typeof spec !== 'object') continue
+    if (spec === null || typeof spec !== "object") continue;
     out[name] = {
       label: spec.label ?? null,
       placeholder: spec.placeholder ?? null,
@@ -399,21 +435,25 @@ function serializeFields(fields) {
       order: spec.order ?? null,
       widget: spec.widget ?? null,
       options: spec.options ?? null,
-      hasShowWhen: typeof spec.showWhen === 'function',
-      hasRequireWhen: typeof spec.requireWhen === 'function',
+      hasShowWhen: typeof spec.showWhen === "function",
+      hasRequireWhen: typeof spec.requireWhen === "function",
       aiDescription: spec.aiDescription ?? null,
-    }
+    };
   }
-  return out
+  return out;
 }
 
 function serializeFilters(filters) {
-  if (filters === undefined || filters === null || typeof filters !== 'object') {
-    return {}
+  if (
+    filters === undefined ||
+    filters === null ||
+    typeof filters !== "object"
+  ) {
+    return {};
   }
-  const out = {}
+  const out = {};
   for (const [name, spec] of Object.entries(filters)) {
-    if (spec === null || typeof spec !== 'object') continue
+    if (spec === null || typeof spec !== "object") continue;
     out[name] = {
       label: spec.label ?? null,
       placeholder: spec.placeholder ?? null,
@@ -426,9 +466,9 @@ function serializeFilters(filters) {
       depends: spec.depends ?? null,
       options: spec.options ?? null,
       aiDescription: spec.aiDescription ?? null,
-    }
+    };
   }
-  return out
+  return out;
 }
 
 function serializeReaction(reaction) {
@@ -437,13 +477,13 @@ function serializeReaction(reaction) {
     on: reaction.on,
     description: nullable(reaction.description),
     tags: Array.isArray(reaction.tags) ? reaction.tags : [],
-    handler: '<function>',
+    handler: "<function>",
     retry: reaction.retry ?? null,
     timeout: reaction.timeout ?? null,
     concurrency: reaction.concurrency ?? null,
-    hasDedup: typeof reaction.dedup === 'function',
-    hasAuthorize: typeof reaction.authorize === 'function',
-  }
+    hasDedup: typeof reaction.dedup === "function",
+    hasAuthorize: typeof reaction.authorize === "function",
+  };
 }
 
 function serializeSchedule(sched) {
@@ -457,8 +497,8 @@ function serializeSchedule(sched) {
     description: nullable(sched.description),
     tags: Array.isArray(sched.tags) ? sched.tags : [],
     input:
-      typeof sched.input === 'function' ? '<function>' : (sched.input ?? null),
-  }
+      typeof sched.input === "function" ? "<function>" : (sched.input ?? null),
+  };
 }
 
 // =============================================================================
@@ -466,16 +506,16 @@ function serializeSchedule(sched) {
 // =============================================================================
 
 function* iterateActions(actions) {
-  if (actions === undefined) return
+  if (actions === undefined) return;
   if (Array.isArray(actions)) {
-    for (const a of actions) yield a
-    return
+    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
+      for (const a of value) yield a;
     } else {
-      yield value
+      yield value;
     }
   }
 }
@@ -483,36 +523,36 @@ function* iterateActions(actions) {
 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
+  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
+    const strs = req.filter((r) => typeof r === "string");
+    return strs.length > 0 ? strs : null;
   }
-  return null
+  return null;
 }
 
 function serializeAuthorize(authorize) {
-  if (authorize === undefined || authorize === null) return null
+  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
+  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
+  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
+  if (schema === undefined || schema === null) return null;
   try {
-    return ctx.toJsonSchema(schema)
+    return ctx.toJsonSchema(schema);
   } catch (err) {
-    return { __unserializable: true, reason: err.message }
+    return { __unserializable: true, reason: err.message };
   }
 }
 
@@ -520,13 +560,13 @@ 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
+  return null;
 }
 
 function nullable(value) {
-  if (value === undefined || value === null) return null
-  if (typeof value === 'string' && value.length === 0) return null
-  return value
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string" && value.length === 0) return null;
+  return value;
 }
 
 // =============================================================================
@@ -534,14 +574,14 @@ function nullable(value) {
 // =============================================================================
 
 function emit(payload) {
-  process.stdout.write(JSON.stringify(payload) + '\n')
+  process.stdout.write(JSON.stringify(payload) + "\n");
 }
 
 function emitError(message) {
-  emit({ ok: false, error: message })
-  process.exit(1)
+  emit({ ok: false, error: message });
+  process.exit(1);
 }
 
 main().catch((err) => {
-  emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`)
-})
+  emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`);
+});