@microteia/console 2.7.0

package/lib/console/customFunctions.js

@@ -0,0 +1,298 @@
+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';
+/**
+ * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
+ *
+ * Elas moravam em `.microteia/install/functions/custom/src/`, e isso tinha o mesmo defeito que a
+ * configuração de backend tinha: editar à mão dentro de um diretório que o `unpack` substitui por
+ * inteiro. Sobreviviam porque `functions/custom` estava numa lista de exceção — o que funciona até
+ * alguém mexer na lista, e não resolve o problema de o lugar certo não ser óbvio.
+ *
+ * Agora a fonte fica fora, ao lado do `microteia.yaml`, em dois lugares que respondem a duas perguntas
+ * diferentes:
+ *
+ * - `extensions/<plugin>/functions/` — a function é DAQUELA extensão. Fica junto do plugin que a usa,
+ *   e quem lê a pasta da extensão vê tudo o que ela é.
+ * - `functions/` — a function é COMUM a várias. É o lugar de quem não pertence a uma só.
+ *
+ * O que vai para dentro de `install/` é uma cópia montada no deploy, com um barril gerado. É por isso
+ * que `functions/custom` saiu da lista de preservação do `unpack`: não há mais nada ali para preservar.
+ */
+/** O nome do diretório, nos dois lugares. */
+export const FUNCTIONS_DIR = 'functions';
+export const EXTENSIONS_DIR = 'extensions';
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Os nomes que um módulo de entrada exporta. Cobre as duas formas que se escreve de fato: o
+ * `export const x = onCall(...)` de quem declara no lugar, e o `export { a, b }` de quem reexporta.
+ */
+export const exportedNames = (source) => {
+    const names = new Set();
+    for (const match of source.matchAll(/export\s+(?:const|let|var|function|async\s+function)\s+([A-Za-z_$][\w$]*)/g)) {
+        names.add(match[1]);
+    }
+    for (const match of source.matchAll(/export\s*\{([^}]*)\}/g)) {
+        for (const part of match[1].split(',')) {
+            const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+            if (name !== undefined && name !== '' && name !== 'default')
+                names.add(name);
+        }
+    }
+    return [...names].sort();
+};
+/** Todo `.ts` do diretório, recursivamente — a fonte das declarações que não moram no `index.ts`. */
+const sourceFiles = async (path) => {
+    const found = [];
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+            continue;
+        const child = join(path, entry.name);
+        if (entry.isDirectory())
+            found.push(...await sourceFiles(child));
+        else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts'))
+            found.push(child);
+    }
+    return found.sort();
+};
+/**
+ * As dependências npm que o diretório declara. O `package.json` é OPCIONAL: a maioria das functions do
+ * escritório só usa o que o pacote já traz, e exigir o arquivo cobraria cerimônia de quem não precisa.
+ */
+const readDependencies = async (path, label) => {
+    const manifest = join(path, 'package.json');
+    if (!await exists(manifest))
+        return {};
+    const parsed = JSON.parse(await readFile(manifest, 'utf8'));
+    if (parsed.dependencies === undefined)
+        return {};
+    if (typeof parsed.dependencies !== 'object' || parsed.dependencies === null) {
+        throw new Error(`${label}/package.json has a "dependencies" that is not an object.`);
+    }
+    return parsed.dependencies;
+};
+const readSource = async (path, label, slug, shared) => {
+    const entry = join(path, 'index.ts');
+    if (!await exists(entry)) {
+        throw new Error(`${label}/ has no index.ts.\n`
+            + 'A directory of Cloud Functions is read through its index.ts — export from there what should be'
+            + ' deployed.');
+    }
+    const exported = exportedNames(await readFile(entry, 'utf8'));
+    const callables = new Set();
+    const parameters = new Map();
+    for (const file of await sourceFiles(path)) {
+        const source = await readFile(file, 'utf8');
+        for (const name of callableFunctionNames(source))
+            callables.add(name);
+        // Um nome declarado em vários lugares é UM parâmetro, e ele é exigido se ALGUMA declaração o pede
+        // sem `default`: é essa que recusa o deploy quando o valor falta, e a conservadora é a que avisa.
+        for (const parameter of declaredParametersIn(source)) {
+            const previous = parameters.get(parameter.name);
+            parameters.set(parameter.name, {
+                name: parameter.name,
+                required: parameter.required || (previous?.required ?? false),
+            });
+        }
+    }
+    return {
+        label,
+        slug,
+        path,
+        exported,
+        shared,
+        // Só as que o `index.ts` de fato exporta: uma callable escrita e não exportada não é deployada, e
+        // conferir o alcance dela mandaria procurar um erro que não existe.
+        callables: exported.filter((name) => callables.has(name)),
+        parameters: [...parameters.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        dependencies: await readDependencies(path, label),
+    };
+};
+/** Onde o escritório pode ter escrito function, na ordem em que as mensagens as citam. */
+export const findFunctionSources = async (root) => {
+    const found = [];
+    if (await exists(join(root, FUNCTIONS_DIR))) {
+        found.push(await readSource(join(root, FUNCTIONS_DIR), FUNCTIONS_DIR, 'shared', true));
+    }
+    const extensions = join(root, EXTENSIONS_DIR);
+    if (await exists(extensions)) {
+        for (const entry of (await readdir(extensions, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory() || entry.name === 'node_modules' || entry.name.startsWith('.'))
+                continue;
+            const path = join(extensions, entry.name, FUNCTIONS_DIR);
+            if (!await exists(path))
+                continue;
+            found.push(await readSource(path, `${EXTENSIONS_DIR}/${entry.name}/${FUNCTIONS_DIR}`, entry.name, false));
+        }
+    }
+    return found;
+};
+export const officeFunctionsOf = (sources) => {
+    const parameters = new Map();
+    for (const source of sources) {
+        for (const parameter of source.parameters) {
+            const previous = parameters.get(parameter.name);
+            parameters.set(parameter.name, {
+                name: parameter.name,
+                required: parameter.required || (previous?.required ?? false),
+            });
+        }
+    }
+    return {
+        sources,
+        all: sources.flatMap((source) => source.exported),
+        shared: sources.filter((source) => source.shared).flatMap((source) => source.exported),
+        callables: sources.flatMap((source) => source.callables),
+        parameters: [...parameters.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    };
+};
+/**
+ * O que o escritório escreveu, lido de onde ele escreve. É a porta única: `deploy`, `provision` e
+ * `unpack` precisam da mesma resposta, e três leituras divergiriam no ponto em que ninguém olha.
+ */
+export const readOfficeFunctions = async (root) => officeFunctionsOf(await findFunctionSources(root));
+/**
+ * Os problemas que impedem montar o conjunto. São recusa e não aviso, pelo mesmo motivo do `pack`: o
+ * `index.js` do pacote espalha o customizado DEPOIS do kernel, então um nome repetido substitui em
+ * silêncio — e substituir um gatilho do kernel é o tipo de defeito que só aparece quando algo deixa de
+ * acontecer, sem erro em lugar nenhum.
+ */
+export const functionProblems = (sources, kernelFunctions) => {
+    const problems = [];
+    const kernel = new Set(kernelFunctions);
+    const seen = new Map();
+    for (const source of sources) {
+        if (source.exported.length === 0) {
+            problems.push(`${source.label}/index.ts exports nothing — remove the directory or export a function`);
+        }
+        for (const name of source.exported) {
+            if (kernel.has(name)) {
+                problems.push(`${source.label} exports "${name}", which is the name of a Microteia function — rename yours`);
+            }
+            const previous = seen.get(name);
+            if (previous !== undefined) {
+                problems.push(`"${name}" is exported by both ${previous} and ${source.label} — names must be unique`);
+            }
+            else {
+                seen.set(name, source.label);
+            }
+        }
+    }
+    return problems;
+};
+const barrel = (sources) => `// Generated by "microteia deploy". Do not edit.
+//
+// The Cloud Functions this installation adds, gathered from where they are written:
+${sources.map((source) => `//   ${source.label}/`).join('\n')}
+//
+// Write them there, not here — this directory is rebuilt on every deploy.
+
+${sources.map((source) => `export * from './${source.slug}';`).join('\n')}
+`;
+/**
+ * O que de um diretório de functions vai para dentro do pacote — e o que NÃO vai.
+ *
+ * Teste fica fora, e não por economia de bytes: o `predeploy` do pacote compila `custom/` com o `tsc`, e
+ * um `import ... from 'vitest'` é `Cannot find module` ali dentro. O `vitest` é dependência de
+ * DESENVOLVIMENTO do escritório e não pode ser dependência das functions deployadas — então a compilação
+ * falha, e com ela falha o deploy de TODAS as functions, não só das da extensão que trouxe o teste.
+ *
+ * Foi assim que as cinco functions de uma extensão falharam juntas, com o relatório culpando cada uma
+ * delas. O `AGENTS.md` manda o autor escrever teste ao lado da function; era este lado que faltava.
+ *
+ * O `__fixtures__` continua entrando: é módulo comum, compila sozinho, e adivinhar pelo nome do
+ * diretório seria heurística. O que se reconhece aqui são as duas convenções inequívocas.
+ */
+const deployable = (source) => {
+    const name = basename(source);
+    return !/\.(test|spec)\.tsx?$/.test(name) && name !== '__tests__';
+};
+export const dependencyPlan = (sources, kernelDependencies) => {
+    const added = {};
+    const overridden = [];
+    const problems = [];
+    const owner = new Map();
+    for (const source of sources) {
+        for (const [name, range] of Object.entries(source.dependencies)) {
+            const inKernel = kernelDependencies[name];
+            if (inKernel !== undefined) {
+                if (inKernel !== range)
+                    overridden.push(`${name}: ${source.label} asks for ${range}, the package has ${inKernel}`);
+                continue;
+            }
+            const previous = added[name];
+            if (previous !== undefined && previous !== range) {
+                problems.push(`dependency "${name}" is declared as ${previous} by ${owner.get(name)} and as ${range} by `
+                    + `${source.label} — one installation has one node_modules, so the two must agree`);
+                continue;
+            }
+            added[name] = range;
+            owner.set(name, source.label);
+        }
+    }
+    return { added, overridden: overridden.sort(), problems };
+};
+/**
+ * Escreve no `package.json` do pacote as dependências que os diretórios do escritório declaram.
+ *
+ * Elas não podem viajar no pacote: o kernel não sabe o que o escritório vai escrever. E o `npm install`
+ * do deploy é o que as instala — o `package-lock.json` que veio do pacote deixa de cobrir tudo, e o npm
+ * resolve o que falta e reescreve o lock. É por isso que a primeira instalação depois de declarar uma
+ * dependência nova demora mais que as seguintes.
+ */
+export const applyFunctionDependencies = async (install, sources) => {
+    // Nenhum diretório declarou dependência: não há o que decidir, e não se abre o `package.json` do
+    // pacote para nada. É o caso comum — a maioria das functions do escritório só usa o que já vem.
+    if (sources.every((source) => Object.keys(source.dependencies).length === 0)) {
+        return { added: {}, overridden: [], problems: [] };
+    }
+    const path = join(install, 'functions', 'package.json');
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    const kernel = parsed.dependencies ?? {};
+    const plan = dependencyPlan(sources, kernel);
+    if (plan.problems.length > 0) {
+        throw new Error(`Your Cloud Functions cannot be assembled:\n${plan.problems.map((problem) => `  ${problem}`).join('\n')}`);
+    }
+    if (Object.keys(plan.added).length === 0)
+        return plan;
+    const merged = Object.fromEntries(Object.entries({ ...kernel, ...plan.added }).sort(([left], [right]) => left.localeCompare(right)));
+    await writeFile(path, `${JSON.stringify({ ...parsed, dependencies: merged }, null, 2)}\n`);
+    return plan;
+};
+/**
+ * Monta `install/functions/custom/src/` a partir das fontes de fora, escreve o barril e acrescenta ao
+ * `package.json` do pacote as dependências que essas fontes declaram.
+ *
+ * O diretório é apagado antes: ele é DERIVADO, e um resto da montagem anterior seria deployado sem que
+ * nada apontasse a origem dele.
+ */
+export const gatherCustomFunctions = async (root, install, kernelFunctions) => {
+    const sources = await findFunctionSources(root);
+    const problems = functionProblems(sources, kernelFunctions);
+    if (problems.length > 0) {
+        throw new Error(`Your Cloud Functions cannot be assembled:\n${problems.map((p) => `  ${p}`).join('\n')}`);
+    }
+    const target = join(install, 'functions', 'custom', 'src');
+    await rm(target, { recursive: true, force: true });
+    await mkdir(target, { recursive: true });
+    for (const source of sources) {
+        await cp(source.path, join(target, source.slug), { recursive: true, filter: deployable });
+    }
+    await writeFile(join(target, 'index.ts'), sources.length === 0
+        ? '// Generated by "microteia deploy". No Cloud Functions of your own were found.\nexport {};\n'
+        : barrel(sources));
+    const office = officeFunctionsOf(sources);
+    return {
+        ...office,
+        functions: [...office.all].sort(),
+        dependencies: await applyFunctionDependencies(install, sources),
+    };
+};

package/lib/console/deploy.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../shared/args.js';
+export declare const deploy: (args: ParsedArgs) => Promise<void>;

package/lib/console/deploy.js

@@ -0,0 +1,261 @@
+import { writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { flagValue, hasFlag, requiredFlag } from '../shared/args.js';
+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 { checkCallables, invokerGrantCommand } from './callableAccess.js';
+import { checkHostingServed, htmlIsRevalidated } from './hostingCheck.js';
+import { provisionBackend } from './provision.js';
+import { installPath, readInstalledManifest } from './unpack.js';
+import { ensureOfficeEnv, ensureRootGitignore, officeEnvName, stageOfficeEnv } from './backendEnv.js';
+import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
+import { readResolvedConfig, stampedConfigJs, writeResolvedConfig, } from './workspace.js';
+const COMPONENTS = ['rules', 'indexes', 'functions', 'hosting'];
+const selectedComponents = (args) => {
+    const only = flagValue(args, 'only');
+    if (only === undefined)
+        return [...COMPONENTS];
+    const requested = only.split(',').map((name) => name.trim());
+    const unknown = requested.filter((name) => !COMPONENTS.includes(name));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown component(s): ${unknown.join(', ')}. Valid: ${COMPONENTS.join(', ')}.`);
+    }
+    return requested;
+};
+export const deploy = async (args) => {
+    const file = resolve(hasFlag(args, 'file') ? requiredFlag(args, 'file') : join(process.cwd(), ENVIRONMENT_FILE));
+    const root = dirname(file);
+    const components = selectedComponents(args);
+    const delaySeconds = Number.parseInt(flagValue(args, 'delay') ?? '1', 10);
+    const environment = await readEnvironment(file);
+    const projectId = environment.firebase.projectId;
+    if (projectId === null) {
+        throw new Error('This installation is not connected yet. Run "microteia connect --project <id>".');
+    }
+    const resolvedConfig = await readResolvedConfig(root);
+    const firstInstall = environment.kernel.version === null;
+    heading(`Deploying Microteia to ${projectId}`);
+    const total = components.length + 1;
+    let current = 0;
+    // Publica o que o `unpack` trouxe. Separar os dois é o que permite trocar de kernel e publicar SÓ o
+    // que mudou naquela versão — e é o que dá um momento para preencher um parâmetro novo antes de subir.
+    const install = installPath(root);
+    const manifest = await readInstalledManifest(root);
+    // A região é do PACOTE, não do arquivo: as Cloud Functions são compiladas com ela fixa, então o
+    // que está no `microteia.yaml` é registro, e não escolha.
+    const region = manifest.requires.functionsRegion;
+    if (environment.firebase.region !== region) {
+        warn(`this package is compiled for region ${region}; the installation recorded ${environment.firebase.region}.`);
+    }
+    const baselineCount = (manifest.baselineFunctions ?? manifest.functions).length;
+    success(`kernel ${manifest.version} (contract ${manifest.kernelVersion}), ${baselineCount} baseline function(s)`
+        + `, ${manifest.functions.length - baselineCount} claimed by extensions`);
+    if (firstInstall)
+        info('  first install: functions are deployed with --force so cleanup policies get configured');
+    current += 1;
+    step(current, total, 'Stamping the installation configuration');
+    const stamped = { ...resolvedConfig, functionsRegion: region };
+    await writeResolvedConfig(root, stamped);
+    await writeFile(join(install, 'hosting', 'firebase-config.js'), stampedConfigJs(stamped));
+    success(`hosting/firebase-config.js → ${projectId}`);
+    // O arquivo que o escritório edita é o da RAIZ; o que o `firebase-functions` lê tem de estar em
+    // `install/functions/`, e por isso é uma cópia escrita agora. Antes a fonte era a cópia, e o deploy
+    // seguinte a apagava junto com o pacote.
+    await ensureRootGitignore(root);
+    // A união, e não só o que o pacote declara: o `firebase-functions` valida os `defineString`
+    // GLOBALMENTE, então um parâmetro declarado por uma function do escritório e sem linha no arquivo
+    // recusa o deploy de TODAS elas — inclusive as que não têm relação com ele.
+    const office = await readOfficeFunctions(root);
+    const settings = await ensureOfficeEnv(root, projectId, [...manifest.backendParameters, ...office.parameters]);
+    if (settings.created) {
+        warn(`created ${officeEnvName(projectId)} with ${settings.added.length} setting(s), all empty —`);
+        warn('  features that need one stay off until it is filled in and "microteia provision" runs again.');
+    }
+    else if (settings.added.length > 0) {
+        warn(`this package declares ${settings.added.length} new setting(s), added empty to `
+            + `${officeEnvName(projectId)}: ${settings.added.join(', ')}`);
+    }
+    await stageOfficeEnv(root, projectId, install);
+    const failures = [];
+    const unreachableCallables = [];
+    let staleHosting = false;
+    for (const component of components) {
+        current += 1;
+        if (component === 'rules') {
+            step(current, total, 'Firestore and Storage rules');
+            await run(FIREBASE_BIN, ['deploy', '--only', 'firestore:rules,storage', '--project', projectId], { cwd: install });
+            continue;
+        }
+        if (component === 'indexes') {
+            step(current, total, 'Firestore indexes');
+            await run(FIREBASE_BIN, ['deploy', '--only', 'firestore:indexes', '--project', projectId], { cwd: install });
+            continue;
+        }
+        if (component === 'functions') {
+            // A BASELINE, e não tudo o que foi empacotado: function de extensão sobe quando a extensão for
+            // instalada, pelo provisionamento no fim deste comando.
+            const baseline = manifest.baselineFunctions ?? manifest.functions;
+            // As functions do escritório são montadas AGORA, a partir de onde ele as escreve: `functions/` (as
+            // comuns) e `extensions/<plugin>/functions/` (as de cada extensão). O `predeploy` do pacote compila
+            // só o `custom/`, então o que não estiver aqui não sobe.
+            const gathered = await gatherCustomFunctions(root, install, manifest.functions);
+            // O que sobe aqui é a baseline MAIS as functions comuns do escritório (`functions/`). As de
+            // `extensions/<plugin>/functions/` têm dono e sobem pelo provisionamento, no fim deste comando:
+            // é o mesmo "empacotar não é deployar" que vale para as do kernel reivindicadas por extensão.
+            const own = [...baseline, ...gathered.shared];
+            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 `
+                    + `${gathered.sources.map((source) => `${source.label}/`).join(', ')}`);
+                const owned = gathered.all.length - gathered.shared.length;
+                if (owned > 0)
+                    info(`  ${owned} of them belong to an extension and go up with "provision"`);
+            }
+            if (Object.keys(gathered.dependencies.added).length > 0) {
+                success(`${Object.keys(gathered.dependencies.added).length} npm dependency(ies) your functions declare: `
+                    + `${Object.keys(gathered.dependencies.added).join(', ')}`);
+                info('  the packaged lockfile does not cover them, so this npm install resolves them and takes');
+                info('  longer than the following ones.');
+            }
+            for (const line of gathered.dependencies.overridden) {
+                warn(`${line} — the package's range wins; the runtime is the kernel's choice`);
+            }
+            info('  installing function dependencies… (~250 packages, a few seconds)');
+            // Os dois avisos que o npm dá aqui são esperados, e explicá-los antes evita que quem instala pare
+            // para investigar: `EBADENGINE` compara a Node DESTA máquina com a do runtime das functions (que
+            // é fixa em 22 de propósito), e as notas de descontinuação vêm de dependências do próprio
+            // Firebase, não do kernel. Nenhum dos dois impede o deploy.
+            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') });
+            // 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, {
+                projectId,
+                cwd: install,
+                delaySeconds,
+                force: firstInstall,
+            });
+            if (report.failed.length > 0) {
+                failures.push(`${report.failed.length} function(s): ${report.failed.map((entry) => entry.name).join(', ')}`);
+                blank();
+                reportFailures(report.failed);
+            }
+            reportNotices(report.notices);
+            // Deployada não quer dizer alcançável: a concessão de invocação pública pode ter sido
+            // recusada, e o `firebase deploy` termina bem do mesmo jeito. Quem paga a conta é o escritório,
+            // com uma aplicação que abre e não consegue falar com o servidor.
+            const callables = [...(manifest.callables ?? []), ...gathered.callables]
+                .filter((name) => own.includes(name));
+            if (callables.length > 0) {
+                info(`  checking that the browser can reach the ${callables.length} callable(s)…`);
+                const origin = `https://${projectId}.web.app`;
+                const checks = await checkCallables(callables, { projectId, region, origin });
+                const blocked = checks.filter((check) => check.access === 'blocked');
+                const unclear = checks.filter((check) => check.access !== 'blocked' && check.access !== 'reachable');
+                if (blocked.length > 0) {
+                    unreachableCallables.push(...blocked.map((check) => check.name));
+                    blank();
+                    failure(`${blocked.length} of ${checks.length} callable(s) refuse calls from ${origin}.`);
+                    info('  The deploy could not make them public — an organization policy that forbids allUsers');
+                    info('  in IAM does exactly this. The application will open and every server call will fail,');
+                    info('  in the browser, as what looks like a CORS error. Run once per function:');
+                    bullets(blocked.map((check) => invokerGrantCommand(region, projectId, check.name)));
+                }
+                else if (unclear.length > 0) {
+                    warn(`could not confirm ${unclear.length} of ${checks.length} callable(s): `
+                        + `${unclear.map((check) => check.name).join(', ')}. Re-run the check, or open the`
+                        + ' application and watch the browser console.');
+                }
+                else {
+                    success(`all ${checks.length} callables answer calls from ${origin}`);
+                }
+            }
+            continue;
+        }
+        step(current, total, 'Hosting');
+        await run(FIREBASE_BIN, ['deploy', '--only', 'hosting', '--project', projectId], { cwd: install });
+        // Publicado não é servido: se o navegador ainda recebe o `index.html` antigo, ele continua
+        // carregando o bundle antigo — e a aplicação segue na versão anterior com o deploy em sucesso.
+        const hosting = await checkHostingServed(install, `https://${projectId}.web.app`);
+        if (hosting.served === 'current') {
+            success(`the site serves this version's bundle (${hosting.servedBundle})`);
+        }
+        else if (hosting.served === 'stale') {
+            warn(`the site is still serving the PREVIOUS bundle (${hosting.servedBundle},`);
+            warn(`  this package ships ${hosting.packagedBundle}). Give the CDN a moment and reload; if the`);
+            warn('  application keeps showing the old version, force a reload to drop the cached page.');
+            staleHosting = true;
+        }
+        else {
+            info('  could not confirm which bundle the site serves — open it and check the version in the footer');
+        }
+        if (!htmlIsRevalidated(hosting.htmlCacheControl) && hosting.htmlCacheControl !== null) {
+            warn(`the page is served with "cache-control: ${hosting.htmlCacheControl}", so a browser that`);
+            warn('  already visited it may keep the previous version until that expires. This package sets');
+            warn('  the page to revalidate on every load, so the value above is the one from the deploy');
+            warn('  BEFORE this one — it settles once this deploy propagates.');
+        }
+    }
+    /**
+     * O que o `deploy` carimba é o `deployed`: o `version` já foi gravado pelo `unpack`, que é quem põe o
+     * pacote no lugar. Um número só mentia numa das duas pontas — entre desempacotar e publicar, o
+     * `MICROTEIA.md` anunciava a versão nova e o `microteia.yaml` ao lado dele, a anterior.
+     */
+    const applied = {
+        ...environment,
+        firebase: { ...environment.firebase, region },
+        kernel: { version: manifest.version, deployed: manifest.version },
+    };
+    await writeEnvironment(file, applied);
+    // Um motor só: o que as extensões instaladas exigem é aplicado aqui, no fim do deploy, e pelo
+    // `microteia provision` quando alguém instala uma extensão depois. Numa instalação nova não há nada
+    // instalado e este passo não faz nada — é justamente o que se quer.
+    if (components.includes('functions') || components.includes('indexes')) {
+        blank();
+        info('Extension backends');
+        const provisioned = await provisionBackend({
+            projectId,
+            region,
+            install,
+            manifest,
+            delaySeconds,
+            prune: hasFlag(args, 'prune'),
+            environmentFile: file,
+            environment: applied,
+        });
+        if (provisioned.failed.length > 0) {
+            failures.push(`${provisioned.failed.length} extension function(s): ${provisioned.failed.join(', ')}`);
+        }
+    }
+    blank();
+    if (failures.length > 0) {
+        failure(`Deploy finished with problems: ${failures.join('; ')}`);
+        info('Re-run to retry only what failed:');
+        bullets(['microteia deploy --only functions']);
+        blank();
+        throw new Error('Some components did not deploy.');
+    }
+    info(`Microteia ${manifest.version} is installed in ${projectId}.`);
+    bullets([`https://${projectId}.web.app`]);
+    blank();
+    if (staleHosting) {
+        warn('the browser may still load the previous version for a few minutes. A forced reload');
+        warn('  (Shift+Reload, or Empty Cache and Hard Reload) settles it immediately.');
+        blank();
+    }
+    if (unreachableCallables.length > 0) {
+        warn(`the deploy finished, but ${unreachableCallables.length} function(s) still refuse calls from`);
+        warn('  the browser. Grant the invoker role with the commands printed above before signing in,');
+        warn('  otherwise the application opens and nothing it asks the server for will work.');
+        blank();
+    }
+    info('Sign in to create the first office. Everything else is configured from inside the application.');
+    blank();
+};

