@softize/opus 25.6.0 → 26.0.0

package/src/ui/docs/content/installation.md

@@ -0,0 +1,94 @@
+---
+title: Instalação
+---
+
+# Instalação
+
+Use `opus create` para começar um projeto com TypeScript, React, testes e as verificações do
+Opus configurados. Se o aplicativo já existe, instale o pacote e execute o setup para acrescentar
+os artefatos do SDK ao repositório.
+
+Os comandos desta página usam pnpm. Os pacotes Opus e Base são públicos e não exigem token de
+registro.
+
+## Criar um aplicativo
+
+```bash
+pnpm dlx @softize/opus create meu-app
+cd meu-app
+git init
+pnpm install
+pnpm run setup
+pnpm test
+```
+
+O aplicativo inclui um domínio de tarefas, `opus.config.ts`, Vite, React, o tema do Opus e os
+comandos de teste e verificação. O dev server respeita a variável `PORT`. `opus.json` registra a
+versão do SDK adotada pelo app; `setup` materializa as instruções, skills e hooks gerenciados.
+
+Quando os testes passarem, continue em [Primeiros passos](/docs/getting-started).
+
+## Criar um monorepo
+
+Crie a raiz do workspace antes dos aplicativos:
+
+```bash
+pnpm dlx @softize/opus create meu-cliente --monorepo
+cd meu-cliente
+git init
+pnpm dlx @softize/opus create apps/portal
+pnpm install
+pnpm --dir apps/portal run setup
+```
+
+Dentro de um workspace pnpm, `create` gera somente os arquivos do aplicativo. Ele detecta o
+`pnpm-workspace.yaml` da raiz e evita criar um workspace aninhado.
+
+Se a raiz já existir, o comando avisa quando faltar configuração para incluir o app em
+`packages`, permitir o postinstall com `allowBuilds` ou excluir Opus e Base da quarentena de
+versões. Esses avisos não alteram os arquivos da raiz.
+
+## Adotar em um projeto existente
+
+Na pasta do aplicativo, instale o SDK e execute o setup do Opus. Execute o setup da Base na raiz
+do repositório:
+
+```bash
+pnpm add @softize/opus
+pnpm add -D @softize/base
+pnpm exec opus setup
+pnpm exec base setup
+```
+
+Os dois setups são idempotentes. O Opus grava o marcador `opus.json`, o inventário de copy e as
+projeções específicas do SDK. A Base materializa o método geral de trabalho, a memória e os
+agentes. Em um monorepo, cada aplicativo mantém seu próprio marcador e sua configuração Opus.
+
+Para usar a UI em um aplicativo com Tailwind v4, importe o tema e inclua os componentes do
+pacote no scan do Tailwind. Este exemplo considera um CSS dentro de `src/`:
+
+```css
+@import '@softize/opus/ui/theme.css';
+@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
+```
+
+Os componentes são importados de `@softize/opus/ui/react`. A configuração dos providers e da
+execução de actions está em [Como consumir](/ui/como-consumir).
+
+## Resolver uma falha antes da criação
+
+Se o pnpm informar que o diretório global de binários não está no `PATH`, execute `pnpm setup`
+e abra uma nova sessão do terminal. Quando o setup apontar `ERR_PNPM_BAD_SHELL_SECTION`,
+`pnpm setup --force` substitui o bloco antigo do pnpm no arquivo de inicialização do shell.
+
+Uma política de quarentena do pnpm pode resolver uma versão anterior durante as primeiras
+horas de uma release. Se `create` responder com “Comando desconhecido”, informe a versão que
+você quer usar:
+
+```bash
+pnpm dlx @softize/opus@<versão> create meu-app
+```
+
+Outra opção é desativar a quarentena somente nessa chamada com
+`pnpm --config.minimum-release-age=0 dlx @softize/opus create meu-app`.
+O workspace gerado exclui Opus e Base dessa quarentena para manter o par adotado pelo template.

package/src/ui/docs/content/mcp.md

@@ -57,8 +57,8 @@ entrada. Em `_meta`, cada tool traz os
 identificadores e `com.softize.opus/data-product-labels`, o nome legível de cada um.
 
 Quando a action declara o que faz com os dados, a tool traz também as anotações padrão do MCP:
