@microteia/console 2.31.1 → 2.33.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,14 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.33.0] — 2026-10-28
+
+- feat(export-catalog): each screen now carries `keys` — every record key of the collection as `name`, `kind`, `fields`, `scope`, `normalize` and `sparse`, plus `ownerPluginId` when an extension declared it — and each field carries `unique: true` when it is set. The conflict `message` and the deprecated `status` stay out: they do not change which reservation a record gets. Without this, the artifact plan proposed as new, on every run, a key the office declared in the Form Design or a third-party extension installed. Always written, even empty; a snapshot taken by an older Console is read as "keys unknown", and the authoring tools say so.
+
+#### [2.32.0] — 2026-10-27
+
+- feat(export-catalog): each installed extension now carries `fieldPresets` — every `data.field.preset` it declares, as its key and the parts it has (`mask`, `format`, `validate`), never the templates, formatting ops or validation rules. The authoring tools check a field's `mask`, `rules.format.preset` and `rules.validate.check` against it, so a key the dependency does not declare (`cpf-cnpj` for the Brasil extension's `cpfCnpj`) is refused by `check` instead of installing a field that silently has no mask. Always written, even empty; a snapshot taken by an older Console is read as "presets unknown".
+
 #### [2.31.1] — 2026-10-26
 
 - docs(kernel/manifest): the optional prerequisite `portal-identity-signing` now names a third feature that signs with the functions' runtime account: a portal screen declaring `documentLinks` hands guests V4 signed URLs, and without `iam.serviceAccounts.signBlob` the guest cannot open its documents (the denial shows in the log of `getPortalDocumentUrl`). `microteia grant-signing` grants the same permission for all three.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.31.1
+# Microteia Console 2.33.0
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/exportCatalog.d.ts

