@microteia/console 2.7.2 → 2.10.0

package/lib/console/functionsUpToDate.d.ts

@@ -0,0 +1,55 @@
+import type { FunctionDeployOptions, FunctionDeployReport } from './deployFunctions.js';
+import type { DeployedFunction } from './regionOrphans.js';
+/** As functions que o projeto roda com exatamente o mesmo carimbo. */
+export interface HashGroup {
+    hash: string;
+    platform: string;
+    names: string[];
+}
+export interface DeployPlan {
+    /**
+     * Sem carimbo com que comparar: ausente do projeto, em outra região, no meio de um deploy, ou
+     * deployada por um CLI que não gravava o label. Sobem sempre — não saber nunca vira pular.
+     */
+    unverifiable: string[];
+    groups: HashGroup[];
+}
+export declare const planFunctionDeploy: (wanted: string[], deployed: DeployedFunction[] | null, region: string) => DeployPlan;
+export interface UpToDateReport extends FunctionDeployReport {
+    /** Não subiram porque o projeto já roda exatamente este código. */
+    skipped: string[];
+    /**
+     * O carimbo antigo de cada grupo sondado, e o que a sonda dele voltou carregando. É o que deixa o
+     * provisionamento decidir sobre as functions de extensão sem sondar de novo: elas estão no MESMO
+     * codebase, então o carimbo de agora é o mesmo.
+     */
+    refreshed: Map<string, string>;
+}
+export interface UpToDateContext {
+    /** A listagem que o comando já fez, para não perguntar duas vezes a mesma coisa ao projeto. */
+    deployed: DeployedFunction[] | null;
+    region: string;
+    /** `--all`: sobe todas, sem perguntar ao projeto o que ele já roda. */
+    all: boolean;
+}
+export declare const deployFunctionsThatChanged: (wanted: string[], options: FunctionDeployOptions, context: UpToDateContext) => Promise<UpToDateReport>;
+/**
+ * A function de extensão que o projeto roda e que este pacote não constrói mais assim.
+ *
+ * Ela existe porque o provisionamento sempre decidiu por NOME: uma function já aplicada só voltava
+ * para a fila quando um parâmetro dela mudava de valor. Editar o código em
+ * `extensions/<plugin>/functions/` não movia nada — a fonte mudava, o pacote era remontado, e a
+ * function seguia rodando a versão anterior sem que comando nenhum a alcançasse.
+ *
+ * O carimbo responde isso de graça, e sem sondar nada: a function de extensão está no MESMO codebase
+ * da baseline, então o carimbo que a sonda do `deploy` acabou de observar é o dela também.
+ */
+export interface OutdatedFunctions {
+    /** Não estão rodando em lugar nenhum do projeto, apesar de a lista de nomes dizer que subiram. */
+    absent: string[];
+    /** Estão lá, e carregam um carimbo anterior ao que este pacote constrói. */
+    stale: string[];
+}
+export declare const outdatedByStamp: (applied: string[], deployed: DeployedFunction[] | null, region: string, 
+/** Carimbo antigo -> carimbo de agora, observado pelas sondas. Ausente: não há o que concluir. */
+refreshed: Map<string, string> | undefined) => OutdatedFunctions;

package/lib/console/functionsUpToDate.js

