npm - @softize/opus - Versions diffs - 18.1.0 → 18.2.0 - Mend

@softize/opus 18.1.0 → 18.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (102) hide show

package/CHANGELOG.md +75 -0
package/PROMOTED.md +4 -5
package/README.md +5 -4
package/bin/cli.mjs +4 -0
package/docs/adr/0004-page-content-state-is-composed.md +3 -0
package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md +6 -2
package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md +6 -1
package/docs/adr/0014-structural-headers-do-not-carry-description.md +2 -2
package/docs/adr/0015-action-size-follows-interaction-density.md +4 -3
package/docs/adr/{0012-modal-header-only-names-the-surface.md → 0018-modal-header-only-names-the-surface.md} +4 -1
package/docs/adr/{0016-productive-surfaces-use-compact-density.md → 0019-productive-surfaces-use-compact-density.md} +4 -1
package/docs/code-style.md +2 -2
package/docs/consumer-upgrade-propagation.md +1 -1
package/docs/data-products.md +5 -3
package/docs/protocol.md +6 -6
package/docs/releasing.md +28 -4
package/package.json +1 -1
package/registry/skills/build-opus-ui/references/ui-patterns.md +11 -1
package/src/auth/drivers/jwt.ts +2 -1
package/src/core/presentation.ts +143 -58
package/src/core/runtime.ts +25 -4
package/src/core/types.ts +4 -4
package/src/mcp/index.ts +9 -0
package/src/ui/components/patterns/content-header.tsx +1 -1
package/src/ui/components/patterns/form.tsx +1 -1
package/src/ui/components/patterns/presentation.tsx +199 -60
package/src/ui/components/patterns/sidebar.tsx +1 -1
package/src/ui/components/patterns/split.tsx +5 -2
package/src/ui/components/patterns/surface-assistant.tsx +74 -0
package/src/ui/components/primitives/card.tsx +1 -1
package/src/ui/components/primitives/detail.tsx +7 -7
package/src/ui/components/primitives/radio-group.tsx +1 -1
package/src/ui/components/primitives/select.tsx +1 -1
package/src/ui/docs/content/action-form-dialog.md +11 -4
package/src/ui/docs/content/action-form.md +7 -16
package/src/ui/docs/content/action-list-dialog.md +4 -6
package/src/ui/docs/content/action-list.md +46 -4
package/src/ui/docs/content/action-trigger.md +9 -5
package/src/ui/docs/content/action-view.md +12 -8
package/src/ui/docs/content/actions.md +36 -13
package/src/ui/docs/content/ai.md +26 -7
package/src/ui/docs/content/alert.md +4 -3
package/src/ui/docs/content/aspect-ratio.md +2 -2
package/src/ui/docs/content/auth.md +25 -10
package/src/ui/docs/content/avatar.md +1 -1
package/src/ui/docs/content/badge.md +2 -2
package/src/ui/docs/content/breadcrumb.md +3 -2
package/src/ui/docs/content/button.md +31 -7
package/src/ui/docs/content/calendar.md +1 -1
package/src/ui/docs/content/card.md +1 -1
package/src/ui/docs/content/carousel.md +14 -3
package/src/ui/docs/content/chat.md +1 -1
package/src/ui/docs/content/cli.md +13 -7
package/src/ui/docs/content/command.md +34 -2
package/src/ui/docs/content/composer.md +1 -1
package/src/ui/docs/content/content.md +5 -4
package/src/ui/docs/content/customization.md +1 -1
package/src/ui/docs/content/cycle.md +7 -5
package/src/ui/docs/content/data-state.md +6 -5
package/src/ui/docs/content/data.md +3 -3
package/src/ui/docs/content/detail.md +3 -2
package/src/ui/docs/content/dialog.md +2 -2
package/src/ui/docs/content/dictionary-value.md +1 -1
package/src/ui/docs/content/dock.md +23 -2
package/src/ui/docs/content/dot.md +0 -2
package/src/ui/docs/content/drawer.md +1 -1
package/src/ui/docs/content/empty.md +1 -4
package/src/ui/docs/content/events.md +1 -1
package/src/ui/docs/content/field.md +20 -11
package/src/ui/docs/content/getting-started.md +4 -2
package/src/ui/docs/content/icon-picker.md +2 -2
package/src/ui/docs/content/input-otp.md +2 -0
package/src/ui/docs/content/input.md +2 -3
package/src/ui/docs/content/item.md +5 -4
package/src/ui/docs/content/kbd.md +2 -1
package/src/ui/docs/content/mcp.md +10 -4
package/src/ui/docs/content/menu.md +27 -0
package/src/ui/docs/content/page.md +19 -5
package/src/ui/docs/content/pagination.md +9 -2
package/src/ui/docs/content/popover.md +2 -2
package/src/ui/docs/content/presentation.md +85 -58
package/src/ui/docs/content/progress.md +2 -6
package/src/ui/docs/content/runtime.md +8 -5
package/src/ui/docs/content/scheduler.md +1 -1
package/src/ui/docs/content/select.md +13 -8
package/src/ui/docs/content/sidebar.md +3 -2
package/src/ui/docs/content/skeleton.md +1 -1
package/src/ui/docs/content/slider.md +4 -4
package/src/ui/docs/content/spinner.md +3 -3
package/src/ui/docs/content/split.md +80 -19
package/src/ui/docs/content/tabs.md +6 -6
package/src/ui/docs/content/testing.md +4 -2
package/src/ui/docs/content/toast.md +3 -5
package/src/ui/docs/content/toggle.md +37 -0
package/src/ui/docs/content/tooltip.md +4 -3
package/src/ui/docs/content/truncate.md +3 -2
package/src/ui/docs/content/ui.md +3 -1
package/src/ui/docs/content/upgrading.md +43 -13
package/src/ui/docs/doc-client.tsx +1 -1
package/src/ui/docs/registry.tsx +30 -5
package/src/ui/meta.ts +5 -5
package/src/ui/react.tsx +5 -0

