@softize/opus 25.0.0 → 25.2.0

package/CHANGELOG.md

@@ -7,6 +7,99 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.2.0 — 2026-10-03
+
+Uma action `view` pode declarar o assistente do recurso que ela lê (ADR 0053). Com isso, a conversa
+especializada num cliente, num relatório ou num pedido passa a ler o recurso, conferir o acesso,
+saber o procedimento da IA e escolher o dado ao modelo a partir de uma declaração só, no contrato:
+
+```ts
+ai: true,
+assistant: {
+  resource: 'customer',
+  skill: 'review-customer',
+  label: 'Assistente do cliente',
+  title: 'name',
+  context: ['kind', 'stage', 'leads.totalCount'],
+},
+```
+
+A action que declara passa a ser a action dona daquele tipo de recurso. Ela precisa ser `view`,
+estar publicada para a IA, declarar `personalData` e receber só `{ id }`.
+
+- `runtime.readResource(resource, id, base, { context })` executa a action dona pelo mesmo
+  `execute` de qualquer chamada, com a autorização, a auditoria e a marca de dado pessoal dela, e
+  devolve o descritor (`kind`, `id`, `title`, `label`, `skill`) e, com `context: true`, a projeção
+  limitada do dado. Um tipo sem dona devolve `runtime.assistant_resource_unknown` sem executar nada.
+- `runtime.assistants()` lista as declarações com a action dona, para o produto montar rotas sem
+  lista paralela e conferir num teste que cada `skill` existe no registro dele.
+- `projectAssistantContext(assistant, output)` devolve só os caminhos declarados e, acima do teto
+  (4.000 caracteres por padrão, de 1.000 a 16.000 em `maxContextChars`), corta por etapas até
+  caber, marcando `truncated` e listando o que saiu em `omitted`. Caminho ausente na saída é
+  omitido com o motivo `missing` e gera aviso no log, sem falhar a leitura.
+- `resourceDataBlock`, de `@softize/opus/ai`, monta o bloco delimitado que o host entrega ao modelo
+  numa mensagem de dado, com os escapes que impedem um valor de fechar o delimitador.
+- `runtime.aiTools()` leva `metadata.assistant`, e o `ListTools` do MCP publica
+  `com.softize.opus/assistant` em `_meta`.
+- O registro recusa a declaração inválida (`runtime.assistant_declaration_invalid`), o teto fora do
+  intervalo (`runtime.assistant_context_limit_invalid`) e duas donas do mesmo recurso
+  (`runtime.assistant_duplicate_resource`). O `opus check` ganha a regra `assistant-declaration`, o
+  `opus gen` confere `title`, `context` e a entrada contra os schemas, e o `opus copy` inventaria
+  `assistant.label`.
+- `@softize/opus/assistant-schema`, com tipos, exporta `assistantContextLeaves(output, context)`,
+  que lista, a partir do JSON Schema da saída no manifest, os campos folha que cada caminho de
+  `context` leva ao modelo. Um caminho que termina num objeto ou numa lista leva tudo abaixo dele; use a função num
+  teste para garantir que nenhum campo pessoal chega ao modelo por esse caminho.
+
+O manifest passa a projetar, em toda action, a publicação para a IA em `ai` (`enabled`,
+`description`, `destructive`, `requiresConfirmation`) e, na action dona, `assistant`. Se o seu
+projeto versiona o manifest, rode `opus gen` depois da atualização: sem isso, a conferência de
+frescor do manifest acusa a diferença. Nada muda para quem não declara assistente.
+
+## 25.1.0 — 2026-10-03
+
+`FloatingLayer`, de `@softize/opus/ui/react`, é uma camada que continua utilizável por cima de
+qualquer `Dialog` ou `Drawer` modal, como o botão e o painel de um assistente (ADR 0052). Quem está
+preenchendo um formulário em um modal pode usar a camada sem fechar o modal nem perder o que digitou.
+Os filhos vão para um hospedeiro fixo no `body`, `div[data-slot="floating-layer"]`, e cada um se
+posiciona contra a janela. Com um `Dialog` ou `Drawer` aberto:
+
+- clicar na camada não fecha o modal, mesmo que o elemento clicado suma no próprio clique, e o véu
+  continua fechando, respeitando `closeDisabled`;
+- o foco pode ir para a camada por clique ou por código sem ser puxado de volta, e o Tab passa do
+  último elemento do modal para a camada e dela de volta ao primeiro; quando o elemento focado da
+  camada some, o foco volta ao campo do modal em que a pessoa estava, e um modal que fecha com a
+  pessoa na camada não leva o foco ao gatilho dele;
+- o Esc age onde a pessoa está: na camada, nenhum modal fecha e `onEscapeKeyDown` é chamado uma vez
+  por tecla; no modal, o modal fecha;
+- a camada rola e continua visível ao leitor de tela, enquanto a página atrás segue travada e
+  escondida.
+
+O hospedeiro publica o `Dialog` ou `Drawer` do topo em `data-modal` (`none`, `dialog` ou `drawer`) e o
+lado do Drawer em `data-modal-side`, para o consumidor tirar o painel de cima do modal. O Opus não
+desloca nem redimensiona modais. Os patterns construídos sobre `Dialog` e `Drawer`, como
+`ActionFormDialog`, `ActionListDialog`, `Presentation` e `CommandDialog`, convivem com a camada sem
+mudança.
+
+Outras mudanças:
+
+- Popover, Menu, Tooltip, Select, Dialog e Drawer abertos de dentro de uma `FloatingLayer` vão para o
+  hospedeiro dela, e não para o `body`; fora da camada, nada muda;
+- `Dialog mode="alert"`, que também serve às confirmações do `DialogHost`, passa à faixa `z-70`,
+  acima da camada (`z-60`) e dos demais modais (`z-50`), e cobre a camada até a resposta, inclusive
+  enquanto um `Dialog` aberto de dentro dele estiver aberto. Popover, Menu e Tooltip do Opus abertos
+  de dentro de um alerta acompanham a faixa dele. Dois efeitos para conferir no seu código: um
+  elemento próprio com `z-index` entre 51 e 69, que antes ficava acima do alerta, agora fica abaixo
+  dele; e uma sobreposição de outra biblioteca com `z-50`, aberta de dentro de um alerta, fica
+  abaixo do véu dele. Durante a animação de saída, o alerta deixa de receber clique. A escala está
+  em `docs/stacking-scale.md`;
+- `DialogPortal` e `MenuPortal` sem `container` usam o hospedeiro da camada quando abertos de
+  dentro dela;
+- a `ref` de `DialogContent` e `DrawerContent` continua recebendo a limpeza das callback refs do
+  React 19, agora composta com a ref interna da camada;
+- o pacote ganha testes em navegador real (Chromium, pelo modo navegador do Vitest com Playwright)
+  para o foco da camada: `pnpm test:browser` roda à parte do `pnpm test` e entra no gate de release.
+
 ## 25.0.0 — 2026-10-02
 
 A exclusão lógica passa a declarar quando o registro excluído sai de vez (ADR 0051). `softDelete`