@@ -0,0 +1,192 @@
+import { blank, info, success, warn } from '../shared/ui.js';
+import { deployFunctionsOneByOne } from './deployFunctions.js';
+import { listDeployedFunctions } from './regionOrphans.js';
+/**
+ * O deploy que não sobe de novo o que o projeto já roda.
+ *
+ * O `firebase` sabe responder isso, e sempre soube: ele grava em cada function o label
+ * `firebase-functions-hash` — sha1 do diretório de fontes INTEIRO, mais as variáveis de ambiente
+ * resolvidas, mais as versões de segredo — e num deploy em lote pula toda function cujo carimbo
+ * gravado é igual ao que o código atual produz. O que desliga esse pulo é justamente o
+ * `--only functions:<nome>` com que o Console deploya: `planner.js` só pula endpoint que
+ * `!targetedByOnly`, e nomear a function no `--only` a marca. Deployar uma a uma não é opcional (em
+ * lote estoura a quota de CPU do projeto), então o pulo teve de ser reconstruído aqui.
+ *
+ * **Não é um mecanismo de detecção novo, e essa é a decisão inteira.** Não há digest nosso, não há
+ * lista de insumos que alguém possa esquecer de atualizar, não há estado guardado que possa divergir
+ * do projeto. O carimbo é do `firebase`: calculado por ele, gravado por ele na function, lido do
+ * projeto a cada execução. Comparar por ele é tomar a MESMA decisão que o `firebase deploy` tomaria.
+ *
+ * O que faltava é o outro lado da comparação: o carimbo que o código de AGORA produziria. Calculá-lo
+ * aqui exigiria reimplementar o algoritmo dele — e uma reimplementação que envelhece em silêncio é
+ * exatamente o que não se quer num comando que decide NÃO publicar. Em vez disso ele é OBSERVADO: as
+ * functions são agrupadas pelo carimbo que carregam, UMA de cada grupo é deployada, e o carimbo que
+ * ela volta carregando é o carimbo do código de agora. Voltou igual, o grupo inteiro é byte a byte o
+ * que o projeto já roda; voltou diferente, o grupo inteiro sobe.
+ *
+ * A sonda ser MEMBRO do grupo é o que faz a conclusão valer para os outros: duas functions com o
+ * mesmo carimbo antigo têm, além da mesma fonte e do mesmo ambiente, o mesmo conjunto de segredos —
+ * é a terceira parcela do hash. Uma sonda de fora do grupo não provaria isso.
+ *
+ * Ler o carimbo da sonda logo depois de ela subir depende de o `functions:list` já enxergar o que o
+ * deploy acabou de gravar. Não é uma aposta nossa: é a MESMA leitura de que o `firebase deploy`
+ * depende para montar o `haveBackend` com que ele decide o que pular, e o comando só retorna depois
+ * de a operação do Google ter terminado.
+ *
+ * O custo do pior caso é o comportamento de hoje; o do caso bom é uma function em vez de 28.
+ *
+ * O que ele NÃO enxerga — porque o `firebase deploy` em lote também não — é configuração trocada por
+ * fora, pelo console do Google: memória, timeout, concorrência, política de invocação. Para isso
+ * existe `--all`. O alcance das callables continua conferido em TODAS a cada deploy, inclusive nas
+ * que não subiram, e é ele que acusa uma concessão de IAM removida por fora.
+ */
+const ACTIVE = 'ACTIVE';
+const SEPARATOR = ' ';
+export const planFunctionDeploy = (wanted, deployed, region) => {
+    if (deployed === null)
+        return { unverifiable: [...wanted], groups: [] };
+    const byName = new Map();
+    for (const entry of deployed) {
+        if (entry.region === region)
+            byName.set(entry.name, entry);
+    }
+    const unverifiable = [];
+    const grouped = new Map();
+    for (const name of wanted) {
+        const entry = byName.get(name);
+        if (entry === undefined || entry.state !== ACTIVE || entry.hash === null) {
+            unverifiable.push(name);
+            continue;
+        }
+        // A plataforma entra na chave porque `gcfv1` e `gcfv2` empacotam fontes diferentes e carimbam
+        // hashes diferentes: o carimbo de uma nunca fala pela outra.
+        const key = `${entry.platform}${SEPARATOR}${entry.hash}`;
+        const names = grouped.get(key);
+        if (names === undefined)
+            grouped.set(key, [name]);
+        else
+            names.push(name);
+    }
+    const groups = [...grouped.entries()].map(([key, names]) => {
+        const [platform, hash] = key.split(SEPARATOR);
+        return { hash, platform, names };
+    });
+    return { unverifiable, groups };
+};
+const merge = (left, right) => ({
+    deployed: [...left.deployed, ...right.deployed],
+    failed: [...left.failed, ...right.failed],
+    notices: [...new Set([...left.notices, ...right.notices])],
+});
+const plural = (count, singular) => (count === 1 ? singular : `${singular}s`);
+export const deployFunctionsThatChanged = async (wanted, options, context) => {
+    const plain = async (names) => ({
+        ...(await deployFunctionsOneByOne(names, options)),
+        skipped: [],
+        refreshed: new Map(),
+    });
+    if (wanted.length === 0)
+        return plain(wanted);
+    if (context.all) {
+        info(`  --all: deploying all ${wanted.length}, without asking the project what it already runs.`);
+        return plain(wanted);
+    }
+    const plan = planFunctionDeploy(wanted, context.deployed, context.region);
+    if (plan.groups.length === 0) {
+        // Nada com que comparar. Numa instalação nova é o caso normal, e é o certo: não há nada lá.
+        return plain(wanted);
+    }
+    const comparable = plan.groups.reduce((count, group) => count + group.names.length, 0);
+    const probes = plan.groups.map((group) => group.names[0]);
+    const candidates = comparable - probes.length;
+    info(`  ${comparable} of the ${wanted.length} already run in this project carrying a Firebase stamp`);
+    info(`  of the source, settings and secrets they were built with. Deploying ${probes.length} reference`);
+    info(`  ${plural(probes.length, 'function')} first (${probes.join(', ')}): if the stamp comes back`);
+    info(`  unchanged, the other ${candidates} are what the project already runs and are left alone.`);
+    info('  It is the same comparison "firebase deploy" makes when it deploys in bulk.');
+    blank();
+    // As sondas primeiro: é o que se aprende com elas que decide o resto.
+    const first = await deployFunctionsOneByOne([...probes, ...plan.unverifiable], options);
+    const fresh = await listDeployedFunctions(options.projectId);
+    const freshByName = new Map();
+    for (const entry of fresh ?? []) {
+        if (entry.region === context.region)
+            freshByName.set(entry.name, entry);
+    }
+    const refreshed = new Map();
+    const skipped = [];
+    const rest = [];
+    let unconfirmed = 0;
+    for (const group of plan.groups) {
+        const [probe, ...others] = group.names;
+        if (others.length === 0)
+            continue;
+        const entry = freshByName.get(probe);
+        const stamp = first.deployed.includes(probe) && entry !== undefined && entry.state === ACTIVE
+            ? entry.hash
+            : null;
+        if (stamp === null) {
+            // Não deu para ler o carimbo novo da sonda: a resposta é subir, que é o que se fazia antes
+            // deste mecanismo existir. Não saber nunca vira pular.
+            unconfirmed += others.length;
+            rest.push(...others);
+            continue;
+        }
+        refreshed.set(group.hash, stamp);
+        if (stamp === group.hash)
+            skipped.push(...others);
+        else
+            rest.push(...others);
+    }
+    blank();
+    if (skipped.length > 0) {
+        success(`${skipped.length} ${plural(skipped.length, 'function')} already up to date — same source,`);
+        info('        settings and secrets as what this project runs. Not deployed.');
+    }
+    if (unconfirmed > 0) {
+        warn(`could not read the new stamp of ${unconfirmed} ${plural(unconfirmed, 'function')}: deploying them.`);
+    }
+    if (rest.length > 0) {
+        info(`  ${rest.length} ${plural(rest.length, 'function')} changed and go up now.`);
+    }
+    blank();
+    const second = await deployFunctionsOneByOne(rest, options);
+    return { ...merge(first, second), skipped, refreshed };
+};
+export const outdatedByStamp = (applied, deployed, region, 
+/** Carimbo antigo -> carimbo de agora, observado pelas sondas. Ausente: não há o que concluir. */
+refreshed) => {
+    if (deployed === null)
+        return { absent: [], stale: [] };
+    const byName = new Map();
+    const running = new Set();
+    for (const entry of deployed) {
+        // A ausência é perguntada ao projeto INTEIRO, e não à região do pacote: uma function que o
+        // escritório escreveu de propósito noutra região está rodando, e devolvê-la à fila por não estar
+        // aqui a redeployaria em toda execução, para sempre. É a mesma distinção que `regionOrphans` faz
+        // ao casar por nome-que-vai-subir em vez de por região diferente da esperada.
+        if (entry.state === ACTIVE)
+            running.add(entry.name);
+        if (entry.region === region)
+            byName.set(entry.name, entry);
+    }
+    const absent = [];
+    const stale = [];
+    for (const name of applied) {
+        if (!running.has(name)) {
+            absent.push(name);
+            continue;
+        }
+        const entry = byName.get(name);
+        if (entry === undefined || entry.state !== ACTIVE)
+            continue;
+        // Sem carimbo, ou sem o carimbo de agora com que compará-lo, não há conclusão a tirar — e a
+        // ausência de conclusão mantém o comportamento anterior a este mecanismo, que é não mexer.
+        if (entry.hash === null || refreshed === undefined)
+            continue;
+        const now = refreshed.get(entry.hash);
+        if (now !== undefined && now !== entry.hash)
+            stale.push(name);
+    }
+    return { absent, stale };
+};

