@softize/opus 21.0.1 → 22.1.0

package/src/vite/design.ts

@@ -6,7 +6,7 @@
  * Antes, o dev server proxeava `/api` pra um backend real — o que vaza escrita
  * pra prod e exige infra de pé pra desenhar tela. Com o plugin, `vite --mode
  * design` monta o runtime (driver `nodeServer`) no próprio dev server: os
- * `mockHandler` dos contratos respondem (`OPUS_MODE=design`), qualquer proxy
+ * actions respondem pelos dados de design (ADR 0037), qualquer proxy
  * configurado é DESLIGADO (prefixo ex-proxy sem cobertura responde 503 em
  * envelope, nunca vaza), e o Maestro sonda `GET /__opus/design` pra saber que
  * o preview está montado.
@@ -44,6 +44,7 @@ import {
   isDomainConfig,
   isReaction,
   isSchedule,
+  type ActionContext,
   type ActionDef,
   type AuthAdapter,
   type ErrorInput,
@@ -53,6 +54,7 @@ import {
   type User,
 } from '../core/index.ts'
 import { readPackageVersion } from '../core/package-version.ts'
+import { designResponse, isDesignScenario, type DesignScenario } from '../design/index.ts'
 import { mittEvents } from '../events/drivers/mitt.ts'
 import { nodeServer, type NodeServerHandle } from '../server/drivers/node.ts'
 import { serializeResult } from '../server/index.ts'
@@ -84,6 +86,14 @@ export interface OpusDesignOptions {
    */
   entry?: string | string[]
 
+  /**
+   * Cenários de design (ADR 0037): módulos que exportam `defineDesignScenario(contrato, resposta)`.
+   * Aceita caminhos e globs, como `entry`. O cenário vence o `mockHandler` e a resposta padrão
+   * gerada pelo `fake`; cenário de action inexistente impede o boot, com a lista no erro.
+   * Sem default: o projeto decide onde os cenários ficam e se são versionados.
+   */
+  scenarios?: string | string[]
+
   /** Prefixo do path. Default '/api'. */
   apiPrefix?: string
 
@@ -145,10 +155,14 @@ const PROBE_PATH = '/__opus/design'
 // deixá-los chegar no handler (moram fora do apiPrefix).
 const RUNTIME_ENDPOINT_PATHS = new Set(['/health', '/ready', '/openapi.json'])
 
+/** De onde vem a resposta de cada action no modo design, na ordem de precedência. */
+type DesignSource = 'scenario' | 'mock' | 'handler' | 'generated'
+
 interface DesignState {
   handle: NodeServerHandle
   runtime: Runtime
   actions: ActionDef[]
+  sources: Map<string, DesignSource>
 }
 
 export function opusDesign(options: OpusDesignOptions = {}): Plugin {
@@ -156,6 +170,12 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
   const entries = Array.isArray(options.entry)
     ? options.entry
     : [options.entry ?? './opus.config.ts']
+  const scenarioEntries =
+    options.scenarios === undefined
+      ? []
+      : Array.isArray(options.scenarios)
+        ? options.scenarios
+        : [options.scenarios]
   const devBackend = options.devBackend === true
   // Mais-específico primeiro: prefixo mais longo vence.
   const stubEntries = Object.entries(options.stubs ?? {}).sort(
@@ -194,8 +214,8 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       exProxyPrefixes = Object.keys(config.server?.proxy ?? {})
       // 2) Mata o proxy: fecha o vazamento preview→prod pra QUALQUER prefixo.
       if (config.server?.proxy !== undefined) config.server.proxy = undefined
-      // 3) O execute() roteia handler×mockHandler lendo OPUS_MODE (isOpusDesignMode);
-      //    com o runtime local, o preview fica autossuficiente.
+      // 3) O execute() roteia pro mockHandler lendo OPUS_MODE (isOpusDesignMode); o boot
+      //    liga em cada action a resposta de design, e o preview fica autossuficiente.
       process.env.OPUS_MODE = 'design'
     },
 
@@ -215,7 +235,14 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
             registrables.push(...(await loadEntry(server, entry)))
           }
         }
-        const { actions, dropped } = collectActions(registrables)
+        const collected = collectActions(registrables)
+        const { dropped } = collected
+        const scenarios = isDesign
+          ? await loadScenarios(server, scenarioEntries, collected.actions)
+          : new Map<string, DesignScenario>()
+        const { actions, sources } = isDesign
+          ? prepareDesignActions(collected.actions, scenarios)
+          : { actions: collected.actions, sources: new Map<string, DesignSource>() }
 
         const handle = nodeServer({ apiPrefix })
         const runtime = createRuntime({
@@ -223,8 +250,8 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
           auth: designAuth({ user: options.user, tenantId: options.tenantId }),
           eventBus: mittEvents(),
           storage: memStorage(),
-          // SEM `data` de propósito: design não toca ctx.db — handler real sem
-          // mock falhando é o sinal certo de que falta mockar.
+          // SEM `data` de propósito: design não toca ctx.db. Uma action ligada a handler real
+          // que dependa do banco falha aqui; o caminho é um cenário (ADR 0037).
           ...options.runtime,
           config: { env: 'development', dev: true, ...options.runtime?.config },
         })
@@ -236,19 +263,9 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
             `[opus-design] ${dropped} reaction(s)/schedule(s) ignorada(s) — o runtime de design é request/response.`,
           )
         }
