@microteia/console 2.7.2 → 2.10.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,62 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.10.0] — 2026-08-27
+
+- feat(export-catalog): a new command writes what an office HAS — its screens with their fields, its
+  lists of options, its tag lists and its installed extensions — into `extensions/installed-catalog.json`,
+  for the authoring tools to read. The MCP server's catalog knew only the `plugin.ts` files in that
+  directory plus the platform's own entities, so a screen built in the Form Design and an extension
+  already installed were invisible to it, and the check that catches a field belonging to another
+  entity could not fire against the entities that matter most. Closing it by giving the SDK a
+  credential was the wrong trade: `microteia-plugin` is offline by design. The Console already holds
+  the gcloud token, so the Console exports and the SDK only reads a file.
+- feat(export-catalog): `--tenant` is required, and without it the command LISTS the offices in the
+  project instead of guessing one. A Firebase project can hold several, and exporting the wrong one
+  would put another office's vocabulary inside somebody's extension work.
+- feat(export-catalog): the file is written beside `microteia.yaml`, in `extensions/` — never in
+  `.microteia/`, which `unpack` deletes whole on every kernel change. A snapshot that disappears on
+  upgrade is a snapshot nothing can depend on. `--output` overrides the path; without `extensions/`
+  the command refuses and names `microteia plugin-init`.
+- feat(export-catalog): it exports SHAPE, not content. Records, the values inside a list of options or
+  a tag list, members, permissions, workflows, scripts, actions, secrets and settings never leave the
+  office. A disabled screen is left out too: nothing draws it, and carrying it would assert that the
+  entity exists.
+- refactor(provision): reading what an office installed moved to `installedExtensions.ts`, and
+  `provision` now goes through it. Two paths to the same document are two chances to disagree about
+  what counts as installed.
+
+#### [2.9.0] — 2026-08-26
+
+- feat(deploy): `login.extensions` in `microteia.yaml` lists compiled extension packages that `deploy`
+  stamps into `hosting/microteia-extensions.js`, loaded before the bundle like `firebase-config.js`.
+  It is how a corporate SSO reaches the sign-in screen: that screen runs above the organization, so
+  nothing an organization installed can reach it, and until now the only way in was a commit in the
+  kernel.
+- feat(deploy): the stamp is written on EVERY deploy, empty list included. Skipping the write would
+  leave the previous deploy's stamp live, so removing a package from the list would not remove it from
+  the screen.
+- feat(deploy): a package that contributes to none of the points that work before sign-in is REFUSED,
+  not stamped. It would load with no effect, and whoever stamped it would believe it was live. The list
+  of those points comes from `preLoginPoints` in the installed package's manifest, never from a copy
+  here: the Console is versioned separately, and a copy would silently describe another version's
+  contract.
+- feat(deploy): the stamp is capped — a warning past 256 KiB, a refusal past 1 MiB. The file blocks the
+  page on every visit, including visits by people who never sign in.
+- feat(deploy): a duplicated package id is refused. The Kernel would ignore the second one, so the file
+  would say something the installation does not do. A missing path, broken JSON and a file that is not a
+  package each name themselves.
+- feat(deploy): a stamped package that ships views gets a warning saying its code does not run before
+  sign-in — stamping is not trusting, and that is what allows stamping without a code review.
+
+#### [2.8.0] — 2026-08-25
+
+- feat(console/functionsUpToDate): new module. It reconstructs the skip that `firebase deploy` performs in bulk and that `--only functions:<name>` disables, WITHOUT reimplementing the hash: functions are grouped by the `firebase-functions-hash` label they carry, one member of each group is deployed, and the stamp it comes back with is the stamp of the current code. The probe being a MEMBER of its group is what makes the conclusion carry to the others — two functions with the same old stamp share source, environment and secret set, the three parcels of the hash. Absent, non-`ACTIVE`, unstamped or wrong-region always deploys: not knowing never becomes skipping.
+- feat(console/deploy): asks the project once (`functions:list --json`) and feeds both decisions from that one answer — the region orphan check and the up-to-date check. Two questions could disagree, and then the decision depends on which answer the code happened to read.
+- feat(console/provision): `outdatedByStamp` requeues an applied extension function that carries a stamp older than what this package builds, or that is missing from the project. The stamp comes from the probes the `deploy` step just ran — extension functions live in the same codebase, so it is their stamp too. Called on its own, provisioning decides as it always did: probing there would cost a deploy on every extension install to answer a question that is almost always "nothing".
+- feat(console): `--all` on `deploy` and `provision` deploys every function without asking the project what it runs.
+- fix(console/regionOrphans): `listDeployedFunctions` keeps `hash`, `state` and `platform` instead of discarding everything but id and region; `clearRegionOrphans` accepts an already-fetched listing.
+
 #### [2.7.2] — 2026-08-25
 
 - feat(vendor/exampleSources): stages `automation-example` alongside the others, so the workspace ships a complete automation to read. Every example that travelled carried `workflows: []`, and automation was the one mechanism an author had only prose for.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.7.2