package/lib/console/init.js

@@ -31,6 +31,7 @@ export const init = async (args) => {
         firebase: { projectId: null, region: DEFAULT_FUNCTIONS_REGION },
         kernel: { version: null, deployed: null },
         backend: { functions: null, parameters: null, indexes: null },
+        login: { extensions: null },
     };
     await writeEnvironment(file, environment);
     // O diretório de trabalho guarda o pacote desempacotado e a configuração resolvida. Ele é local à

package/lib/console/installedExtensions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * O CAMINHO ÚNICO até o que um escritório instalou.
+ *
+ * Estava dentro do `provision`, e é dele que a leitura nasceu: para saber quais Cloud Functions subir,
+ * o comando precisa do `manifest.backend` de cada extensão instalada. O `export-catalog` faz a mesma
+ * pergunta com outro propósito, e um segundo caminho até o mesmo documento seria uma segunda chance de
+ * discordar — a forma do documento, o que conta como instalada, o que fazer com a desativada.
+ *
+ * Então o caminho é este, e o `provision` também passa por aqui.
+ */
+/** Um escritório do projeto. O `name` existe para que escolher um `--tenant` não seja adivinhar um id. */
+export interface TenantSummary {
+    id: string;
+    name: string;
+}
+export interface InstalledExtensionRecord {
+    tenantId: string;
+    documentPath: string;
+    id: string;
+    name: string;
+    version: string;
+    /** Desligada no escritório: o pacote continua ali, e nada dele está no ar. */
+    active: boolean;
+    /** O manifesto cru da cópia instalada — é dele que sai `backend`, e nada aqui o interpreta. */
+    manifest: Record<string, unknown> | undefined;
+    /** O documento inteiro, decodificado, para quem precisa de mais que o manifesto. */
+    data: Record<string, unknown>;
+}
+export declare const listTenants: (projectId: string) => Promise<TenantSummary[]>;
+/**
+ * As extensões instaladas num escritório.
+ *
+ * A DESATIVADA vem junto, marcada. Quem decide o que fazer com ela é quem chamou: para o `provision`
+ * ela não exige backend nenhum; para o catálogo ela ainda explica de onde veio uma tela que continua
+ * gravada no banco.
+ */
+export declare const readInstalledExtensions: (projectId: string, tenantId: string) => Promise<InstalledExtensionRecord[]>;