-`readOnlyHint` vem de `effect`. Numa action que escreve, `destructiveHint` vai sempre explícito, a
-partir de `ai.destructive`, porque o MCP trata a ausência numa escrita como destrutiva.
+`readOnlyHint` vem de `effect`. Em uma action que escreve, `destructiveHint` vai sempre explícito, a
+partir de `ai.destructive`, porque o MCP trata a ausência em uma escrita como destrutiva.
 Em `_meta`, `com.softize.opus/effect` repete o efeito e `com.softize.opus/personal-data` diz se a
 resposta contém dado pessoal. Na action dona de um tipo de recurso, `com.softize.opus/assistant`
 traz o assistente declarado, para o host conhecê-lo pelo catálogo que já consulta e aplicar à saída

package/src/ui/docs/content/overview.md

@@ -0,0 +1,58 @@
+---
+title: Visão geral
+---
+
+# Opus
+
+Opus é um SDK para aplicações TypeScript. Você declara as operações do produto em contratos
+compartilhados, liga a implementação no servidor e usa essas mesmas definições no cliente,
+nos testes e nas ferramentas do projeto.
+
+Uma consulta de mensalidade, por exemplo, recebe o tamanho da equipe e devolve o preço. O
+contrato define o formato dessas duas informações e permite o acesso sem login. O handler
+calcula o valor. A interface importa o contrato para chamar a operação com os mesmos tipos
+e validações usados no servidor.
+
+## O que você precisa entender primeiro
+
+Uma **action** é uma operação do sistema: consultar um preço, listar tarefas, salvar um cadastro
+ou ler um registro. Cada action tem um nome, uma entrada e uma saída.
+
+O **contrato** é a parte compartilhada da action. Ele declara o formato dos dados e as informações
+que seus consumidores precisam conhecer. O **binding** acrescenta o handler que executa a regra
+no servidor. Essa divisão permite importar o contrato na interface sem levar banco ou segredo
+para o navegador.
+
+O **domínio** agrupa actions e dados de um assunto do produto. O **runtime** executa o que foi
+registrado e oferece as dependências configuradas pelo aplicativo, como autenticação, banco ou
+auditoria. Essas dependências entram por adapters; você escolhe as peças necessárias ao projeto.
+
+```text
+Contrato compartilhado ──→ Cliente e interface
+         │
+         └── + handler ──→ Action registrada no runtime
+```
+
+Você escreve a regra de negócio e monta o aplicativo. O Opus fornece as declarações, a execução,
+os componentes de interface e as verificações que trabalham sobre essas declarações.
+
+## Faça uma primeira operação
+
+Em [Primeiros passos](/docs/getting-started), você calcula uma mensalidade, valida a entrada e
+testa o resultado. O exemplo usa uma regra pequena e dispensa banco, servidor HTTP e login.
+
+Depois desse percurso, [Actions e contratos](/docs/actions) explica como a mesma estrutura atende
+a formulários, listas, detalhes e operações com autorização.
+
+## Continue o trabalho que trouxe você até aqui
+
+| Você precisa… | Comece por… |
+| --- | --- |
+| Criar uma operação ou mudar uma regra | [Actions e contratos](/docs/actions) |
+| Publicar uma API e conectar dependências | [Runtime e adapters](/docs/runtime) |
+| Modelar dados persistidos | [Camada de dados](/docs/data) |
+| Construir uma tela | [Como consumir](/ui/como-consumir) |
+| Testar uma operação e suas permissões | [Testes de actions](/docs/testing) |
+| Atualizar a versão usada no projeto | [Atualização do Opus](/docs/upgrading) |
+
+O catálogo de [UI](/ui) tem navegação própria pelo volume de componentes e exemplos visuais.

package/src/ui/docs/content/sidebar.md

