@microteia/console 2.8.0 → 2.18.0

package/lib/console/provision.js

@@ -2,7 +2,7 @@ import { dirname, join, resolve } from 'node:path';
 import { hasFlag, requiredFlag, flagValue } from '../shared/args.js';
 import { run } from '../shared/run.js';
 import { blank, bullets, failure, heading, info, step, success, warn } from '../shared/ui.js';
-import { backendFingerprint, claimedIndexes, claimedParameters, functionClaimProblems, hasBackendRequirement, indexKey, } from '../kernel/backendShape.js';
+import { backendFingerprint, baselineClaimProblems, claimedIndexes, claimedParameters, functionClaimProblems, hasBackendRequirement, indexKey, sharedClaimProblems, } from '../kernel/backendShape.js';
 import { convergeIndexes, describeIndex, parseIndexState, readIndexFile, serializeIndexState, writeIndexFile, } from './backendIndexes.js';
 import { officeEnvPath, stageOfficeEnv } from './backendEnv.js';
 import { installPath, readInstalledManifest } from './unpack.js';
@@ -13,8 +13,12 @@ import { deployFunctionsOneByOne, reportFailures, reportNotices } from './deploy
 import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
 import { outdatedByStamp } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
-import { asString, asTimestamp, decodeFields, documentId, listDocuments, patchMapField } from './firestoreRest.js';
+import { asString, asTimestamp, patchMapField } from './firestoreRest.js';
+import { writeBackendResidue } from './backendResidue.js';
+import { listTenants, readInstalledExtensions } from './installedExtensions.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
+import { describeMisgated, misgatedTriggers, singleClaimants, ungatedTriggerProblems, unguardedCallableProblems, unscopedTriggerProblems, } from './functionGate.js';
+import { appliedAfterRun, classifyApplied, describeApplied, parseAppliedFunctions, serializeAppliedFunctions, } from './appliedFunctions.js';
 /**
  * O que cada escritório do projeto instalou e exige do backend.
  *
@@ -22,34 +26,38 @@ import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js
  * contra `manifest.functions` antes de qualquer deploy. Nome de function fora do pacote é recusado com
  * explicação; não há injeção possível, porque o código é sempre o do pacote.
  */
-export const readInstalledClaims = async (projectId) => {
-    const tenants = await listDocuments(projectId, '/tenants');
+export const surveyInstallations = async (projectId) => {
+    const tenants = await listTenants(projectId);
     const claims = [];
+    const installedIds = new Set();
+    let extensions = 0;
     for (const tenant of tenants) {
-        const tenantId = documentId(tenant);
-        const extensions = await listDocuments(projectId, `/tenants/${tenantId}/installed_extensions`);
-        for (const document of extensions) {
-            const data = decodeFields(document.fields);
-            if (data.active === false)
+        for (const extension of await readInstalledExtensions(projectId, tenant.id)) {
+            extensions += 1;
+            if (!extension.active)
                 continue;
-            const pkg = data.package;
-            const manifest = pkg?.manifest;
-            const backend = manifest?.backend;
+            installedIds.add(extension.id);
+            const backend = extension.manifest?.backend;
             if (!hasBackendRequirement(backend))
                 continue;
-            const state = data.backendState;
+            const state = extension.data.backendState;
             claims.push({
-                tenantId,
-                documentPath: `/tenants/${tenantId}/installed_extensions/${documentId(document)}`,
-                pluginId: String(manifest?.id ?? documentId(document)),
-                name: String(manifest?.name ?? manifest?.id ?? documentId(document)),
-                version: String(manifest?.version ?? '0.0.0'),
+                tenantId: extension.tenantId,
+                documentPath: extension.documentPath,
+                pluginId: extension.id,
+                name: extension.name,
+                version: extension.version,
                 backend: backend,
                 applied: state?.fingerprint === backendFingerprint(backend),
             });
         }
     }
-    return claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0));
+    return {
+        tenants: tenants.length,
+        extensions,
+        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0)),
+        installedIds,
+    };
 };
 const uniqueByPlugin = (claims) => {
     const seen = new Set();
@@ -60,7 +68,6 @@ const uniqueByPlugin = (claims) => {
         return true;
     });
 };
