@microteia/console 2.7.0

package/lib/console/backendParameters.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * O valor de um parâmetro de backend é carimbado no deploy de CADA function: o `firebase-functions`
+ * resolve os `defineString` e grava o resultado como variável de ambiente da function que está
+ * subindo. Quem preenche o `.env.<projectId>` DEPOIS da instalação não alcança function nenhuma — ela
+ * continua rodando com a string vazia que o `ensureOfficeEnv` escreveu, e a falha aparece só no runtime
+ * da feature.
+ *
+ * O provisionamento não notava isso porque o estado que ele guardava era só QUAIS functions subiram,
+ * nunca COM QUAIS VALORES. Este módulo é a outra metade: uma impressão digital por parâmetro no
+ * `microteia.yaml`, comparada a cada execução. Parâmetro que mudou torna obsoletas as functions da
+ * extensão que o declara, e elas voltam para a fila de deploy mesmo já estando aplicadas.
+ */
+/**
+ * Os parâmetros PREENCHIDOS do arquivo de ambiente. Linha sem valor é ausência: é assim que o
+ * `ensureOfficeEnv` grava o que ainda falta, e tratá-la como valor faria toda instalação nova nascer
+ * com uma mudança pendente.
+ */
+export const parseBackendEnv = (content) => {
+    const values = new Map();
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const separator = trimmed.indexOf('=');
+        if (separator === -1)
+            continue;
+        const name = trimmed.slice(0, separator).trim();
+        const value = trimmed.slice(separator + 1).trim();
+        if (name === '' || value === '')
+            continue;
+        values.set(name, value);
+    }
+    return values;
+};
+/**
+ * Lê a FONTE: o `.env.<projectId>` ao lado do `microteia.yaml`. A cópia dentro de
+ * `.microteia/install/functions/` existe só porque é de lá que o `firebase-functions` lê — comparar
+ * contra ela seria comparar contra o que o último deploy carimbou, não contra o que a pessoa digitou.
+ */
+export const readBackendEnv = async (root, projectId) => {
+    const content = await readFile(join(root, `.env.${projectId}`), 'utf8').catch(() => null);
+    return content === null ? new Map() : parseBackendEnv(content);
+};
+/**
+ * A impressão digital é SALGADA com o projeto e o nome do parâmetro. O `microteia.yaml` fica ao lado
+ * das Cloud Functions do escritório e não guarda credencial: um sha256 puro de um valor curto seria
+ * uma consulta de dicionário, e um salgado não é. Doze hexadecimais bastam para detectar mudança e
+ * não reconstroem valor nenhum.
+ */
+export const parameterDigest = (projectId, name, value) => createHash('sha256').update(`${projectId} ${name} ${value}`).digest('hex').slice(0, 12);
+export const parameterDigests = (projectId, values, tracked) => {
+    const digests = new Map();
+    for (const name of tracked) {
+        const value = values.get(name);
+        if (value === undefined)
+            continue;
+        digests.set(name, parameterDigest(projectId, name, value));
+    }
+    return digests;
+};
+/**
+ * `NOME:digest` separado por vírgula, no mesmo escalar de `backend.functions` e pelo mesmo motivo: o
+ * leitor de YAML daqui entende mapas de dois níveis e escalares, e trazer sequências para guardar meia
+ * dúzia de pares seria pagar caro pela generalidade.
+ */
+export const parseParameterState = (raw) => {
+    const state = new Map();
+    for (const entry of (raw ?? '').split(',')) {
+        const trimmed = entry.trim();
+        if (trimmed === '')
+            continue;
+        const separator = trimmed.lastIndexOf(':');
+        if (separator <= 0)
+            continue;
+        state.set(trimmed.slice(0, separator), trimmed.slice(separator + 1));
+    }
+    return state;
+};
+export const serializeParameterState = (state) => {
+    const entries = [...state.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, digest]) => `${name}:${digest}`);
+    return entries.length === 0 ? null : entries.join(',');
+};
+/**
+ * O que mudou entre o que foi aplicado e o que está no arquivo agora — incluindo o parâmetro que
+ * ESVAZIOU, porque a function deployada continua carregando o valor antigo e convergir é reescrevê-la
+ * com o que o arquivo diz.
+ */
+export const changedParameters = (recorded, current, tracked) => tracked.filter((name) => recorded.get(name) !== current.get(name)).sort();
+/** As functions das extensões que declaram algum destes parâmetros. */
+export const functionsDeclaringParameters = (claims, names) => {
+    const wanted = new Set(names);
+    return [...new Set(claims
+            .filter((claim) => (claim.backend.parameters ?? []).some((name) => wanted.has(name)))
+            .flatMap((claim) => claim.backend.functions ?? []))].sort();
+};