package/src/core/presentation.ts CHANGED Viewed

@@ -90,7 +90,7 @@ const presentationFieldSchema = z
   })
   .strict();
-const presentationBodySchema = z
+const presentationActionBodySchema = z
   .object({
     action: z.string().min(1),
     input: z.record(presentationBindingSchema).default({}),
@@ -108,6 +108,27 @@ const presentationBodySchema = z
   })
   .strict();
+const presentationComponentBodySchema = z
+  .object({
+    /** Boundary estático do conteúdo React fornecido pelo consumidor. */
+    component: identifierSchema,
+    /** Define se o heading principal nasce na casca ou no conteúdo React. */
+    heading: z.enum(["shell", "content"]).default("shell"),
+  })
+  .strict();
+const presentationBodySchema = z.union([
+  presentationActionBodySchema,
+  presentationComponentBodySchema,
+]);
+const presentationAssistantSchema = z
+  .object({
+    /** Nome acessível do botão que abre a assistência contextual. */
+    triggerLabel: z.string().min(1),
+  })
+  .strict();
 const presentationRouteRecordSchema = z
   .object({
     presentation: identifierSchema,
@@ -136,6 +157,7 @@ export const presentationSchema = z
     title: z.string().min(1),
     route: presentationRouteSchema.optional(),
     body: presentationBodySchema,
+    assistant: presentationAssistantSchema.optional(),
     actions: z.array(presentationCommandSchema).default([]),
   })
   .strict();
@@ -143,6 +165,12 @@ export const presentationSchema = z
 export type PresentationDefinition = z.infer<typeof presentationSchema>;
 export type PresentationDefinitionInput = z.input<typeof presentationSchema>;
 export type PresentationCommand = PresentationDefinition["actions"][number];
+export type PresentationActionBody = z.infer<
+  typeof presentationActionBodySchema
+>;
+export type PresentationComponentBody = z.infer<
+  typeof presentationComponentBodySchema
+>;
 type DefaultedProperty<
   Input,
   Key extends PropertyKey,
@@ -174,27 +202,48 @@ type DefinedPresentationEffects<
         }
       : PresentationCommand["onSuccess"]
   : PresentationCommand["onSuccess"];
-type PresentationOpen = NonNullable<PresentationDefinition["body"]["open"]>;
+type PresentationOpen = NonNullable<PresentationActionBody["open"]>;
 type DefinedPresentationOpen<Open> = Open extends object
   ? Omit<Open, "input"> &
       Omit<PresentationOpen, "input"> & {
         input: DefaultedProperty<Open, "input", PresentationOpen["input"]>;
       }
   : never;
