@softize/opus 15.2.1 → 15.2.2

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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.
 
+## 15.2.2 — 2026-09-11
+
+O acesso descritivo de Produtos de Dados usa `permissionContexts` no lugar do nome genérico
+`contexts`. A qualificação evita confundir contextos do framework, contexto de tela, domínio de
+dados e vocabulário de autorização nas projeções do manifest e da Lens.
+
+**Migração recomendada:** em declarações `defineDataProduct`, renomeie `access.contexts` para
+`access.permissionContexts` e regenere o manifest. O nome anterior continua aceito e projetado em
+toda a série 15.x como alias deprecated; consumidores novos devem ler somente o nome qualificado.
+
 ## 15.2.1 — 2026-09-11
 
 `opus copy` agora poda diretórios cobertos por um glob recursivo de `copy.exclude`, em vez de

package/bin/lib/gen-runner.mjs

@@ -220,7 +220,16 @@ function serializeDataProducts(source) {
       : [],
     entities: Array.isArray(product.entities) ? product.entities : [],
     access: {
-      contexts: Array.isArray(product.access?.contexts) ? product.access.contexts : [],
+      permissionContexts: Array.isArray(product.access?.permissionContexts)
+        ? product.access.permissionContexts
+        : Array.isArray(product.access?.contexts)
+          ? product.access.contexts
+          : [],
+      contexts: Array.isArray(product.access?.permissionContexts)
+        ? product.access.permissionContexts
+        : Array.isArray(product.access?.contexts)
+          ? product.access.contexts
+          : [],
       organizationalScopes: Array.isArray(product.access?.organizationalScopes)
         ? product.access.organizationalScopes
         : [],

package/docs/adr/0012-data-products-are-first-class-declarations.md

@@ -27,10 +27,12 @@ descritivo e Actions de interface. Produtos ativos podem ser descontinuados com
 duplicados e relações literais que apontam para Action ou Entity inexistente. A declaração não
 executa consulta, não contém driver e não substitui uma Action.
 
-A autorização continua sendo responsabilidade da Action. `access.contexts` e
+A autorização continua sendo responsabilidade da Action. `access.permissionContexts` e
 `access.organizationalScopes` documentam o alcance esperado para catálogo, Lens e revisão, mas o
 runtime não os converte em autorização implícita. Essa separação impede que uma descrição
-incompleta abra dados.
+incompleta abra dados. O alias histórico `access.contexts` permanece aceito como entrada e
+projetado no manifest durante a série 15.x por compatibilidade. Novos consumidores usam o nome
+qualificado; o alias será removido somente numa versão major.
 
 O manifest projeta a declaração integral. Tools de IA recebem a lista de produtos que expõem em
 metadata, e o servidor MCP publica essa lista em `_meta['com.softize.opus/data-products']`. A

package/docs/data-products.md

@@ -24,7 +24,7 @@ export const salesLeads = defineDataProduct({
   sources: [{ id: 'followize', label: 'Followize' }],
   entities: ['Lead'],
   access: {
-    contexts: ['sales'],
+    permissionContexts: ['sales'],
     organizationalScopes: ['unit', 'team'],
   },
   interfaces: ['sale.list', 'sales.performance'],
@@ -49,6 +49,12 @@ que uma interface deveria respeitar, por exemplo, unidade e equipe. Não é RLS
 automática. Toda interface precisa aplicar seus próprios `requires`, `authorize` e recortes no
 handler/repositório, inclusive quando for chamada por IA ou MCP.
 
+`permissionContexts` nomeia especificamente chaves do vocabulário de permissão. Ele não descreve
+domínio de dados, Área, departamento nem contexto de tela; projetos que não adotam essa dimensão
+declaram uma lista vazia. O alias `contexts`, publicado originalmente na série 15.x, permanece
+aceito na entrada e projetado no manifest apenas para compatibilidade. Novas declarações e
+consumidores usam o nome qualificado; o alias só poderá ser removido numa versão major.
+
 ## Projeções
 
 `opus gen` publica os produtos no `.opus/manifest.json`. Actions expostas como tools carregam os

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.2.1",
+  "version": "15.2.2",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -212,17 +212,6 @@
   "bin": {
     "opus": "bin/cli.mjs"
   },
-  "scripts": {
-    "postinstall": "node ./bin/lib/postinstall.mjs",
-    "copy:check": "node ./bin/cli.mjs copy --check",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:cov": "vitest run --coverage",
-    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
-    "release": "bash ./scripts/release.sh",
-    "release:local": "bash ./scripts/release.sh --local"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@radix-ui/react-checkbox": "^1.1.3",
@@ -368,11 +357,21 @@
     "vitest": "^2.1.0",
     "zod": "^3.24.0"
   },
-  "packageManager": "pnpm@9.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/softize-dev/opus.git",
     "directory": "packages/opus"
   },
-  "homepage": "https://opus.softize.com.br"
-}
+  "homepage": "https://opus.softize.com.br",
+  "scripts": {
+    "postinstall": "node ./bin/lib/postinstall.mjs",
+    "copy:check": "node ./bin/cli.mjs copy --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
+    "release": "bash ./scripts/release.sh",
+    "release:local": "bash ./scripts/release.sh --local"
+  }
+}

package/src/core/data-product.ts

@@ -14,12 +14,21 @@ export interface DataProductSource {
 }
 
 export interface DataProductAccess {
-  /** Contextos de dados normalmente exigidos pelas interfaces do produto. Descritivo. */
+  /** @deprecated Use `permissionContexts`; este alias será removido numa versão major. */
   contexts: readonly string[]
+  /** Nome qualificado dos contextos de permissão. Sempre presente após `defineDataProduct`. */
+  permissionContexts?: readonly string[]
   /** Eixos organizacionais que as Actions precisam considerar, como unit e team. Descritivo. */
   organizationalScopes: readonly string[]
 }
 
+export interface DataProductAccessInput {
+  permissionContexts?: readonly string[]
+  /** @deprecated Use `permissionContexts`; este alias será removido numa versão major. */
+  contexts?: readonly string[]
+  organizationalScopes: readonly string[]
+}
+
 export interface DataProductConfig {
   /** Identidade estável e namespaced, como `sales.leads`. */
   id: string
@@ -46,6 +55,19 @@ export interface DataProductConfig {
   replacedBy?: string
 }
 
+export type DataProductInput = Omit<DataProductConfig, 'access'> & { access: DataProductAccessInput }
+type PermissionContextsOf<T extends DataProductAccessInput> = Extract<
+  | ('permissionContexts' extends keyof T ? T['permissionContexts'] : never)
+  | ('contexts' extends keyof T ? T['contexts'] : never),
+  readonly string[]
+>
+export type DefinedDataProduct<T extends DataProductInput = DataProductInput> = Omit<T, 'access'> & {
+  access: Omit<T['access'], 'contexts' | 'permissionContexts'> & DataProductAccess & {
+    contexts: PermissionContextsOf<T['access']>
+    permissionContexts: PermissionContextsOf<T['access']>
+  }
+}
+
 const ID_RE = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/
 
 function nonEmpty(value: unknown, field: string): void {
@@ -55,7 +77,7 @@ function nonEmpty(value: unknown, field: string): void {
 }
 
 /** Declara e valida um Produto de Dados sem introduzir dependência de banco ou runtime. */
-export function defineDataProduct<const T extends DataProductConfig>(config: T): T {
+export function defineDataProduct<const T extends DataProductInput>(config: T): DefinedDataProduct<T> {
   if (!ID_RE.test(config.id)) {
     throw new TypeError(`DataProduct id "${config.id}" deve ser namespaced e casar com ${ID_RE.source}`)
   }
@@ -90,10 +112,23 @@ export function defineDataProduct<const T extends DataProductConfig>(config: T):
     throw new TypeError(`DataProduct "${config.id}" possui interface duplicada`)
   }
   for (const action of config.interfaces) nonEmpty(action, 'interfaces[]')
-  if (!Array.isArray(config.access?.contexts) || !Array.isArray(config.access?.organizationalScopes)) {
-    throw new TypeError('DataProduct "access" deve declarar contexts e organizationalScopes')
+  const hasPermissionContexts = Array.isArray(config.access?.permissionContexts)
+  const hasLegacyContexts = Array.isArray(config.access?.contexts)
+  if ((!hasPermissionContexts && !hasLegacyContexts) || !Array.isArray(config.access?.organizationalScopes)) {
+    throw new TypeError('DataProduct "access" deve declarar permissionContexts e organizationalScopes')
+  }
+  if (
+    hasPermissionContexts &&
+    hasLegacyContexts &&
+    (config.access.permissionContexts!.length !== config.access.contexts!.length ||
+      config.access.permissionContexts!.some((context, index) => context !== config.access.contexts![index]))
+  ) {
+    throw new TypeError('DataProduct "access" recebeu permissionContexts e contexts divergentes')
   }
-  for (const context of config.access.contexts) nonEmpty(context, 'access.contexts[]')
+  const permissionContexts = (
+    hasPermissionContexts ? config.access.permissionContexts : config.access.contexts
+  ) as PermissionContextsOf<T['access']>
+  for (const context of permissionContexts) nonEmpty(context, 'access.permissionContexts[]')
   for (const scope of config.access.organizationalScopes) nonEmpty(scope, 'access.organizationalScopes[]')
   if (config.status !== undefined && config.status !== 'active' && config.status !== 'deprecated') {
     throw new TypeError('DataProduct "status" deve ser "active" ou "deprecated"')
@@ -107,13 +142,22 @@ export function defineDataProduct<const T extends DataProductConfig>(config: T):
   } else if (config.replacedBy !== undefined) {
     throw new TypeError('DataProduct ativo não pode declarar "replacedBy"')
   }
-  return config
+  return {
+    ...config,
+    access: {
+      ...config.access,
+      permissionContexts,
+      contexts: permissionContexts,
+    },
+  } as unknown as DefinedDataProduct<T>
 }
 
 export function isDataProduct(value: unknown): value is DataProductConfig {
   if (typeof value !== 'object' || value === null) return false
+  const access = (value as { access?: { contexts?: unknown } }).access
+  if (!Array.isArray(access?.contexts)) return false
   try {
-    defineDataProduct(value as DataProductConfig)
+    defineDataProduct(value as DataProductInput)
     return true
   } catch {
     return false

package/src/core/index.ts

@@ -204,7 +204,10 @@ export type { DomainConfig, FlattenedDomain } from './domain.ts'
 export { defineDataProduct, isDataProduct } from './data-product.ts'
 export type {
   DataProductAccess,
+  DataProductAccessInput,
   DataProductConfig,
+  DataProductInput,
+  DefinedDataProduct,
   DataProductSource,
   DataProductStatus,
 } from './data-product.ts'