@softize/opus 18.0.1 → 18.1.1

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -56,8 +56,11 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
   estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
-- A fonte raiz pertence ao navegador e à aplicação. Medidas escaláveis usam `rem` ou a escala
-  relativa do Tailwind; `px` fica restrito a hairlines e compensações ligadas a essas bordas.
+- A UI assume layout desktop fixo e largura mínima suportada de `64rem`. Não introduzir
+  breakpoints de viewport ou container queries isoladas; uma futura responsividade precisa começar
+  pelo shell e formar um contrato sistêmico. A fonte raiz pertence ao navegador e à aplicação.
+  Medidas escaláveis usam `rem` ou a escala relativa do Tailwind; `px` fica restrito a hairlines
+  e compensações ligadas a essas bordas.
 - Superfície semântica e foreground são um par local (`bg-card text-card-foreground`,
   `bg-popover text-popover-foreground`); herança do foreground global não substitui o par.
 - Forma usa a escala `rounded-*`; nome de componente não cria uma segunda escala de radius.
@@ -70,6 +73,11 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
 - `ActionFilterBar` renderiza busca, filtros, período e ações declarados por uma list action
   quando a tela precisa da toolbar sem entregar os resultados a `ActionList`. Manter seu
   `state` e `onStateChange` ligados à mesma projeção de URL usada pela superfície.
+- Filtros de list action declaram onde aparecem com `placement`: `inline` fica na barra;
+  `advanced` vai para o painel de filtros avançados, agrupado por `section` e distribuído em até
+  três colunas com `advancedFilters.columns`; `external` continua no estado navegável e no input,
+  mas a tela apresenta o controle por conta própria. `advanced: true` segue aceito só durante a
+  migração; em código novo, declarar `placement`.
 - `ActionForm` mantém validação, execução e estados do contrato nos dois modos: sem `children`,
   renderiza os campos declarados; com `children`, o consumidor diagrama `ActionFormField` e
   controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
@@ -78,8 +86,13 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   a ação principal mantém `solid`. Criação e edição comuns preservam o rótulo padrão `Salvar`;
   `submitLabel` fica para efeitos específicos, como `Renomear` ou `Criar nova versão`. Em
   `Dialog mode="alert"`, a saída segura também usa `outline`.
+- `DialogFooter` e `DrawerFooter` cuidam só da faixa. Agrupar e distribuir as decisões cabe a um
+  `ButtonGroup` dentro deles, com `distribution="equal"` para o footer 50/50; botões soltos no
+  footer não são distribuídos. `ActionFormDialog` já compõe isso: por padrão o footer acompanha o
+  conteúdo com o cancelamento em `ghost`, e `footerDistribution="equal"` divide a faixa e passa o
+  cancelamento a `outline`.
 - Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
