@microteia/console 2.18.0 → 2.20.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,20 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.20.0] — 2026-09-01
+
+- feat(cli/export-catalog): the snapshot carries what each installed extension declares in `manifest.exports` — the artifacts another extension may reference as `<extension-id>/<source-id>`. Whoever authors outside the office knew an extension was installed and had no way to learn the name of anything inside it, so the reference could be written by hand and never discovered. Each entry carries the id, the artifact's name, and its `kind`, which is the part that decides where the reference fits: a script goes in `scriptId`, an automation in `targetWorkflowId`. What the artifact DOES still never travels — the steps and the code are behaviour, and the snapshot is shape.
+- feat(cli/export-catalog): a declared export that matches no artifact in the package travels as `unknown` rather than being dropped. The install gate checks the LIST, so a reference to it would be accepted there and fail only on the step's first run; saying it is better than hiding it.
+- feat(cli/export-catalog): `exports` is written for every extension, empty list included. A present-and-empty list is the answer "this extension exports nothing"; an absent key is the silence of a Console older than the field, and the kernel tells the two apart instead of reading absence as a claim.
+
+#### [2.19.0] — 2026-08-28
+
+- fix(cli/deploy): the installation gate is charged against the functions that are GOING UP, not against every source found on disk. It lived in `functionProblems` — the door that answers "can this set be assembled?" — and that door reads every `extensions/<x>/functions/` directory that exists, including one left behind by an extension that was uninstalled and removed. The result was `microteia deploy` refusing in full — hosting, rules and indexes with it — over a callable no command would have deployed. `gateProblems` now carries the function's name, and `gateProblemsFor` filters by what is being deployed.
+- fix(cli/provision): a gated function that fails the check leaves the deploy queue instead of taking the command down with it. Everything else provisions, `--prune` still removes the orphan, and the command ends in an error naming the function that was held back.
+- feat(cli/provision): orphan functions are found in the PROJECT, not only in the record. `backend.functions` in `microteia.yaml` was the single source of truth about what had been deployed, and it is a truth that gets lost — a redone `init`, a restored backup, a Console older than the field. Lost it, and the Cloud Function of an extension nobody has stayed in the air with no command mentioning it. `straysInProject` crosses `firebase functions:list` with what the installation can justify; only a name this installation knows how to produce can become an orphan, and what it does not know is reported and never touched.
+- feat(cli/provision): an orphan found that way enters the record when it is not removed, so it stays known from the next run on even if its source leaves the disk.
+- fix(cli/provision): `functions:list` is asked on every run. It was skipped when there was nothing applied to check — the exact case that needed it, since an installation with no extensions left is where the departed extension's function sits. When the listing cannot be read, the command says so instead of letting silence read as "nothing left over".
+
 #### [2.18.0] — 2026-08-28
 
 - feat(console/functionGate): an extension's callable without `requireInstalledExtension` is refused, and a guard naming another extension's id is rejected the way a misgated trigger is. The refusal exists because the deploy makes every callable publicly invocable — this Console's own `callableAccess.ts` is there to confirm that grant went through — so the callable answers any signed-in user of the project, from any organization, whether or not they installed the extension, with the organization arriving in the payload.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.18.0
+# Microteia Console 2.20.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/appliedFunctions.d.ts

@@ -77,3 +77,38 @@ export declare const appliedAfterRun: (input: {
 }) => AppliedFunction[];
 /** Como uma function aplicada aparece num relatório: sem dono conhecido, só o nome. */
 export declare const describeApplied: (entry: AppliedFunction) => string;
+export interface StrayFunctions {
+    /** Roda no projeto, esta instalação sabe produzi-la, e nada a justifica agora: órfã de verdade. */
+    orphans: AppliedFunction[];
+    /** Roda no projeto e esta instalação não a conhece. Relatada, nunca apagada. */
+    strangers: string[];
+}
+/**
+ * A órfã que o REGISTRO não conhece — e o limite que impede a varredura de virar um estrago.
+ *
+ * O registro (`backend.functions` do `microteia.yaml`) era a ÚNICA verdade sobre o que havia sido
+ * deployado, e é uma verdade que se perde: um Console anterior ao campo, um `init` refeito, um deploy
+ * dado à mão, um arquivo restaurado de um backup mais velho. Perdido o registro, `classifyApplied` não
+ * tinha o que classificar, `--prune` não tinha o que apagar, e a Cloud Function de uma extensão que
+ * ninguém tem mais ficava no ar para sempre, sem nenhum comando que a mencionasse. É o pior sintoma da
+ * família: uma callable publicamente invocável, de código que ninguém instalou, e silêncio.
+ *
+ * A resposta é perguntar ao PROJETO o que ele roda, em vez de só ao arquivo. E o limite é `known`: só é
+ * candidata a órfã a function que ESTA instalação sabe produzir — o que o pacote traz mais o que o
+ * escritório escreveu. O que o projeto roda e a instalação não conhece pode ser de qualquer um: um
+ * projeto Firebase é compartilhável, e apagar ali seria a Microteia decidir sobre o que não é dela.
+ * Esse caso é relatado e nunca tocado.
+ *
+ * `recorded` sai do resultado porque quem responde por ele é `classifyApplied`, que sabe mais: ele tem o
+ * dono e as duas razões de preservação. Contar duas vezes a mesma function proporia apagá-la duas vezes.
+ */
+export declare const straysInProject: (input: {
+    /** O que o projeto roda AGORA, na região do kernel. */
+    running: string[];
+    /** O que esta instalação sabe produzir: o pacote mais o que o escritório escreveu. */
+    known: string[];
+    /** O que tem razão de estar no ar agora: exigida, baseline, comum sem declaração, ou não resolvida. */
+    justified: string[];
+    /** O que o registro já conhece — respondido por `classifyApplied`. */
+    recorded: string[];
+}) => StrayFunctions;