package/lib/console/callableAccess.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Uma callable no ar não é o mesmo que uma callable alcançável. O deploy concede a `allUsers` o papel
+ * `roles/run.invoker` em cada uma, mas a concessão pode ser RECUSADA — é o que uma política de
+ * Domain Restricted Sharing faz — e o `firebase deploy` termina com sucesso mesmo assim.
+ *
+ * O resultado é a pior forma de defeito: a aplicação abre, o login funciona, e toda chamada ao
+ * servidor falha no navegador como se fosse CORS. Parece problema de front, e manda procurar no lugar
+ * errado; o 403 do Cloud Run não carrega cabeçalho de CORS, e é só isso que o navegador reporta.
+ *
+ * Por isso a verificação é feita de fora, pelo mesmo caminho que o navegador usa: um preflight de
+ * verdade contra o endpoint da região. É a única prova que vale, porque é a única que reproduz a
+ * chamada que falharia.
+ */
+export type CallableAccess = 'reachable' | 'blocked' | 'missing' | 'unknown';
+export interface CallableCheck {
+    name: string;
+    access: CallableAccess;
+    status: number | null;
+}
+export interface CallableProbeOptions {
+    projectId: string;
+    region: string;
+    origin: string;
+}
+/** O host é por REGIÃO: fora da região do pacote, a callable simplesmente não existe neste endereço. */
+export declare const callableEndpoint: (region: string, projectId: string, name: string) => string;
+/**
+ * Uma function de 2ª geração é um serviço do Cloud Run, e lá ela aparece com o nome em MINÚSCULAS
+ * (`getUserInfo` → `getuserinfo`). Errar isso devolve "service not found", que parece indicar que a
+ * function não subiu.
+ */
+export declare const invokerGrantCommand: (region: string, projectId: string, name: string) => string;
+/**
+ * O 403 é a assinatura do IAM negando a invocação: o Cloud Run responde antes de a function existir
+ * para o mundo, e sem cabeçalho de CORS. Um 2xx sem `access-control-allow-origin` não conta como
+ * alcançável — é exatamente o caso em que o navegador recusa a resposta que o `curl` aceitaria.
+ */
+export declare const accessFromPreflight: (status: number, allowOrigin: string | null) => CallableAccess;
+export declare const checkCallables: (names: string[], options: CallableProbeOptions) => Promise<CallableCheck[]>;

package/lib/console/callableAccess.js