+type DefinedPresentationActionBody<Body> =
+  Body extends z.input<typeof presentationActionBodySchema>
+    ? Omit<Body, "input" | "open" | "onSuccess"> &
+        Omit<PresentationActionBody, "input" | "open" | "onSuccess"> & {
+          input: DefaultedProperty<
+            Body,
+            "input",
+            PresentationActionBody["input"]
+          >;
+          onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
+        } & ("open" extends keyof Body
+          ? undefined extends Body["open"]
+            ? {
+                open?: DefinedPresentationOpen<
+                  Exclude<Body["open"], undefined>
+                >;
+              }
+            : { open: DefinedPresentationOpen<Body["open"]> }
+          : { open?: PresentationActionBody["open"] })
+    : never;
+type DefinedPresentationComponentBody<Body> =
+  Body extends z.input<typeof presentationComponentBodySchema>
+    ? Omit<Body, "heading"> &
+        Omit<PresentationComponentBody, "heading"> & {
+          heading: DefaultedProperty<
+            Body,
+            "heading",
+            PresentationComponentBody["heading"]
+          >;
+        }
+    : never;
 type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
-  Omit<Body, "input" | "open" | "onSuccess"> &
-    Omit<PresentationDefinition["body"], "input" | "open" | "onSuccess"> & {
-      input: DefaultedProperty<
-        Body,
-        "input",
-        PresentationDefinition["body"]["input"]
-      >;
-      onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
-    } & ("open" extends keyof Body
-      ? undefined extends Body["open"]
-        ? { open?: DefinedPresentationOpen<Exclude<Body["open"], undefined>> }
-        : { open: DefinedPresentationOpen<Body["open"]> }
-      : { open?: PresentationDefinition["body"]["open"] });
+  Body extends { component: string }
+    ? DefinedPresentationComponentBody<Body>
+    : DefinedPresentationActionBody<Body>;
 type DefinedPresentationCommand<Command> = Command extends object
   ? Omit<Command, "input" | "blocking" | "onSuccess"> &
       Omit<PresentationCommand, "input" | "blocking" | "onSuccess"> & {
@@ -272,6 +321,18 @@ export interface PresentationActionRegistry {
   readonly [name: string]: ActionContract;
 }
+export function isPresentationActionBody(
+  body: PresentationDefinition["body"],
+): body is PresentationActionBody {
+  return "action" in body;
+}
+export function isPresentationComponentBody(
+  body: PresentationDefinition["body"],
+): body is PresentationComponentBody {
+  return "component" in body;
+}
 export interface PresentationRouteMatch {
   definition: PresentationDefinition;
   input: Record<string, string>;
@@ -312,8 +373,7 @@ export function matchPresentationRoute(
         const decoded = decodeRouteSegment(received);
         if (decoded === null) return [];
         input[expected.slice(1)] = decoded;
-      }
-      else if (expected !== received) return [];
+      } else if (expected !== received) return [];
     }
     return [{ definition, input }];
   });