package/lib/console/installedExtensions.js

@@ -0,0 +1,37 @@
+import { decodeFields, documentId, listDocuments } from './firestoreRest.js';
+export const listTenants = async (projectId) => {
+    const documents = await listDocuments(projectId, '/tenants');
+    return documents
+        .map((document) => {
+        const id = documentId(document);
+        const data = decodeFields(document.fields);
+        return { id, name: typeof data.name === 'string' && data.name !== '' ? data.name : id };
+    })
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+};
+/**
+ * As extensões instaladas num escritório.
+ *
+ * A DESATIVADA vem junto, marcada. Quem decide o que fazer com ela é quem chamou: para o `provision`
+ * ela não exige backend nenhum; para o catálogo ela ainda explica de onde veio uma tela que continua
+ * gravada no banco.
+ */
+export const readInstalledExtensions = async (projectId, tenantId) => {
+    const documents = await listDocuments(projectId, `/tenants/${tenantId}/installed_extensions`);
+    return documents.map((document) => {
+        const data = decodeFields(document.fields);
+        const pkg = data.package;
+        const manifest = pkg?.manifest;
+        const fallbackId = documentId(document);
+        return {
+            tenantId,
+            documentPath: `/tenants/${tenantId}/installed_extensions/${fallbackId}`,
+            id: String(manifest?.id ?? fallbackId),
+            name: String(manifest?.name ?? manifest?.id ?? fallbackId),
+            version: String(manifest?.version ?? '0.0.0'),
+            active: data.active !== false,
+            manifest,
+            data,
+        };
+    });
+};