@@ -69,6 +69,10 @@ render(
 Use `SidebarNav` quando grupos e itens já puderem ser descritos como dados. Use `SidebarItem`
 diretamente quando a composição precisar de controles, badges ou hierarquia particular.
 
+`SidebarItem` aceita `href` para destinos nativos, mantendo foco e abertura em outra aba.
+Quando o host usa um roteador, forneça também `onClick`: somente o clique simples é interceptado;
+cliques com modificadores preservam o comportamento do link. Sem `href`, o item continua sendo um botão.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os

package/src/ui/docs/index.ts

@@ -7,7 +7,14 @@
  *    `@softize/opus/ui/docs/standalone` — não passa por aqui.
  */
 export { DocBrowser } from './CatalogDocBrowser.tsx'
+export { DocHeader } from './DocHeader.tsx'
+export { DocCatalog, DocRecordDetail } from './DocCatalog.tsx'
+export type { DocCatalogProps, DocRecordDetailProps } from './DocCatalog.tsx'
+export { decisionRecord, releaseRecords, parseChangelog, filterDocumentationRecords } from './records.ts'
+export type { DocumentationRecord } from './records.ts'
+export type { DocHeaderProps } from './DocHeader.tsx'
 export type { DocBrowserProps } from './CatalogDocBrowser.tsx'
+export type { DocBrowserSearchOptions } from './DocBrowser.tsx'
 export { DOC_SECTIONS, PROTOCOL_SECTIONS, UI_SECTIONS } from './registry.tsx'
 export type { DocEntry, DocGroup, DocSection } from './types.ts'
 export { docSectionsFromFolder } from './catalog-folder.tsx'
@@ -17,5 +24,5 @@ export { Example, CodeBlock, DocPage } from './doc.tsx'
 // Renderer de markdown do DocBrowser: prosa + fence ```tsx preview vira componente vivo.
 export { DocMarkdown } from './markdown.tsx'
 export type { DocMarkdownProps } from './markdown.tsx'
-// O changelog do pacote, pronto pra montar (o site o usa como página do menu superior).
+// O changelog do pacote, pronto para montar em um destino global ou no catálogo embutido.
 export { OpusChangelog, ChangelogView } from './changelog.tsx'

package/src/ui/docs/markdown.tsx

@@ -88,9 +88,11 @@ export interface DocMarkdownProps {
   /** Reescreve links do Markdown antes da renderização. Útil para resolver caminhos relativos
    *  quando o documento é publicado sob uma rota do aplicativo. */
   resolveHref?: (href: string) => string
+  /** Mantém código didático aberto quando false; exemplos vivos preservam sua composição. */
+  codeCollapsible?: boolean
 }
 
-export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps): React.ReactElement {
+export function DocMarkdown({ content, scope, resolveHref, codeCollapsible = true }: DocMarkdownProps): React.ReactElement {
   // O `scope` ESTENDE o default (não substitui): o pattern injeta o palco doc-client
   // (DocBrowserActionProvider + contratos) sem perder o opus/ui + lucide + hooks. Memoiza pra
   // não re-avaliar os LiveBlocks a cada render (o scope injetado é estável no chamador).
@@ -135,7 +137,7 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
           {/\b(preview|live)\b/.test(info) ? (
             <LiveBlock code={t.content} scope={liveScope} previewClassName={previewClassName} />
           ) : (
-            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} />
+            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} collapsible={codeCollapsible} />
           )}
         </div>,
       )
@@ -144,5 +146,5 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
     }
   }
   flush()
-  return <div className="prose prose-sm max-w-none space-y-4">{parts}</div>
+  return <div data-slot="markdown" className="prose prose-sm max-w-none space-y-4">{parts}</div>
 }

package/src/ui/docs/records.ts