-        if (isDesign) {
-          for (const action of actions) {
-            if (action.mockHandler === undefined) {
-              logger.warn(
-                `[opus-design] Action "${action.name}" sem mockHandler — em design cai no handler real e pode falhar sem adapters.`,
-              )
-            }
-          }
-        }
-
         await runtime.start()
         handle.adapter.mountEndpoints({ health: true, ready: true, openapi: true })
-        return { handle, runtime, actions }
+        return { handle, runtime, actions, sources }
       }
 
       // Promise-mutex: requests em voo aguardam o MESMO boot; rebuild (stale)
@@ -285,8 +302,9 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       //   add/unlink: QUALQUER arquivo sob o root (fora node_modules/.git) —
       //   arquivo novo nunca importado não está no graph, e é exatamente ele
       //   que um entry glob precisa enxergar. Over-invalidation é barata.
+      const watchedEntries = [...entries, ...scenarioEntries]
       const entryPaths = new Set(
-        entries
+        watchedEntries
           .filter((entry) => !isGlobPattern(entry))
           .map((entry) => path.resolve(server.config.root, entry)),
       )
@@ -294,7 +312,7 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       // pode apontar pra FORA dele (ex.: '../../services/*/contract.ts', caso GB):
       // mandamos o chokidar observar o PREFIXO ESTÁTICO de cada glob — o mesmo que
       // o expandGlob anda, nunca o mundo — pra change/unlink lá também invalidar.
-      const globSpecs = entries
+      const globSpecs = watchedEntries
         .filter(isGlobPattern)
         .map((pattern) => globSpec(server.config.root, pattern))
       for (const { prefixDir } of globSpecs) server.watcher.add(prefixDir)