-export const parseAppliedFunctions = (value) => (value ?? '').split(',').map((name) => name.trim()).filter((name) => name !== '');
 /**
  * O motor: alinha o projeto Firebase com o que as extensões instaladas exigem, e carimba nelas o
  * estado. Um motor só, chamado pelo `deploy` no fim e pelo `provision` sozinho — duas implementações
@@ -81,12 +88,26 @@ export const provisionBackend = async (options) => {
      */
     const office = await readOfficeFunctions(root);
     const deployable = [...manifest.functions, ...office.all];
-    const claims = await readInstalledClaims(projectId);
-    const problems = functionClaimProblems(claims, deployable);
+    const survey = await surveyInstallations(projectId);
+    const claims = survey.claims;
+    const missing = functionClaimProblems(claims, deployable);
+    const overlapping = baselineClaimProblems(claims, manifest.baselineFunctions ?? []);
+    // A comum do escritório tem o MESMO desfecho da function da plataforma, e por isso a mesma recusa: o
+    // `deploy` a sobe sempre, então reivindicá-la não muda nada — até o dia em que `--prune` a apaga.
+    const appropriated = sharedClaimProblems(claims, office.shared);
+    // O portão aberto para o id de OUTRA extensão. Só aqui se pode perguntar: é a reivindicação que diz de
+    // quem a function é, e ela vem do banco do escritório — o `deploy` não a tem.
+    const misgated = misgatedTriggers(office.sources, singleClaimants(claims));
+    const problems = [
+        ...missing,
+        ...overlapping,
+        ...appropriated,
+        ...misgated.map(describeMisgated),
+    ];
     const rejected = new Set();