@@ -0,0 +1,61 @@
+/**
+ * Uma callable no ar não é o mesmo que uma callable alcançável. O deploy concede a `allUsers` o papel
+ * `roles/run.invoker` em cada uma, mas a concessão pode ser RECUSADA — é o que uma política de
+ * Domain Restricted Sharing faz — e o `firebase deploy` termina com sucesso mesmo assim.
+ *
+ * O resultado é a pior forma de defeito: a aplicação abre, o login funciona, e toda chamada ao
+ * servidor falha no navegador como se fosse CORS. Parece problema de front, e manda procurar no lugar
+ * errado; o 403 do Cloud Run não carrega cabeçalho de CORS, e é só isso que o navegador reporta.
+ *
+ * Por isso a verificação é feita de fora, pelo mesmo caminho que o navegador usa: um preflight de
+ * verdade contra o endpoint da região. É a única prova que vale, porque é a única que reproduz a
+ * chamada que falharia.
+ */
+const PROBE_TIMEOUT_MS = 10_000;
+/** O host é por REGIÃO: fora da região do pacote, a callable simplesmente não existe neste endereço. */
+export const callableEndpoint = (region, projectId, name) => `https://${region}-${projectId}.cloudfunctions.net/${name}`;
+/**
+ * Uma function de 2ª geração é um serviço do Cloud Run, e lá ela aparece com o nome em MINÚSCULAS
+ * (`getUserInfo` → `getuserinfo`). Errar isso devolve "service not found", que parece indicar que a
+ * function não subiu.
+ */
+export const invokerGrantCommand = (region, projectId, name) => `gcloud run services add-iam-policy-binding ${name.toLowerCase()}`
+    + ` --region=${region} --project=${projectId} --member=allUsers --role=roles/run.invoker`;
+/**
+ * O 403 é a assinatura do IAM negando a invocação: o Cloud Run responde antes de a function existir
+ * para o mundo, e sem cabeçalho de CORS. Um 2xx sem `access-control-allow-origin` não conta como
+ * alcançável — é exatamente o caso em que o navegador recusa a resposta que o `curl` aceitaria.
+ */
+export const accessFromPreflight = (status, allowOrigin) => {
+    if (status === 403)
+        return 'blocked';
+    if (status === 404)
+        return 'missing';
+    if (status >= 200 && status < 300)
+        return allowOrigin === null ? 'unknown' : 'reachable';
+    return 'unknown';
+};
+const probe = async (name, options) => {
+    try {
+        const response = await fetch(callableEndpoint(options.region, options.projectId, name), {
+            method: 'OPTIONS',
+            headers: {
+                Origin: options.origin,
+                'Access-Control-Request-Method': 'POST',
+                'Access-Control-Request-Headers': 'content-type',
+            },
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        return {
+            name,
+            access: accessFromPreflight(response.status, response.headers.get('access-control-allow-origin')),
+            status: response.status,
+        };
+    }
+    catch {
+        // Rede indisponível não é veredito: quem instala pode estar atrás de proxy, e acusar bloqueio
+        // aqui mandaria mexer em IAM que está correto.
+        return { name, access: 'unknown', status: null };
+    }
+};
+export const checkCallables = (names, options) => Promise.all(names.map((name) => probe(name, options)));

package/lib/console/channel.d.ts

@@ -0,0 +1,49 @@
+import type { ChannelEntry, ChannelIndex } from '../kernel/channel.js';
+/**
+ * O lado que BAIXA. Uma responsabilidade: transformar "a versão que eu quero" num arquivo local que já
+ * foi verificado.
+ *
+ * Ele é opcional por construção. `microteia unpack --kernel <arquivo>.tgz` continua existindo e continua
+ * sendo o caminho de quem está numa rede fechada, ou de quem recebeu o pacote por outro meio — o canal
+ * não pode virar pré-requisito para instalar, porque a instalação já depende de coisas demais que não
+ * são nossas.
+ */
+/**
+ * A URL do catálogo, e a razão de ela ser NOSSA e não a do host dos arquivos.
+ *
+ * Os tarballs ficam onde é barato hospedá-los, e as URLs deles são dado dentro do índice. Esta é a única
+ * que o Console conhece de cor, e é por isso que ela tem de estar num domínio que responda por si:
+ * mudar de hospedagem — ou passar a emitir URL assinada por escritório, que o host de hoje não faz —
+ * reescreve o índice, e um Console já instalado continua achando o catálogo no mesmo lugar.
+ */
+export declare const DEFAULT_INDEX_URL = "https://dist.microteia.app/kernel/index.json";
+export declare const indexUrl: () => string;
+/**
+ * O cache fica FORA da instalação, de propósito: `.microteia/` é apagado por inteiro a cada troca de
+ * kernel, e um cache ali seria descartado exatamente no momento em que serve para algo (voltar à versão
+ * anterior sem baixá-la de novo).
+ */
+export declare const cacheRoot: () => string;
+export declare const fetchIndex: (url?: string) => Promise<ChannelIndex>;
+export interface KernelDownload {
+    path: string;
+    entry: ChannelEntry;
+    /** `true` quando o arquivo já estava no cache e conferiu — o comando não usou a rede para baixá-lo. */
+    cached: boolean;
+}
+/**
+ * Resolve a versão pedida num arquivo local verificado, reusando o cache quando ele confere.
+ *
+ * Não há bandeira para ignorar o cache, e é deliberado: a entrada que não confere é apagada e baixada de
+ * novo aqui mesmo. Uma bandeira só serviria para quem já desconfia — e quem desconfia é justamente quem
+ * não vai lembrar de passá-la.
+ */
+export declare const fetchKernel: (requested: string, url?: string) => Promise<KernelDownload>;
+/**
+ * A versão mais nova que o canal oferece, ou `null` — e NUNCA uma exceção.
+ *
+ * Serve ao `--version`, que responde sobre a instalação e não sobre a rede: numa máquina sem acesso ao
+ * catálogo, perguntar a versão não pode falhar. O aviso é para o caso de alguém ter apontado
+ * `MICROTEIA_INDEX_URL` para um lugar errado e ficar sem entender por que nada é oferecido.
+ */
+export declare const newerThan: (version: string | null) => Promise<ChannelEntry | null>;

package/lib/console/channel.js

@@ -0,0 +1,145 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { digestMismatch, digestOfFile } from '../shared/digest.js';
+import { info, pending, success, warn } from '../shared/ui.js';
+import { compareVersions } from '../kernel/manifest.js';
+import { LATEST, kernelTarballName, parseIndex, resolveVersion } from '../kernel/channel.js';
+/**
+ * O lado que BAIXA. Uma responsabilidade: transformar "a versão que eu quero" num arquivo local que já
+ * foi verificado.
+ *
+ * Ele é opcional por construção. `microteia unpack --kernel <arquivo>.tgz` continua existindo e continua
+ * sendo o caminho de quem está numa rede fechada, ou de quem recebeu o pacote por outro meio — o canal
+ * não pode virar pré-requisito para instalar, porque a instalação já depende de coisas demais que não
+ * são nossas.
+ */
+/**
+ * A URL do catálogo, e a razão de ela ser NOSSA e não a do host dos arquivos.
+ *
+ * Os tarballs ficam onde é barato hospedá-los, e as URLs deles são dado dentro do índice. Esta é a única
+ * que o Console conhece de cor, e é por isso que ela tem de estar num domínio que responda por si:
+ * mudar de hospedagem — ou passar a emitir URL assinada por escritório, que o host de hoje não faz —
+ * reescreve o índice, e um Console já instalado continua achando o catálogo no mesmo lugar.
+ */
+export const DEFAULT_INDEX_URL = 'https://dist.microteia.app/kernel/index.json';
+export const indexUrl = () => {
+    const override = process.env.MICROTEIA_INDEX_URL;
+    return override === undefined || override === '' ? DEFAULT_INDEX_URL : override;
+};
+/**
+ * O cache fica FORA da instalação, de propósito: `.microteia/` é apagado por inteiro a cada troca de
+ * kernel, e um cache ali seria descartado exatamente no momento em que serve para algo (voltar à versão
+ * anterior sem baixá-la de novo).
+ */
+export const cacheRoot = () => {
+    const override = process.env.MICROTEIA_CACHE;
+    return override === undefined || override === ''
+        ? join(homedir(), '.microteia', 'cache')
+        : override;
+};
+/** O catálogo é pequeno, e o timeout existe para que uma rede muda não pareça um comando travado. */
+const INDEX_TIMEOUT_MS = 15_000;
+const fetchText = async (url, timeoutMs) => {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+        throw new Error(`${url} answered ${response.status} ${response.statusText}.`);
+    }
+    return response.text();
+};
+export const fetchIndex = async (url = indexUrl()) => {
+    const text = await fetchText(url, INDEX_TIMEOUT_MS).catch((error) => {
+        throw new Error(`Could not read the Microteia catalog at ${url}.\n`
+            + `${error instanceof Error ? error.message : String(error)}\n`
+            + 'If this machine has no access to it, install from a file: microteia unpack --kernel <package>.tgz');
+    });
+    return parseIndex(text, url);
+};
+const verified = async (path, entry) => {
+    const digest = await digestOfFile(path).catch(() => null);
+    if (digest === null)
+        return 'it is not there.';
+    return digestMismatch({ bytes: entry.bytes, sha256: entry.sha256 }, digest);
+};
+/**
+ * Baixa para um `.part` e só então renomeia.
+ *
+ * Escrever direto no nome final deixa, numa queda de rede, um arquivo com o nome certo e o conteúdo
+ * incompleto — e o `tar` recusa aquilo com uma mensagem sobre formato de arquivo, que manda procurar o
+ * defeito no pacote. Um `.part` que sobrou não é confundido com nada.
+ */
+const download = async (entry, target) => {
+    const part = `${target}.part`;
+    await rm(part, { force: true });
+    const response = await fetch(entry.tarball);
+    if (!response.ok) {
+        throw new Error(`${entry.tarball} answered ${response.status} ${response.statusText}.\n`
+            + 'The catalog points at this file, so either the release was removed or the catalog is ahead of it.');
+    }
+    // Em memória, e não por stream: o artefato é de um dígito de MB, e o que se ganharia em bytes
+    // residentes se pagaria em duas conversões de tipo entre o corpo web e o stream do Node.
+    await writeFile(part, Buffer.from(await response.arrayBuffer()));
+    await rename(part, target);
+};
+/**
+ * Resolve a versão pedida num arquivo local verificado, reusando o cache quando ele confere.
+ *
+ * Não há bandeira para ignorar o cache, e é deliberado: a entrada que não confere é apagada e baixada de
+ * novo aqui mesmo. Uma bandeira só serviria para quem já desconfia — e quem desconfia é justamente quem
+ * não vai lembrar de passá-la.
+ */
+export const fetchKernel = async (requested, url = indexUrl()) => {
+    const index = await fetchIndex(url);
+    const entry = resolveVersion(index, requested);
+    const directory = join(cacheRoot(), 'kernel', entry.version);
+    const target = join(directory, kernelTarballName(entry.version));
+    await mkdir(directory, { recursive: true });
+    const stale = await verified(target, entry);
+    if (stale === null) {
+        success(`kernel ${entry.version} is already in the cache, and it checks out`);
+        return { path: target, entry, cached: true };
+    }
+    pending(`downloading kernel ${entry.version} (${(entry.bytes / 1_000_000).toFixed(1)} MB)`);
+    await rm(target, { force: true });
+    await download(entry, target);
+    const problem = await verified(target, entry);
+    if (problem !== null) {
+        await rm(target, { force: true });
+        throw new Error(`What was downloaded is not the kernel ${entry.version} the catalog describes: ${problem}\n`
+            + `Source: ${entry.tarball}`);
+    }
+    success(`downloaded kernel ${entry.version} and verified its sha256`);
+    info(`  cached in ${directory}`);
+    return { path: target, entry, cached: false };
+};
+/**
+ * A versão mais nova que o canal oferece, ou `null` — e NUNCA uma exceção.
+ *
+ * Serve ao `--version`, que responde sobre a instalação e não sobre a rede: numa máquina sem acesso ao
+ * catálogo, perguntar a versão não pode falhar. O aviso é para o caso de alguém ter apontado
+ * `MICROTEIA_INDEX_URL` para um lugar errado e ficar sem entender por que nada é oferecido.
+ */
+export const newerThan = async (version) => {
+    const url = indexUrl();
+    const index = await fetchIndex(url).catch((error) => {
+        if (url !== DEFAULT_INDEX_URL) {
+            warn(`could not read the catalog at ${url}: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+        return null;
+    });
+    if (index === null)
+        return null;
+    const latest = (() => {
+        try {
+            return resolveVersion(index, LATEST);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (latest === null || version === null)
+        return latest;
+    // MAIOR, não "diferente": numa máquina de desenvolvimento a versão local costuma estar à frente do
+    // que foi publicado, e oferecer um downgrade como se fosse novidade é pior que não dizer nada.
+    return compareVersions(latest.version, version) > 0 ? latest : null;
+};

package/lib/console/connect.d.ts

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

package/lib/console/connect.js

@@ -0,0 +1,74 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { hasFlag, requiredFlag } from '../shared/args.js';
+import { blank, bullets, heading, info, step, success, warn } from '../shared/ui.js';
+import { GOOGLE_DEFAULT_REGION, MANUAL_PREREQUISITES } from '../kernel/manifest.js';
+import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environment.js';
+import { assertFirebaseCli, assertLoggedIn, createWebApp, listWebApps, webAppSdkConfig, } from './firebaseCli.js';
+import { runtimeConfigFrom } from './runtimeConfigShape.js';
+import { workspacePath, writeResolvedConfig } from './workspace.js';
+export const connect = async (args) => {
+    const file = resolve(hasFlag(args, 'file') ? requiredFlag(args, 'file') : join(process.cwd(), ENVIRONMENT_FILE));
+    const root = dirname(file);
+    const projectId = requiredFlag(args, 'project');
+    const environment = await readEnvironment(file);
+    heading(`Connecting "${environment.project.name}" to Firebase project ${projectId}`);
+    const total = 4;
+    step(1, total, 'Checking the Firebase CLI');
+    const cliVersion = await assertFirebaseCli();
+    await assertLoggedIn();
+    success(`firebase-tools ${cliVersion}, signed in`);
+    step(2, total, 'Looking for a web app in the project');
+    const apps = await listWebApps(projectId);
+    let appId = apps[0]?.appId;
+    if (appId === undefined) {
+        if (hasFlag(args, 'no-create-web-app')) {
+            throw new Error(`Firebase project "${projectId}" has no web app, and --no-create-web-app was given.\n`
+                + 'Create one in the Firebase console, then run "microteia connect" again.');
+        }
+        appId = await createWebApp(projectId, environment.project.name);
+        success(`created a web app in ${projectId} (${appId})`);
+    }
+    else {
+        success(`using the existing web app ${appId}`);
+        if (apps.length > 1) {
+            warn(`the project has ${apps.length} web apps; the first one was used.`);
+        }
+    }
+    step(3, total, 'Reading the web SDK configuration');
+    const sdkConfig = await webAppSdkConfig(projectId, appId);
+    const runtimeConfig = runtimeConfigFrom(sdkConfig, environment.firebase.region);
+    await mkdir(workspacePath(root), { recursive: true });
+    await writeResolvedConfig(root, runtimeConfig);
+    success('configuration resolved');
+    step(4, total, `Recording the project in ${ENVIRONMENT_FILE}`);
+    await writeEnvironment(file, {
+        ...environment,
+        firebase: { ...environment.firebase, projectId },
+    });
+    success(`${environment.environment.id} → ${projectId}`);
+    blank();
+    info('Before deploying, make sure the Firebase project is prepared. These cannot be done from here:');
+    blank();
+    for (const prerequisite of MANUAL_PREREQUISITES) {
+        info(`  ${prerequisite.optional ? '(optional) ' : ''}${prerequisite.title}`);
+        info(`      ${prerequisite.detail.replace(/\n/g, '\n      ')}`);
+        blank();
+    }
+    if (environment.firebase.region !== GOOGLE_DEFAULT_REGION) {
+        info(`This installation runs its functions in ${environment.firebase.region}, not in Google's`);
+        info(`  ${GOOGLE_DEFAULT_REGION} default. The browser calls them at that region, so the permission to`);
+        info('  invoke them has to exist there — see "unauthenticated invocation" above. The deploy grants');
+        info('  it, then verifies it from outside, and prints the exact command per function if the grant');
+        info('  was refused.');
+        blank();
+    }
+    /**
+     * A linha aqui dizia `microteia deploy --kernel <…>.tgz`, e aquela bandeira saiu do `deploy` na
+     * `2.0.0` — o pacote passou a chegar pelo `unpack`. Desde então ela mandava quem acabou de conectar
+     * direto para uma recusa, no primeiro comando depois do que funcionou.
+     */
+    info('Then:');
+    bullets(['microteia unpack --version latest', 'microteia deploy']);
+    blank();
+};

package/lib/console/customFunctions.d.ts

@@ -0,0 +1,120 @@
+import type { BackendParameter } 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 declare const FUNCTIONS_DIR = "functions";
+export declare const EXTENSIONS_DIR = "extensions";
+export interface FunctionSource {
+    /** Como aparece nas mensagens: `functions` ou `extensions/<plugin>/functions`. */
+    label: string;
+    /** Diretório dentro de `custom/src/`, e o que o barril importa. */
+    slug: string;
+    path: string;
+    exported: string[];
+    /**
+     * `functions/` é COMUM a várias extensões, e por isso não tem dono que possa reivindicá-la: ela sobe
+     * no `deploy`, sempre. `extensions/<plugin>/functions/` tem dono, e sobe pelo provisionamento — só no
+     * escritório que instalou a extensão. A distinção sai do LUGAR do arquivo, e não de uma declaração:
+     * duas extensões não podem reivindicar o mesmo nome (`functionClaimProblems`), então uma function
+     * comum não teria como ser declarada.
+     */
+    shared: boolean;
+    /** As callables — as únicas que o navegador chama, e por isso as únicas com alcance a conferir. */
+    callables: string[];
+    /** Os `defineString` que ela declara. O `firebase-functions` os valida GLOBALMENTE (ver abaixo). */
+    parameters: BackendParameter[];
+    /** As dependências npm que ela declara no `package.json` do próprio diretório. */
+    dependencies: Record<string, string>;
+}
+/**
+ * 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 declare const exportedNames: (source: string) => string[];
+/** Onde o escritório pode ter escrito function, na ordem em que as mensagens as citam. */
+export declare const findFunctionSources: (root: string) => Promise<FunctionSource[]>;
+/**
+ * O que o escritório escreveu, na forma em que os comandos precisam dele.
+ *
+ * `shared` e `owned` respondem a perguntas diferentes, e é por isso que são duas listas: a comum sobe
+ * no `deploy`, sempre; a de extensão sobe pelo provisionamento, e só onde a extensão está instalada.
+ */
+export interface OfficeFunctions {
+    sources: FunctionSource[];
+    /** Todos os nomes, na ordem em que as origens são lidas. */
+    all: string[];
+    /** As de `functions/` — sem dono, e por isso deployadas sempre. */
+    shared: string[];
+    callables: string[];
+    parameters: BackendParameter[];
+}
+export declare const officeFunctionsOf: (sources: FunctionSource[]) => OfficeFunctions;
+/**
+ * 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 declare const readOfficeFunctions: (root: string) => Promise<OfficeFunctions>;
+/**
+ * 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 declare const functionProblems: (sources: FunctionSource[], kernelFunctions: string[]) => string[];
+/**
+ * Duas declarações da MESMA dependência com faixas diferentes, entre diretórios do escritório.
+ *
+ * É recusa e não escolha porque não há dono: `install/functions/` é uma árvore de `node_modules` só, e
+ * eleger uma das faixas em silêncio é a mesma classe de defeito do nome de function repetido — funciona
+ * até a versão escolhida ser a errada, e aí a falha aparece longe da causa.
+ *
+ * Contra o KERNEL a regra é outra e é deliberada: a faixa do pacote VENCE, e o fato é relatado. O
+ * runtime das functions é escolha de quem publica o kernel, e uma extensão não pode movê-lo por baixo
+ * das outras.
+ */
+export interface DependencyPlan {
+    /** O que acrescentar ao `package.json` do pacote. */
+    added: Record<string, string>;
+    /** Declarada pelo escritório e já no kernel, com faixa diferente — a do kernel fica. */
+    overridden: string[];
+    problems: string[];
+}
+export declare const dependencyPlan: (sources: FunctionSource[], kernelDependencies: Record<string, string>) => DependencyPlan;
+/**
+ * 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 declare const applyFunctionDependencies: (install: string, sources: FunctionSource[]) => Promise<DependencyPlan>;
+export interface GatherResult extends OfficeFunctions {
+    /** Todos os nomes, ordenados — o que as mensagens citam. */
+    functions: string[];
+    dependencies: DependencyPlan;
+}
+/**
+ * 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 declare const gatherCustomFunctions: (root: string, install: string, kernelFunctions: string[]) => Promise<GatherResult>;