@@ -0,0 +1,144 @@
+export interface DocumentationRecord {
+  id: string;
+  title: string;
+  href: string;
+  date?: string;
+  status?: string;
+  searchText: string;
+  body: string;
+  summary?: string;
+  content?: string;
+  breaking?: string;
+  afterBreaking?: string;
+}
+
+export interface ChangelogVersion {
+  version: string;
+  date?: string;
+  body: string;
+  breaking?: string;
+  beforeBreaking?: string;
+  afterBreaking?: string;
+  /** Corpo original, com a ordem das seções preservada para a leitura integral. */
+  sourceBody?: string;
+}
+
+export interface ParsedChangelog {
+  intro: string;
+  versions: ChangelogVersion[];
+}
+
+/** Preserva a convenção publicada: `## versão — data` e seção `### Breaking`. */
+export function parseChangelog(source: string): ParsedChangelog {
+  const chunks = `\n${source.trim()}`.split(/\n## /);
+  const versions = chunks.slice(1).map((chunk) => {
+    const nl = chunk.indexOf("\n");
+    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim();
+    const rest = nl === -1 ? "" : chunk.slice(nl + 1);
+    const [version, date] = header.split(/\s+—\s+/);
+    const sourceBody = rest.trim();
+    const breakingSection =
+      /^### Breaking[\t ]*\r?\n([\s\S]*?)(?=^###[\t ]|(?![\s\S]))/m.exec(sourceBody);
+    const body = breakingSection
+      ? sourceBody.slice(0, breakingSection.index) +
+        sourceBody.slice(breakingSection.index + breakingSection[0].length)
+      : sourceBody;
+    return {
+      version: (version ?? header).trim(),
+      ...(date !== undefined ? { date: date.trim() } : {}),
+      body: (body ?? "").trim(),
+      sourceBody,
+      ...(breakingSection
+        ? {
+            breaking: breakingSection[1]!.trim(),
+            beforeBreaking: sourceBody.slice(0, breakingSection.index).trim(),
+            afterBreaking: sourceBody
+              .slice(breakingSection.index + breakingSection[0].length)
+              .trim(),
+          }
+        : {}),
+    };
+  });
+  return { intro: chunks[0]?.trim() ?? "", versions };
+}
+
+/** Extrai só os campos declarados; a ausência de metadata não vira uma decisão presumida. */
+export function decisionRecord(
+  source: string,
+  href: string,
+): DocumentationRecord | undefined {
+  const heading = source.match(/^#\s+ADR\s+(\d+)\s*[—–:-]\s*(.+)$/m);
+  if (!heading) return undefined;
+  const header = source.split(/^##\s/m)[0] ?? "";
+  const metadata = (name: string): string | undefined => {
+    const value = header.match(
+      new RegExp(`^[\\t ]*-?[\\t ]*\\*\\*${name}:?\\*\\*:?[\\t ]*(.+)$`, "mi"),
+    )?.[1];
+    return value?.trim().replace(/\.$/, "");
+  };
+  const declaredStatus = metadata("Status");
+  // O estado resume a metadata; ressalvas e andamento permanecem no texto integral da decisão.
+  const status =
+    declaredStatus?.match(
+      /^(parcialmente (?:substituída|supersedida)|substituída|supersedida|aceita(?: para (?:protótipo|implementação(?: local)?|candidato local)| como primeiro corte)?|proposta|implementada|rejeitada)\b/i,
+    )?.[1] ?? declaredStatus;
+  const context = source
+    .match(/^##[\t ]+Contexto\b[^\n]*\n([\s\S]*)/im)?.[1]
+    ?.split(/^##[\t ]/m)[0];
+  return {
+    id: heading[1]!,
+    title: heading[2]!.trim(),
+    href,
+    date: metadata("Data"),
+    status,
+    summary:
+      context
+        ?.replace(/^#{1,6}[\t ].*(?:\r?\n|$)/gm, "")
+        .trim()
+        .split(/\n\s*\n/)[0]
+        ?.trim() || undefined,
+    searchText: source,
+    body: source,
+  };
+}
+
+export function releaseRecords(
+  source: string,
+  basePath: string,
+): DocumentationRecord[] {
+  return parseChangelog(source).versions.map((release) => {
+    return {
+      id: release.version,
+      title: release.version,
+      href: `${basePath}/${encodeURIComponent(release.version)}`,
+      date: release.date,
+      content: release.beforeBreaking ?? release.body,
+      breaking: release.breaking,
+      afterBreaking: release.afterBreaking,
+      body: `# ${release.version}\n\n${release.date ?? ""}\n\n${release.sourceBody}`,
+      searchText: `${release.version} ${release.date ?? ""} ${release.sourceBody}`,
+    };
+  });
+}
+
+function searchable(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLocaleLowerCase("pt-BR");
+}
+
+export function filterDocumentationRecords(
+  records: readonly DocumentationRecord[],
+  query: string,
+): DocumentationRecord[] {
+  const terms = searchable(query).trim().split(/\s+/).filter(Boolean);
+  return records.filter(
+    (record) =>
+      terms.every((term) =>
+        searchable(
+          `${record.id} ${record.title} ${record.status ?? ""} ${record.searchText}`,
+        ).includes(term),
+      ),
+  );
+}