+# Microteia Console 2.10.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/deploy.js

@@ -5,8 +5,9 @@ import { run } from '../shared/run.js';
 import { blank, bullets, failure, heading, info, step, success, warn } from '../shared/ui.js';
 import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environment.js';
 import { FIREBASE_BIN } from './firebaseCli.js';
-import { deployFunctionsOneByOne, reportFailures, reportNotices } from './deployFunctions.js';
-import { clearRegionOrphans } from './regionOrphans.js';
+import { reportFailures, reportNotices } from './deployFunctions.js';
+import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
+import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
 import { checkHostingServed, htmlIsRevalidated } from './hostingCheck.js';
 import { provisionBackend } from './provision.js';
@@ -14,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');
@@ -62,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.
@@ -83,6 +99,12 @@ export const deploy = async (args) => {
     const failures = [];
     const unreachableCallables = [];
     let staleHosting = false;
+    let skippedFunctions = 0;
+    // O que as sondas do passo de functions descobriram: carimbo antigo -> carimbo de agora. O
+    // provisionamento está no MESMO codebase, então esse é o carimbo das functions de extensão também.
+    // Segue `undefined` quando o passo de functions não rodou: ali não há conclusão a tirar, e um mapa
+    // vazio diria a mesma coisa por acaso, e não por decisão.
+    let refreshedStamps;
     for (const component of components) {
         current += 1;
         if (component === 'rules') {
@@ -132,16 +154,25 @@ export const deploy = async (args) => {
             info('  npm may warn about the Node engine and about deprecated packages: both are expected —');
             info('  "engines" names the Cloud Functions runtime, and the notices come from Firebase\'s deps.');
             await run('npm', ['install', '--no-audit', '--no-fund'], { cwd: join(install, 'functions') });
+            // Uma pergunta só ao projeto, e duas decisões a partir dela: qual cópia ficou numa região
+            // abandonada, e o que ele já roda. Perguntar duas vezes não é caro, é ambíguo — as duas
+            // respostas podem divergir, e aí a decisão passa a depender de qual delas o código olhou.
+            const deployedNow = await listDeployedFunctions(projectId);
             // ANTES de deployar: uma cópia da mesma function numa região que o pacote abandonou faz o
             // `firebase` recusar o deploy dela, tentativa após tentativa, e faz um gatilho de Firestore
             // disparar duas vezes por gravação enquanto ninguém percebe.
-            await clearRegionOrphans(projectId, own, region, hasFlag(args, 'prune'));
-            const report = await deployFunctionsOneByOne(own, {
+            await clearRegionOrphans(projectId, own, region, hasFlag(args, 'prune'), deployedNow);
+            // Numa instalação nova não há carimbo nenhum com que comparar, e o mecanismo cai sozinho no
+            // caminho de sempre — não é preciso um desvio para isso. `--all` é o pedido explícito de subir
+            // tudo, para a configuração trocada por fora, que carimbo nenhum enxerga.
+            const report = await deployFunctionsThatChanged(own, {
                 projectId,
                 cwd: install,
                 delaySeconds,
                 force: firstInstall,
-            });
+            }, { deployed: deployedNow, region, all: hasFlag(args, 'all') });
+            refreshedStamps = report.refreshed;
+            skippedFunctions = report.skipped.length;
             if (report.failed.length > 0) {
                 failures.push(`${report.failed.length} function(s): ${report.failed.map((entry) => entry.name).join(', ')}`);
                 blank();
@@ -227,6 +258,8 @@ export const deploy = async (args) => {
             manifest,
             delaySeconds,
             prune: hasFlag(args, 'prune'),
+            all: hasFlag(args, 'all'),
+            refreshedStamps,
             environmentFile: file,
             environment: applied,
         });
@@ -242,6 +275,11 @@ export const deploy = async (args) => {
         blank();
         throw new Error('Some components did not deploy.');
     }
+    if (skippedFunctions > 0) {
+        info(`${skippedFunctions} Cloud Function(s) were already running this exact code and were left alone.`);
+        bullets(['microteia deploy --all', '  deploys every one of them, whatever the project already runs']);
+        blank();
+    }
     info(`Microteia ${manifest.version} is installed in ${projectId}.`);
     bullets([`https://${projectId}.web.app`]);
     blank();

package/lib/console/environment.d.ts

@@ -53,6 +53,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();
+};