package/lib/console/appliedFunctions.js

@@ -86,3 +86,38 @@ export const appliedAfterRun = (input) => {
 };
 /** Como uma function aplicada aparece num relatório: sem dono conhecido, só o nome. */
 export const describeApplied = (entry) => entry.owner === null ? entry.name : `${entry.name} (${entry.owner})`;
+/**
+ * A órfã que o REGISTRO não conhece — e o limite que impede a varredura de virar um estrago.
+ *
+ * O registro (`backend.functions` do `microteia.yaml`) era a ÚNICA verdade sobre o que havia sido
+ * deployado, e é uma verdade que se perde: um Console anterior ao campo, um `init` refeito, um deploy
+ * dado à mão, um arquivo restaurado de um backup mais velho. Perdido o registro, `classifyApplied` não
+ * tinha o que classificar, `--prune` não tinha o que apagar, e a Cloud Function de uma extensão que
+ * ninguém tem mais ficava no ar para sempre, sem nenhum comando que a mencionasse. É o pior sintoma da
+ * família: uma callable publicamente invocável, de código que ninguém instalou, e silêncio.
+ *
+ * A resposta é perguntar ao PROJETO o que ele roda, em vez de só ao arquivo. E o limite é `known`: só é
+ * candidata a órfã a function que ESTA instalação sabe produzir — o que o pacote traz mais o que o
+ * escritório escreveu. O que o projeto roda e a instalação não conhece pode ser de qualquer um: um
+ * projeto Firebase é compartilhável, e apagar ali seria a Microteia decidir sobre o que não é dela.
+ * Esse caso é relatado e nunca tocado.
+ *
+ * `recorded` sai do resultado porque quem responde por ele é `classifyApplied`, que sabe mais: ele tem o
+ * dono e as duas razões de preservação. Contar duas vezes a mesma function proporia apagá-la duas vezes.
+ */
+export const straysInProject = (input) => {
+    const known = new Set(input.known);
+    const justified = new Set(input.justified);
+    const recorded = new Set(input.recorded);
+    const stray = { orphans: [], strangers: [] };
+    for (const name of [...new Set(input.running)].sort()) {
+        if (!known.has(name)) {
+            stray.strangers.push(name);
+            continue;
+        }
+        if (justified.has(name) || recorded.has(name))
+            continue;
+        stray.orphans.push({ name, owner: null });
+    }
+    return stray;
+};

package/lib/console/customFunctions.js

@@ -1,7 +1,7 @@
 import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { callableFunctionNames, declaredParametersIn } from '../kernel/manifest.js';