@@ -527,46 +587,53 @@ export function validatePresentations(
       problems.push(`Presentation “${presentation.id}” duplicada.`);
     byId.set(presentation.id, presentation);
-    const bodyAction = actions[presentation.body.action];
-    if (bodyAction === undefined) {
-      problems.push(
-        `A action “${presentation.body.action}” não está disponível.`,
-      );
-    } else if (bodyAction.kind === "simple") {
-      problems.push(
-        `A action simple “${bodyAction.name}” não pode ocupar o body.`,
-      );
+    if (isPresentationComponentBody(presentation.body)) {
+      // O conteúdo interno permanece uma fronteira React opaca para a spec da casca.
     } else {
-      validateActionBindings(
-        presentation.body.input,
-        bodyAction,
-        `${presentation.id}.body.input`,
-        problems,
-      );
-      if (
-        bodyAction.kind === "view" &&
-        presentation.body.fields === undefined
-      ) {
+      const bodyAction = actions[presentation.body.action];
+      if (bodyAction === undefined) {
         problems.push(
-          `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          `A action “${presentation.body.action}” não está disponível.`,
         );
-      }
-      if (
-        bodyAction.kind !== "view" &&
-        presentation.body.fields !== undefined
-      ) {
-        problems.push(`Fields só podem ser declarados para uma action view.`);
-      }
-      if (bodyAction.kind !== "list" && presentation.body.open !== undefined) {
-        problems.push(`Open só pode ser declarado para uma action list.`);
-      }
-      if (
-        bodyAction.kind !== "form" &&
-        presentation.body.submitLabel !== undefined
-      ) {
+      } else if (bodyAction.kind === "simple") {
         problems.push(
-          `SubmitLabel só pode ser declarado para uma action form.`,
+          `A action simple “${bodyAction.name}” não pode ocupar o body.`,
+        );
+      } else {
+        validateActionBindings(
+          presentation.body.input,
+          bodyAction,
+          `${presentation.id}.body.input`,
+          problems,
         );
+        if (
+          bodyAction.kind === "view" &&
+          presentation.body.fields === undefined
+        ) {
+          problems.push(
+            `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          );
+        }
+        if (
+          bodyAction.kind !== "view" &&
+          presentation.body.fields !== undefined
+        ) {
+          problems.push(`Fields só podem ser declarados para uma action view.`);
+        }
+        if (
+          bodyAction.kind !== "list" &&
+          presentation.body.open !== undefined
+        ) {
+          problems.push(`Open só pode ser declarado para uma action list.`);
+        }
+        if (
+          bodyAction.kind !== "form" &&
+          presentation.body.submitLabel !== undefined
+        ) {
+          problems.push(
+            `SubmitLabel só pode ser declarado para uma action form.`,
+          );
+        }
       }
     }
@@ -615,7 +682,10 @@ export function validatePresentations(
           problems.push(
             `A route de “${presentation.id}” consulta a Presentation inexistente “${record.presentation}”.`,
           );
-        } else if (actions[source.body.action]?.kind !== "list") {
+        } else if (
+          !isPresentationActionBody(source.body) ||
+          actions[source.body.action]?.kind !== "list"
+        ) {
           problems.push(
             `A route de “${presentation.id}” exige que “${record.presentation}” tenha uma list action no body.`,
           );
@@ -633,7 +703,9 @@ export function validatePresentations(
         }
       }
     }
-    const open = presentation.body.open;
+    const open = isPresentationActionBody(presentation.body)
+      ? presentation.body.open
+      : undefined;
     if (open !== undefined && !byId.has(open.presentation)) {
       problems.push(
         `A lista “${presentation.id}” abre a Presentation inexistente “${open.presentation}”.`,
@@ -650,7 +722,9 @@ export function validatePresentations(
         );
       }
       const action =
-        target === undefined ? undefined : actions[target.body.action];
+        target !== undefined && isPresentationActionBody(target.body)
+          ? actions[target.body.action]
+          : undefined;
       if (action !== undefined) {
         validateActionBindings(
           open.input,
@@ -660,7 +734,10 @@ export function validatePresentations(
         );
       }
     }
-    for (const effect of presentation.body.onSuccess) {
+    const bodyEffects = isPresentationActionBody(presentation.body)
+      ? presentation.body.onSuccess
+      : [];
+    for (const effect of bodyEffects) {
       if (effect.effect !== "navigate") continue;
       const target = byId.get(effect.presentation);
       if (target === undefined) {
@@ -678,7 +755,9 @@ export function validatePresentations(
           `O body de “${presentation.id}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
         );
       }
-      const action = actions[target.body.action];
+      const action = isPresentationActionBody(target.body)
+        ? actions[target.body.action]
+        : undefined;
       if (action !== undefined) {
         validateActionBindings(
           effect.input,
@@ -706,7 +785,9 @@ export function validatePresentations(
                 `A action “${command.action}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
               );
             }
-            const action = actions[target.body.action];
+            const action = isPresentationActionBody(target.body)
+              ? actions[target.body.action]
+              : undefined;
             if (action !== undefined) {
               validateActionBindings(
                 effect.input,
@@ -724,6 +805,10 @@ export function validatePresentations(
         problems.push(
           `A action “${command.action}” abre a Presentation inexistente “${command.target.presentation}”.`,
         );
+      } else if (!isPresentationActionBody(target.body)) {
+        problems.push(
+          `A Presentation “${target.id}” usa conteúdo de componente e não pode ser aberta pela action “${command.action}”.`,
+        );
       } else if (target.body.action !== command.action) {
         problems.push(
           `A Presentation “${target.id}” usa “${target.body.action}”, mas foi aberta por “${command.action}”.`,

package/src/core/runtime.ts CHANGED Viewed

@@ -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)
@@ -848,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 CHANGED Viewed

@@ -620,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. */
@@ -1385,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 CHANGED Viewed

@@ -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
@@ -55,6 +56,14 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
   }))
   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/content-header.tsx CHANGED Viewed

@@ -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;

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

@@ -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. */