package/lib/console/loginExtensions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Este arquivo BLOQUEIA a página: é um `<script>` no `<head>`, antes do bundle. Um pacote gordo aqui
+ * custa em toda visita, inclusive na de quem nem vai entrar. O aviso vem antes de doer, e a recusa
+ * vem quando já dói para todo mundo.
+ */
+export declare const STAMP_WARN_BYTES: number;
+export declare const STAMP_MAX_BYTES: number;
+export declare const STAMP_FILE = "microteia-extensions.js";
+export interface LoginExtensionsResult {
+    /** O conteúdo do arquivo carimbado. Escrito sempre, mesmo vazio — ver `stampLoginExtensions`. */
+    contents: string;
+    /** `id@version` de cada pacote carimbado, na ordem declarada. */
+    stamped: string[];
+    /** O que quem instala precisa saber sem que o deploy pare. */
+    warnings: string[];
+    bytes: number;
+}
+export declare const parseExtensionPaths: (declared: string | null) => string[];
+/**
+ * Monta o carimbo. `preLoginPoints` vem do manifesto do PACOTE do kernel instalado, e não de uma lista
+ * aqui: o Console é versionado separadamente, e uma cópia dela passaria a descrever o contrato de
+ * outra versão em silêncio. Ausente (pacote antigo), a checagem é pulada em vez de inventada.
+ */
+export declare const buildLoginExtensions: (root: string, declared: string | null, preLoginPoints: string[] | undefined) => Promise<LoginExtensionsResult>;
+/**
+ * Escreve o carimbo SEMPRE, inclusive vazio. Pular a escrita quando a lista está vazia deixaria o
+ * carimbo do deploy anterior no ar: tirar um pacote de `login.extensions` não o tiraria da tela.
+ */
+export declare const stampPath: (install: string) => string;

package/lib/console/loginExtensions.js