-import { callableDeclarations, triggerDeclarations, ungatedTriggerProblems, unguardedCallableProblems, unguardedSharedProblems, unscopedDeclarations, unscopedTriggerProblems, } from './functionGate.js';
+import { callableDeclarations, triggerDeclarations, unscopedDeclarations, } from './functionGate.js';
 /**
  * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
  *
@@ -273,12 +273,11 @@ export const functionProblems = (sources, kernelFunctions) => {
         }
     }
     problems.push(...servesProblems(sources));
-    // O portão de instalação entra aqui, e não numa verificação à parte, porque o momento é o mesmo: é
-    // este o ponto em que a fonte do escritório passa a fazer parte do pacote que vai subir.
-    problems.push(...ungatedTriggerProblems(sources));
-    problems.push(...unscopedTriggerProblems(sources));
-    problems.push(...unguardedSharedProblems(sources));
-    problems.push(...unguardedCallableProblems(sources));
+    // O portão de instalação NÃO entra aqui. Esta porta responde "dá para montar o conjunto?", e a
+    // resposta dela vale para toda fonte que existe no disco — inclusive a da extensão que foi
+    // desinstalada e cujo diretório ficou. O portão responde outra coisa: "esta function pode ir para o
+    // ar?", e ela só é devida de quem vai. Quem pergunta é `gateProblemsFor`, no ponto em que os nomes
+    // que sobem já estão decididos: `deploy` contra a baseline mais as comuns, `provision` contra a fila.
     return problems;
 };
 const barrel = (sources) => `// Generated by "microteia deploy". Do not edit.

package/lib/console/deploy.js

@@ -7,6 +7,7 @@ import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environme
 import { FIREBASE_BIN } from './firebaseCli.js';
 import { reportFailures, reportNotices } from './deployFunctions.js';
 import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
+import { gateProblemsFor } from './functionGate.js';
 import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
 import { checkHostingServed, htmlIsRevalidated } from './hostingCheck.js';
@@ -138,6 +139,19 @@ export const deploy = async (args) => {
              * impede esta versão de tirar do ar function de uma instalação que já existe.
              */
             const own = [...baseline, ...gathered.unserved];