@@ -55,6 +55,29 @@ export interface CatalogFieldExport {
     ownerPluginId?: string;
     aggregation?: Record<string, unknown>;
     compute?: string;
+    /** O atalho de chave de um campo só — o kernel o desaçucara em `field:<key>`. */
+    unique?: true;
+}
+/**
+ * Uma chave da coleção (`ScreenDefinition.keys`): o que não pode se repetir. É esquema, como o campo:
+ * quem modela precisa saber que ela existe antes de propor outra, e o plano a propunha como nova a
+ * cada execução quando ela só existia na instalação.
+ *
+ * A mensagem do conflito NÃO viaja — é apresentação, e não muda qual reserva um registro recebe. O
+ * `status` também não: ele é ignorado pelo kernel desde que a adoção passou a ser estado dele.
+ */
+export interface CatalogKeyExport {
+    name: string;
+    kind: string;
+    fields: string[];
+    scope?: string;
+    normalize?: {
+        trim?: boolean;
+        caseInsensitive?: boolean;
+        formatPreset?: string;
+    };
+    sparse?: boolean;
+    ownerPluginId?: string;
 }
 export interface CatalogScreenExport {
     key: string;
@@ -74,6 +97,11 @@ export interface CatalogScreenExport {
     parentRelation?: string;
     tagCollection?: string;
     eventPrefix?: string;
+    /**
+     * Sempre escrita, mesmo vazia, pela mesma razão de `CatalogExtensionExport.exports`: a lista vazia diz
+     * "esta tela não tem chave"; a chave ausente é o silêncio de um Console anterior a este campo.
+     */
+    keys: CatalogKeyExport[];
     fields: CatalogFieldExport[];
 }
 export interface CatalogListExport {
@@ -132,6 +160,15 @@ export interface CatalogExtensionDocumentTemplate {
     source: 'record' | 'payload';
     parameters: CatalogExtensionDocumentParameter[];
 }
+/**
+ * Um preset de campo que a extensão declara (`data.field.preset`), como as PARTES que ele tem — nunca o
+ * template, o formato nem a regra. É contra ele que o `mask` de um campo de outra extensão é conferido:
+ * `mask: 'cpf-cnpj'` contra o `cpfCnpj` da Brasil instalava, e o campo ficava sem máscara.
+ */
+export interface CatalogExtensionFieldPreset {
+    key: string;
+    slots: ('mask' | 'format' | 'validate')[];
+}
 export interface CatalogExtensionExport {
     id: string;
     name: string;
@@ -146,6 +183,8 @@ export interface CatalogExtensionExport {
     navGroups: CatalogExtensionNavGroup[];
     /** Sempre escrita, mesmo vazia, pela mesma razão de `exports`. */
     documentTemplates: CatalogExtensionDocumentTemplate[];
+    /** Sempre escrita, mesmo vazia, pela mesma razão de `exports`. */
+    fieldPresets: CatalogExtensionFieldPreset[];
 }
 export interface CatalogExport {
     version: number;

package/lib/console/exportCatalog.js

@@ -165,6 +165,33 @@ const documentTemplatesOf = (extension) => {
     })
         .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
 };
+const FIELD_PRESET_POINT = 'data.field.preset';
+/**
+ * Os presets de campo de uma cópia instalada. É a mesma leitura que `declaredFieldPresets` faz no
+ * kernel — chave e rótulo obrigatórios, e as partes pelo critério do editor de campo —, repetida porque
+ * o Console não alcança `src/`; o teste que atravessa a fronteira confere as duas.
+ */
+const fieldPresetsOf = (extension) => {
+    const contributes = Array.isArray(extension.manifest?.contributes) ? extension.manifest.contributes : [];
+    return contributes
+        .map(asRecord)
+        .filter((one) => one?.point === FIELD_PRESET_POINT)
+        .flatMap((one) => {
+        const metadata = asRecord(one.metadata);
+        const key = text(metadata?.key);
+        if (metadata === undefined || key === undefined || text(metadata.label) === undefined)
+            return [];
+        return [{
+                key,
+                slots: [
+                    ...(metadata.mask ? ['mask'] : []),
+                    ...(Array.isArray(metadata.format) && metadata.format.length > 0 ? ['format'] : []),
+                    ...(metadata.validate ? ['validate'] : []),
+                ],
+            }];
+    })
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+};
 /**
  * A mesma dedução que a aplicação faz ao ler a tela (`screenDefinitionMapper.ts`): o `origin` gravado
  * quando ele existe, senão `plugin` para quem tem dono e `design` para o que o escritório criou. Ela é
@@ -200,6 +227,38 @@ const fieldExport = (raw, index, screenOrigin) => {
         ...(text(field.ownerPluginId) === undefined ? {} : { ownerPluginId: text(field.ownerPluginId) }),
         ...(asRecord(field.aggregation) === undefined ? {} : { aggregation: asRecord(field.aggregation) }),
         ...(compute === undefined ? {} : { compute }),
+        ...(field.unique === true ? { unique: true } : {}),
+    };
+};
+const normalizeExport = (raw) => {
+    const normalize = asRecord(raw);
+    if (normalize === undefined)
+        return undefined;
+    const formatPreset = text(normalize.formatPreset);
+    const picked = {
+        ...(typeof normalize.trim === 'boolean' ? { trim: normalize.trim } : {}),
+        ...(typeof normalize.caseInsensitive === 'boolean' ? { caseInsensitive: normalize.caseInsensitive } : {}),
+        ...(formatPreset === undefined ? {} : { formatPreset }),
+    };
+    return Object.keys(picked).length > 0 ? picked : undefined;
+};
+/** A chave como o kernel a grava, sem o que é apresentação. Sem nome ou sem campo, não é chave. */
+const keyExport = (raw) => {
+    const key = asRecord(raw);
+    const name = text(key?.name);
+    const kind = text(key?.kind);
+    const fields = (Array.isArray(key?.fields) ? key.fields : []).filter((one) => typeof one === 'string' && one !== '');
+    if (key === undefined || name === undefined || kind === undefined || fields.length === 0)
+        return null;
+    const normalize = normalizeExport(key.normalize);
+    return {
+        name,
+        kind,
+        fields,
+        ...(text(key.scope) === undefined ? {} : { scope: text(key.scope) }),
+        ...(normalize === undefined ? {} : { normalize }),
+        ...(typeof key.sparse === 'boolean' ? { sparse: key.sparse } : {}),
+        ...(text(key.ownerPluginId) === undefined ? {} : { ownerPluginId: text(key.ownerPluginId) }),
     };
 };
 const screenExport = (document) => {
@@ -220,6 +279,9 @@ const screenExport = (document) => {
         ...(text(data.parentRelation) === undefined ? {} : { parentRelation: text(data.parentRelation) }),
         ...(text(data.tagCollection) === undefined ? {} : { tagCollection: text(data.tagCollection) }),
         ...(text(data.eventPrefix) === undefined ? {} : { eventPrefix: text(data.eventPrefix) }),
+        keys: (Array.isArray(data.keys) ? data.keys : [])
+            .map(keyExport)
+            .filter((key) => key !== null),
         fields: fields
             .map((field, index) => fieldExport(field, index, origin))
             .filter((field) => field !== null),
@@ -263,6 +325,7 @@ export const buildCatalogExport = (input) => ({
         exports: exportedArtifacts(one),
         navGroups: navGroupsOf(one),
         documentTemplates: documentTemplatesOf(one),
+        fieldPresets: fieldPresetsOf(one),
     }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
     screens: input.screens

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.31.1";
+export declare const CLI_VERSION = "2.33.0";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.31.1';
+export const CLI_VERSION = '2.33.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.31.1",
+  "version": "2.33.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",