package/bin/cli.mjs

@@ -426,6 +426,11 @@ Regras das actions:
                             binding (o join contrato↔bind é cross-file)
   ignored-by-kind         — \`emits\` ou \`background\` em action list/view: o runtime
                             e o manifest só os aplicam em simple e form
+  assistant-declaration   — o assistente do recurso (ADR 0053): só em view, com \`ai\`
+                            habilitado, \`personalData\` declarado, \`resource\` em camelCase,
+                            \`skill\` em minúsculas com hífen, \`label\`, \`title\` e
+                            \`context\` presentes e \`maxContextChars\`, quando literal,
+                            de 1.000 a 16.000; o mesmo \`resource\` em duas actions reprova
 
 Regras da UI (@softize/opus/ui):
   ui-structure            — anatomia pública das superfícies compostas (ADR 0005):

package/bin/lib/assistant-schema.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Tipos de `@softize/opus/assistant-schema` (ADR 0053): a conferência do assistente do recurso
+ * contra o JSON Schema da action, como o manifest o traz. A implementação é `assistant-schema.mjs`.
+ */
+
+/** Um JSON Schema como o `opus gen` o projeta no manifest. */
+export type JsonSchema = Record<string, unknown>
+
+/** Os campos que um caminho de `context` leva ao modelo. */
+export interface AssistantContextLeaves {
+  /** O caminho declarado em `context`. */
+  path: string
+  /** Os campos folha alcançados, com ponto e sem índice de lista; `*` marca a chave de um mapa. */
+  leaves: string[]
+  /**
+   * Pontos em que o schema não declara forma ou volta a si mesmo por `$ref`: qualquer campo abaixo
+   * deles pode ir ao modelo, e a conferência não alcança.
+   */
+  open: string[]
+}
+
+/**
+ * Os campos folha que cada caminho de `context` leva ao modelo, a partir do JSON Schema da saída.
+ * Serve a um teste do consumidor que reprova campo pessoal alcançado por um caminho que termina
+ * num objeto ou numa lista.
+ */
+export function assistantContextLeaves(
+  output: JsonSchema,
+  context: readonly string[],
+  root?: JsonSchema,
+): AssistantContextLeaves[]
+
+/** O caminho existe em algum ramo não nulo do schema; listas são atravessadas. */
+export function schemaHasPath(schema: JsonSchema, segments: readonly string[], root?: JsonSchema): boolean
+
+/** O título resolve para texto ou número, fora de lista, em algum ramo não nulo. */
+export function schemaTitleIsText(schema: JsonSchema, segments: readonly string[], root?: JsonSchema): boolean
+
+/**
+ * Os problemas do assistente diante dos schemas de entrada e de saída, como frases. Lista vazia
+ * quando a declaração confere.
+ */
+export function assistantSchemaIssues(args: {
+  assistant: { title?: unknown; context?: unknown }
+  input: unknown
+  output: unknown
+}): string[]
+
+/** O `ai` de uma action normalizado como o manifest o projeta. */
+export function serializeAiConfig(ai: unknown): {
+  enabled: boolean
+  description: string | null
+  destructive: boolean
+  requiresConfirmation: boolean
+}

package/bin/lib/assistant-schema.mjs

@@ -0,0 +1,286 @@
+/**
+ * assistant-schema — confere o assistente do recurso (ADR 0053) contra o JSON Schema da action,
+ * no `opus gen`: `title` e cada caminho de `context` precisam existir na saída, e a entrada precisa
+ * ser um objeto em que `id`, do tipo texto, é o único campo obrigatório.
+ *
+ * Num campo anulável ou numa união (`anyOf`, `oneOf`, `allOf`), o caminho vale se existir em algum
+ * ramo que não seja `null`. Uma lista é atravessada: o caminho continua nos itens. Um schema sem
+ * forma declarada (`{}`, de `z.unknown()` ou `z.any()`) aceita qualquer caminho abaixo dele, porque
+ * não há o que conferir.
+ */
+
+const COMBINATORS = ["anyOf", "oneOf", "allOf"];
+const STRUCTURE_KEYS = ["type", "properties", "items", "additionalProperties", "enum", "const"];
+const MAX_DEPTH = 64;
+// Segmentos que mexem no protótipo de um objeto JavaScript; o registro do runtime também os recusa.
+const RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+
+function reservedSegments(path) {
+  return typeof path === "string" ? path.split(".").filter((segment) => RESERVED_SEGMENTS.has(segment)) : [];
+}
+
+function resolveRef(root, ref) {
+  if (!ref.startsWith("#/")) return undefined;
+  let node = root;
+  for (const raw of ref.slice(2).split("/")) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, key)) return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+function isNullOnly(schema) {
+  if (schema.type === "null") return true;
+  if (Array.isArray(schema.type) && schema.type.every((type) => type === "null")) return true;
+  // O alvo OpenAPI 3.0 do zod-to-json-schema escreve o ramo nulo como `{ enum: ['null'], nullable: true }`.
+  return (
+    Array.isArray(schema.enum) &&
+    schema.enum.length > 0 &&
+    schema.enum.every((value) => value === null || value === "null") &&
+    (schema.nullable === true || schema.enum.includes(null))
+  );
+}
+
+const NO_REFS = new Set();
+/** Marca o ponto em que um `$ref` volta a um schema que já está no caminho atual. */
+const CYCLE = Object.freeze({ cycle: true });
+
+/**
+ * Os ramos concretos e não nulos de um schema, com `$ref` e combinadores expandidos. Cada ramo traz
+ * os `$ref` percorridos no caminho atual; um `$ref` que se repete ali vira `CYCLE`, em vez de
+ * expandir de novo.
+ */
+function expand(schema, root, active = NO_REFS, depth = 0) {
+  if (schema === null || typeof schema !== "object" || depth > MAX_DEPTH) return [];
+  if (typeof schema.$ref === "string") {
+    if (active.has(schema.$ref)) return [{ schema: CYCLE, active }];
+    const target = resolveRef(root, schema.$ref);
+    return target === undefined ? [] : expand(target, root, new Set([...active, schema.$ref]), depth + 1);
+  }
+  const nested = COMBINATORS.flatMap((key) =>
+    Array.isArray(schema[key]) ? schema[key].flatMap((branch) => expand(branch, root, active, depth + 1)) : [],
+  );
+  const hasOwnStructure = STRUCTURE_KEYS.some((key) => Object.hasOwn(schema, key));
+  const combined = COMBINATORS.some((key) => Array.isArray(schema[key]));
+  if (combined && !hasOwnStructure) return nested;
+  if (isNullOnly(schema)) return nested;
+  return [{ schema, active }, ...nested];
+}
+
+/** Os ramos sem os ciclos, para quem só olha o tipo do próprio nó. */
+function branches(schema, root) {
+  return expand(schema, root).flatMap(({ schema: branch }) => (branch === CYCLE ? [] : [branch]));
+}
+
+function isOpen(schema) {
+  return (
+    !Object.hasOwn(schema, "$ref") &&
+    !STRUCTURE_KEYS.some((key) => Object.hasOwn(schema, key)) &&
+    !COMBINATORS.some((key) => Object.hasOwn(schema, key))
+  );
+}
+
+function isArraySchema(schema) {
+  return schema.type === "array" || (Array.isArray(schema.type) && schema.type.includes("array")) || Object.hasOwn(schema, "items");
+}
+
+/**
+ * Os schemas alcançados por `segments` em todos os ramos não nulos. Um schema sem forma alcança
+ * qualquer caminho abaixo dele e entra como está. Com `throughLists`, uma lista é atravessada. Um
+ * ciclo de `$ref` sem avançar no caminho (por lista ou união) não leva a lugar nenhum; ao descer
+ * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore.
+ */
+function collectTargets(schema, segments, root, throughLists, out, active = NO_REFS, depth = 0) {
+  if (depth > MAX_DEPTH) return;
+  if (segments.length === 0) {
+    out.push(schema);
+    return;
+  }
+  for (const { schema: branch, active: refs } of expand(schema, root, active)) {
+    if (branch === CYCLE) continue;
+    if (isOpen(branch)) {
+      out.push(branch);
+      continue;
+    }
+    if (isArraySchema(branch)) {
+      if (!throughLists) continue;
+      const items = Array.isArray(branch.items) ? branch.items : [branch.items];
+      for (const item of items) {
+        if (item !== undefined) collectTargets(item, segments, root, throughLists, out, refs, depth + 1);
+      }
+      continue;
+    }
+    const [head, ...rest] = segments;
+    const properties = branch.properties;
+    if (properties !== null && typeof properties === "object" && Object.hasOwn(properties, head)) {
+      collectTargets(properties[head], rest, root, throughLists, out, NO_REFS, depth + 1);
+    }
+    const additional = branch.additionalProperties;
+    if (additional !== null && typeof additional === "object") {
+      collectTargets(additional, rest, root, throughLists, out, NO_REFS, depth + 1);
+    }
+  }
+}
+
+/** O caminho `segments` existe em algum ramo não nulo de `schema`. */
+export function schemaHasPath(schema, segments, root = schema) {
+  const targets = [];
+  collectTargets(schema, segments, root, true, targets);
+  return targets.length > 0;
+}
+
+const TITLE_TYPES = new Set(["string", "number", "integer"]);
+
+/**
+ * O título resolve para texto ou número em algum ramo não nulo, sem atravessar lista: é o que o
+ * runtime consegue mostrar como nome do recurso.
+ */
+export function schemaTitleIsText(schema, segments, root = schema) {
+  const targets = [];
+  collectTargets(schema, segments, root, false, targets);
+  return targets.some((target) =>
+    isOpen(target) ||
+    branches(target, root).some((branch) => {
+      if (isOpen(branch)) return true;
+      const types = Array.isArray(branch.type) ? branch.type : [branch.type];
+      return types.some((type) => TITLE_TYPES.has(type));
+    }),
+  );
+}
+
+/**
+ * As folhas abaixo de `schema`. Um `$ref` que volta a um schema já no caminho atual (uma estrutura
+ * recursiva) entra em `open` naquele ponto: abaixo dele, qualquer profundidade pode chegar ao modelo.
+ */
+function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, depth = 0) {
+  if (depth > MAX_DEPTH) {
+    open.add(prefix);
+    return;
+  }
+  for (const { schema: branch, active: refs } of expand(schema, root, active)) {
+    if (branch === CYCLE || isOpen(branch)) {
+      open.add(prefix);
+      continue;
+    }
+    if (isArraySchema(branch)) {
+      const items = Array.isArray(branch.items) ? branch.items : [branch.items];
+      for (const item of items) if (item !== undefined) collectLeaves(item, prefix, root, leaves, open, refs, depth + 1);
+      continue;
+    }
+    const properties = branch.properties;
+    const hasProperties = properties !== null && typeof properties === "object" && Object.keys(properties).length > 0;
+    if (hasProperties) {
+      for (const [key, child] of Object.entries(properties)) {
+        collectLeaves(child, `${prefix}.${key}`, root, leaves, open, refs, depth + 1);
+      }
+    }
+    const additional = branch.additionalProperties;
+    if (additional !== null && typeof additional === "object") {
+      collectLeaves(additional, `${prefix}.*`, root, leaves, open, refs, depth + 1);
+    }
+    if (!hasProperties && !(additional !== null && typeof additional === "object")) leaves.add(prefix);
+  }
+}
+
+/**
+ * Os campos folha que cada caminho de `context` leva ao modelo, segundo o JSON Schema da saída
+ * (ADR 0053). Um caminho que termina num objeto ou numa lista projeta tudo abaixo dele; esta função
+ * lista o que é, para o consumidor conferir num teste, por exemplo, que nenhum campo pessoal chega
+ * ao modelo por um caminho que termina num contêiner.
+ *
+ * - `leaves`: caminhos das folhas, com ponto e sem índice de lista; `*` marca a chave de um mapa;
+ * - `open`: pontos em que o schema não declara forma (`z.unknown()`, `z.any()`) ou volta a si mesmo
+ *   por `$ref`: qualquer campo abaixo deles pode ir ao modelo, e a conferência não alcança.
+ */
+export function assistantContextLeaves(output, context, root = output) {
+  return context.map((path) => {
+    const targets = [];
+    collectTargets(output, path.split("."), root, true, targets);
+    const leaves = new Set();
+    const open = new Set();
+    for (const target of targets) collectLeaves(target, path, root, leaves, open);
+    return { path, leaves: [...leaves].sort(), open: [...open].sort() };
+  });
+}
+
+function isText(schema, root) {
+  return branches(schema, root).some(
+    (branch) => branch.type === "string" || (Array.isArray(branch.type) && branch.type.includes("string")),
+  );
+}
+
+function unserializable(schema) {
+  return schema === null || schema === undefined || schema.__unserializable === true;
+}
+
+/**
+ * Os problemas do assistente de uma action diante dos JSON Schemas de entrada e de saída, como
+ * frases. Lista vazia quando a declaração cabe nos schemas.
+ */
+export function assistantSchemaIssues({ assistant, input, output }) {
+  const issues = [];
+  if (unserializable(input)) {
+    issues.push("o schema de entrada não pôde ser convertido em JSON Schema para conferir o `id`");
+  } else {
+    const objects = branches(input, input).filter(
+      (branch) => branch.type === "object" || Object.hasOwn(branch, "properties"),
+    );
+    if (objects.length !== 1) {
+      issues.push("a entrada precisa ser um objeto com `id`, do tipo texto, como único campo obrigatório");
+    } else {
+      const [object] = objects;
+      const required = Array.isArray(object.required) ? object.required : [];
+      const id = object.properties?.id;
+      if (id === undefined || !required.includes("id")) {
+        issues.push("a entrada precisa ter `id` obrigatório");
+      } else if (!isText(id, input)) {
+        issues.push("o `id` da entrada precisa ser do tipo texto");
+      }
+      const others = required.filter((key) => key !== "id");
+      if (others.length > 0) {
+        issues.push(
+          `a entrada só pode exigir \`id\`, mas também exige ${others.map((key) => `\`${key}\``).join(", ")}; dê um valor padrão a esses campos ou torne-os opcionais`,
+        );
+      }
+    }
+  }
+  const reserved = [assistant.title, ...(Array.isArray(assistant.context) ? assistant.context : [])].filter(
+    (path) => reservedSegments(path).length > 0,
+  );
+  if (reserved.length > 0) {
+    issues.push(
+      `${reserved.map((path) => `\`${path}\``).join(", ")} usa __proto__, constructor ou prototype, que não são campos da saída`,
+    );
+    return issues;
+  }
+  if (unserializable(output)) {
+    issues.push("o schema de saída não pôde ser convertido em JSON Schema para conferir `title` e `context`");
+    return issues;
+  }
+  const missing = (path) => typeof path !== "string" || !schemaHasPath(output, path.split("."));
+  if (missing(assistant.title)) {
+    issues.push(`\`${assistant.title}\`, de \`title\`, não existe na saída`);
+  } else if (!schemaTitleIsText(output, assistant.title.split("."))) {
+    issues.push(
+      `\`${assistant.title}\`, de \`title\`, precisa ser texto ou número, fora de lista, para nomear o recurso`,
+    );
+  }
+  const absent = (Array.isArray(assistant.context) ? assistant.context : []).filter(missing);
+  if (absent.length > 0) {
+    const list = absent.map((path) => `\`${path}\``).join(", ");
+    issues.push(`${list}, de \`context\`, ${absent.length === 1 ? "não existe" : "não existem"} na saída`);
+  }
+  return issues;
+}
+
+/** O `ai` da action normalizado para o manifest. */
+export function serializeAiConfig(ai) {
+  const config = ai === true ? { enabled: true } : ai !== null && typeof ai === "object" ? ai : null;
+  return {
+    enabled: config !== null && config.enabled !== false,
+    description: typeof config?.description === "string" && config.description.length > 0 ? config.description : null,
+    destructive: config?.destructive === true,
+    requiresConfirmation: config?.requiresConfirmation === true,
+  };
+}