+            /**
+             * O portão de instalação, cobrado do que ESTE passo sobe — e não de toda fonte que existe no
+             * disco.
+             *
+             * Na prática ele quase nunca tem o que dizer aqui, e isso é a confirmação de que o lugar é este:
+             * o que sobe no `deploy` é a baseline (do kernel) e a comum sem declaração (de quem não há id a
+             * cobrar). É no `provision` que a function de extensão entra na fila, e é lá que a recusa morde.
+             * Cobrar aqui mantém a regra atada ao ato — se um dia esta lista crescer, ela vem coberta.
+             */
+            const refused = gateProblemsFor(gathered.sources, own);
+            if (refused.length > 0) {
+                throw new Error(`These Cloud Functions cannot go up as they are:\n${refused.map((line) => `  ${line}`).join('\n')}`);
+            }
             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 `

package/lib/console/exportCatalog.d.ts

@@ -76,11 +76,33 @@ export interface CatalogListExport {
     label: string;
     ownerPluginId?: string;
 }
+/**
+ * Um artefato que a extensão declara em `manifest.exports` — a superfície que outra extensão pode
+ * referenciar como `<pluginId>/<sourceId>`.
+ *
+ * O `kind` viaja porque é ele que decide ONDE a referência cabe: script em `scriptId`, automação em
+ * `targetWorkflowId`. `unknown` é o export declarado que não casa com artefato nenhum do pacote —
+ * dizê-lo é melhor que omiti-lo, porque uma referência a ele passaria no portão da instalação, que
+ * confere a LISTA, e falharia só na primeira execução.
+ *
+ * O que NÃO viaja é o que o artefato faz: os passos e o código são comportamento, e o retrato é
+ * esquema. O nome e o tipo são contrato.
+ */
+export interface CatalogExtensionExportedArtifact {
+    id: string;
+    kind: 'workflow' | 'action' | 'script' | 'unknown';
+    name: string;
+}
 export interface CatalogExtensionExport {
     id: string;
     name: string;
     version: string;
     active: boolean;
+    /**
+     * Sempre escrita, mesmo vazia. É a lista PRESENTE e vazia que diz "esta extensão não exporta nada";
+     * a chave ausente é o silêncio de um Console anterior a este campo, e o kernel distingue as duas.
+     */
+    exports: CatalogExtensionExportedArtifact[];
 }
 export interface CatalogExport {
     version: number;

package/lib/console/exportCatalog.js

@@ -46,6 +46,38 @@ const asRecord = (value) => (typeof value === 'object' && value !== null && !Arr
     ? value
     : undefined);
 const FIELD_ORIGINS = ['builtin', 'plugin', 'design'];
+/**
+ * A superfície exportada de uma cópia instalada: os ids de `manifest.exports`, cada um casado com o
+ * artefato do pacote que o atende, para ganhar tipo e nome.
+ *
+ * O Console não alcança `src/` — logo não há `MarketplacePlugin` tipado aqui, e a leitura é do
+ * documento cru, como todo o resto deste arquivo. Um export que não casa com nada continua na lista
+ * como `unknown`: a extensão está declarando algo que não entrega, e esconder isso do autor apenas
+ * adia a descoberta para a primeira execução.
+ */
+const exportedArtifacts = (extension) => {
+    const declared = extension.manifest?.exports;
+    if (!Array.isArray(declared))
+        return [];
+    const pkg = asRecord(extension.data.package) ?? {};
+    const named = new Map();
+    const collect = (raw, kind) => {
+        for (const one of Array.isArray(raw) ? raw : []) {
+            const record = asRecord(one);
+            const id = text(record?.templateId);
+            if (id === undefined || named.has(id))
+                continue;
+            named.set(id, { id, kind, name: text(record?.name) ?? text(record?.title) ?? id });
+        }
+    };
+    collect(pkg.workflows, 'workflow');
+    collect(pkg.actions, 'action');
+    collect(pkg.scripts, 'script');
+    return declared
+        .filter((id) => typeof id === 'string' && id !== '')
+        .map((id) => named.get(id) ?? { id, kind: 'unknown', name: id })
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+};
 /**
  * A mesma dedução que a aplicação faz ao ler a tela (`screenDefinitionMapper.ts`): o `origin` gravado
  * quando ele existe, senão `plugin` para quem tem dono e `design` para o que o escritório criou. Ela é
@@ -135,7 +167,13 @@ export const buildCatalogExport = (input) => ({
     kernelVersion: input.kernelVersion,
     consoleVersion: CLI_VERSION,
     extensions: input.extensions
-        .map((one) => ({ id: one.id, name: one.name, version: one.version, active: one.active }))
+        .map((one) => ({
+        id: one.id,
+        name: one.name,
+        version: one.version,
+        active: one.active,
+        exports: exportedArtifacts(one),
+    }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
     screens: input.screens
         .filter((document) => document.data.enabled !== false)
@@ -252,13 +290,16 @@ export const exportCatalog = async (args) => {
         + `${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.`);
+    const exported = document.extensions.reduce((total, one) => total + one.exports.length, 0);
+    info(`  ${exported} artifact(s) are declared for other extensions to reference as <extension-id>/<id>.`);
     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.');
+    info('members and permissions, what a workflow, script or action DOES, secrets and settings. It');
+    info('describes what the entities ARE, and nothing an office typed into them. What each extension');
+    info('declares in "exports" travels: that is the surface another extension may reference.');
     blank();
 };

package/lib/console/functionGate.d.ts

@@ -13,8 +13,11 @@
  * código de uma extensão que ninguém tem mais rodando sobre os dados de quem nunca a pediu, sem erro em
  * lugar nenhum.
  *
- * É recusa e não aviso pelo mesmo motivo do nome de function repetido (`functionProblems`): o defeito é
- * invisível depois de instalado, e um aviso na saída de um deploy é lido uma vez.
+ * É recusa, e não aviso, pelo mesmo motivo do nome de function repetido: o defeito é invisível depois de
+ * instalado, e um aviso na saída de um deploy é lido uma vez. Mas ela é cobrada da function que VAI
+ * SUBIR, e não de toda fonte que existe no disco — ver `gateProblemsFor`. Toda origem é lida, sempre, e
+ * o que não vai subir é relatado pelo `provision`: quem tem a fonte parada ao lado do `microteia.yaml`
+ * fica sabendo dela, sem ter o comando trancado por ela.
  *
  * A análise é por texto, no idioma dos outros leitores de fonte do Console (`callableFunctionNames`,
  * `declaredParametersIn`). Ela erra para o lado ALTO — o que ela não entende ela recusa —, e é por isso
@@ -105,6 +108,22 @@ export interface GateSubject {
     /** As callables declaradas, com o estado da guarda de cada uma. */
     callableGuards: TriggerDeclaration[];
 }
+/**
+ * Um problema de portão, e a function a que ele pertence.
+ *
+ * O nome está aqui porque é ele que decide o PESO do problema. A verificação lê toda fonte que existe no
+ * disco — é assim que ela acha o que precisa achar —, mas o que existe no disco não é o que vai subir:
+ * `extensions/<x>/functions/` de uma extensão que ninguém instalou é lida, copiada e nunca deployada.
+ * Sem o nome, quem chama só tem a frase, e a única coisa que dá para fazer com uma frase é recusar tudo.
+ * Foi o que acontecia: uma extensão desinstalada, com a fonte parada ao lado do `microteia.yaml`,
+ * trancava o `deploy` inteiro — hosting, rules e índices junto — por causa de uma function que nenhum
+ * comando teria subido.
+ */
+export interface GateProblem {
+    /** A function a que o problema pertence. É por ela que se sabe se ela vai, de fato, subir. */
+    name: string;
+    message: string;
+}
 /**
  * Gatilho de extensão sem portão.
  *
@@ -113,7 +132,7 @@ export interface GateSubject {
  * endereço próprio — enquanto ela não fechar, exigir aqui um portão impossível seria recusar a única
  * forma que a plataforma oferece para uma function compartilhada.
  */
-export declare const ungatedTriggerProblems: (subjects: GateSubject[]) => string[];
+export declare const ungatedTriggerProblems: (subjects: GateSubject[]) => GateProblem[];
 /**
  * Function de extensão cujo evento não tem escritório, e que não passa pelo laço.
  *
@@ -123,7 +142,7 @@ export declare const ungatedTriggerProblems: (subjects: GateSubject[]) => string
  * `functions/` fica de fora pelo mesmo motivo de sempre: a comum não tem um id de extensão para dar ao
  * laço. Quem responde por ela é a declaração de quem ela serve.
  */
-export declare const unscopedTriggerProblems: (subjects: GateSubject[]) => string[];
+export declare const unscopedTriggerProblems: (subjects: GateSubject[]) => GateProblem[];
 /**
  * Gatilho de uma function COMUM que declara quem serve, e não guarda ninguém.
  *
@@ -139,7 +158,7 @@ export declare const unscopedTriggerProblems: (subjects: GateSubject[]) => strin
  * respondem à mesma pergunta em dois lugares, e divergirem faz uma delas mentir — a `serves` decide a
  * retirada, a guarda decide a execução, e a function passaria a agir onde não pode ser retirada.
  */
-export declare const unguardedSharedProblems: (subjects: GateSubject[]) => string[];
+export declare const unguardedSharedProblems: (subjects: GateSubject[]) => GateProblem[];
 /**
  * Callable de extensão sem a guarda de instalação.
  *
@@ -157,7 +176,18 @@ export declare const unguardedSharedProblems: (subjects: GateSubject[]) => strin
  * conhecida e está registrada — a guarda "alguma das que eu sirvo" existe para gatilho, não para
  * callable.
  */
-export declare const unguardedCallableProblems: (subjects: GateSubject[]) => string[];
+export declare const unguardedCallableProblems: (subjects: GateSubject[]) => GateProblem[];
+/** Todo problema de portão de um conjunto de origens, na ordem em que as mensagens os citam. */
+export declare const gateProblems: (subjects: GateSubject[]) => GateProblem[];
+/**
+ * Os problemas das functions que ESTÃO subindo — a lista que autoriza uma recusa.
+ *
+ * É a diferença entre "a fonte foi lida" e "a function vai para o ar", e ela não é sutil: a primeira
+ * inclui toda extensão cujo diretório ficou no disco depois de desinstalada, e recusar por causa dela é
+ * recusar um comando que não faria nada de errado. A segunda é o momento em que a recusa tem
+ * consequência — e é o único em que ela é devida.
+ */
+export declare const gateProblemsFor: (subjects: GateSubject[], deploying: string[]) => string[];
 export interface MisgatedTrigger {
     /** A origem, como as mensagens a citam. */
     label: string;

package/lib/console/functionGate.js

@@ -13,8 +13,11 @@
  * código de uma extensão que ninguém tem mais rodando sobre os dados de quem nunca a pediu, sem erro em
  * lugar nenhum.
  *
- * É recusa e não aviso pelo mesmo motivo do nome de function repetido (`functionProblems`): o defeito é
- * invisível depois de instalado, e um aviso na saída de um deploy é lido uma vez.
+ * É recusa, e não aviso, pelo mesmo motivo do nome de function repetido: o defeito é invisível depois de
+ * instalado, e um aviso na saída de um deploy é lido uma vez. Mas ela é cobrada da function que VAI
+ * SUBIR, e não de toda fonte que existe no disco — ver `gateProblemsFor`. Toda origem é lida, sempre, e
+ * o que não vai subir é relatado pelo `provision`: quem tem a fonte parada ao lado do `microteia.yaml`
+ * fica sabendo dela, sem ter o comando trancado por ela.
  *
  * A análise é por texto, no idioma dos outros leitores de fonte do Console (`callableFunctionNames`,
  * `declaredParametersIn`). Ela erra para o lado ALTO — o que ela não entende ela recusa —, e é por isso
@@ -269,9 +272,12 @@ export const ungatedTriggerProblems = (subjects) => subjects
     .filter((subject) => !subject.shared)
     .flatMap((subject) => exportedTriggers(subject)
     .filter((trigger) => trigger.gatedFor === null)
-    .map((trigger) => `${subject.label} exports "${trigger.name}", a ${trigger.trigger} trigger with no `
-    + `installation gate — wrap its handler in ${GATE}('<this extension's id>', …) or it fires for `
-    + 'every office in the project, including the ones that never installed the extension'));
+    .map((trigger) => ({
+    name: trigger.name,
+    message: `${subject.label} exports "${trigger.name}", a ${trigger.trigger} trigger with no `
+        + `installation gate — wrap its handler in ${GATE}('<this extension's id>', …) or it fires for `
+        + 'every office in the project, including the ones that never installed the extension',
+})));
 /**
  * Function de extensão cujo evento não tem escritório, e que não passa pelo laço.
  *
@@ -285,10 +291,13 @@ export const unscopedTriggerProblems = (subjects) => subjects
     .filter((subject) => !subject.shared)
     .flatMap((subject) => exportedUnscoped(subject)
     .filter((trigger) => trigger.gatedFor === null)
-    .map((trigger) => `${subject.label} exports "${trigger.name}", a ${trigger.trigger} function whose `
-    + `event carries no {tenantId} — ${GATE} cannot gate it (it fails closed, so the function would `
-    + `never run at all). Loop with ${OFFICE_LOOP}('<this extension's id>', …) inside the handler, or `
-    + 'it acts on every office in the project, including the ones that never installed the extension'));
+    .map((trigger) => ({
+    name: trigger.name,
+    message: `${subject.label} exports "${trigger.name}", a ${trigger.trigger} function whose `
+        + `event carries no {tenantId} — ${GATE} cannot gate it (it fails closed, so the function would `
+        + `never run at all). Loop with ${OFFICE_LOOP}('<this extension's id>', …) inside the handler, or `
+        + 'it acts on every office in the project, including the ones that never installed the extension',
+})));
 /**
  * Gatilho de uma function COMUM que declara quem serve, e não guarda ninguém.
  *
@@ -311,16 +320,22 @@ export const unguardedSharedProblems = (subjects) => subjects
     if (serves === undefined || serves.length === 0)
         return [];
     if (trigger.guards.length === 0) {
-        return [`${subject.label} exports "${trigger.name}", a ${trigger.trigger} trigger declared as `
-                + `serving ${serves.join(', ')} — guard it with ${ANY_GATE}([${serves.map((id) => `'${id}'`).join(', ')}], …) `
-                + 'or it fires for every office in the project, including the ones that installed none of them'];
+        return [{
+                name: trigger.name,
+                message: `${subject.label} exports "${trigger.name}", a ${trigger.trigger} trigger declared as `
+                    + `serving ${serves.join(', ')} — guard it with ${ANY_GATE}([${serves.map((id) => `'${id}'`).join(', ')}], …) `
+                    + 'or it fires for every office in the project, including the ones that installed none of them',
+            }];
     }
     const stranger = trigger.guards.filter((id) => !serves.includes(id));
     if (stranger.length === 0)
         return [];
-    return [`${subject.label} guards "${trigger.name}" for ${stranger.join(', ')}, which it does not `
-            + `declare serving in microteia.serves (${serves.join(', ')}) — the two lists answer the same `
-            + 'question, and one of them is wrong'];
+    return [{
+            name: trigger.name,
+            message: `${subject.label} guards "${trigger.name}" for ${stranger.join(', ')}, which it does not `
+                + `declare serving in microteia.serves (${serves.join(', ')}) — the two lists answer the same `
+                + 'question, and one of them is wrong',
+        }];
 }));
 /**
  * Callable de extensão sem a guarda de instalação.
@@ -343,10 +358,32 @@ export const unguardedCallableProblems = (subjects) => subjects
     .filter((subject) => !subject.shared)
     .flatMap((subject) => exportedCallables(subject)
     .filter((callable) => callable.gatedFor === null)
-    .map((callable) => `${subject.label} exports "${callable.name}", a callable with no installation `
-    + `check — call ${CALLABLE_GUARD}('<this extension's id>', tenantId, request) before you read the `
-    + 'payload. The deploy makes every callable publicly invocable, so it answers any signed-in user '
-    + 'of this project, from any office, whether or not they installed the extension'));
+    .map((callable) => ({
+    name: callable.name,
+    message: `${subject.label} exports "${callable.name}", a callable with no installation `
+        + `check — call ${CALLABLE_GUARD}('<this extension's id>', tenantId, request) before you read the `
+        + 'payload. The deploy makes every callable publicly invocable, so it answers any signed-in user '
+        + 'of this project, from any office, whether or not they installed the extension',
+})));
+/** Todo problema de portão de um conjunto de origens, na ordem em que as mensagens os citam. */
+export const gateProblems = (subjects) => [
+    ...ungatedTriggerProblems(subjects),
+    ...unscopedTriggerProblems(subjects),
+    ...unguardedSharedProblems(subjects),
+    ...unguardedCallableProblems(subjects),
+];
+/**
+ * Os problemas das functions que ESTÃO subindo — a lista que autoriza uma recusa.
+ *
+ * É a diferença entre "a fonte foi lida" e "a function vai para o ar", e ela não é sutil: a primeira
+ * inclui toda extensão cujo diretório ficou no disco depois de desinstalada, e recusar por causa dela é
+ * recusar um comando que não faria nada de errado. A segunda é o momento em que a recusa tem
+ * consequência — e é o único em que ela é devida.
+ */
+export const gateProblemsFor = (subjects, deploying) => {
+    const going = new Set(deploying);
+    return gateProblems(subjects).filter((problem) => going.has(problem.name)).map((p) => p.message);
+};
 /**
  * Portão aberto para o id ERRADO.
  *

package/lib/console/provision.js

@@ -17,8 +17,8 @@ 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';
+import { describeMisgated, gateProblems, misgatedTriggers, singleClaimants, } from './functionGate.js';
+import { appliedAfterRun, classifyApplied, describeApplied, parseAppliedFunctions, serializeAppliedFunctions, straysInProject, } from './appliedFunctions.js';
 /**
  * O que cada escritório do projeto instalou e exige do backend.
  *
@@ -140,22 +140,26 @@ export const provisionBackend = async (options) => {
         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.
+     * O portão é RELATADO por inteiro aqui, e COBRADO uma a uma na fila de deploy, mais abaixo.
+     *
+     * A assimetria é deliberada, e é o que este comando exige: ele é o único capaz de RETIRAR uma function
+     * do projeto. Recusar o comando inteiro trancaria `--prune` — que é justamente quem apaga a órfã — por
+     * causa de uma fonte que a órfã não tem nada a ver. Então a fonte defeituosa sai da fila, é dita em voz
+     * alta, o comando termina em erro por causa dela, e tudo o mais acontece.
+     *
+     * O relato é de TODAS, e não só das que estão subindo agora: uma fonte com portão faltando é uma
+     * function que ninguém vai conseguir deployar, e descobrir isso no dia da instalação da extensão é
+     * tarde. Aqui o que ela custa é uma linha.
      */