-    if (problems.length > 0) {
+    if (missing.length > 0) {
         warn('some extensions ask for backend artifacts that are nowhere to be found:');
-        bullets(problems);
+        bullets(missing);
         // A mensagem sozinha é um beco sem saída: ela diz que o nome não existe, e não onde ele deveria
         // existir. As duas respostas possíveis são estas, e a segunda é a que mais acontece — a function é
         // da extensão, o autor a declarou, e ninguém a exportou do `index.ts` do diretório dela.
@@ -97,18 +118,92 @@ export const provisionBackend = async (options) => {
         ]);
         info(`  this installation currently exports ${office.all.length} function(s) of its own`
             + `${office.all.length === 0 ? '' : `: ${office.all.join(', ')}`}`);
+    }
+    if (overlapping.length > 0) {
+        warn('some extensions claim a function that belongs to the platform itself:');
+        bullets(overlapping);
+        info('  every "microteia deploy" puts those up, extension or no extension, so claiming one changes');
+        info('  nothing while it is installed — and takes a working trigger out of this project the day it');
+        info('  is uninstalled. Rename the extension\'s own function, or drop the name from its');
+        info('  manifest.backend.functions.');
+    }
+    if (appropriated.length > 0) {
+        warn('some extensions claim a function that is shared by this whole installation:');
+        bullets(appropriated);
+        info('  functions/ next to microteia.yaml is the place for a function that serves SEVERAL');
+        info('  extensions, so it has no owner and every "microteia deploy" puts it up. Claiming one changes');
+        info('  nothing while the extension is installed — and the day it is uninstalled the function turns');
+        info('  into an orphan, --prune deletes it, and the next deploy puts it back. Whoever else depended');
+        info('  on it loses their backend in a window nothing explains. Move the function into');
+        info('  extensions/<folder>/functions/ if it is really this extension\'s, drop the name from its');
+        info('  manifest.backend.functions, or — if several extensions need it — name them in "microteia" ->');
+        info('  "serves" in functions/package.json, which is how a shared function gets withdrawn.');
+    }
+    /**
+     * O gatilho sem portão é RELATADO aqui e RECUSADO na montagem (`functionProblems`), e a assimetria é
+     * deliberada: este é o único comando capaz de RETIRAR uma function do projeto. Recusar aqui trancaria
+     * `--prune` — o comando que apaga a órfã — por causa de uma fonte que ele não precisa ler. A recusa
+     * acontece onde a fonte de fato entra no pacote, e aí ela não tranca a saída de ninguém.
+     */
+    const ungated = [
+        ...ungatedTriggerProblems(office.sources),
+        ...unscopedTriggerProblems(office.sources),
+        ...unguardedCallableProblems(office.sources),
+    ];
+    if (ungated.length > 0) {
+        warn(`${ungated.length} function(s) written in this installation act outside any office's`
+            + ' installation:');
+        bullets(ungated);
+        info('  they are refused the moment something tries to deploy them. Until then they keep acting on');
+        info('  every office in this project.');
+    }
+    /**
+     * A comum SEM declaração de quem serve. Ela continua subindo no `deploy`, sempre, e nada a retira — é
+     * o comportamento anterior, mantido para não quebrar instalação nenhuma.
+     *
+     * O que muda é que ele deixa de ser invisível. Era esse o defeito: quem herdasse a instalação não tinha
+     * como saber que aquelas functions estavam fora do mecanismo de retirada, e a única forma de descobrir
+     * era um gatilho disparando anos depois de a última extensão que o usava ter saído.
+     */
+    if (office.unserved.length > 0) {
+        blank();
+        info(`  ${office.unserved.length} shared function(s) do not say which extensions they serve:`);
+        bullets(office.unserved);
+        info('  they go up with every "microteia deploy" and nothing here withdraws them — not even --prune.');
+        info('  Name the extensions each one exists for in "microteia" -> "serves" in functions/package.json,');
+        info('  and they are deployed only while one of those is installed, and removed when none is.');
+    }
+    if (misgated.length > 0) {
+        warn('some extensions gate a trigger for an extension id that is not their own:');
+        bullets(misgated.map(describeMisgated));
+        info('  it is what a copied function leaves behind. The trigger deploys, fires on every write, and');
+        info('  the handler never runs — the gate asks about an extension nobody installed. Fix the id in');
+        info('  the forInstalledExtension call.');
+    }
+    if (problems.length > 0) {
         for (const claim of claims) {
             if (problems.some((problem) => problem.includes(claim.pluginId)))
                 rejected.add(claim.pluginId);
         }
+        // O dono de um portão errado é pendurado por IDENTIDADE, e não por o id dele aparecer no texto: a
+        // mensagem cita DOIS ids, e casar por substring penduraria também a extensão cujo id foi copiado.
+        for (const entry of misgated)
+            rejected.add(entry.owner);
     }
     const valid = uniqueByPlugin(claims.filter((claim) => !rejected.has(claim.pluginId)));
     /**
-     * Os índices são resolvidos ANTES do desvio de "nenhuma extensão exige nada" — e não depois, onde
-     * estavam. Desinstalar a única extensão com backend caía justamente naquele desvio, então o índice
-     * dela não era relatado por ninguém: o aviso existia para o caso de sobrar um órfão entre outras
-     * extensões, e faltava no caso de sobrar sozinho.
+     * O nome que uma reivindicação RECUSADA carrega. Ele não entra em `wantedFunctions` — não há como
+     * deployá-lo —, mas também não pode virar órfão: a extensão que o pede continua instalada, e o que
+     * falhou foi resolver a declaração dela. Sem esta lista, um export renomeado em
+     * `extensions/<x>/functions/index.ts` fazia `--prune` apagar a function de uma extensão viva.
      */
+    const unresolved = new Map();
+    for (const claim of claims) {
+        if (!rejected.has(claim.pluginId))
+            continue;
+        for (const name of claim.backend.functions ?? [])
+            unresolved.set(name, claim.pluginId);
+    }
     if (valid.length === 0) {
         info('  no installed extension asks for backend artifacts');
     }
@@ -117,14 +212,60 @@ export const provisionBackend = async (options) => {
         bullets(valid.map((claim) => `${claim.name} ${claim.version} (${claim.pluginId})`));
     }
     const settled = await settleIndexes(options, valid);