@@ -0,0 +1,101 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/**
+ * Este arquivo BLOQUEIA a página: é um `<script>` no `<head>`, antes do bundle. Um pacote gordo aqui
+ * custa em toda visita, inclusive na de quem nem vai entrar. O aviso vem antes de doer, e a recusa
+ * vem quando já dói para todo mundo.
+ */
+export const STAMP_WARN_BYTES = 256 * 1024;
+export const STAMP_MAX_BYTES = 1024 * 1024;
+export const STAMP_FILE = 'microteia-extensions.js';
+export const parseExtensionPaths = (declared) => (declared ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '');
+const asStampedPackage = (parsed, path) => {
+    const manifest = parsed?.manifest;
+    if (!manifest || typeof manifest !== 'object') {
+        throw new Error(`${path} is not an extension package: it has no "manifest".`);
+    }
+    const { id, version, contributes } = manifest;
+    if (typeof id !== 'string' || id === '') {
+        throw new Error(`${path} has no "manifest.id".`);
+    }
+    if (typeof version !== 'string' || version === '') {
+        throw new Error(`${path} has no "manifest.version".`);
+    }
+    if (!Array.isArray(contributes)) {
+        throw new Error(`${path} has no "manifest.contributes" array.`);
+    }
+    return parsed;
+};
+/**
+ * Monta o carimbo. `preLoginPoints` vem do manifesto do PACOTE do kernel instalado, e não de uma lista
+ * aqui: o Console é versionado separadamente, e uma cópia dela passaria a descrever o contrato de
+ * outra versão em silêncio. Ausente (pacote antigo), a checagem é pulada em vez de inventada.
+ */
+export const buildLoginExtensions = async (root, declared, preLoginPoints) => {
+    const paths = parseExtensionPaths(declared);
+    const packages = [];
+    const stamped = [];
+    const warnings = [];
+    for (const path of paths) {
+        const absolute = resolve(root, path);
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(absolute, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Error(`login.extensions lists ${path}, which does not exist.\n`
+                    + 'Compile the extension first ("microteia-plugin build" inside extensions/), '
+                    + 'or remove the path from microteia.yaml.', { cause: error });
+            }
+            throw new Error(`${path} is not valid JSON.`, { cause: error });
+        }
+        const pkg = asStampedPackage(parsed, path);
+        if (preLoginPoints !== undefined) {
+            const points = pkg.manifest.contributes
+                .map((contribution) => contribution.point)
+                .filter((point) => typeof point === 'string');
+            const effective = points.filter((point) => preLoginPoints.includes(point));
+            if (effective.length === 0) {
+                throw new Error(`${path} (${pkg.manifest.id}) contributes nothing that works before sign-in, so stamping it `
+                    + 'would load it with no effect.\n'
+                    + `  Points that work before sign-in: ${preLoginPoints.join(', ')}.\n`
+                    + `  This package contributes: ${points.length === 0 ? '(none)' : [...new Set(points)].join(', ')}.\n`
+                    + '  To USE it inside the organization, install it from the Extensions screen instead.');
+            }
+        }
+        if (Array.isArray(pkg.views) && pkg.views.length > 0) {
+            warnings.push(`${pkg.manifest.id} ships ${pkg.views.length} view(s): stamped packages load untrusted, `
+                + 'so their code does not run before sign-in — only declarations apply');
+        }
+        const duplicate = packages.find((existing) => existing.manifest.id === pkg.manifest.id);
+        if (duplicate !== undefined) {
+            throw new Error(`login.extensions lists ${pkg.manifest.id} twice. The Kernel would ignore the second one, `
+                + 'so the file says something the installation does not do.');
+        }
+        packages.push(pkg);
+        stamped.push(`${pkg.manifest.id}@${pkg.manifest.version}`);
+    }
+    const contents = `// Generated by "microteia deploy". Do not edit by hand.\n`
+        + `window.__MICROTEIA_EXTENSIONS__ = ${JSON.stringify(packages)};\n`;
+    const bytes = Buffer.byteLength(contents, 'utf8');
+    if (bytes > STAMP_MAX_BYTES) {
+        throw new Error(`The stamped extensions would be ${Math.round(bytes / 1024)} KiB, over the `
+            + `${STAMP_MAX_BYTES / 1024} KiB limit. This file blocks the page on every visit, including `
+            + 'visits by people who never sign in.\n'
+            + '  Keep before-sign-in packages to what the sign-in screen needs, and install the rest.');
+    }
+    if (bytes > STAMP_WARN_BYTES) {
+        warnings.push(`the stamped extensions are ${Math.round(bytes / 1024)} KiB, and this file blocks the page on `
+            + 'every visit');
+    }
+    return { contents, stamped, warnings, bytes };
+};
+/**
+ * Escreve o carimbo SEMPRE, inclusive vazio. Pular a escrita quando a lista está vazia deixaria o
+ * carimbo do deploy anterior no ar: tirar um pacote de `login.extensions` não o tiraria da tela.
+ */
+export const stampPath = (install) => join(install, 'hosting', STAMP_FILE);