-    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`
+    const gateFaults = gateProblems(office.sources);
+    const gateFaultBy = new Map(gateFaults.map((fault) => [fault.name, fault.message]));
+    if (gateFaults.length > 0) {
+        warn(`${gateFaults.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.');
+        bullets(gateFaults.map((fault) => fault.message));
+        info('  each one is refused the moment this command tries to deploy IT — the others go up as');
+        info('  usual, and a source sitting here for an extension nobody installed blocks nothing.');
+        info('  Whatever is already in the air keeps acting on every office in this project.');
     }
     /**
      * A comum SEM declaração de quem serve. Ela continua subindo no `deploy`, sempre, e nada a retira — é
@@ -305,10 +309,11 @@ export const provisionBackend = async (options) => {
      * 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ê.
+     * Ela é feita SEMPRE, e a versão anterior a pulava quando não havia function aplicada a conferir —
+     * economia que custava exatamente o caso que mais importa. É a instalação sem extensão nenhuma que
+     * precisa da pergunta: é ali que mora a function de uma extensão que saiu, e sem perguntar ao projeto
+     * a resposta é o silêncio. A ida vale segundos; a alternativa é uma callable órfã que nenhum comando
+     * menciona.
      */
     let asked;
     const projectFunctions = async () => {
@@ -358,11 +363,29 @@ 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 || !appliedNames.has(name) || staleFunctions.has(name));
+    const queued = wantedFunctions.filter((name) => options.all === true || !appliedNames.has(name) || staleFunctions.has(name));
+    /**
+     * A recusa do portão, cobrada de quem está na fila — e só dela.
+     *
+     * Ela sai da fila em vez de derrubar o comando, e as duas metades disso importam. Sair da fila é o que
+     * impede a function de ir para o ar agindo sobre escritório que não a instalou, que é o defeito
+     * inteiro. Não derrubar é o que deixa o resto acontecer: as outras extensões recebem o backend delas,
+     * os índices convergem, e `--prune` apaga a órfã. O comando termina em erro por causa dela, no fim,
+     * quando já não há nada a atrapalhar.
+     */
+    const refused = queued.filter((name) => gateFaultBy.has(name));
+    const toDeploy = queued.filter((name) => !gateFaultBy.has(name));
+    if (refused.length > 0) {
+        blank();
+        failure(`${refused.length} function(s) are needed by an installed extension and cannot go up:`);
+        bullets(refused.map((name) => gateFaultBy.get(name) ?? name));
+        info('  they are the only ones held back. Fix the guard and run "microteia provision" again.');
+        outcome.failed.push(...refused);
+    }
     if (toDeploy.length === 0) {
         // 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) {
+        if (wantedFunctions.length > 0 && refused.length === 0) {
             success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
         }
     }