-    if (valid.length === 0) {
-        await recordBackendState(options, parseAppliedFunctions(options.environment.backend.functions), parseParameterState(options.environment.backend.parameters), settled.declared);
-        reportOrphanIndexes(projectId, settled.orphans, options.prune);
-        return outcome;
+    /**
+     * NÃO existe mais um desvio de "nenhuma extensão exige nada" aqui — e é a correção do defeito que
+     * este comando tinha justamente no caso mais comum. Desinstalar a ÚLTIMA extensão com backend caía
+     * naquele desvio, e o desvio devolvia antes do cálculo de órfã: a Cloud Function dela continuava no
+     * ar para sempre, `--prune` não a alcançava, e a lista de aplicadas era regravada intacta. O sintoma
+     * era um gatilho `onDocumentWritten` de uma extensão que ninguém tem mais, disparando sobre os dados
+     * do escritório a cada gravação.
+     *
+     * O índice já havia sido salvo dessa mesma armadilha — foi por isso que `settleIndexes` subiu para
+     * antes do desvio. A function ficou para trás, e a lição é que o desvio é que estava errado: o que
+     * ele pulava não era "trabalho inútil", era a retirada.
+     *
+     * O que sobrou dele são duas guardas pontuais mais abaixo: não perguntar ao projeto o que ele roda
+     * quando não há nada a conferir, e não anunciar que "as 0 functions já estão deployadas".
+     */
+    /**
+     * A function COMUM que declara quem serve entra aqui, e é o que a tira da invisibilidade.
+     *
+     * Ela não tem dono que possa reivindicá-la — nenhuma extensão pode —, então ela ficava fora do
+     * mecanismo por inteiro: nunca entrava no registro de aplicadas, nunca virava órfã, nunca era
+     * relatada, e o `--prune` não a alcançava. Com a declaração, a pergunta passa a ter resposta: ela é
+     * devida enquanto ALGUMA das extensões que ela serve estiver instalada em algum escritório do projeto.
+     *
+     * "Basta uma" é a única regra possível: a function existe porque mais de uma extensão precisa dela.
+     * Exigir todas faria desinstalar uma desligar o backend das outras.
+     */
+    const sharedWanted = office.served.filter((entry) => entry.serves.some((id) => survey.installedIds.has(id)));
+    const sharedWantedNames = new Set(sharedWanted.map((entry) => entry.name));
+    const wantedFunctions = deployable.filter((name) => sharedWantedNames.has(name)
+        || valid.some((claim) => (claim.backend.functions ?? []).includes(name)));
+    /** Quem reivindica cada nome AGORA — é com este dono que o registro é reconciliado. */
+    const owners = new Map();
+    for (const claim of valid) {
+        for (const name of claim.backend.functions ?? [])
+            owners.set(name, claim.pluginId);
     }
-    const wantedFunctions = deployable.filter((name) => valid.some((claim) => (claim.backend.functions ?? []).includes(name)));
-    const alreadyApplied = parseAppliedFunctions(options.environment.backend.functions);
-    const trackedParameters = claimedParameters(valid);
+    // A comum tem VÁRIOS donos, e o registro guarda a lista declarada em vez de eleger um deles: é ela que
+    // explica, meses depois, por que aquela function estava ali — e por que ela deixou de estar.
+    for (const entry of sharedWanted)
+        owners.set(entry.name, entry.serves.join('+'));
+    const applied = parseAppliedFunctions(options.environment.backend.functions);
+    const appliedNames = new Set(applied.map((entry) => entry.name));
+    const classification = classifyApplied({
+        applied,
+        wanted: wantedFunctions,
+        baseline: manifest.baselineFunctions ?? [],
+        unresolved,
+    });
+    // Os do diretório comum entram: são eles que as functions comuns servidas carregam, e um parâmetro
+    // que ninguém acompanha é um valor que nunca chega à function que o lê.
+    const trackedParameters = [...new Set([
+            ...claimedParameters(valid),
+            ...(office.sources.find((source) => source.shared)?.parameters ?? []).map((p) => p.name),
+        ])].sort();
     // A raiz, e não o `install/`: a fonte é o arquivo que o escritório edita ao lado do `microteia.yaml`.
     const filledParameters = await readBackendEnv(dirname(options.environmentFile), projectId);
     const recordedDigests = parseParameterState(options.environment.backend.parameters);
@@ -141,13 +282,46 @@ export const provisionBackend = async (options) => {
     // instalação fica sem nenhum comando que o aplique, e a feature falha no runtime.
     const changed = changedParameters(recordedDigests, currentDigests, trackedParameters);
     const staleFunctions = new Set(functionsDeclaringParameters(valid, changed)
-        .filter((name) => wantedFunctions.includes(name) && alreadyApplied.includes(name)));
-    // Uma pergunta só ao projeto, e duas decisões a partir dela: o que ele já roda, e qual cópia ficou
-    // numa região abandonada.
-    const deployedFunctions = await listDeployedFunctions(projectId);
+        .filter((name) => wantedFunctions.includes(name) && appliedNames.has(name)));
+    /**
+     * A comum que agora sobe pelo provisionamento também precisa voltar à fila quando um parâmetro muda.
+     * Antes ela subia a cada `deploy`, e isso mascarava a pergunta.
+     *
+     * A granularidade é o DIRETÓRIO, e não a function: `functions/` declara os `defineString` num conjunto
+     * só, sem dizer qual function lê qual. Redeployar todas as comuns servidas quando um parâmetro do
+     * diretório muda erra para o lado de fazer o que é devido — o inverso deixaria uma delas rodando com o
+     * valor antigo, que é o defeito que este mecanismo existe para fechar.
+     */
+    const sharedSource = office.sources.find((source) => source.shared);
+    const sharedParameters = new Set((sharedSource?.parameters ?? []).map((parameter) => parameter.name));
+    if (changed.some((name) => sharedParameters.has(name))) {
+        for (const entry of sharedWanted) {
+            if (appliedNames.has(entry.name))
+                staleFunctions.add(entry.name);
+        }
+    }
+    /**
+     * Uma pergunta só ao projeto, e duas decisões a partir dela: o que ele já roda, e qual cópia ficou
+     * numa região abandonada. 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.
+     *
+     * E ela é feita só quando há o que decidir. Sem o desvio lá em cima, este caminho passou a ser
+     * percorrido também pelo `provision` que roda quando não sobrou extensão nenhuma — e ali não há
+     * function para conferir nem para subir, então um `functions:list` seria pagar segundos por uma
+     * resposta que ninguém lê.
+     */
+    let asked;
+    const projectFunctions = async () => {
+        if (asked === undefined)
+            asked = await listDeployedFunctions(projectId);
+        return asked;
+    };
     // O que a lista de nomes nunca respondeu: a function aplicada que sumiu do projeto, e a que segue
     // lá carregando o carimbo de um código anterior. As duas voltam para a fila.
-    const outdated = outdatedByStamp(wantedFunctions.filter((name) => alreadyApplied.includes(name)), deployedFunctions, region, options.refreshedStamps);
+    const appliedAndWanted = wantedFunctions.filter((name) => appliedNames.has(name));
+    const outdated = appliedAndWanted.length === 0
+        ? { absent: [], stale: [] }
+        : outdatedByStamp(appliedAndWanted, await projectFunctions(), region, options.refreshedStamps);
     for (const name of [...outdated.absent, ...outdated.stale])
         staleFunctions.add(name);
     if (outdated.absent.length > 0) {
@@ -184,9 +358,13 @@ export const provisionBackend = async (options) => {
         info('  Cloud Function at ITS deploy, so a function already running keeps the previous one.');
         blank();
     }
-    const toDeploy = wantedFunctions.filter((name) => options.all === true || !alreadyApplied.includes(name) || staleFunctions.has(name));
+    const toDeploy = wantedFunctions.filter((name) => options.all === true || !appliedNames.has(name) || staleFunctions.has(name));
     if (toDeploy.length === 0) {
-        success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
+        // Anunciar "as 0 functions já estão deployadas" seria o preço de ter tirado o desvio, e não é
+        // preciso pagá-lo: quando não há exigência nenhuma, quem já falou foi a linha lá em cima.
+        if (wantedFunctions.length > 0) {
+            success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
+        }
     }
     else {
         // A cópia que o `firebase-functions` lê é atualizada AGORA, e não só no `deploy`: este comando é o
@@ -203,7 +381,7 @@ export const provisionBackend = async (options) => {
         }
         // A extensão que mudou de região deixa a cópia antiga para trás igual ao kernel, e ali o efeito
         // é o mesmo: deploy recusado em toda tentativa, e gatilho disparando em duas regiões.
-        await clearRegionOrphans(projectId, toDeploy, region, options.prune, deployedFunctions);
+        await clearRegionOrphans(projectId, toDeploy, region, options.prune, await projectFunctions());
         info(`  deploying ${toDeploy.length} function(s), one at a time…`);
         const report = await deployFunctionsOneByOne(toDeploy, {
             projectId, cwd: install, delaySeconds, force: false,
@@ -214,7 +392,7 @@ export const provisionBackend = async (options) => {
         reportNotices(report.notices);
         await checkNewCallables([...(manifest.callables ?? []), ...office.callables], report.deployed, projectId, region);
     }
-    const deployedNow = new Set([...alreadyApplied, ...outcome.deployed]);
+    const deployedNow = new Set([...appliedNames, ...outcome.deployed]);
     for (const claim of valid) {
         const satisfied = (claim.backend.functions ?? []).every((name) => deployedNow.has(name));
         if (satisfied) {
@@ -224,14 +402,16 @@ export const provisionBackend = async (options) => {
             outcome.pending.push(claim);
         }
     }
-    const orphans = alreadyApplied.filter((name) => !wantedFunctions.includes(name));
-    outcome.orphans = orphans;
-    const remaining = await settleOrphans(options, orphans);
+    reportPreserved(classification.preserved);
+    outcome.orphans = classification.orphans.map((entry) => entry.name);
+    const remaining = await settleOrphans(options, classification.orphans, survey);
     await recordBackendState(options, appliedAfterRun({
-        alreadyApplied,
+        applied,
         wanted: wantedFunctions,
         deployed: outcome.deployed,
         keptOrphans: remaining,
+        preserved: classification.preserved.map((item) => item.entry),
+        owners,
     }), appliedParameterState({
         recorded: recordedDigests,
         current: currentDigests,
@@ -240,8 +420,37 @@ export const provisionBackend = async (options) => {
         claims: valid,
     }), settled.declared);
     reportOrphanIndexes(projectId, settled.orphans, options.prune);
+    await publishResidue(projectId, remaining, settled.orphans, survey);
     return outcome;
 };
+/**
+ * O que sobrou, devolvido ao banco para a aplicação poder mostrá-lo.
+ *
+ * A lista é a que sobra DEPOIS do `--prune`: o que ele apagou saiu, e o que ele não conseguiu apagar
+ * fica — é o estado do projeto agora, e não o do começo da execução.
+ *
+ * Falhar aqui não derruba o comando, e a exceção é justificada: as functions e os índices já foram
+ * aplicados, e o que ficou de fazer era um RELATO. Recusar o `provision` inteiro por causa dele mandaria
+ * quem instala rodar de novo um comando que já terminou o trabalho. Mas o aviso é dito em voz alta —
+ * calar deixaria a tela silenciosa parecendo "não há resíduo", que é a afirmação oposta.
+ */
+const publishResidue = async (projectId, functions, indexes, survey) => {
+    try {
+        await writeBackendResidue(projectId, {
+            scannedAt: new Date(),
+            tenants: survey.tenants,
+            extensions: survey.extensions,
+            functions: functions.map((entry) => ({ name: entry.name, owner: entry.owner ?? '' })),
+            indexes: indexes.map(describeIndex),
+        });
+    }
+    catch (error) {
+        warn('could not record what is left over where the application can show it:');
+        info(`  ${error instanceof Error ? error.message : String(error)}`);
+        info('  the artifacts above were applied. What did not happen is the Extensions screen learning');
+        info('  about the leftovers — it keeps showing what the previous run recorded.');
+    }
+};
 /**
  * O que o projeto tem de declarar de índice composto, e o que sobrou de uma extensão que saiu.
  *
@@ -324,34 +533,74 @@ const stampApplied = async (projectId, all, claim) => {
     success(`${claim.name} is ready in ${projectId}`);
 };
 /**
- * Function que nenhuma extensão instalada exige mais. Apagar é destrutivo e irreversível, então o
- * padrão RELATA e só `--prune` remove — e o que foi removido sai da lista de aplicadas.
+ * O que ninguém exige e mesmo assim NÃO é órfã.
+ *
+ * Relatar é o ponto. As duas causas são configuração errada de um lado ou do outro, e o silêncio sobre
+ * elas faria a próxima pessoa a abrir o `microteia.yaml` concluir que a lista está suja — e apagar à
+ * mão exatamente o que estas linhas protegem.
+ */
+const reportPreserved = (preserved) => {
+    const baseline = preserved.filter((item) => item.reason === 'baseline');
+    const unresolved = preserved.filter((item) => item.reason === 'unresolved');
+    if (baseline.length > 0) {
+        blank();
+        warn(`${baseline.length} function(s) in this installation's record belong to the platform:`);
+        bullets(baseline.map((item) => describeApplied(item.entry)));
+        info('  every "microteia deploy" puts them up, extension or no extension, so nothing here removes');
+        info('  them — not even --prune.');
+    }
+    if (unresolved.length > 0) {
+        blank();
+        warn(`${unresolved.length} function(s) belong to an extension whose declaration did not resolve:`);
+        bullets(unresolved.map((item) => `${item.entry.name} — claimed by ${item.claimant}`));
+        info('  the extension is still installed, so they are not orphans and nothing removes them.');
+        info('  Fix what is reported above and run "microteia provision" again.');
+    }
+};
+/**
+ * Function que nenhuma extensão instalada exige mais.
+ *
+ * A CERTEZA vem antes da remoção, e é dita em voz alta: a Cloud Function é do PROJETO e a instalação é
+ * do ESCRITÓRIO, então "ninguém mais exige" é uma afirmação sobre TODOS os escritórios do projeto, e
+ * não sobre o último que foi lido. A varredura é completa ou não existe — `listDocuments` pagina até o
+ * fim e qualquer leitura recusada derruba o comando lá em cima —, e é o número dito aqui que permite a
+ * quem lê conferir a afirmação em vez de acreditar nela.
+ *
+ * Apagar é destrutivo e irreversível, então o padrão RELATA e só `--prune` remove — e o que foi
+ * removido sai da lista de aplicadas.
  */
-const settleOrphans = async (options, orphans) => {
+const settleOrphans = async (options, orphans, survey) => {
     if (orphans.length === 0)
         return [];
     blank();
+    warn(`${orphans.length} function(s) are deployed and no installed extension needs them:`);
+    bullets(orphans.map(describeApplied));
+    info(`  read from every office in this project: ${survey.tenants} office(s), `
+        + `${survey.extensions} installed extension(s).`);
     if (!options.prune) {
-        warn(`${orphans.length} function(s) are deployed but no installed extension needs them:`);
-        bullets(orphans);
-        info('  they keep working and cost nothing while idle. To remove them:');
+        // O custo mudou de descrição porque a descrição estava errada. Uma callable ociosa não custa nada;
+        // um gatilho de Firestore não fica ocioso — ele segue disparando a cada gravação do escritório,
+        // rodando o código de uma extensão que ninguém tem mais, e é esse efeito que faz a remoção valer
+        // a pena antes de "algum dia".
+        info('  a callable just sits there. A Firestore trigger does not: it keeps firing on every write,');
+        info('  running the code of an extension nobody has any more. To remove them:');
         bullets(['microteia provision --prune']);
         blank();
         return orphans;
     }
     info(`  deleting ${orphans.length} orphan function(s)…`);
-    const deleted = [];
-    for (const name of orphans) {
+    const deleted = new Set();
+    for (const orphan of orphans) {
         try {
-            await run(FIREBASE_BIN, ['functions:delete', name, '--project', options.projectId, '--region', options.region, '--force'], { cwd: options.install });
-            deleted.push(name);
+            await run(FIREBASE_BIN, ['functions:delete', orphan.name, '--project', options.projectId, '--region', options.region, '--force'], { cwd: options.install });
+            deleted.add(orphan.name);
         }
         catch {
-            warn(`could not delete ${name}; it stays recorded as deployed`);
+            warn(`could not delete ${orphan.name}; it stays recorded as deployed`);
         }
     }
-    success(`${deleted.length} orphan function(s) removed`);
-    return orphans.filter((name) => !deleted.includes(name));
+    success(`${deleted.size} orphan function(s) removed`);
+    return orphans.filter((orphan) => !deleted.has(orphan.name));
 };
 /**
  * Índice órfão é RELATADO, nunca apagado às cegas: o `firebase deploy` não remove índice por conta, e a
@@ -384,16 +633,6 @@ const reportOrphanIndexes = (projectId, orphans, prune) => {
     ]);
     blank();
 };
-/**
- * A lista aplicada CONVERGE para o que ainda é exigido: o que já estava e continua sendo pedido, mais
- * o que subiu agora, mais o órfão que não foi removido. Reescrevê-la só com o que subiu NESTA execução
- * a esvaziava na segunda passada — e a terceira redeployava tudo, achando que nada havia sido feito.
- */
-export const appliedAfterRun = (input) => [...new Set([
-        ...input.alreadyApplied.filter((name) => input.wanted.includes(name)),
-        ...input.deployed,
-        ...input.keptOrphans,
-    ])].sort();
 /**
  * A impressão digital do parâmetro só avança quando TODAS as functions que o carregam subiram. Gravar
  * antes disso é o que transformaria uma falha de deploy em silêncio permanente: o valor novo ficaria
@@ -418,7 +657,7 @@ export const appliedParameterState = (input) => {
     }
     return next;
 };
-const recordBackendState = async (options, names, parameters, indexes) => {
+const recordBackendState = async (options, applied, parameters, indexes) => {
     const state = serializeIndexState(indexes);
     /**
      * Índice que a codificação não representa sem ambiguidade fica de fora COM AVISO, em vez de voltar do
@@ -435,7 +674,7 @@ const recordBackendState = async (options, names, parameters, indexes) => {
     await writeEnvironment(options.environmentFile, {
         ...options.environment,
         backend: {
-            functions: names.length === 0 ? null : names.join(','),
+            functions: serializeAppliedFunctions(applied),
             parameters: serializeParameterState(parameters),
             indexes: state.value,
         },

package/lib/index.js

@@ -10,6 +10,7 @@ import { connect } from './console/connect.js';
 import { unpack } from './console/unpack.js';
 import { deploy } from './console/deploy.js';
 import { provision } from './console/provision.js';
+import { exportCatalog } from './console/exportCatalog.js';
 import { pluginInit } from './console/pluginWorkspace.js';
 import { versionReport } from './console/versions.js';
 import { newerThan } from './console/channel.js';
@@ -49,6 +50,13 @@ const COMMANDS = [
         audience: 'office',
         execute: provision,
     },
+    {
+        name: 'export-catalog',
+        usage: 'microteia export-catalog --tenant <tenantId> [--output <path>]',
+        summary: 'Write what an office has — screens, lists, extensions — for the authoring tools to read.',
+        audience: 'office',
+        execute: exportCatalog,
+    },
     {
         name: 'plugin-init',
         usage: 'microteia plugin-init [--dir <path>] [--force]',

package/lib/kernel/backendShape.d.ts

@@ -54,6 +54,33 @@ export declare const baselineIndexesOf: (rootIndexes: FirestoreIndexSpec[], clai
  * no `provision`, contra o que veio do banco do escritório, que é dado e não código.
  */
 export declare const functionClaimProblems: (claims: BackendClaim[], packagedFunctions: string[]) => string[];
+/**
+ * Reivindicar uma function que a PLATAFORMA sobe sempre.
+ *
+ * É conferência de PROVISIONAMENTO, não de empacotamento, e a assimetria é da própria definição: no
+ * `pack` a baseline é DERIVADA (`todas − reivindicadas`), então reivindicar é o que tira o nome dela e
+ * a pergunta não existe. Do lado de quem instala a baseline já está decidida e viaja no manifesto, e
+ * aí a reivindicação de um nome dela é uma contradição com duas consequências, nenhuma visível: o
+ * `deploy` sobe a function de qualquer jeito, e a desinstalação da extensão faz `--prune` apagar um
+ * gatilho do produto num escritório que não fez nada.
+ */
+export declare const baselineClaimProblems: (claims: BackendClaim[], baselineFunctions: string[]) => string[];
+/**
+ * Reivindicar uma function COMUM do escritório — a que mora em `functions/`, ao lado do
+ * `microteia.yaml`.
+ *
+ * É o mesmo defeito de reivindicar uma function da plataforma, com o mesmo par de consequências
+ * invisíveis, e por isso é conferido no mesmo lugar. A comum não tem dono por construção: ela é o lugar
+ * de quem serve várias extensões, nenhuma pode declará-la (duas reivindicando o mesmo nome é recusa), e
+ * o `deploy` a sobe SEMPRE. Reivindicá-la, então, não muda nada enquanto a extensão está instalada — e
+ * no dia em que ela sai, a function vira órfã, `--prune` a apaga, e o `deploy` seguinte a repõe. As
+ * outras extensões que dependiam dela perdem o backend numa janela que nada explica, e a fonte continua
+ * intacta em `functions/`, sem nada na árvore que sequer sugira o que aconteceu.
+ *
+ * A assimetria com o `pack` é a mesma de `baselineClaimProblems`: o pacote do kernel não sabe o que o
+ * escritório vai escrever em `functions/`, então a pergunta só existe do lado de quem instala.
+ */
+export declare const sharedClaimProblems: (claims: BackendClaim[], sharedFunctions: string[]) => string[];
 /**
  * Índice reivindicado que não existe na raiz. É conferência de EMPACOTAMENTO, não de provisionamento:
  * a raiz é o que roda em `microteia-dev` e `curatino`, então uma declaração que não esteja lá deixaria