-  padrão é uma action ghost somente com ícone no final do header; não crie uma posição flutuante
+  padrão é o `CloseButton` (`neutral`, `subtle`, pílula) no final do header, sem posição flutuante
   alternativa. Não preencher uma segunda linha por hábito. Consequência, restrição ou instrução que
   realmente mude a tarefa entra no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`;
   wrappers usam `intro` e a API imperativa usa `body`. Relacione texto conciso por
@@ -90,7 +103,10 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   ou views nomeadas. Usar `ActionFilterBar` isoladamente só quando outra superfície assumir a
   renderização dos resultados. Colunas numéricas não recebem alinhamento ou tipografia por
   inferência do tipo: declarar `className` no header e na célula quando o produto exigir, de
-  modo que números preservem o alinhamento natural por padrão.
+  modo que números preservem o alinhamento natural por padrão. O valor principal de uma célula
+  preserva `text-sm` e o foreground da superfície; `text-xs text-muted-foreground` fica restrito
+  a metadado subordinado a outro valor na mesma célula. Cabeçalhos e `EmptyValue` continuam muted;
+  não reduzir nem atenuar uma coluna inteira por ela ser técnica, temporal ou menos destacada.
 - `ItemGroup` representa uma coleção e pode oferecer moldura explícita; `Item` já carrega
   semântica de item de lista. Preferir essa composição a uma sequência visual sem estrutura.
 - `Empty` com moldura tracejada comunica uma região disponível para criar ou vincular algo.

package/src/auth/drivers/jwt.ts

@@ -34,7 +34,8 @@ import type { AuthAdapter, CanFn, User } from '../../core/index.ts'
 // =============================================================================
 
 export interface JwtAuthOptions<P extends JwtPayload = JwtPayload> {
-  /** Secret HMAC ou public key. Pode ser string sync ou async resolver. */
+  /** Secret HMAC ou public key, fixo ou por resolver (sync ou async). O resolver é chamado
+   *  sem argumentos: a escolha da chave pelo `kid` do token ainda não é suportada. */
   secret: string | Buffer | ((kid?: string) => Promise<string | Buffer> | string | Buffer)
 
   /** Algorithms aceitos (default ['HS256']). */

package/src/core/runtime.ts

@@ -75,6 +75,23 @@ import type {
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+/**
+ * Erro devolvido a um cliente de IA que chama uma tool fora do conjunto exposto.
+ *
+ * Quem executa tools (o agente co-locado e o servidor MCP) só pode rodar o que `aiTools()`
+ * anunciou. O modelo, ou um prompt injetado, pode emitir qualquer nome; sem este corte, uma
+ * action sem `ai.enabled` — inclusive destrutiva — rodaria dentro da autorização do contexto.
+ * A resposta é a mesma para nome inexistente e para action registrada mas não exposta, para
+ * que o cliente não descubra quais actions existem.
+ */
+export function aiToolNotFound(name: string): ReturnType<typeof error> {
+  return error({
+    code: 'runtime.action_not_found',
+    category: 'not_found',
+    message: `Tool "${name}" não está disponível.`,
+  })
+}
+
 /** Normaliza o `ai` da action (`boolean | AIConfig`) → config, ou null se não exposta à IA. */
 function normalizeAiConfig(ai: boolean | AIConfig | undefined): AIConfig | null {
   if (ai === undefined || ai === false) return null
@@ -620,10 +637,10 @@ export class Runtime {
       // — 1. Validate input ————————————————————————————————————————————————
       const validatedInput = await this.validate(action.input, input, 'input')
 
-      // — 2. Load —————————————————————————————————————————————————————————
-      const loaded = await this.runLoaders(action, ctx, validatedInput)
-
-      // — 3. Authenticate (public-or-user) ——————————————————————————————————
+      // — 2. Authenticate (public-or-user) ——————————————————————————————————
+      // Antes dos loaders: eles consultam dados, e um chamador anônimo não pode nem disparar essas
+      // consultas nem distinguir, pelo erro de um loader, se um registro existe. A autenticação
+      // não depende de nada carregado; a autorização, sim, e por isso vem depois.
       if (action.public !== true && ctx.user === null) {
         throw error({
           code: 'auth.unauthenticated',
@@ -632,6 +649,9 @@ export class Runtime {
         })
       }
 
+      // — 3. Load —————————————————————————————————————————————————————————
+      const loaded = await this.runLoaders(action, ctx, validatedInput)
+
       // — 4. Authorize ——————————————————————————————————————————————————————
       if (action.authorize !== undefined) {
         const authorizeFn = this.compileAuthorize(action.authorize)
@@ -815,6 +835,7 @@ export class Runtime {
     for (const action of this.actions.values()) {
       const cfg = normalizeAiConfig(action.ai)
       if (cfg === null) continue
+      const dataProducts = [...(this.actionDataProducts.get(action.name) ?? [])].sort()
       tools.push({
         name: action.name,
         ...(action.label !== undefined
@@ -822,7 +843,12 @@ export class Runtime {
           : {}),
         description: cfg.description ?? action.description ?? action.name,
         inputSchema: action.input,
-        metadata: { dataProducts: [...(this.actionDataProducts.get(action.name) ?? [])].sort() },
+        metadata: {
+          dataProducts,
+          dataProductLabels: Object.fromEntries(
+            dataProducts.map((id) => [id, this.dataProducts.get(id)?.label ?? id]),
+          ),
+        },
       })
     }
     this.aiToolsCache = tools
@@ -842,6 +868,7 @@ export class Runtime {
       ...opts,
       tools,
       execute: async (name, toolInput) => {
+        if (!tools.some((tool) => tool.name === name)) return { error: aiToolNotFound(name) }
         const cfg = normalizeAiConfig(this.actions.get(name)?.ai)
         if (cfg !== null && (cfg.destructive === true || cfg.requiresConfirmation === true)) {
           const approved = opts?.confirm ? await opts.confirm({ name, input: toolInput }) : false

package/src/core/types.ts

@@ -602,8 +602,12 @@ export interface FilterSpec {
   operators?: FilterOp[]
   path?: string
 
-  /** Filtro AVANÇADO: sai da barra inline e vai pro modal "Filtros" (com contador de
-   *  ativos no botão). Os não-avançados rendem inline na toolbar da listagem. */
+  /** Onde o filtro é controlado na interface. `external` mantém o filtro no contrato,
+   *  no estado navegável e no input efetivo, mas deixa sua apresentação para outra
+   *  superfície — por exemplo, cards de status acima da lista. */
+  placement?: 'inline' | 'advanced' | 'external'
+
+  /** @deprecated Use `placement: 'advanced'`. Mantido durante a migração dos contratos. */
   advanced?: boolean
 
   section?: string
@@ -616,9 +620,9 @@ export interface FilterSpec {
 
 /**
  * Coluna declarativa de uma `ListAction` — a UI (ActionList) deriva a tabela
- * daqui; células custom entram POR CIMA na UI (prop `cells`, chave = key). É a base
- * do futuro column picker (o usuário escolher colunas): a lista completa vive no
- * contrato, `hidden` marca as que nascem fora.
+ * daqui; células custom entram POR CIMA na UI (prop `cells`, chave = key). O seletor
+ * de colunas parte desta lista: ela vive completa no contrato, e `hidden` marca as que
+ * nascem fora.
  */
 export interface ListColumnSpec {
   /** Chave do item (`Out`) que a coluna mostra. */
@@ -1264,7 +1268,12 @@ export interface AiTool {
   description: string
   inputSchema: unknown
   /** Metadados de governança para o host; não fazem parte do prompt nem concedem acesso. */
-  metadata?: { dataProducts?: string[] }
+  metadata?: {
+    /** Identificadores técnicos dos Produtos de Dados relacionados. */
+    dataProducts?: string[]
+    /** Labels humanas por identificador; ausente para runtimes legados. */
+    dataProductLabels?: Record<string, string>
+  }
 }
 
 /** Turno de conversa (histórico multi-turn do chat). */
@@ -1376,7 +1385,7 @@ export interface ScheduleDef {
   cron?: string
   /** Shorthand interval — ex: '1h', '30m', '15s'. */
   every?: string
-  /** Timezone IANA — ex: 'America/Sao_Paulo'. Default: UTC. */
+  /** Timezone IANA — ex: 'America/Sao_Paulo'. Sem ela, vale a hora local do processo. */
   timezone?: string
 
   /** Input passado ao runtime.execute(); estático ou dinâmico. */

package/src/mcp/index.ts

@@ -14,6 +14,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { zodToJsonSchema } from 'zod-to-json-schema'
 import type { ContextBase, Runtime } from '../core/index.ts'
 import { readPackageVersion } from '../core/package-version.ts'
+import { aiToolNotFound } from '../core/runtime.ts'
 
 export interface OpusMcpOptions {
   name?: string
@@ -47,11 +48,22 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
       ...(t.title !== undefined ? { title: t.title } : {}),
       description: t.description,
       inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
-      _meta: { 'com.softize.opus/data-products': t.metadata?.dataProducts ?? [] },
+      _meta: {
+        'com.softize.opus/data-products': t.metadata?.dataProducts ?? [],
+        'com.softize.opus/data-product-labels': t.metadata?.dataProductLabels ?? {},
+      },
     })),
   }))
 
   server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+    // Executa só o que ListTools anunciou. Sem este corte, qualquer action registrada — sem
+    // `ai.enabled`, inclusive destrutiva — rodaria dentro da autorização do contexto.
+    if (!runtime.aiTools().some((tool) => tool.name === req.params.name)) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: aiToolNotFound(req.params.name) }) }],
+        isError: true,
+      }
+    }
     const base = opts.resolveContext ? await opts.resolveContext(extra) : ANON
     const result = await runtime.execute(req.params.name, req.params.arguments ?? {}, base)
     const payload = result.ok ? result.data : { error: result.error }

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -48,7 +48,7 @@ export interface ActionListDialogProps<
   empty?: (items: TItem[]) => boolean
   /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
   loading?: boolean
-  /** Classes do DialogContent (largura). Default: sm:max-w-3xl (lista pede espaço). */
+  /** Classes do DialogContent (largura). Default: max-w-3xl (lista pede espaço). */
   className?: string
   /** O layout dos itens (cards/linhas) — os estados já saíram daqui. */
   children: (items: TItem[], refetch: () => Promise<void>) => ReactNode
@@ -78,7 +78,7 @@ export function ActionListDialog<
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent
-        className={cn('sm:max-w-3xl', className)}
+        className={cn('max-w-3xl', className)}
         aria-describedby={intro === undefined ? undefined : introId}
       >
         <DialogHeader>

package/src/ui/components/patterns/content-header.tsx

@@ -50,7 +50,7 @@ interface ContentBaseProps extends Omit<
 
 interface ContentShorthandProps extends ContentBaseProps {
   title: ReactNode;
-  /** Total de itens ao lado do título — o mesmo `count` de Page. */
+  /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
   description?: ReactNode;
   actions?: ReactNode;
@@ -171,7 +171,7 @@ export function ContentHeader({
         }}
         className={cn(
           content.variant === "page" &&
-            "flex-row items-center justify-start gap-3 sm:flex-row sm:items-center sm:justify-start",
+            "flex-row items-center justify-start gap-3",
           className,
         )}
         {...props}

package/src/ui/components/patterns/form-dialog.tsx

@@ -29,6 +29,8 @@ export interface ActionFormDialogProps<
   title: string;
   /** Conteúdo relevante apresentado antes dos campos, como texto ou Alert. */
   intro?: ReactNode;
+  /** Distribui as ações pela largura disponível somente quando as decisões pedem peso equivalente. */
+  footerDistribution?: "content" | "equal";
 }
 
 export function ActionFormDialog<
@@ -42,6 +44,7 @@ export function ActionFormDialog<
   onSuccess,
   onCancel,
   cancelVariant,
+  footerDistribution = "content",
   ...rest
 }: ActionFormDialogProps<TInput, TData>) {
   const introId = useId();
@@ -72,7 +75,7 @@ export function ActionFormDialog<
           )}
           footer={(actions) => (
             <DialogFooter>
-              <ButtonGroup mode="spaced" distribution="equal">
+              <ButtonGroup mode="spaced" distribution={footerDistribution}>
                 {actions}
               </ButtonGroup>
             </DialogFooter>
@@ -82,7 +85,9 @@ export function ActionFormDialog<
             onOpenChange(false);
           }}
           onCancel={onCancel ?? (() => onOpenChange(false))}
-          cancelVariant={cancelVariant ?? "outline"}
+          cancelVariant={
+            cancelVariant ?? (footerDistribution === "equal" ? "outline" : "ghost")
+          }
         />
       </DialogContent>
     </Dialog>

package/src/ui/components/patterns/form.tsx

@@ -702,7 +702,7 @@ export interface ActionFormProps<
   onSuccess?: (data: TData) => void;
   submitLabel?: string;
   cancelLabel?: string;
-  /** Tratamento visual do cancelamento. Use outline quando ele dividir o footer com a ação principal. */
+  /** Tratamento visual do cancelamento. `ghost` por padrão; `outline` quando o footer distribui as ações por igual. */
   cancelVariant?: Extract<ButtonVariant, "ghost" | "outline">;
   onCancel?: () => void;
   /** Bloqueia campos e ações sem desmontar o formulário. */