@@ -387,7 +410,7 @@ export const provisionBackend = async (options) => {
             projectId, cwd: install, delaySeconds, force: false,
         });
         outcome.deployed = report.deployed;
-        outcome.failed = report.failed.map((entry) => entry.name);
+        outcome.failed.push(...report.failed.map((entry) => entry.name));
         reportFailures(report.failed);
         reportNotices(report.notices);
         await checkNewCallables([...(manifest.callables ?? []), ...office.callables], report.deployed, projectId, region);
@@ -402,9 +425,42 @@ export const provisionBackend = async (options) => {
             outcome.pending.push(claim);
         }
     }
+    /**
+     * O que o PROJETO roda, cruzado com o que esta instalação consegue justificar.
+     *
+     * O registro respondia sozinho por essa pergunta, e é um registro que se perde — e quando se perde,
+     * some com ele a única memória de que aquela function existe. Perguntar ao projeto é o que fecha o
+     * buraco: uma callable de extensão desinstalada, no ar, publicamente invocável, com o
+     * `backend.functions` do `microteia.yaml` vazio, não era mencionada por comando nenhum.
+     *
+     * O limite está em `straysInProject`, e é o que torna isto seguro: só vira órfã o nome que ESTA
+     * instalação sabe produzir. O que a órfã ganha aqui, além da remoção, é entrar no registro quando não
+     * for removida — a partir da próxima execução ela é conhecida mesmo que o código-fonte dela saia do
+     * disco.
+     */
+    const running = await projectFunctions();
+    const stray = straysInProject({
+        // A região é o filtro, e o ESTADO não é. Uma cópia em região abandonada tem endereço próprio
+        // (`clearRegionOrphans`); já o estado só decide se dá para comparar carimbo — para existir no
+        // projeto, basta estar na listagem. E o `functions:list` nem sempre traz o campo: exigir `ACTIVE`
+        // deixaria a varredura cega em silêncio no dia em que ele viesse vazio.
+        running: (running ?? []).filter((entry) => entry.region === region).map((entry) => entry.name),
+        known: [...manifest.functions, ...office.all],
+        justified: [
+            ...wantedFunctions,
+            // A baseline do PACOTE, com o mesmo fallback que o `deploy` usa para decidir o que subir. Um
+            // `?? []` aqui faria toda function da plataforma virar órfã num pacote sem o campo.
+            ...(manifest.baselineFunctions ?? manifest.functions),
+            ...office.unserved,
+            ...unresolved.keys(),
+        ],
+        recorded: applied.map((entry) => entry.name),
+    });
+    reportStrays(stray, running);
     reportPreserved(classification.preserved);
