@microteia/console 2.7.1 → 2.8.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,18 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.8.0] — 2026-08-25
+
+- feat(console/functionsUpToDate): new module. It reconstructs the skip that `firebase deploy` performs in bulk and that `--only functions:<name>` disables, WITHOUT reimplementing the hash: functions are grouped by the `firebase-functions-hash` label they carry, one member of each group is deployed, and the stamp it comes back with is the stamp of the current code. The probe being a MEMBER of its group is what makes the conclusion carry to the others — two functions with the same old stamp share source, environment and secret set, the three parcels of the hash. Absent, non-`ACTIVE`, unstamped or wrong-region always deploys: not knowing never becomes skipping.
+- feat(console/deploy): asks the project once (`functions:list --json`) and feeds both decisions from that one answer — the region orphan check and the up-to-date check. Two questions could disagree, and then the decision depends on which answer the code happened to read.
+- feat(console/provision): `outdatedByStamp` requeues an applied extension function that carries a stamp older than what this package builds, or that is missing from the project. The stamp comes from the probes the `deploy` step just ran — extension functions live in the same codebase, so it is their stamp too. Called on its own, provisioning decides as it always did: probing there would cost a deploy on every extension install to answer a question that is almost always "nothing".
+- feat(console): `--all` on `deploy` and `provision` deploys every function without asking the project what it runs.
+- fix(console/regionOrphans): `listDeployedFunctions` keeps `hash`, `state` and `platform` instead of discarding everything but id and region; `clearRegionOrphans` accepts an already-fetched listing.
+
+#### [2.7.2] — 2026-08-25
+
+- feat(vendor/exampleSources): stages `automation-example` alongside the others, so the workspace ships a complete automation to read. Every example that travelled carried `workflows: []`, and automation was the one mechanism an author had only prose for.
+
 #### [2.7.1] — 2026-08-24
 
 - fix(unpack): the default catalog URL is `https://microteia.github.io/releases/kernel/index.json`.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.7.1
+# Microteia Console 2.8.0
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/deploy.js

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

package/lib/console/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/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,7 +10,8 @@ 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 { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
@@ -141,6 +142,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 +184,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 +203,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 +479,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);

package/lib/index.js

@@ -37,14 +37,14 @@ const COMMANDS = [
     },
     {
         name: 'deploy',
-        usage: 'microteia deploy [--only rules,indexes,functions,hosting] [--delay <seconds>] [--prune]',
+        usage: 'microteia deploy [--only rules,indexes,functions,hosting] [--delay <seconds>] [--prune] [--all]',
         summary: 'Publish the package that is in place to the connected Firebase project.',
         audience: 'office',
         execute: deploy,
     },
     {
         name: 'provision',
-        usage: 'microteia provision [--prune] [--delay <seconds>]',
+        usage: 'microteia provision [--prune] [--delay <seconds>] [--all]',
         summary: 'Give the installed extensions the Cloud Functions and indexes they ask for.',
         audience: 'office',
         execute: provision,

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.7.1";
+export declare const CLI_VERSION = "2.8.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.7.1';
+export const CLI_VERSION = '2.8.0';

package/lib/vendor/exampleSources.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
  */
 /** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
 export const EXAMPLE_SOURCES = {
+    'automation-example': 'automation.ts',
     brasil: 'brasil.ts',
     calendar: 'calendar.ts',
     dashboard: 'dashboard.ts',

package/lib/vendor/installationDocs.js

@@ -90,8 +90,8 @@ const commandRows = () => [
     '|---|---|',
     '| `microteia unpack --version <latest\\|x.y.z>` | Downloads a platform version, verifies it, and puts it in place. Touches no Firebase — safe any time |',
     '| `microteia unpack --kernel <pkg>.tgz` | The same, from a file you already have — for a machine with no access to the catalog |',
-    '| `microteia deploy [--only …] [--prune]` | Publishes what is in place: `rules`, `indexes`, `functions`, `hosting`. `--prune` also deletes functions left behind in a region this version no longer uses |',
-    '| `microteia provision [--prune]` | Gives installed extensions the functions and indexes they ask for |',
+    '| `microteia deploy [--only …] [--prune] [--all]` | Publishes what is in place: `rules`, `indexes`, `functions`, `hosting`. A Cloud Function the project already runs with this exact code is not deployed again; `--all` deploys every one of them anyway. `--prune` also deletes functions left behind in a region this version no longer uses |',
+    '| `microteia provision [--prune] [--all]` | Gives installed extensions the functions and indexes they ask for |',
     '| `microteia connect --project <id>` | Binds this installation to a Firebase project you own |',
     '| `microteia plugin-init` | Prepares `extensions/` for authoring in TypeScript |',
 ].join('\n');
@@ -179,6 +179,19 @@ carry that setting.
 
 An empty line means "not configured". A feature that needs it stays off rather than failing halfway.
 
+## 3.1 Why a deploy is usually much faster than the first one
+
+Firebase stamps every Cloud Function with what it was built from — the whole source directory, the
+resolved environment variables, and the secret versions. \`microteia deploy\` reads those stamps, deploys
+one reference function, and compares: a function whose stamp comes back unchanged is byte-for-byte what
+the project already runs, and is left alone. It is the same comparison \`firebase deploy\` makes when it
+deploys in bulk, which is why a version that only changed the application's screens finishes in minutes
+instead of publishing every function again.
+
+What the stamp does not see is configuration changed **outside** this installation — memory, timeout,
+concurrency or invoker policy edited in the Google console. \`microteia deploy --all\` deploys everything
+regardless, and is the answer for that.
+
 ## 4. Your own Cloud Functions
 
 Two places, answering two different questions:

package/package.json

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