@softize/opus 25.0.0 → 25.2.0

package/bin/lib/check.mjs

@@ -24,6 +24,12 @@
  *                            identificador exportado; um `entities` ou `purges` que o check não
  *                            consegue ler (spread, variável) suspende a regra de ausência
  *                            correspondente, sem falso positivo.
+ *   assistant-declaration  — o assistente do recurso (ADR 0053): só em action `view`, com `ai`
+ *                            habilitado, `personalData` declarado, `resource` em camelCase, `skill`
+ *                            em minúsculas com hífen, `label`, `title` e `context` presentes e
+ *                            `maxContextChars` literal de 1.000 a 16.000. O
+ *                            mesmo `resource` literal em duas actions, entre arquivos, reprova. Um
+ *                            `assistant` ou `ai` que não é literal suspende o que depende dele.
  *
  * A checagem cross-file de registro no runtime (graph) fica pra v2 (introspecção/MCP).
  * Saída: findings + exit ≠ 0 se houver erro. Zero actions num diretório NÃO-marcado
@@ -73,6 +79,7 @@ const FIELD_GROUP = {
   rateLimit: 5,
   idempotency: 5,
   ai: 6,
+  assistant: 6,
   automatable: 6,
   internal: 6,
 };
@@ -82,6 +89,17 @@ const FIELD_GROUP = {
 const SEG = "[a-z][a-z0-9]*(-[a-z0-9]+)*";
 const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`);
 const KINDS = new Set(["simple", "form", "list", "view"]);
+// O assistente do recurso (ADR 0053): o mesmo formato que o registro do runtime confere.
+const ASSISTANT_RESOURCE_RE = /^[a-z][a-zA-Z0-9]*$/;
+const ASSISTANT_SKILL_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const ASSISTANT_CONTEXT_MIN = 1000;
+const ASSISTANT_RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const ASSISTANT_CONTEXT_MAX = 16000;
+const ASSISTANT_REQUIRED = {
+  label: "`label`, o nome do assistente para pessoas",
+  title: "`title`, o caminho do campo que nomeia o recurso",
+  context: "`context`, os caminhos dos campos que vão ao modelo",
+};
 // O runtime e o manifest só aplicam estes campos em `simple` e `form`; o tipo do binding os aceita
 // em qualquer kind, então a declaração num list/view compila e não tem efeito.
 const EXECUTION_ONLY_FIELDS = ["emits", "background"];
@@ -977,6 +995,73 @@ export function parseActions(fileName, sourceText) {
       .filter(Boolean);
   }
 
+  function prop(obj, key) {
+    return obj.properties.find(
+      (pr) =>
+        ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
+    );
+  }
+
+  /** `ai` literal → "enabled" | "disabled"; ausente → null; não literal → "unknown". */
+  function aiState(obj) {
+    const p = prop(obj, "ai");
+    if (!p) return obj.properties.some((pr) => pr.name?.getText(sf) === "ai") ? "unknown" : null;
+    const value = p.initializer;
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
+    if (value.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
+    if (ts.isObjectLiteralExpression(value)) {
+      const enabled = prop(value, "enabled");
+      if (!enabled) return "enabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.FalseKeyword) return "disabled";
+      if (enabled.initializer.kind === ts.SyntaxKind.TrueKeyword) return "enabled";
+    }
+    return "unknown";
+  }
+
+  /** O `assistant` literal → { readable, resource, skill, keys }; ausente → null. */
+  function assistantDeclaration(obj) {
+    const p = prop(obj, "assistant");
+    if (!p) return null;
+    if (!ts.isObjectLiteralExpression(p.initializer))
+      return { readable: false, line: lineOf(p) };
+    const value = p.initializer;
+    const literal = (key) => {
+      const found = prop(value, key);
+      if (!found) return { present: objKeys(value).includes(key), text: null };
+      return {
+        present: true,
+        text: ts.isStringLiteralLike(found.initializer) ? found.initializer.text : null,
+      };
+    };
+    const limit = prop(value, "maxContextChars");
+    let maxContextChars = null;
+    if (limit) {
+      const node = limit.initializer;
+      if (ts.isNumericLiteral(node)) maxContextChars = Number(node.text.replace(/_/g, ""));
+      else if (
+        ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)
+      )
+        maxContextChars = -Number(node.operand.text.replace(/_/g, ""));
+    }
+    const contextNode = prop(value, "context");
+    const contextPaths =
+      contextNode && ts.isArrayLiteralExpression(contextNode.initializer)
+        ? contextNode.initializer.elements.filter(ts.isStringLiteralLike).map((element) => element.text)
+        : [];
+    return {
+      readable: true,
+      line: lineOf(p),
+      resource: literal("resource"),
+      skill: literal("skill"),
+      title: literal("title"),
+      contextPaths,
+      maxContextChars,
+      keys: objKeys(value),
+    };
+  }
+
   function visit(node) {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
       const callee = node.expression.text;
@@ -992,6 +1077,8 @@ export function parseActions(fileName, sourceText) {
           name: strProp(obj, "name"),
           kind: strProp(obj, "kind"),
           effect: strProp(obj, "effect"),
+          ai: aiState(obj),
+          assistant: assistantDeclaration(obj),
           keys: objKeys(obj),
           ident: constIdent(node),
           exported: isExported(node),
@@ -1023,6 +1110,61 @@ export function parseActions(fileName, sourceText) {
   return actions;
 }
 
+/**
+ * Regra `assistant-declaration` (ADR 0053) sobre um item: a forma do assistente do recurso. O
+ * `resource` repetido entre actions é conferido no `checkProject`.
+ */
+function assistantMessages(a) {
+  const assistant = a.assistant;
+  if (assistant === null || assistant === undefined) return [];
+  const out = [];
+  if (a.kind !== null && a.kind !== "view")
+    out.push(
+      `Só uma action view declara assistente, e esta é ${a.kind}. A leitura de um recurso identificado é o papel da view.`,
+    );
+  if (a.ai === null || a.ai === "disabled")
+    out.push(
+      "A action dona precisa estar publicada para a IA: declare `ai: true` ou `ai` sem `enabled: false`.",
+    );
+  if (!a.keys.includes("personalData"))
+    out.push(
+      "A action dona precisa declarar `personalData`, `true` ou `false`: a declaração decide como o host trata o dado que entrega ao modelo.",
+    );
+  if (!assistant.readable) return out;
+  const { resource, skill } = assistant;
+  if (!resource.present)
+    out.push("O assistente precisa declarar `resource`, o tipo de recurso de que a action é dona.");
+  else if (resource.text !== null && !ASSISTANT_RESOURCE_RE.test(resource.text))
+    out.push(`\`resource: "${resource.text}"\` precisa estar em camelCase, como \`customer\` ou \`aftersaleOpportunity\`.`);
+  if (!skill.present)
+    out.push("O assistente precisa declarar `skill`, a chave do procedimento que a IA segue.");
+  else if (skill.text !== null && !ASSISTANT_SKILL_RE.test(skill.text))
+    out.push(`\`skill: "${skill.text}"\` precisa estar em minúsculas com hífen, como \`review-customer\`.`);
+  const reserved = [assistant.title.text, ...assistant.contextPaths].filter(
+    (path) =>
+      typeof path === "string" &&
+      path.split(".").some((segment) => ASSISTANT_RESERVED_SEGMENTS.has(segment)),
+  );
+  if (reserved.length > 0)
+    out.push(
+      `${reserved.map((path) => `\`${path}\``).join(", ")} usa __proto__, constructor ou prototype, que não são campos da saída.`,
+    );
+  const limit = assistant.maxContextChars;
+  if (
+    limit !== null &&
+    (!Number.isInteger(limit) || limit < ASSISTANT_CONTEXT_MIN || limit > ASSISTANT_CONTEXT_MAX)
+  )
+    out.push(
+      `\`maxContextChars: ${limit}\` precisa ser um inteiro de 1.000 a 16.000; sem ele, o teto é de 4.000 caracteres.`,
+    );
+  const missing = Object.keys(ASSISTANT_REQUIRED).filter((key) => !assistant.keys.includes(key));
+  if (missing.length > 0)
+    out.push(
+      `O assistente precisa declarar ${missing.map((key) => ASSISTANT_REQUIRED[key]).join("; ")}.`,
+    );
+  return out;
+}
+
 /** Aplica as regras locais (por arquivo) a um item → findings. */
 export function lintAction(a) {
   const out = [];
@@ -1088,6 +1230,15 @@ export function lintAction(a) {
   const ignored = ignoredByKindMessage(a.kind, a.keys);
   if (ignored !== null) at("ignored-by-kind", ignored);
 
+  for (const message of assistantMessages(a))
+    out.push({
+      rule: "assistant-declaration",
+      level: "error",
+      action: label,
+      line: a.assistant.line,
+      message,
+    });
+
   if (
     a.form === "defineAction" &&
     a.keys.includes("requires") &&
@@ -1126,6 +1277,7 @@ export function checkProject(sources) {
   const entityNames = new Set();
   const actionNames = new Set();
   const retention = [];
+  const assistantResources = new Map(); // resource literal → [{ item, file }]
   // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
   let missingEffect = 0;
   let missingPersonalData = 0;
@@ -1159,6 +1311,12 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
+      const resource = item.assistant?.resource?.text ?? null;
+      if (resource !== null) {
+        const owners = assistantResources.get(resource) ?? [];
+        owners.push({ item, file });
+        assistantResources.set(resource, owners);
+      }
       if (item.form !== "bindAction") {
         const writesByGet = item.kind === "list" || item.kind === "view";
         if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
@@ -1265,6 +1423,21 @@ export function checkProject(sources) {
     }
   }
 
+  for (const [resource, owners] of assistantResources) {
+    if (owners.length < 2) continue;
+    const names = owners.map(({ item }) => item.name ?? item.ident ?? "(sem name)");
+    for (const { item, file } of owners) {
+      findings.push({
+        rule: "assistant-declaration",
+        level: "error",
+        action: item.name ?? item.ident ?? "(sem name)",
+        line: item.assistant.line,
+        file,
+        message: `O recurso "${resource}" tem mais de uma action dona (${names.join(", ")}). Cada tipo de recurso tem uma única action dona.`,
+      });
+    }
+  }
+
   findings.push(...checkRetention(retention));
 
   return {

package/bin/lib/copy.mjs

@@ -1540,6 +1540,8 @@ export function extractCopyFromSource(file, sourceText) {
       addProperty(example, 'description', 'description', prefix)
     })
     nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
+    // O nome do assistente do recurso (ADR 0053), que a interface mostra como título do chat.
+    nestedObject(object, 'assistant', (assistant, prefix) => addProperty(assistant, 'label', 'title', prefix))
   }
 
   function extractPresentation(object) {

package/bin/lib/gen-manifest.mjs

@@ -55,6 +55,9 @@ function shapeAction(a) {
     automatable: a.automatable,
     effect: a.effect ?? null,
     personalData: a.personalData ?? null,
+    // ADR 0053: a publicação para a IA e, na action dona, o assistente do recurso.
+    ai: a.ai ?? { enabled: false, description: null, destructive: false, requiresConfirmation: false },
+    ...(a.assistant !== undefined && a.assistant !== null ? { assistant: a.assistant } : {}),
     internal: a.internal,
     successStatus: a.successStatus,
     input: a.input,

package/bin/lib/gen-runner.mjs

@@ -53,6 +53,8 @@
  *       automatable?: boolean,             // aceita execução pelo sistema (ADR 0028)
  *       effect: 'read'|'write'|null,       // efeito resolvido; list/view = read (ADR 0041)
  *       personalData: boolean|null,        // devolve dado pessoal; null = não declarado
+ *       ai: { enabled, description, destructive, requiresConfirmation }, // ADR 0053
+ *       assistant?: { resource, skill, label, title, context, maxContextChars }, // view dona
  *       internal?: boolean,
  *       rateLimit?: { window, max },
  *       confirm?: ConfirmSpec,
@@ -67,6 +69,7 @@
 
 import path from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
+import { assistantSchemaIssues, serializeAiConfig } from "./assistant-schema.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -90,7 +93,7 @@ async function main() {
   const opusCoreUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "core", "index.ts"),
   ).href;
-  const { flattenDomain, domainPurges, declaredJsonSchema } = await import(opusCoreUrl);
+  const { flattenDomain, domainPurges, declaredJsonSchema, publicAssistant } = await import(opusCoreUrl);
 
   const opusSeedUrl = pathToFileURL(
     path.join(PACKAGE_ROOT, "src", "seed", "index.ts"),
@@ -138,6 +141,7 @@ async function main() {
   const ctx = {
     flattenDomain,
     domainPurges,
+    publicAssistant,
     // Standard Schema que declara o próprio JSON Schema (ADR 0051) dispensa o zod.
     toJsonSchema: (schema) =>
       declaredJsonSchema(schema, { target: "openapi-3.0" }) ??
@@ -393,6 +397,8 @@ function serializeAction(action, ctx) {
     // ADR 0041: `list` e `view` são leitura pelo protocolo; null = não declarado.
     effect: action.kind === "list" || action.kind === "view" ? "read" : (action.effect ?? null),
     personalData: typeof action.personalData === "boolean" ? action.personalData : null,
+    // ADR 0053: a publicação para a IA entra no manifest, e a action dona, o assistente.
+    ai: serializeAiConfig(action.ai),
     internal: action.internal === true,
     successStatus: action.successStatus,
     input: safeToJsonSchema(action.input, ctx),
@@ -434,6 +440,20 @@ function serializeAction(action, ctx) {
     base.expand = action.expand ?? null;
   }
 
+  if (action.kind === "view" && action.assistant !== undefined && action.assistant !== null) {
+    const issues = assistantSchemaIssues({
+      assistant: action.assistant,
+      input: base.input,
+      output: base.output,
+    });
+    if (issues.length > 0) {
+      throw declarationError(
+        `O assistente da action "${action.name}" não confere com o contrato (ADR 0053): ${issues.join("; ")}.`,
+      );
+    }
+    base.assistant = ctx.publicAssistant(action.assistant);
+  }
+
   return base;
 }
 
@@ -605,6 +625,14 @@ function emitError(message) {
   process.exit(1);
 }
 
+/** Erro de declaração do consumidor: a mensagem basta, sem a pilha do runner. */
+function declarationError(message) {
+  const err = new Error(message);
+  err.name = "OpusDeclarationError";
+  return err;
+}
+
 main().catch((err) => {
+  if (err?.name === "OpusDeclarationError") return emitError(err.message);
   emitError(`runner crash: ${err.stack ?? err.message ?? String(err)}`);
 });

package/bin/lib/mcp.mjs

@@ -42,7 +42,7 @@ export function buildServer() {
   server.registerTool(
     'opus_check',
     {
-      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind, soft-delete-retention. Retorna findings.',
+      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize, ignored-by-kind, assistant-declaration, soft-delete-retention. Retorna findings.',
       inputSchema: { dir: z.string().optional() },
     },
     async ({ dir }) => asText(await scanDir(dirOf(dir))),