-    outcome.orphans = classification.orphans.map((entry) => entry.name);
-    const remaining = await settleOrphans(options, classification.orphans, survey);
+    const orphans = [...classification.orphans, ...stray.orphans];
+    outcome.orphans = orphans.map((entry) => entry.name);
+    const remaining = await settleOrphans(options, orphans, survey);
     await recordBackendState(options, appliedAfterRun({
         applied,
         wanted: wantedFunctions,
@@ -557,6 +613,42 @@ const reportPreserved = (preserved) => {
         info('  Fix what is reported above and run "microteia provision" again.');
     }
 };
+/**
+ * O que a varredura do projeto achou, e que o registro não conhecia.
+ *
+ * As duas listas são ditas porque respondem a perguntas diferentes de quem lê. A órfã é uma decisão a
+ * tomar — ela vai para `settleOrphans` logo abaixo, e sai com `--prune`. O estranho não é decisão
+ * nenhuma: é um aviso de que o projeto Firebase tem inquilino que a Microteia não pôs ali, e dizer que
+ * nada o toca vale mais do que o silêncio, porque o silêncio aqui parece "não há mais nada".
+ */
+const reportStrays = (stray, running) => {
+    if (running === null) {
+        blank();
+        warn('could not list what this project is running, so nothing was compared against it.');
+        info('  a function left behind by an extension that is gone would not be found this run. The');
+        info('  account needs permission to run "firebase functions:list".');
+        return;
+    }
+    if (stray.orphans.length > 0) {
+        blank();
+        info(`  ${stray.orphans.length} function(s) are running in this project and this installation's`);
+        info('  record does not mention them:');
+        bullets(stray.orphans.map((entry) => entry.name));
+        info('  this installation is what produces them, and nothing installed needs them — so they are');
+        info('  treated as orphans below. A record is lost by a re-init, a restored backup, or a Console');
+        info('  older than the field; the function it forgot stays in the air either way.');
+    }
+    if (stray.strangers.length > 0) {
+        blank();
+        info(`  ${stray.strangers.length} function(s) run in this project and did not come from this`);
+        info('  installation:');
+        bullets(stray.strangers);
+        info('  nothing here touches them — not even --prune. A Firebase project can be shared, and');
+        info('  deleting what Microteia did not put there is not this command\'s call.');
+        info('  A function of yours lands here once its source is gone from this installation: run');
+        info('  "microteia provision" BEFORE deleting extensions/<folder>/, and it is recognized.');
+    }
+};
 /**
  * Function que nenhuma extensão instalada exige mais.
  *

package/lib/shared/paths.d.ts

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

package/lib/shared/paths.js

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

package/package.json

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