package/lib/console/provision.d.ts

@@ -24,6 +24,18 @@ export interface ProvisionOptions {
     manifest: KernelManifest;
     delaySeconds: number;
     prune: boolean;
+    /** `--all`: ignora o carimbo e sobe toda function que as extensões instaladas exigem. */
+    all?: boolean;
+    /**
+     * O que as sondas do passo de functions do `deploy` observaram: carimbo antigo -> carimbo de
+     * agora. A function de extensão está no MESMO codebase da baseline, então esse carimbo vale para
+     * ela — e é por ele que uma cujo CÓDIGO mudou volta para a fila, coisa que o nome nunca disse.
+     *
+     * Sem ele — o `provision` chamado sozinho, logo depois de alguém instalar uma extensão pela
+     * aplicação — o comando decide como sempre decidiu. Sondar ali custaria um deploy a cada
+     * instalação de extensão para responder uma pergunta que naquele momento é quase sempre "nada".
+     */
+    refreshedStamps?: Map<string, string>;
     environmentFile: string;
     environment: Environment;
 }

package/lib/console/provision.js

@@ -10,9 +10,11 @@ import { changedParameters, functionsDeclaringParameters, parameterDigests, pars
 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 { 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 { listTenants, readInstalledExtensions } from './installedExtensions.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
 /**
  * O que cada escritório do projeto instalou e exige do backend.
@@ -22,27 +24,22 @@ import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js
  * 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');
+    const tenants = await listTenants(projectId);
     const claims = [];
     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)) {
+            if (!extension.active)
                 continue;
-            const pkg = data.package;
-            const manifest = pkg?.manifest;
-            const backend = manifest?.backend;
+            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),
             });
@@ -141,6 +138,28 @@ export const provisionBackend = async (options) => {
     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);
+    // 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);
+    for (const name of [...outdated.absent, ...outdated.stale])
+        staleFunctions.add(name);
+    if (outdated.absent.length > 0) {
+        blank();
+        info(`  ${outdated.absent.length} function(s) recorded as applied are not running in this project:`);
+        bullets(outdated.absent);
+        info('  they are deployed again — the record is a list of names, and a name does not know what');
+        info('  happened to the function after it went up.');
+    }
+    if (outdated.stale.length > 0) {
+        blank();
+        info(`  ${outdated.stale.length} function(s) still carry the code of a previous package:`);
+        bullets(outdated.stale);
+        info('  Firebase stamps every function with what it was built from, and theirs no longer matches');
+        info('  what this package builds. They are deployed again.');
+    }
     if (changed.length > 0) {
         blank();
         info(`  ${changed.length} backend setting(s) changed since the last run: ${changed.join(', ')}`);
@@ -161,7 +180,7 @@ 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) => !alreadyApplied.includes(name) || staleFunctions.has(name));
+    const toDeploy = wantedFunctions.filter((name) => options.all === true || !alreadyApplied.includes(name) || staleFunctions.has(name));
     if (toDeploy.length === 0) {
         success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
     }
@@ -180,7 +199,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);
+        await clearRegionOrphans(projectId, toDeploy, region, options.prune, deployedFunctions);
         info(`  deploying ${toDeploy.length} function(s), one at a time…`);
         const report = await deployFunctionsOneByOne(toDeploy, {
             projectId, cwd: install, delaySeconds, force: false,
@@ -456,6 +475,7 @@ export const provision = async (args) => {
         manifest,
         delaySeconds,
         prune: hasFlag(args, 'prune'),
+        all: hasFlag(args, 'all'),
         environmentFile: file,
         environment,
     });

package/lib/console/regionOrphans.d.ts

@@ -1,6 +1,21 @@
 export interface DeployedFunction {
     name: string;
     region: string;
+    /**
+     * O carimbo que o PRÓPRIO `firebase` grava na function, no label `firebase-functions-hash`:
+     * sha1 do diretório de fontes inteiro, mais as variáveis de ambiente resolvidas, mais as versões
+     * de segredo. É o valor que ele compara consigo mesmo para pular uma function que não mudou num
+     * deploy em lote (`calculateChangesets`), e é por isso que ele serve aqui: comparar por ele é
+     * tomar a MESMA decisão que o `firebase deploy` tomaria, não uma parecida.
+     *
+     * `null` quando a function foi deployada por uma versão do CLI que não gravava o label — nesse
+     * caso não há o que comparar, e ela sobe.
+     */
+    hash: string | null;
+    /** `ACTIVE` é a única resposta que autoriza comparar: o resto está no meio de alguma coisa. */
+    state: string;
+    /** `gcfv1` e `gcfv2` empacotam fontes diferentes, então carimbam hashes diferentes. */
+    platform: string;
 }
 /**
  * A cópia da mesma function numa região que o pacote não usa mais.
@@ -40,4 +55,10 @@ export declare const settleRegionOrphans: (projectId: string, orphans: RegionOrp
  * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve `true` quando o caminho está
  * livre — inclusive quando não deu para verificar, pela mesma razão de `listDeployedFunctions`.
  */
-export declare const clearRegionOrphans: (projectId: string, wanted: string[], region: string, prune: boolean) => Promise<boolean>;
+export declare const clearRegionOrphans: (projectId: string, wanted: string[], region: string, prune: boolean, 
+/**
+ * A listagem já feita, quando quem chama vai usá-la para outra coisa também. Perguntar duas vezes
+ * a mesma coisa ao mesmo projeto não é caro, é ambíguo: as duas respostas podem divergir, e a
+ * decisão passa a depender de qual delas o código olhou.
+ */
+listed?: DeployedFunction[] | null) => Promise<boolean>;

package/lib/console/regionOrphans.js

@@ -17,7 +17,13 @@ export const listDeployedFunctions = async (projectId) => {
             return null;
         return parsed.result
             .filter((entry) => entry !== null && typeof entry === 'object')
-            .map((entry) => ({ name: String(entry.id ?? ''), region: String(entry.region ?? '') }))
+            .map((entry) => ({
+            name: String(entry.id ?? ''),
+            region: String(entry.region ?? ''),
+            hash: typeof entry.hash === 'string' && entry.hash !== '' ? entry.hash : null,
+            state: typeof entry.state === 'string' ? entry.state : '',
+            platform: typeof entry.platform === 'string' ? entry.platform : '',
+        }))
             .filter((entry) => entry.name !== '' && entry.region !== '');
     }
     catch {
@@ -91,8 +97,14 @@ export const settleRegionOrphans = async (projectId, orphans, prune) => {
  * O passo inteiro, para quem só quer chamá-lo antes de deployar. Devolve `true` quando o caminho está
  * livre — inclusive quando não deu para verificar, pela mesma razão de `listDeployedFunctions`.
  */
-export const clearRegionOrphans = async (projectId, wanted, region, prune) => {
-    const deployed = await listDeployedFunctions(projectId);
+export const clearRegionOrphans = async (projectId, wanted, region, prune, 
+/**
+ * A listagem já feita, quando quem chama vai usá-la para outra coisa também. Perguntar duas vezes
+ * a mesma coisa ao mesmo projeto não é caro, é ambíguo: as duas respostas podem divergir, e a
+ * decisão passa a depender de qual delas o código olhou.
+ */
+listed) => {
+    const deployed = listed === undefined ? await listDeployedFunctions(projectId) : listed;
     if (deployed === null)
         return true;
     return settleRegionOrphans(projectId, regionOrphans(deployed, wanted, region), prune);