@@ -341,12 +359,21 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
         }
         try {
           const state = await ensureBoot()
-          const unmocked = state.actions.filter((a) => a.mockHandler === undefined)
+          const named = (source: DesignSource): string[] =>
+            state.actions.filter((a) => state.sources.get(a.name) === source).map((a) => a.name)
+          const scenarios = named('scenario')
+          const mocks = named('mock')
           payload.runtime = {
             prefix: apiPrefix,
             actions: state.actions.length,
-            mocked: state.actions.length - unmocked.length,
-            unmocked: unmocked.map((a) => a.name),
+            // `mocked`/`unmocked` mantêm o formato anterior da sonda: resposta escrita à mão
+            // (cenário ou mockHandler) contra o resto, que responde por handler real ou `fake`.
+            mocked: scenarios.length + mocks.length,
+            unmocked: state.actions
+              .filter((a) => !['scenario', 'mock'].includes(state.sources.get(a.name) ?? ''))
+              .map((a) => a.name),
+            scenarios,
+            generated: named('generated'),
           }
         } catch (err) {
           payload.error = String(err)
@@ -605,6 +632,89 @@ function registrablesOfModule(mod: Record<string, unknown>): unknown[] {
   return [...out]
 }
 
+// =============================================================================
+// Dados de design (ADR 0037)
+// =============================================================================
+
+/**
+ * Carrega os cenários dos módulos casados por `scenarios`. Cenário de action inexistente ou dois
+ * cenários para a mesma action impedem o boot: o preview mostra o erro em vez de silenciar.
+ */
+async function loadScenarios(
+  server: ViteDevServer,
+  patterns: string[],
+  actions: ActionDef[],
+): Promise<Map<string, DesignScenario>> {
+  const scenarios = new Map<string, DesignScenario>()
+  const known = new Set(actions.map((action) => action.name))
+  const unknown: string[] = []
+  const duplicated: string[] = []
+  for (const pattern of patterns) {
+    const files = isGlobPattern(pattern) ? expandGlob(server.config.root, pattern) : [normalizeEntryUrl(pattern)]
+    for (const file of files) {
+      const mod = (await server.ssrLoadModule(file)) as Record<string, unknown>
+      for (const scenario of scenariosOfModule(mod)) {
+        if (!known.has(scenario.action)) unknown.push(scenario.action)
+        else if (scenarios.has(scenario.action) && scenarios.get(scenario.action) !== scenario) {
+          duplicated.push(scenario.action)
+        } else scenarios.set(scenario.action, scenario)
+      }
+    }
+  }
+  if (unknown.length > 0 || duplicated.length > 0) {
+    const names = (list: string[]): string => [...new Set(list)].join(', ')
+    const problems = [
+      unknown.length > 0 ? `sem action registrada: ${names(unknown)}` : '',
+      duplicated.length > 0 ? `mais de um cenário para: ${names(duplicated)}` : '',
+    ].filter(Boolean)
+    throw error({
+      code: 'design.invalid_scenario',
+      category: 'internal',
+      message: `Cenários de design inválidos (${problems.join('; ')}).`,
+    })
+  }
+  return scenarios
+}
+
+function scenariosOfModule(mod: Record<string, unknown>): DesignScenario[] {
+  const out = new Set<DesignScenario>()
+  const add = (value: unknown): void => {
+    if (Array.isArray(value)) value.forEach(add)
+    else if (isDesignScenario(value)) out.add(value)
+  }
+  Object.values(mod).forEach(add)
+  return [...out]
+}
+
+/**
+ * Liga a cada action a resposta de design, nesta precedência: cenário, `mockHandler` declarado,
+ * handler real (`bindAction`) e, por fim, a resposta padrão gerada pelo `fake`.
+ */
+function prepareDesignActions(
+  actions: ActionDef[],
+  scenarios: Map<string, DesignScenario>,
+): { actions: ActionDef[]; sources: Map<string, DesignSource> } {
+  const sources = new Map<string, DesignSource>()
+  const prepared = actions.map((action): ActionDef => {
+    const scenario = scenarios.get(action.name)
+    if (scenario !== undefined) {
+      sources.set(action.name, 'scenario')
+      return { ...action, mockHandler: (ctx: ActionContext, input: unknown) => scenario.respond(input, ctx) } as ActionDef
+    }
+    if (action.mockHandler !== undefined) {
+      sources.set(action.name, 'mock')
+      return action
+    }
+    if (typeof (action as { handler?: unknown }).handler === 'function') {
+      sources.set(action.name, 'handler')
+      return action
+    }
+    sources.set(action.name, 'generated')
+    return { ...action, mockHandler: async (_ctx: ActionContext, input: unknown) => designResponse(action, input) } as ActionDef
+  })
+  return { actions: prepared, sources }
+}
+
 /** Achata os registráveis em actions; reactions/schedules ficam de fora (contados). */
 function collectActions(items: unknown[]): { actions: ActionDef[]; dropped: number } {
   const actions: ActionDef[] = []
@@ -621,7 +731,7 @@ function collectActions(items: unknown[]): { actions: ActionDef[]; dropped: numb
       dropped += 1
       continue
     }
-    // ActionDef ou contrato (sem handler): em design o mockHandler responde.
+    // ActionDef ou contrato (sem handler): em design, a resposta de design responde.
     actions.push(item as ActionDef)
   }
   return { actions, dropped }