package/lib/console/deployFunctions.d.ts

@@ -0,0 +1,45 @@
+export interface FunctionDeployOptions {
+    projectId: string;
+    cwd: string;
+    delaySeconds: number;
+    /** `--force` deixa o Firebase configurar sozinho a política de limpeza do Artifact Registry. */
+    force: boolean;
+}
+export interface FunctionDeployFailure {
+    name: string;
+    /** A saída do `firebase`, sem os avisos que não têm relação com o resultado. */
+    output: string;
+    /** A linha que explica a falha. */
+    reason: string;
+    /** Repetir dá o mesmo resultado: é uma recusa do `firebase`, não uma corrida com o Google. */
+    terminal: boolean;
+    /** O que fazer a respeito, quando dá para dizer. Impresso UMA vez, não uma por function. */
+    hint: string[];
+}
+export interface FunctionDeployReport {
+    deployed: string[];
+    failed: FunctionDeployFailure[];
+    /** Avisos que valem uma linha no fim do deploy, e não uma linha por function. */
+    notices: string[];
+}
+export declare const stripNotices: (text: string) => {
+    text: string;
+    summaries: string[];
+};
+export declare const failureReason: (output: string) => string;
+/**
+ * A falha que repetir não conserta.
+ *
+ * A segunda passada existe para UMA coisa (identidade de serviço que ainda não propagou), e tratá-la
+ * como remédio de tudo custa uma rodada inteira de deploy por function — a de região antiga leva
+ * ~40s cada, e a resposta da segunda vez é palavra por palavra a mesma. Pior: repetir sugere a quem
+ * está olhando que aquilo é intermitente, quando é uma recusa deliberada do `firebase`.
+ */
+export interface TerminalFailure {
+    match: RegExp;
+    hint: string[];
+}
+export declare const terminalFailure: (output: string) => TerminalFailure | undefined;
+export declare const deployFunctionsOneByOne: (names: string[], options: FunctionDeployOptions) => Promise<FunctionDeployReport>;
+export declare const reportFailures: (failures: FunctionDeployFailure[]) => void;
+export declare const reportNotices: (notices: string[]) => void;