@microteia/console 2.8.0 → 2.18.0

package/lib/console/deploy.js

@@ -15,6 +15,7 @@ import { installPath, readInstalledManifest } from './unpack.js';
 import { ensureOfficeEnv, ensureRootGitignore, officeEnvName, stageOfficeEnv } from './backendEnv.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
 import { readResolvedConfig, stampedConfigJs, writeResolvedConfig, } from './workspace.js';
+import { STAMP_FILE, buildLoginExtensions, stampPath } from './loginExtensions.js';
 const COMPONENTS = ['rules', 'indexes', 'functions', 'hosting'];
 const selectedComponents = (args) => {
     const only = flagValue(args, 'only');
@@ -63,6 +64,20 @@ export const deploy = async (args) => {
     await writeResolvedConfig(root, stamped);
     await writeFile(join(install, 'hosting', 'firebase-config.js'), stampedConfigJs(stamped));
     success(`hosting/firebase-config.js → ${projectId}`);
+    // As extensões que valem ANTES do login. Carimbadas no mesmo passo da configuração porque são a
+    // mesma coisa: o que o navegador precisa saber antes de o bundle subir. Escrito sempre, mesmo vazio
+    // — pular a escrita deixaria o carimbo do deploy anterior no ar, e tirar um pacote da lista não o
+    // tiraria da tela.
+    const loginExtensions = await buildLoginExtensions(root, environment.login.extensions, manifest.preLoginPoints);
+    await writeFile(stampPath(install), loginExtensions.contents);
+    if (loginExtensions.stamped.length === 0) {
+        success(`hosting/${STAMP_FILE} → no extensions before sign-in`);
+    }
+    else {
+        success(`hosting/${STAMP_FILE} → ${loginExtensions.stamped.join(', ')}`);
+    }
+    for (const warning of loginExtensions.warnings)
+        warn(warning);
     // O arquivo que o escritório edita é o da RAIZ; o que o `firebase-functions` lê tem de estar em
     // `install/functions/`, e por isso é uma cópia escrita agora. Antes a fonte era a cópia, e o deploy
     // seguinte a apagava junto com o pacote.
@@ -110,17 +125,27 @@ export const deploy = async (args) => {
             // comuns) e `extensions/<plugin>/functions/` (as de cada extensão). O `predeploy` do pacote compila
             // só o `custom/`, então o que não estiver aqui não sobe.
             const gathered = await gatherCustomFunctions(root, install, manifest.functions);
-            // O que sobe aqui é a baseline MAIS as functions comuns do escritório (`functions/`). As de
-            // `extensions/<plugin>/functions/` têm dono e sobem pelo provisionamento, no fim deste comando:
-            // é o mesmo "empacotar não é deployar" que vale para as do kernel reivindicadas por extensão.
-            const own = [...baseline, ...gathered.shared];
+            /**
+             * O que sobe aqui é a baseline MAIS as functions comuns que NÃO dizem a quem servem.
+             *
+             * As de `extensions/<plugin>/functions/` têm dono e sobem pelo provisionamento, no fim deste
+             * comando — é o mesmo "empacotar não é deployar" que vale para as do kernel reivindicadas por
+             * extensão. E a comum que DECLARA quem serve passou a ter a mesma condição, pela mesma razão: ela
+             * é devida enquanto alguma das extensões servidas estiver instalada, e subi-la aqui de qualquer
+             * forma faria o `--prune` apagá-la e este passo repô-la, indefinidamente.
+             *
+             * A comum sem declaração continua subindo sempre. É o comportamento anterior, e mantê-lo é o que
+             * impede esta versão de tirar do ar function de uma instalação que já existe.
+             */
+            const own = [...baseline, ...gathered.unserved];
             step(current, total, `Cloud Functions (${own.length}, one at a time)`);
             if (gathered.sources.length > 0) {
                 success(`${gathered.functions.length} function(s) of your own, from `
                     + `${gathered.sources.map((source) => `${source.label}/`).join(', ')}`);
-                const owned = gathered.all.length - gathered.shared.length;
-                if (owned > 0)
-                    info(`  ${owned} of them belong to an extension and go up with "provision"`);
+                const provisioned = gathered.all.length - gathered.unserved.length;
+                if (provisioned > 0) {
+                    info(`  ${provisioned} of them go up with "provision", only where they are needed`);
+                }
             }
             if (Object.keys(gathered.dependencies.added).length > 0) {
                 success(`${Object.keys(gathered.dependencies.added).length} npm dependency(ies) your functions declare: `

package/lib/console/environment.d.ts

@@ -29,13 +29,14 @@ export interface Environment {
         deployed: string | null;
     };
     /**
-     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto. Fica aqui, e não no banco,
-     * porque é estado da instalação e não do escritório — e é o que permite ao `provision` deployar só o
-     * delta e reconhecer o que ficou órfão depois de uma desinstalação.
+     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto, e de QUEM. Fica aqui, e não no
+     * banco, porque é estado da instalação e não do escritório — e é o que permite ao `provision`
+     * deployar só o delta e reconhecer o que ficou órfão depois de uma desinstalação.
      *
-     * Uma lista num escalar separado por vírgula porque o leitor de YAML daqui entende mapas de dois
-     * níveis e escalares, e trazer sequências para guardar meia dúzia de nomes seria pagar caro pela
-     * generalidade.
+     * `nome@pluginId` separado por vírgula — ver `appliedFunctions.ts`, que o lê e o escreve. O escalar é
+     * porque o leitor de YAML daqui entende mapas de dois níveis e escalares, e trazer sequências para
+     * guardar meia dúzia de pares seria pagar caro pela generalidade. Uma entrada sem `@` é o que uma
+     * instalação anterior ao dono gravou, e continua valendo.
      */
     backend: {
         functions: string | null;
@@ -53,6 +54,21 @@ export interface Environment {
          */
         indexes: string | null;
     };
+    /**
+     * As extensões que a instalação carrega ANTES do login — os pacotes compilados que `deploy` carimba
+     * em `microteia-extensions.js`. É por aqui que um SSO chega à tela de entrada: ali não há escritório,
+     * logo não há como ler o que um escritório instalou.
+     *
+     * É uma lista de CAMINHOS, e é deliberado que seja explícita. Varrer `extensions/` poria no ar um
+     * rascunho de autoria — aquele diretório é onde se escreve, não o que roda. Carimbar é um ato, e
+     * escrever o caminho aqui é o ato.
+     *
+     * Escalar separado por vírgula, como `backend.functions`, pela mesma razão: o leitor de YAML daqui
+     * entende mapas de dois níveis e escalares.
+     */
+    login: {
+        extensions: string | null;
+    };
 }
 export declare const ENVIRONMENT_FILE = "microteia.yaml";
 export declare const parseEnvironment: (source: string) => Environment;

package/lib/console/environment.js

@@ -83,6 +83,7 @@ export const parseEnvironment = (source) => {
             parameters: optional('backend', 'parameters'),
             indexes: optional('backend', 'indexes'),
         },
+        login: { extensions: optional('login', 'extensions') },
     };
 };
 export const serializeEnvironment = (environment) => `# Microteia installation.
@@ -128,6 +129,16 @@ backend:
   # "firebase deploy" offer to delete the indexes of every extension. Managed by
   # "microteia provision".
   indexes: ${quote(environment.backend.indexes)}
+
+login:
+  # Compiled extension packages (.json) to load BEFORE anyone signs in — this is how a corporate SSO
+  # reaches the sign-in screen, since there is no organization to read it from yet. Comma-separated
+  # paths, relative to this file. "microteia deploy" stamps them into microteia-extensions.js and
+  # refuses a package that contributes to none of the points that work before sign-in.
+  #
+  # Nothing stamped here runs JavaScript: the packages load as untrusted, so only declarations apply.
+  # To USE an extension inside the organization, install it from the Extensions screen instead.
+  extensions: ${quote(environment.login.extensions)}
 `;
 export const readEnvironment = async (path) => {
     try {

package/lib/console/exportCatalog.d.ts

@@ -0,0 +1,124 @@
+import type { ParsedArgs } from '../shared/args.js';
+import type { InstalledExtensionRecord, TenantSummary } from './installedExtensions.js';
+/**
+ * `microteia export-catalog` — o RETRATO do domínio instalado, para o diretório de autoria.
+ *
+ * O servidor MCP do SDK monta o catálogo a partir dos `plugin.ts` do diretório mais o registro de
+ * entidades do kernel. Numa instalação real isso deixa de fora as duas coisas que mais importam: a
+ * tela que o escritório criou no Form Design e a extensão de terceiro já instalada. O detector de
+ * "campo que pertence a outra entidade conhecida" não podia disparar contra elas, porque para ele elas
+ * não existiam.
+ *
+ * A saída NÃO foi ligar o SDK ao Firestore. `microteia-plugin` é offline por desenho, e arrastar
+ * credencial para dentro da ferramenta de autoria trocaria uma cegueira por um problema pior. Quem já
+ * fala com o projeto do escritório é o Console — o token vem do `gcloud`, a cada execução, e nada é
+ * guardado. Então é o Console que lê e escreve o arquivo, e o SDK apenas o encontra ali.
+ *
+ * Três decisões que não são preferência:
+ *
+ * - **O arquivo NÃO mora em `.microteia/`.** Aquele diretório é apagado por inteiro a cada `unpack`,
+ *   e um retrato que some na troca de kernel é um retrato que ninguém pode depender de ter. Ele fica
+ *   em `extensions/`, ao lado do `microteia.yaml`, que é onde o autor trabalha.
+ * - **Ele é gitignorado**, pela conciliação que o SDK já faz do `.gitignore` daquele diretório. Ele
+ *   carrega nome de tela e de campo que o escritório digitou: dado do tenant, não artefato do produto.
+ * - **`--tenant` é obrigatório.** Um projeto Firebase pode ter vários escritórios, e escolher um por
+ *   adivinhação escreveria o vocabulário de um dentro do trabalho de outro. Sem a opção, o comando
+ *   LISTA os que existem.
+ */
+/** O nome é contrato com o SDK, que o procura por este nome — ver `installedCatalog.ts` do kernel. */
+export declare const CATALOG_FILE = "installed-catalog.json";
+/**
+ * A versão do FORMATO. Ela existe para que um Console de outra época não seja lido como se falasse a
+ * mesma língua: o SDK recusa o que não for exatamente esta, e diz o comando que refaz o arquivo.
+ */
+export declare const CATALOG_FORMAT_VERSION = 1;
+/**
+ * O que viaja de cada campo, e nada além.
+ *
+ * A linha é ESQUEMA versus CONTEÚDO. Nome, tipo, obrigatoriedade, referência, agregado e expressão
+ * descrevem o que a entidade É, e é disso que o catálogo e os detectores precisam. Opção de lista,
+ * máscara, texto de ajuda, valor padrão e regra de formulário são conteúdo e apresentação: o catálogo
+ * nunca os lê, e cada um deles é mais vocabulário do escritório saindo do banco sem precisar.
+ */
+export interface CatalogFieldExport {
+    key: string;
+    label: string;
+    type: string;
+    required: boolean;
+    order: number;
+    multi?: boolean;
+    refEntity?: string;
+    refDenormKey?: string;
+    lookupCollection?: string;
+    section?: string;
+    origin: string;
+    ownerPluginId?: string;
+    aggregation?: Record<string, unknown>;
+    compute?: string;
+}
+export interface CatalogScreenExport {
+    key: string;
+    collection?: string;
+    titleSingular: string;
+    titlePlural?: string;
+    titleFieldKey: string;
+    origin: string;
+    ownerPluginId?: string;
+    parentEntity?: string;
+    parentFieldKey?: string;
+    parentRelation?: string;
+    tagCollection?: string;
+    eventPrefix?: string;
+    fields: CatalogFieldExport[];
+}
+export interface CatalogListExport {
+    collection: string;
+    label: string;
+    ownerPluginId?: string;
+}
+export interface CatalogExtensionExport {
+    id: string;
+    name: string;
+    version: string;
+    active: boolean;
+}
+export interface CatalogExport {
+    version: number;
+    projectId: string;
+    tenantId: string;
+    tenantName: string;
+    exportedAt: string;
+    kernelVersion: string;
+    consoleVersion: string;
+    extensions: CatalogExtensionExport[];
+    screens: CatalogScreenExport[];
+    lookups: CatalogListExport[];
+    tagLists: CatalogListExport[];
+}
+/** Um documento já decodificado, com o id que a coleção lhe deu. */
+export interface CatalogSourceDocument {
+    id: string;
+    data: Record<string, unknown>;
+}
+export interface CatalogExportInput {
+    projectId: string;
+    tenant: TenantSummary;
+    kernelVersion: string;
+    exportedAt: Date;
+    screens: CatalogSourceDocument[];
+    lookups: CatalogSourceDocument[];
+    tagLists: CatalogSourceDocument[];
+    extensions: InstalledExtensionRecord[];
+}
+/**
+ * O documento, montado a partir do que foi lido. É PURA de propósito: o que ela produz é o contrato com
+ * o SDK, e um contrato que só pode ser exercitado com um projeto Firebase na frente é um contrato que
+ * ninguém confere.
+ *
+ * Uma tela DESLIGADA (`enabled: false`) fica de fora: a coleção dela pode até existir no banco, mas
+ * nada da plataforma a desenha, e trazê-la faria o catálogo afirmar que a entidade existe. Uma tela de
+ * extensão DESATIVADA continua: o documento dela segue gravado, e é ele que explica um campo que o
+ * autor vai encontrar.
+ */
+export declare const buildCatalogExport: (input: CatalogExportInput) => CatalogExport;
+export declare const exportCatalog: (args: ParsedArgs) => Promise<void>;

package/lib/console/exportCatalog.js

@@ -0,0 +1,264 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { flagValue } from '../shared/args.js';
+import { CLI_VERSION } from '../shared/paths.js';
+import { blank, bullets, heading, info, step, success, warn } from '../shared/ui.js';
+import { decodeFields, documentId, listDocuments } from './firestoreRest.js';
+import { listTenants, readInstalledExtensions } from './installedExtensions.js';
+import { ENVIRONMENT_FILE, readEnvironment } from './environment.js';
+import { EXTENSIONS_DIR } from './pluginWorkspace.js';
+import { WORKSPACE_DIR } from './workspace.js';
+/**
+ * `microteia export-catalog` — o RETRATO do domínio instalado, para o diretório de autoria.
+ *
+ * O servidor MCP do SDK monta o catálogo a partir dos `plugin.ts` do diretório mais o registro de
+ * entidades do kernel. Numa instalação real isso deixa de fora as duas coisas que mais importam: a
+ * tela que o escritório criou no Form Design e a extensão de terceiro já instalada. O detector de
+ * "campo que pertence a outra entidade conhecida" não podia disparar contra elas, porque para ele elas
+ * não existiam.
+ *
+ * A saída NÃO foi ligar o SDK ao Firestore. `microteia-plugin` é offline por desenho, e arrastar
+ * credencial para dentro da ferramenta de autoria trocaria uma cegueira por um problema pior. Quem já
+ * fala com o projeto do escritório é o Console — o token vem do `gcloud`, a cada execução, e nada é
+ * guardado. Então é o Console que lê e escreve o arquivo, e o SDK apenas o encontra ali.
+ *
+ * Três decisões que não são preferência:
+ *
+ * - **O arquivo NÃO mora em `.microteia/`.** Aquele diretório é apagado por inteiro a cada `unpack`,
+ *   e um retrato que some na troca de kernel é um retrato que ninguém pode depender de ter. Ele fica
+ *   em `extensions/`, ao lado do `microteia.yaml`, que é onde o autor trabalha.
+ * - **Ele é gitignorado**, pela conciliação que o SDK já faz do `.gitignore` daquele diretório. Ele
+ *   carrega nome de tela e de campo que o escritório digitou: dado do tenant, não artefato do produto.
+ * - **`--tenant` é obrigatório.** Um projeto Firebase pode ter vários escritórios, e escolher um por
+ *   adivinhação escreveria o vocabulário de um dentro do trabalho de outro. Sem a opção, o comando
+ *   LISTA os que existem.
+ */
+/** O nome é contrato com o SDK, que o procura por este nome — ver `installedCatalog.ts` do kernel. */
+export const CATALOG_FILE = 'installed-catalog.json';
+/**
+ * A versão do FORMATO. Ela existe para que um Console de outra época não seja lido como se falasse a
+ * mesma língua: o SDK recusa o que não for exatamente esta, e diz o comando que refaz o arquivo.
+ */
+export const CATALOG_FORMAT_VERSION = 1;
+const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value : undefined);
+const asRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined);
+const FIELD_ORIGINS = ['builtin', 'plugin', 'design'];
+/**
+ * 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 é
+ * repetida aqui porque o Console não alcança `src/` — e é conferida contra a instalação real por teste.
+ */
+const originOf = (data, fallback) => {
+    const declared = text(data.origin);
+    if (declared !== undefined && FIELD_ORIGINS.includes(declared))
+        return declared;
+    return text(data.ownerPluginId) !== undefined ? 'plugin' : fallback;
+};
+const fieldExport = (raw, index, screenOrigin) => {
+    const field = asRecord(raw);
+    if (field === undefined)
+        return null;
+    const key = text(field.key);
+    if (key === undefined)
+        return null;
+    const logic = asRecord(field.logic);
+    const compute = text(logic?.compute);
+    return {
+        key,
+        label: text(field.label) ?? key,
+        type: text(field.type) ?? 'text',
+        required: field.required === true,
+        order: typeof field.order === 'number' ? field.order : index,
+        ...(field.multi === true ? { multi: true } : {}),
+        ...(text(field.refEntity) === undefined ? {} : { refEntity: text(field.refEntity) }),
+        ...(text(field.refDenormKey) === undefined ? {} : { refDenormKey: text(field.refDenormKey) }),
+        ...(text(field.lookupCollection) === undefined ? {} : { lookupCollection: text(field.lookupCollection) }),
+        ...(text(field.section) === undefined ? {} : { section: text(field.section) }),
+        origin: originOf(field, screenOrigin),
+        ...(text(field.ownerPluginId) === undefined ? {} : { ownerPluginId: text(field.ownerPluginId) }),
+        ...(asRecord(field.aggregation) === undefined ? {} : { aggregation: asRecord(field.aggregation) }),
+        ...(compute === undefined ? {} : { compute }),
+    };
+};
+const screenExport = (document) => {
+    const data = document.data;
+    const origin = originOf(data, 'design');
+    const fields = Array.isArray(data.fields) ? data.fields : [];
+    return {
+        key: document.id,
+        ...(text(data.dataCollection) === undefined ? {} : { collection: text(data.dataCollection) }),
+        titleSingular: text(data.titleSingular) ?? document.id,
+        ...(text(data.titlePlural) === undefined ? {} : { titlePlural: text(data.titlePlural) }),
+        titleFieldKey: text(data.titleFieldKey) ?? '',
+        origin,
+        ...(text(data.ownerPluginId) === undefined ? {} : { ownerPluginId: text(data.ownerPluginId) }),
+        ...(text(data.parentEntity) === undefined ? {} : { parentEntity: text(data.parentEntity) }),
+        ...(text(data.parentFieldKey) === undefined ? {} : { parentFieldKey: text(data.parentFieldKey) }),
+        ...(text(data.parentRelation) === undefined ? {} : { parentRelation: text(data.parentRelation) }),
+        ...(text(data.tagCollection) === undefined ? {} : { tagCollection: text(data.tagCollection) }),
+        ...(text(data.eventPrefix) === undefined ? {} : { eventPrefix: text(data.eventPrefix) }),
+        fields: fields
+            .map((field, index) => fieldExport(field, index, origin))
+            .filter((field) => field !== null),
+    };
+};
+/**
+ * O id do documento É o nome da coleção da lista, tanto em `lookupDefinitions` quanto em
+ * `tagDefinitions` — a mesma convenção que os repositórios da aplicação usam ao mapeá-las.
+ */
+const listExport = (document) => ({
+    collection: document.id,
+    label: text(document.data.label) ?? document.id,
+    ...(text(document.data.ownerPluginId) === undefined
+        ? {}
+        : { ownerPluginId: text(document.data.ownerPluginId) }),
+});
+/**
+ * O documento, montado a partir do que foi lido. É PURA de propósito: o que ela produz é o contrato com
+ * o SDK, e um contrato que só pode ser exercitado com um projeto Firebase na frente é um contrato que
+ * ninguém confere.
+ *
+ * Uma tela DESLIGADA (`enabled: false`) fica de fora: a coleção dela pode até existir no banco, mas
+ * nada da plataforma a desenha, e trazê-la faria o catálogo afirmar que a entidade existe. Uma tela de
+ * extensão DESATIVADA continua: o documento dela segue gravado, e é ele que explica um campo que o
+ * autor vai encontrar.
+ */
+export const buildCatalogExport = (input) => ({
+    version: CATALOG_FORMAT_VERSION,
+    projectId: input.projectId,
+    tenantId: input.tenant.id,
+    tenantName: input.tenant.name,
+    exportedAt: input.exportedAt.toISOString(),
+    kernelVersion: input.kernelVersion,
+    consoleVersion: CLI_VERSION,
+    extensions: input.extensions
+        .map((one) => ({ id: one.id, name: one.name, version: one.version, active: one.active }))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+    screens: input.screens
+        .filter((document) => document.data.enabled !== false)
+        .map(screenExport)
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)),
+    lookups: input.lookups
+        .map(listExport)
+        .sort((a, b) => (a.collection < b.collection ? -1 : a.collection > b.collection ? 1 : 0)),
+    tagLists: input.tagLists
+        .map(listExport)
+        .sort((a, b) => (a.collection < b.collection ? -1 : a.collection > b.collection ? 1 : 0)),
+});
+const decode = (documents) => documents.map((document) => ({ id: documentId(document), data: decodeFields(document.fields) }));
+const readSubcollection = async (projectId, tenantId, name) => decode(await listDocuments(projectId, `/tenants/${tenantId}/${name}`));
+/**
+ * O kernel que está NO LUGAR nesta instalação, e não o que já foi publicado: o retrato descreve o
+ * contrato contra o qual o autor compila agora. Ausente, o SDK dirá que não sabe — o que é melhor que
+ * carimbar uma versão inventada.
+ */
+const installedKernelVersion = async (root) => {
+    const path = join(root, WORKSPACE_DIR, 'install', 'manifest.json');
+    if (!existsSync(path))
+        return 'unknown';
+    try {
+        const manifest = JSON.parse(await readFile(path, 'utf8'));
+        return typeof manifest.kernelVersion === 'string' ? manifest.kernelVersion : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+};
+/**
+ * O arquivo é gitignorado pela conciliação que o SDK faz do `.gitignore` de `extensions/` — este
+ * comando não escreve naquele arquivo, porque a política é de lá. O que ele faz é OLHAR: se a linha
+ * ainda não chegou (um diretório sincronizado por um kernel anterior), diz qual comando a traz, em vez
+ * de deixar o retrato pronto para ser commitado sem ninguém notar.
+ */
+const checkIgnored = async (directory) => {
+    const path = join(directory, '.gitignore');
+    if (!existsSync(path))
+        return;
+    const lines = (await readFile(path, 'utf8')).split('\n').map((line) => line.trim());
+    if (lines.includes(CATALOG_FILE) || lines.includes('*.json'))
+        return;
+    warn(`${relative(process.cwd(), path) || '.gitignore'} does not ignore ${CATALOG_FILE}.`);
+    info('  It carries screen and field names the office typed, which is tenant data and does not belong');
+    info(`  in an extension repository. Run "npm run sync" in ${EXTENSIONS_DIR}/ to get the line, or add it`);
+    info('  by hand.');
+};
+const listAndStop = (tenants, projectId) => {
+    if (tenants.length === 0) {
+        warn(`${projectId} has no office yet, so there is no catalog to export.`);
+        info('  An office is created the first time somebody signs in to the application.');
+        blank();
+        return;
+    }
+    info(`${projectId} has ${tenants.length} office(s). Pick one:`);
+    bullets(tenants.map((tenant) => `${tenant.name} — microteia export-catalog --tenant ${tenant.id}`));
+    blank();
+    info('The export is per office because screens, lists and tag lists are per office: exporting the');
+    info('wrong one would put another office\'s vocabulary inside your extension work.');
+    blank();
+};
+export const exportCatalog = async (args) => {
+    const file = resolve(flagValue(args, 'file') ?? join(process.cwd(), ENVIRONMENT_FILE));
+    const root = dirname(file);
+    const environment = await readEnvironment(file);
+    const projectId = environment.firebase.projectId;
+    if (projectId === null) {
+        throw new Error('This installation is not connected yet. Run "microteia connect --project <id>".');
+    }
+    heading(`Exporting the installed catalog from ${projectId}`);
+    const tenants = await listTenants(projectId);
+    const wanted = flagValue(args, 'tenant');
+    if (wanted === undefined) {
+        listAndStop(tenants, projectId);
+        return;
+    }
+    const tenant = tenants.find((one) => one.id === wanted);
+    if (tenant === undefined) {
+        throw new Error(`${projectId} has no office with id "${wanted}".\n`
+            + `  Offices in this project: ${tenants.length === 0 ? '(none)' : tenants.map((one) => `${one.name} (${one.id})`).join(', ')}`);
+    }
+    const output = flagValue(args, 'output');
+    const directory = join(root, EXTENSIONS_DIR);
+    if (output === undefined && !existsSync(directory)) {
+        throw new Error(`There is no ${EXTENSIONS_DIR}/ in this installation, and that is where the catalog belongs — it\n`
+            + '  exists to answer the authoring tools, and nothing else reads it.\n'
+            + '  Run "microteia plugin-init" first, or pass --output <path> to put it somewhere else.');
+    }
+    const target = output === undefined ? join(directory, CATALOG_FILE) : resolve(output);
+    step(1, 2, `Reading what ${tenant.name} has`);
+    const [screens, lookups, tagLists, extensions] = await Promise.all([
+        readSubcollection(projectId, tenant.id, 'screenDefinitions'),
+        readSubcollection(projectId, tenant.id, 'lookupDefinitions'),
+        readSubcollection(projectId, tenant.id, 'tagDefinitions'),
+        readInstalledExtensions(projectId, tenant.id),
+    ]);
+    const document = buildCatalogExport({
+        projectId,
+        tenant,
+        kernelVersion: await installedKernelVersion(root),
+        exportedAt: new Date(),
+        screens,
+        lookups,
+        tagLists,
+        extensions,
+    });
+    step(2, 2, 'Writing the snapshot');
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(document, null, 2)}\n`);
+    const fromExtensions = document.screens.filter((screen) => screen.origin === 'plugin').length;
+    success(`${relative(process.cwd(), target) || CATALOG_FILE} — ${document.screens.length} screen(s), `
+        + `${document.lookups.length} list(s), ${document.tagLists.length} tag list(s)`);
+    info(`  ${fromExtensions} screen(s) come from the ${document.extensions.length} installed extension(s); `
+        + `the rest the office built itself.`);
+    blank();
+    await checkIgnored(directory);
+    info('It is a SNAPSHOT, and it says so: the authoring tools report when it was taken and warn when it');
+    info('is old. Nothing keeps it in step with the office — run this again after screens change there.');
+    blank();
+    info('What it deliberately leaves out: records, the values inside a list of options or a tag list,');
+    info('members and permissions, workflows, scripts, actions, secrets and settings. It describes what');
+    info('the entities ARE, and nothing an office typed into them.');
+    blank();
+};

package/lib/console/firestoreRest.d.ts

@@ -20,8 +20,26 @@ export type FirestoreTypedValue = {
     stringValue: string;
 } | {
     timestampValue: string;
+} | {
+    integerValue: string;
+} | {
+    arrayValue: {
+        values: FirestoreTypedValue[];
+    };
+} | {
+    mapValue: {
+        fields: Record<string, FirestoreTypedValue>;
+    };
 };
 export declare const asString: (value: string) => FirestoreTypedValue;
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export declare const asInteger: (value: number) => FirestoreTypedValue;
+export declare const asArray: (values: FirestoreTypedValue[]) => FirestoreTypedValue;
+export declare const asMap: (fields: Record<string, FirestoreTypedValue>) => FirestoreTypedValue;
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -37,3 +55,12 @@ export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
  * Console carimbar o estado sem conhecer (nem arriscar reescrever) o pacote inteiro que vive ao lado.
  */
 export declare const patchMapField: (projectId: string, path: string, field: string, entries: Record<string, FirestoreTypedValue>) => Promise<void>;
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export declare const patchFields: (projectId: string, path: string, fields: Record<string, FirestoreTypedValue>) => Promise<void>;

package/lib/console/firestoreRest.js

@@ -108,6 +108,14 @@ export const listDocuments = async (projectId, path) => {
 };
 export const documentId = (document) => document.name.slice(document.name.lastIndexOf('/') + 1);
 export const asString = (value) => ({ stringValue: value });
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export const asInteger = (value) => ({ integerValue: String(value) });
+export const asArray = (values) => ({ arrayValue: { values } });
+export const asMap = (fields) => ({ mapValue: { fields } });
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -129,3 +137,18 @@ export const patchMapField = async (projectId, path, field, entries) => {
         body: { fields: { [field]: { mapValue: { fields: entries } } } },
     });
 };
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export const patchFields = async (projectId, path, fields) => {
+    await request(projectId, path, {
+        method: 'PATCH',
+        query: { 'updateMask.fieldPaths': Object.keys(fields) },
+        body: { fields },
+    });
+};